使用 Docker 部署 Clawdbot（官方推荐方式）

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_ENV=production，但测试部署与生产部署的配置要求差异显著，请务必根据实际场景选择对应配置策略。

一、部署模式说明

ℹ️ 说明：本文不覆盖 Clawdbot 多节点高可用（HA）、分布式数据库部署场景，如需此类方案需在单机生产配置基础上另行设计。

二、环境准备

为降低部署门槛、提升成功率，本文提供官方等价的一键安装脚本与官方原生安装方式两种选择，你可根据服务器网络环境适配：

方式一：一键安装 Docker 环境（推荐国内服务器使用）

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

该脚本特性说明：

方式二：Docker 官方安装方式（适用于网络可直连环境）

如果你的服务器可以正常访问 Docker 官方站点，可直接遵循 Docker 官方文档执行安装：

# 以 Ubuntu 为例，其他系统请参考官方文档
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

官方文档地址：https://docs.docker.com/engine/install/

安装验证

无论采用哪种方式，安装完成后请执行以下命令验证：

docker –version
docker compose version

输出类似 Docker version 26.0.0, build 2ae903e 与 Docker Compose version v2.24.6 即表示安装成功。

三、获取 Clawdbot 源码

官方推荐直接从 GitHub 克隆源码：

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

项目目录中已包含：

• Dockerfile
• docker-compose.yml（官方基础版，仅保证最小可运行）
• .env.example

这些文件是 Docker 部署的基础，生产环境建议基于此扩展。

四、配置环境变量

1️⃣ 复制环境变量模板

# 测试场景
cp .env.example .env

# 生产场景（推荐）
cp .env.example .env.production
# 后续命令需指定 –env-file .env.production

2️⃣ 环境变量模板示例（.env.production.example）

# 基础配置
NODE_ENV=production

# 数据库配置（⚠️ 生产环境必须替换为强密码）
DB_PASSWORD=请替换为随机强密码（长度≥16位，含大小写/数字/特殊符号）
DATABASE_URL=postgresql://clawdbot:${DB_PASSWORD}@db:5432/clawdbot

# Bot / Gateway 配置
BOT_TOKEN=请替换为真实的Bot Token
GATEWAY_PORT=3000

# 日志配置
LOG_LEVEL=info
LOG_DIR=/var/log/clawdbot

# 其他可选配置
WORKER_CONCURRENCY=4

3️⃣ 编辑环境变量文件

根据部署场景填写配置，生产环境务必修改所有默认凭证，并严格限制文件权限：

# 生产环境文件权限加固
chmod 600 .env.production

⚠️ 重要安全提示：

五、构建 Docker 镜像

Clawdbot 官方 Docker 方案 不使用远程镜像仓库，需要在本地构建镜像。

在项目根目录执行：

docker build -t clawdbot:latest .

构建完成后可通过以下命令确认：

docker images | grep clawdbot

六、初始化（Onboarding）

在首次运行前，需要执行一次初始化流程（创建数据库结构、基础配置等）。

# 测试场景
docker compose run –rm clawdbot-cli onboard

# 生产场景
docker compose –env-file .env.production run –rm clawdbot-cli onboard

ℹ️ 关键说明：

七、启动 Clawdbot 服务

7.1 测试场景启动（快速体验）

docker compose up -d

7.2 生产场景启动（推荐配置）

首先创建/修改 docker-compose.prod.yml，补充生产级配置（适配普通 Docker Compose 非 Swarm 模式）：

version: '3.8'

services:
clawdbot-gateway:
image: clawdbot:latest
command: ["gateway"]
ports:
– "3000:3000"
env_file: .env.production
restart: unless–stopped # 进程退出时自动重启（生产必需）
# 健康检查配置（生产必需）
healthcheck:
# ⚠️ 以下为示例健康检查路径，请根据 Clawdbot 实际提供的健康接口调整
# 若官方未提供健康接口，可替换为端口连通性检查：["CMD", "nc", "-z", "localhost", "3000"]
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
# Docker Compose（非 Swarm）资源限制（生产建议）
cpus: "1.0"
mem_limit: 1g
# 日志轮转（生产建议）
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "5"
volumes:
– clawdbot–logs:/var/log/clawdbot

