核心内容摘要
8x8x：解码华人世界的无限可能
Clawdbot 项目介绍Clawdbot 是一款开源的运行在您自己的设备上的个人 AI 助手。
它可以通过您常用的渠道WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat以及 BlueBubbles、Matrix、Zalo 和 Zalo Personal 等扩展渠道为您提供帮助。
支持 macOS/iOS/Android 系统并可渲染由您控制的实时 Canvas 界面。
网关只是控制平台产品本身才是真正的助手。
如果你想要一个感觉像本地助手、速度快、始终在线的单人个人助理那一定就是它了。
本文基于 Clawdbot 官方文档整理在官方 docker-compose.yml 基础上补充了生产环境必需的安全性、可靠性与运维建议不与官方配置冲突适用于希望通过Docker / Docker Compose快速部署 Clawdbot 的用户。
本文档可作为官方技术博客或部署指南发布。
说明截至目前Clawdbot未提供官方预构建 Docker 镜像Docker 方式采用源码 Dockerfile 本地构建镜像的模式这是官方推荐且最稳定的部署方式。
⚠️ 核心提示本文示例默认标注NODE_ENVproduction但测试部署与生产部署的配置要求差异显著请务必根据实际场景选择对应配置策略。
部署模式说明部署场景适用场景核心特征测试 / 本地体验功能验证、开发调试配置简化、无资源限制、数据可不持久化、日志仅控制台输出单机生产推荐中小规模线上运行强制数据持久化、配置重启策略/健康检查/资源限制、日志持久化、定期备份企业级生产高可用/大规模业务场景基于单机生产扩展支持多节点、CI/CD、外部数据库、监控告警、容灾备份ℹ️ 说明本文不覆盖 Clawdbot 多节点高可用HA、分布式数据库部署场景如需此类方案需在单机生产配置基础上另行设计。
环境准备为降低部署门槛、提升成功率本文提供官方等价的一键安装脚本与官方原生安装方式两种选择你可根据服务器网络环境适配方式一一键安装 Docker 环境推荐国内服务器使用bash(wget-qO- https://xuanyuan.cloud/docker.sh)该脚本特性说明完全基于 Docker 官方安装流程整理行为与官方安装一致内置国内可访问的 Docker 镜像源与软件仓库解决网络访问问题仅优化安装可达性不修改 Docker 核心配置与运行行为不包含任何 Clawdbot 相关逻辑可独立用于其他 Docker 部署场景方式二Docker 官方安装方式适用于网络可直连环境如果你的服务器可以正常访问 Docker 官方站点可直接遵循 Docker 官方文档执行安装# 以 Ubuntu 为例其他系统请参考官方文档curl-fsSL https://get.docker.com -o get-docker.shsudoshget-docker.sh官方文档地址https://docs.docker.com/engine/install/安装验证无论采用哪种方式安装完成后请执行以下命令验证docker--versiondockercompose version输出类似Docker version
26.
0, build 2ae903e与Docker Compose version v
2.
2
6即表示安装成功。
获取 Clawdbot 源码官方推荐直接从 GitHub 克隆源码gitclone https://github.com/clawdbot/clawdbot.gitcdclawdbot项目目录中已包含Dockerfiledocker-compose.yml官方基础版仅保证最小可运行.env.example这些文件是 Docker 部署的基础生产环境建议基于此扩展。
配置环境变量1️⃣ 复制环境变量模板# 测试场景cp.env.example .env# 生产场景推荐cp.env.example .env.production# 后续命令需指定 --env-file .env.production2️⃣ 环境变量模板示例.env.production.example# 基础配置 NODE_ENVproduction # 数据库配置⚠️ 生产环境必须替换为强密码 DB_PASSWORD请替换为随机强密码长度≥16位含大小写/数字/特殊符号 DATABASE_URLpostgresql://clawdbot:${DB_PASSWORD}db:5432/clawdbot # Bot / Gateway 配置 BOT_TOKEN请替换为真实的Bot Token GATEWAY_PORT3000 # 日志配置 LOG_LEVELinfo LOG_DIR/var/log/clawdbot # 其他可选配置 WORKER_CONCURRENCY43️⃣ 编辑环境变量文件根据部署场景填写配置生产环境务必修改所有默认凭证并严格限制文件权限# 生产环境文件权限加固chmod
env.production⚠️ 重要安全提示请勿使用示例中的弱密码生产环境建议使用随机生成的强密码长度≥16位包含大小写字母、数字、特殊符号.env/.env.production文件包含敏感凭证禁止将其提交到公共代码仓库企业级部署建议使用 Docker Secret 或第三方密钥管理系统替代环境变量文件
构建 Docker 镜像Clawdbot 官方 Docker 方案不使用远程镜像仓库需要在本地构建镜像。
在项目根目录执行dockerbuild -t clawdbot:latest.构建完成后可通过以下命令确认dockerimages|grepclawdbot
初始化Onboarding在首次运行前需要执行一次初始化流程创建数据库结构、基础配置等。
# 测试场景dockercompose run --rm clawdbot-cli onboard# 生产场景dockercompose --env-file .env.production run --rm clawdbot-cli onboardℹ️ 关键说明该步骤是首次部署必需的成功后会看到初始化完成的提示信息clawdbot-cli为官方docker-compose.yml中定义的管理服务用于执行初始化与维护命令onboard命令设计为幂等操作重复执行不会破坏已有数据仅会校验/补全基础配置
启动 Clawdbot 服务
1 测试场景启动快速体验dockercompose up -d
2 生产场景启动推荐配置首先创建/修改docker-compose.prod.yml补充生产级配置适配普通 Docker Compose 非 Swarm 模式version:
8services:clawdbot-gateway:image:clawdbot:latestcommand:[gateway]ports:-3000:3000env_file:.env.productionrestart:unless-stopped# 进程退出时自动重启生产必需# 健康检查配置生产必需healthcheck:# ⚠️ 以下为示例健康检查路径请根据 Clawdbot 实际提供的健康接口调整# 若官方未提供健康接口可替换为端口连通性检查[CMD, nc, -z, localhost, 3000]test:[CMD,curl,-f,http://localhost:3000/health]interval:30stimeout:10sretries:3start_period:60s# Docker Compose非 Swarm资源限制生产建议cpus:
0mem_limit:1g# 日志轮转生产建议logging:driver:json-fileoptions:max-size:100mmax-file:5volumes:-clawdbot-logs:/var/log/clawdbotclawdbot-worker:image:clawdbot:latestcommand:[worker]env_file:.env.productionrestart:unless-stoppedhealthcheck:# ⚠️ 以下为示例健康检查命令请根据 Clawdbot 实际情况调整test:[CMD,node,-e,process.exit(
]interval:30stimeout:10sretries:3# Docker Compose非 Swarm资源限制生产建议cpus:
0mem_limit:512mlogging:driver:json-fileoptions:max-size:100mmax-file:5volumes:-clawdbot-logs:/var/log/clawdbotdb:image:postgres:15-alpineenv_file:.env.productionenvironment:-POSTGRES_USERclawdbot-POSTGRES_PASSWORD${DB_PASSWORD}-POSTGRES_DBclawdbotvolumes:-clawdbot-db-data:/var/lib/postgresql/data# 数据持久化卷生产必需restart:unless-stoppedhealthcheck:test:[CMD-SHELL,pg_isready -U clawdbot -d clawdbot]interval:10stimeout:5sretries:5# Docker Compose非 Swarm资源限制生产建议cpus:
5mem_limit:512m# 生产环境禁止暴露数据库端口到宿主机# ports:# - 5432:5432volumes:clawdbot-db-data:# 数据库持久化卷核心不可随意删除clawdbot-logs:# 日志持久化卷ℹ️ 资源限制补充说明若使用 Docker Swarm 模式可替换为以下配置需删除上述 cpus/mem_limitdeploy:resources:limits:cpus:1memory:1G# ⚠️ 注意deploy.resources 仅在 Docker Swarm 模式下生效启动生产环境服务dockercompose -f docker-compose.prod.yml up -d
3 查看运行状态# 测试场景dockercomposepsdockercompose logs -f# 生产场景dockercompose -f docker-compose.prod.ymlpsdockercompose -f docker-compose.prod.yml logs -f常见服务包括clawdbot-gateway仅该服务需对外暴露clawdbot-worker内部服务禁止公网访问db数据库服务禁止公网访问
数据持久化与安全提示⚠️ 高危提示生产环境必看PostgreSQL 数据存储在名为clawdbot-db-data的 Docker Volume 中该 Volume 是数据唯一持久化载体Docker Volume ≠ 备份Volume 仅保证容器删除后数据不丢失无法应对磁盘故障、误操作等场景必须配合定期备份禁止在生产环境执行docker compose down -v-v参数会删除 Volume导致数据永久丢失如需清理容器生产环境请执行docker compose down仅删除容器保留 Volume
服务访问与防火墙配置
1 访问方式Gateway 默认监听端口3000本地访问示例http://localhost:3000服务器访问示例http://服务器IP:
3
2 防火墙/安全组配置生产必需仅放行3000端口Clawdbot Gateway禁止放行5432端口数据库建议限制3000端口的访问来源如仅允许企业内网 IP云服务器需在厂商控制台配置安全组规则物理机/虚拟机需配置iptables/firewalld
数据库备份生产必需
1
1 手动备份# 测试场景dockercomposeexecdb pg_dump -U clawdbot -d clawdbotclawdbot_backup_$(date%Y%m%d).sql# 生产场景dockercompose -f docker-compose.prod.ymlexec-T db pg_dump -U clawdbot -d clawdbotclawdbot_backup_$(date%Y%m%d_%H%M%S).sql# 备份文件权限加固chmod600clawdbot_backup_*.sql
1
2 自动备份推荐创建定时任务脚本backup_clawdbot.sh#!/bin/bash# Clawdbot 数据库自动备份脚本生产环境set-e# 配置项BACKUP_DIR/data/clawdbot/backupCOMPOSE_FILE/path/to/clawdbot/docker-compose.prod.ymlRETENTION_DAYS7# 创建备份目录mkdir-p$BACKUP_DIR# 执行备份BACKUP_FILE$BACKUP_DIR/clawdbot_backup_$(date%Y%m%d_%H%M%S).sqldockercompose -f$COMPOSE_FILEexec-T db pg_dump -U clawdbot -d clawdbot$BACKUP_FILE# 备份文件权限加固chmod600$BACKUP_FILE# 保留最近N天备份find$BACKUP_DIR-nameclawdbot_backup_*.sql-mtime $RETENTION_DAYS-delete# ⚠️ 建议将备份文件同步至对象存储OSS/S3/NAS或异地服务器# 示例aws s3 cp $BACKUP_FILE s3://clawdbot-backup/# 示例rsync -avz $BACKUP_FILE backupremote-server:/data/backup/添加到 crontab每日凌晨2点备份chmodx backup_clawdbot.shcrontab-e# 新增一行02* * * /path/to/backup_clawdbot.sh/var/log/clawdbot_backup.log21
升级与维护
1
1 更新代码cdclawdbotgitpull
1
2 重新构建镜像dockerbuild -t clawdbot:latest.
1
3 重启服务# 测试场景dockercompose downdockercompose up -d# 生产场景dockercompose -f docker-compose.prod.yml downdockercompose -f docker-compose.prod.yml up -d
1
4 升级
注意事项⚠️ 风险提示升级前必须备份数据库避免 schema 变更导致数据丢失若版本包含数据库结构变更需确认官方升级指引部分版本需执行迁移命令升级后建议先查看日志确认无报错后再对外提供服务
架构说明
1
1 测试/单机部署架构HTTP :3000内部网络SQL用户浏览器/客户端clawdbot-gateway\nWeb/API 接入层clawdbot-worker\n后台任务处理PostgreSQL\n数据持久化服务Docker Volume: clawdbot-db-data\n数据持久化载体核心特征单 Docker 网络组件间内部通信仅 Gateway 暴露端口到外部数据库数据存储在 Docker Volume 中
1
2 生产级单节点增强架构防火墙/安全组内部Docker网络SQL公网/内网clawdbot-gateway- restart策略- 健康检查- 资源限制clawdbot-worker- 无公网暴露- 资源限制PostgreSQL- Volume持久化- 定期备份- 无公网端口定时备份脚本- 权限加固- 异地存储日志卷: clawdbot-logs- 轮转策略- 权限控制核心增强全组件配置重启策略、健康检查、资源限制日志轮转持久化避免磁盘占满数据库定期备份权限加固异地存储建议Gateway 端口访问来源限制敏感文件权限严格控制
日志管理生产建议
1
1 日志持久化通过 Docker Volume 将日志挂载到宿主机已在docker-compose.prod.yml中配置便于集中管理。
1
2 日志接入企业级生产环境建议将日志接入专业日志系统ELK StackElasticsearch Logstash KibanaLoki Grafana云厂商日志服务如阿里云SLS、腾讯云CLS配置示例以 Loki 为例logging:driver:lokioptions:loki-url:http://loki:3100/loki/api/v1/pushloki-external-labels:service,envproduction
十四、
常见问题说明Q1为什么没有docker pull clawdbot/...Clawdbot 官方目前未发布官方 Docker 镜像主要原因包括配置高度定制化Token / DB / Gateway避免通用镜像导致安全误用鼓励用户自行构建、可控部署Q2可以自己发布镜像到私有仓库吗可以流程如下dockertag clawdbot:latest registry.example.com/clawdbot:latestdockerpush registry.example.com/clawdbot:latest适合企业内部部署或 CI/CD 使用。
Q3重复执行onboard命令会有风险吗不会。
onboard命令设计为幂等操作重复执行仅会校验已有配置不会删除/修改业务数据。
Q4生产环境如何进一步提升安全性使用 Docker Secret 或第三方密钥管理系统存储敏感凭证替代 .env 文件为 Gateway 配置 HTTPS通过 Nginx 反向代理限制容器的 Linux 内核能力capabilities使用非 root 用户运行容器开启 Docker 守护进程的 TLS 认证Q5Docker Volume 备份和数据库备份有什么区别Docker Volume 备份对整个数据目录打包恢复速度快但占用空间大无法单表恢复数据库逻辑备份pg_dumpSQL 文本格式占用空间小支持精细恢复是生产环境首选建议两者结合使用Volume 备份用于快速恢复逻辑备份用于精细恢复和异地容灾
十五、
总结✅ 本文基于 Clawdbot 官方基础配置补充了生产环境必需的安全、可靠、运维能力与官方配置无冲突✅ 测试部署配置简化适合功能验证无需严格资源限制✅ 单机生产部署需补充数据持久化、重启策略、健康检查、资源限制、定期备份核心⚠️ 企业级生产需在单机生产基础上扩展多节点、监控、容灾等能力本文不覆盖HA/多节点数据库❌ Docker Volume 不等于备份生产环境必须配置定期数据库备份异地存储❌ 暂无官方预构建镜像需自行构建保证配置可控如需更高级的部署方式K8s / CI/CD / 高可用可在本文单机生产配置基础上进行扩展。
关键点回顾Docker 环境安装提供两种方式国内服务器推荐一键脚本基于官方流程、优化国内访问直连环境使用官方安装方式生产环境需区分 Docker Compose 资源限制参数非 Swarm 用 cpus/mem_limitSwarm 用 deploy.resources并明确标注生效范围健康检查路径需标注为示例避免用户照抄导致容器不健康数据库备份需加固权限、建议异地存储且强调 Docker Volume ≠ 备份文档明确声明是“官方基础配置生产增强”且不覆盖HA/多节点场景。