clawdbot-worker:
image: clawdbot:latest
command: ["worker"]
env_file: .env.production
restart: unless–stopped
healthcheck:
# ⚠️ 以下为示例健康检查命令，请根据 Clawdbot 实际情况调整
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
# Docker Compose（非 Swarm）资源限制（生产建议）
cpus: "1.0"
mem_limit: 512m
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "5"
volumes:
– clawdbot–logs:/var/log/clawdbot

db:
image: postgres:15–alpine
env_file: .env.production
environment:
– POSTGRES_USER=clawdbot
– POSTGRES_PASSWORD=${DB_PASSWORD}
– POSTGRES_DB=clawdbot
volumes:
– clawdbot–db–data:/var/lib/postgresql/data # 数据持久化卷（生产必需）
restart: unless–stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U clawdbot -d clawdbot"]
interval: 10s
timeout: 5s
retries: 5
# Docker Compose（非 Swarm）资源限制（生产建议）
cpus: "0.5"
mem_limit: 512m
# 生产环境禁止暴露数据库端口到宿主机
# ports:
# – "5432:5432"

volumes:
clawdbot-db-data: # 数据库持久化卷（核心，不可随意删除）
clawdbot-logs: # 日志持久化卷

ℹ️ 资源限制补充说明：
若使用 Docker Swarm 模式，可替换为以下配置（需删除上述 cpus/mem_limit）：

deploy:
resources:
limits:
cpus: '1'
memory: 1G
# ⚠️ 注意：deploy.resources 仅在 Docker Swarm 模式下生效

启动生产环境服务：

docker compose -f docker-compose.prod.yml up -d

7.3 查看运行状态

# 测试场景
docker compose ps
docker compose logs -f

# 生产场景
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f

常见服务包括：

• clawdbot-gateway（仅该服务需对外暴露）
• clawdbot-worker（内部服务，禁止公网访问）
• db（数据库服务，禁止公网访问）

八、数据持久化与安全提示

⚠️ 高危提示（生产环境必看）：

九、服务访问与防火墙配置

9.1 访问方式

• Gateway 默认监听端口：3000
• 本地访问示例：http://localhost:3000
• 服务器访问示例：http://<服务器IP>:3000

9.2 防火墙/安全组配置（生产必需）

十、数据库备份（生产必需）

10.1 手动备份

# 测试场景
docker compose exec db pg_dump -U clawdbot -d clawdbot > clawdbot_backup_$(date +%Y%m%d).sql

# 生产场景
docker compose -f docker-compose.prod.yml exec -T db pg_dump -U clawdbot -d clawdbot > clawdbot_backup_$(date +%Y%m%d_%H%M%S).sql
# 备份文件权限加固
chmod 600 clawdbot_backup_*.sql

10.2 自动备份（推荐）

创建定时任务脚本 backup_clawdbot.sh：

#!/bin/bash
# Clawdbot 数据库自动备份脚本（生产环境）
set -e

# 配置项
BACKUP_DIR="/data/clawdbot/backup"
COMPOSE_FILE="/path/to/clawdbot/docker-compose.prod.yml"
RETENTION_DAYS=7

# 创建备份目录
mkdir -p $BACKUP_DIR

# 执行备份
BACKUP_FILE="$BACKUP_DIR/clawdbot_backup_$(date +%Y%m%d_%H%M%S).sql"
docker compose -f $COMPOSE_FILE exec -T db pg_dump -U clawdbot -d clawdbot > $BACKUP_FILE

# 备份文件权限加固
chmod 600 $BACKUP_FILE

# 保留最近N天备份
find $BACKUP_DIR -name "clawdbot_backup_*.sql" -mtime +$RETENTION_DAYS -delete

# ⚠️ 建议：将备份文件同步至对象存储（OSS/S3/NAS）或异地服务器
# 示例：aws s3 cp $BACKUP_FILE s3://clawdbot-backup/
# 示例：rsync -avz $BACKUP_FILE backup@remote-server:/data/backup/

添加到 crontab（每日凌晨2点备份）：

chmod +x backup_clawdbot.sh
crontab -e
# 新增一行
0 2 * * * /path/to/backup_clawdbot.sh >> /var/log/clawdbot_backup.log 2>&1

十一、升级与维护

11.1 更新代码

cd clawdbot
git pull

11.2 重新构建镜像

docker build -t clawdbot:latest .

11.3 重启服务

# 测试场景
docker compose down
docker compose up -d

# 生产场景
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

11.4 升级注意事项

⚠️ 风险提示：

十二、架构说明

12.1 测试/单机部署架构

#mermaid-svg-efbSbnh6C7N2Hdbt{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-efbSbnh6C7N2Hdbt .error-icon{fill:#552222;}#mermaid-svg-efbSbnh6C7N2Hdbt .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-efbSbnh6C7N2Hdbt .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-efbSbnh6C7N2Hdbt .marker{fill:#333333;stroke:#333333;}#mermaid-svg-efbSbnh6C7N2Hdbt .marker.cross{stroke:#333333;}#mermaid-svg-efbSbnh6C7N2Hdbt svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-efbSbnh6C7N2Hdbt p{margin:0;}#mermaid-svg-efbSbnh6C7N2Hdbt .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster-label text{fill:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster-label span{color:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster-label span p{background-color:transparent;}#mermaid-svg-efbSbnh6C7N2Hdbt .label text,#mermaid-svg-efbSbnh6C7N2Hdbt span{fill:#333;color:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt .node rect,#mermaid-svg-efbSbnh6C7N2Hdbt .node circle,#mermaid-svg-efbSbnh6C7N2Hdbt .node ellipse,#mermaid-svg-efbSbnh6C7N2Hdbt .node polygon,#mermaid-svg-efbSbnh6C7N2Hdbt .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-efbSbnh6C7N2Hdbt .rough-node .label text,#mermaid-svg-efbSbnh6C7N2Hdbt .node .label text,#mermaid-svg-efbSbnh6C7N2Hdbt .image-shape .label,#mermaid-svg-efbSbnh6C7N2Hdbt .icon-shape .label{text-anchor:middle;}#mermaid-svg-efbSbnh6C7N2Hdbt .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-efbSbnh6C7N2Hdbt .rough-node .label,#mermaid-svg-efbSbnh6C7N2Hdbt .node .label,#mermaid-svg-efbSbnh6C7N2Hdbt .image-shape .label,#mermaid-svg-efbSbnh6C7N2Hdbt .icon-shape .label{text-align:center;}#mermaid-svg-efbSbnh6C7N2Hdbt .node.clickable{cursor:pointer;}#mermaid-svg-efbSbnh6C7N2Hdbt .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-efbSbnh6C7N2Hdbt .arrowheadPath{fill:#333333;}#mermaid-svg-efbSbnh6C7N2Hdbt .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-efbSbnh6C7N2Hdbt .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-efbSbnh6C7N2Hdbt .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-efbSbnh6C7N2Hdbt .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-efbSbnh6C7N2Hdbt .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-efbSbnh6C7N2Hdbt .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster text{fill:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt .cluster span{color:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-efbSbnh6C7N2Hdbt .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-efbSbnh6C7N2Hdbt rect.text{fill:none;stroke-width:0;}#mermaid-svg-efbSbnh6C7N2Hdbt .icon-shape,#mermaid-svg-efbSbnh6C7N2Hdbt .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-efbSbnh6C7N2Hdbt .icon-shape p,#mermaid-svg-efbSbnh6C7N2Hdbt .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-efbSbnh6C7N2Hdbt .icon-shape rect,#mermaid-svg-efbSbnh6C7N2Hdbt .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-efbSbnh6C7N2Hdbt .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-efbSbnh6C7N2Hdbt .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-efbSbnh6C7N2Hdbt :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

HTTP :3000

内部网络

SQL

用户浏览器/客户端

clawdbot-gateway\\nWeb/API 接入层

clawdbot-worker\\n后台任务处理

PostgreSQL\\n数据持久化服务

Docker Volume: clawdbot-db-data\\n数据持久化载体

核心特征：

• 单 Docker 网络，组件间内部通信
• 仅 Gateway 暴露端口到外部
• 数据库数据存储在 Docker Volume 中

12.2 生产级单节点增强架构

#mermaid-svg-XF14EU1NRxSNQenu{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XF14EU1NRxSNQenu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XF14EU1NRxSNQenu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XF14EU1NRxSNQenu .error-icon{fill:#552222;}#mermaid-svg-XF14EU1NRxSNQenu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XF14EU1NRxSNQenu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XF14EU1NRxSNQenu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XF14EU1NRxSNQenu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XF14EU1NRxSNQenu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XF14EU1NRxSNQenu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XF14EU1NRxSNQenu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XF14EU1NRxSNQenu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XF14EU1NRxSNQenu .marker.cross{stroke:#333333;}#mermaid-svg-XF14EU1NRxSNQenu svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XF14EU1NRxSNQenu p{margin:0;}#mermaid-svg-XF14EU1NRxSNQenu .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-XF14EU1NRxSNQenu .cluster-label text{fill:#333;}#mermaid-svg-XF14EU1NRxSNQenu .cluster-label span{color:#333;}#mermaid-svg-XF14EU1NRxSNQenu .cluster-label span p{background-color:transparent;}#mermaid-svg-XF14EU1NRxSNQenu .label text,#mermaid-svg-XF14EU1NRxSNQenu span{fill:#333;color:#333;}#mermaid-svg-XF14EU1NRxSNQenu .node rect,#mermaid-svg-XF14EU1NRxSNQenu .node circle,#mermaid-svg-XF14EU1NRxSNQenu .node ellipse,#mermaid-svg-XF14EU1NRxSNQenu .node polygon,#mermaid-svg-XF14EU1NRxSNQenu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XF14EU1NRxSNQenu .rough-node .label text,#mermaid-svg-XF14EU1NRxSNQenu .node .label text,#mermaid-svg-XF14EU1NRxSNQenu .image-shape .label,#mermaid-svg-XF14EU1NRxSNQenu .icon-shape .label{text-anchor:middle;}#mermaid-svg-XF14EU1NRxSNQenu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XF14EU1NRxSNQenu .rough-node .label,#mermaid-svg-XF14EU1NRxSNQenu .node .label,#mermaid-svg-XF14EU1NRxSNQenu .image-shape .label,#mermaid-svg-XF14EU1NRxSNQenu .icon-shape .label{text-align:center;}#mermaid-svg-XF14EU1NRxSNQenu .node.clickable{cursor:pointer;}#mermaid-svg-XF14EU1NRxSNQenu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XF14EU1NRxSNQenu .arrowheadPath{fill:#333333;}#mermaid-svg-XF14EU1NRxSNQenu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XF14EU1NRxSNQenu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XF14EU1NRxSNQenu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XF14EU1NRxSNQenu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XF14EU1NRxSNQenu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XF14EU1NRxSNQenu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XF14EU1NRxSNQenu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XF14EU1NRxSNQenu .cluster text{fill:#333;}#mermaid-svg-XF14EU1NRxSNQenu .cluster span{color:#333;}#mermaid-svg-XF14EU1NRxSNQenu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XF14EU1NRxSNQenu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XF14EU1NRxSNQenu rect.text{fill:none;stroke-width:0;}#mermaid-svg-XF14EU1NRxSNQenu .icon-shape,#mermaid-svg-XF14EU1NRxSNQenu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XF14EU1NRxSNQenu .icon-shape p,#mermaid-svg-XF14EU1NRxSNQenu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XF14EU1NRxSNQenu .icon-shape rect,#mermaid-svg-XF14EU1NRxSNQenu .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XF14EU1NRxSNQenu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XF14EU1NRxSNQenu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XF14EU1NRxSNQenu :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

防火墙/安全组

内部Docker网络

SQL

公网/内网

clawdbot-gateway- restart策略- 健康检查- 资源限制

clawdbot-worker- 无公网暴露- 资源限制

PostgreSQL- Volume持久化- 定期备份- 无公网端口

定时备份脚本- 权限加固- 异地存储

日志卷: clawdbot-logs- 轮转策略- 权限控制

核心增强：

• 全组件配置重启策略、健康检查、资源限制
• 日志轮转+持久化，避免磁盘占满
• 数据库定期备份+权限加固+异地存储建议
• Gateway 端口访问来源限制
• 敏感文件权限严格控制

十三、日志管理（生产建议）

13.1 日志持久化

通过 Docker Volume 将日志挂载到宿主机（已在 docker-compose.prod.yml 中配置），便于集中管理。

13.2 日志接入（企业级）

生产环境建议将日志接入专业日志系统：

• ELK Stack（Elasticsearch + Logstash + Kibana）
• Loki + Grafana
• 云厂商日志服务（如阿里云SLS、腾讯云CLS）

配置示例（以 Loki 为例）：

logging:
driver: "loki"
options:
loki-url: "http://loki:3100/loki/api/v1/push"
loki-external-labels: "service={{.Name}},env=production"

十四、常见问题说明

Q1：为什么没有 docker pull clawdbot/…？

Clawdbot 官方目前 未发布官方 Docker 镜像，主要原因包括：

• 配置高度定制化（Token / DB / Gateway）
• 避免通用镜像导致安全误用
• 鼓励用户自行构建、可控部署

Q2：可以自己发布镜像到私有仓库吗？

可以，流程如下：

docker tag clawdbot:latest registry.example.com/clawdbot:latest
docker push registry.example.com/clawdbot:latest

适合企业内部部署或 CI/CD 使用。

Q3：重复执行 onboard 命令会有风险吗？

不会。onboard 命令设计为幂等操作，重复执行仅会校验已有配置，不会删除/修改业务数据。

Q4：生产环境如何进一步提升安全性？

Q5：Docker Volume 备份和数据库备份有什么区别？

• Docker Volume 备份：对整个数据目录打包，恢复速度快，但占用空间大，无法单表恢复
• 数据库逻辑备份（pg_dump）：SQL 文本格式，占用空间小，支持精细恢复，是生产环境首选
• 建议：两者结合使用，Volume 备份用于快速恢复，逻辑备份用于精细恢复和异地容灾

十五、总结

• ✅ 本文基于 Clawdbot 官方基础配置，补充了生产环境必需的安全、可靠、运维能力，与官方配置无冲突
• ✅ 测试部署：配置简化，适合功能验证，无需严格资源限制
• ✅ 单机生产部署：需补充数据持久化、重启策略、健康检查、资源限制、定期备份（核心）
• ⚠️ 企业级生产：需在单机生产基础上扩展多节点、监控、容灾等能力（本文不覆盖HA/多节点数据库）
• ❌ Docker Volume 不等于备份，生产环境必须配置定期数据库备份+异地存储
• ❌ 暂无官方预构建镜像，需自行构建保证配置可控

如需更高级的部署方式（K8s / CI/CD / 高可用），可在本文单机生产配置基础上进行扩展。

关键点回顾