ClawdBot企业级部署教程：Docker Compose集群化配置+健康检查+日志监控

ClawdBot 是一个面向个人与中小团队的本地化 AI 助手平台，它不依赖云端 API，所有推理、对话、文件处理均在你自己的设备上完成。它的核心价值不是“大而全”，而是“稳、快、可控”——你可以把它理解成一个装进 Docker 里的「AI操作系统」：有统一网关、可插拔模型、多通道接入能力，以及真正属于你的数据主权。

但要注意，ClawdBot 本身不是模型，也不是一个开箱即用的聊天机器人 App。它是一个运行时框架，后端靠 vLLM 提供高性能文本推理能力，前端提供 Web 控制台和 CLI 工具，中间通过标准化协议连接各类模型、工具与渠道。换句话说，ClawdBot 是那个帮你把 Qwen3、Phi-4、Llama-3.2 这些模型“管起来、用起来、查得清”的调度中枢。

而 MoltBot，则是另一个完全独立、但理念高度契合的项目：一个为 Telegram 场景深度优化的多模态翻译机器人。它不追求通用对话能力，只专注一件事——让群聊消息、语音、图片，在毫秒级内完成跨语言流转，并顺手解决查天气、换汇率、搜维基这些高频小需求。它用的是 LibreTranslate + Google Translate 双引擎 fallback、Whisper tiny 本地语音转写、PaddleOCR 轻量图文识别，全部打包进一个 300MB 的镜像，树莓派 4 都能扛住 15 人并发。MIT 协议、零配置、5 分钟上线——这是真正把“开箱即用”刻进 DNA 的工程实践。

这两者看似无关，实则共享同一套底层哲学：AI 应用不该被黑盒 API 绑架，而应像 Linux 服务一样可观察、可编排、可审计。 本教程不讲“怎么跑通第一个 demo”，而是带你从运维视角出发，把 ClawdBot 搭建成一个具备生产就绪（Production-Ready）能力的企业级服务：用 Docker Compose 编排集群、用健康检查保障可用性、用日志管道实现可观测性——让你的本地 AI 助手，真正拥有服务器级别的可靠感。

1. 环境准备与基础架构设计

在开始写 docker-compose.yml 之前，先明确我们要构建的不是一个单体容器，而是一个协同工作的服务集群。ClawdBot 的典型生产部署包含三个核心角色：

  • Gateway（网关层）：接收所有外部请求（Web UI、CLI、Telegram Bot、API 调用），做路由、鉴权、限流、日志打标；
  • vLLM Engine（推理引擎）：运行 Qwen3-4B-Instruct 等模型，提供 OpenAI 兼容的 /v1/chat/completions 接口；
  • Dashboard & CLI（控制平面）：提供 Web 管理界面和命令行工具，用于模型管理、配置热更新、设备授权等。

它们之间不是松散调用，而是通过明确的服务发现、健康探针和结构化日志串联起来。下面这张图概括了整个数据流向：

[用户] 
   ↓ (HTTP/WS)
[ClawdBot Gateway] ←→ [ClawdBot Dashboard/UI]
   ↓ (HTTP, load-balanced)
[vLLM Engine] ←→ [模型权重文件]
   ↓ (stdout/stderr)
[Log Aggregator]

我们不使用 Kubernetes，因为对中小团队而言，Docker Compose 已足够表达服务依赖、资源约束与网络拓扑，且调试成本更低。关键是要写出可读、可维护、可复现的编排文件，而不是堆砌参数。

1.1 系统要求与前置条件

ClawdBot 对硬件的要求不高，但对软件环境有明确依赖：

  • 操作系统：Linux（推荐 Ubuntu 22.04+/Debian 12+），macOS 和 Windows WSL2 也可用，但生产环境强烈建议原生 Linux；
  • Docker：≥ 24.0.0，需启用 BuildKit（默认已开启）；
  • Docker Compose：≥ v2.20.0（注意不是旧版 docker-compose v1）；
  • 内存：Qwen3-4B-Instruct 推理约需 6–8 GB 显存（FP16）或 4–5 GB 内存（AWQ 量化）；若无 GPU，vLLM 可回退至 CPU 模式（性能下降，但可用）；
  • 存储：模型缓存目录建议挂载到 SSD，避免频繁 IO 影响响应延迟；
  • ❌ 不支持：Docker Desktop for Mac/Windows 的默认虚拟机磁盘（空间小、IO 慢），请务必使用 --mount type=bind 映射宿主机路径。

小贴士：别急着拉镜像。ClawdBot 官方未提供预编译镜像，你需要自己构建。这不是缺陷，而是设计选择——它确保你完全掌控二进制来源、依赖版本与安全补丁。

1.2 目录结构规划（清晰比炫技更重要）

一个健壮的部署，始于干净的目录组织。请在宿主机创建如下结构：

clawdbot-prod/
├── docker-compose.yml          # 主编排文件（本文核心）
├── .env                        # 环境变量（token、端口、模型路径等）
├── gateway/
│   ├── config.yaml             # Gateway 配置（覆盖默认值）
│   └── Dockerfile              # 自定义构建（如加 Nginx 前置、HTTPS 终止）
├── vllm/
│   ├── Dockerfile              # 基于官方 vLLM 构建，预装 Qwen3-4B 权重
│   └── models/                 # 模型文件夹（软链或 COPY）
├── dashboard/
│   └── Dockerfile              # 基于 clawdbot/cli 镜像，暴露 Web UI
└── logs/                       # 所有容器日志统一落盘（供后续采集）

这个结构的好处是：配置、代码、数据物理隔离；升级某一层（比如只换 vLLM 引擎）无需动其他部分；日志集中管理，方便对接 Filebeat 或 Loki。

2. Docker Compose 集群化配置详解

下面这份 docker-compose.yml 不是“能跑就行”的玩具配置，而是按生产标准设计的最小可行集群。每一行都有其存在理由，我们逐段拆解。

# docker-compose.yml
version: '3.8'

services:
  # ——————————————————————————————
  # 1. Gateway 服务：统一入口，带健康检查与优雅退出
  # ——————————————————————————————
  gateway:
    build: ./gateway
    image: clawdbot/gateway:prod-2026.1
    restart: unless-stopped
    ports:
      - "18780:18780"   # 主 WebSocket 端口（CLI / 设备连接）
      - "7860:7860"     # Web UI 端口（Dashboard）
      - "8000:8000"     # HTTP API 端口（供 vLLM Engine 调用）
    environment:
      - CLAWDBOT_ENV=production
      - CLAWDBOT_LOG_LEVEL=info
      - VLLM_ENGINE_URL=http://vllm:8000/v1
    volumes:
      - ./logs/gateway:/app/logs
      - ~/.clawdbot:/root/.clawdbot:rw
    networks:
      - clawdbot-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3

  # ——————————————————————————————
  # 2. vLLM Engine 服务：高性能推理，带模型预热与负载感知
  # ——————————————————————————————
  vllm:
    build: ./vllm
    image: clawdbot/vllm:qwen3-4b-2026.1
    restart: unless-stopped
    expose:
      - "8000"
    environment:
      - VLLM_MODEL=vllm/Qwen3-4B-Instruct-2507
      - VLLM_TENSOR_PARALLEL_SIZE=1
      - VLLM_ENABLE_PREFIX_CACHING=true
      - VLLM_MAX_NUM_SEQS=256
      - VLLM_TRUST_REMOTE_CODE=true
    volumes:
      - ./vllm/models:/models:ro
      - ./logs/vllm:/var/log/vllm
    networks:
      - clawdbot-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 20s
      timeout: 3s
      retries: 5
      start_period: 120s  # 模型加载耗时长，给足时间
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
        limits:
          memory: 8G
      restart_policy:
        condition: on-failure

  # ——————————————————————————————
  # 3. Dashboard 服务：轻量 Web 控制台，与 Gateway 共享配置
  # ——————————————————————————————
  dashboard:
    build: ./dashboard
    image: clawdbot/dashboard:prod-2026.1
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - DASHBOARD_GATEWAY_URL=http://gateway:18780
      - DASHBOARD_API_TOKEN=${DASHBOARD_TOKEN:-dev-token}
    volumes:
      - ~/.clawdbot:/root/.clawdbot:rw
      - ./logs/dashboard:/app/logs
    networks:
      - clawdbot-net
    depends_on:
      gateway:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 45s

networks:
  clawdbot-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

volumes:
  clawdbot-data:

2.1 关键设计点解析

  • healthcheck 不是摆设：每个服务都定义了真实可用的健康端点（/health）。Gateway 检查 vLLM 是否 ready，Dashboard 检查 Gateway 是否在线。Docker 会据此决定是否将流量路由过去，或触发重启。没有健康检查的集群，等于没有心跳。

  • depends_on + condition: service_healthy：这句至关重要。它确保 dashboard 容器只在 gateway 通过健康检查后才启动，避免 Dashboard 启动时连不上网关，报一堆 Connection refused 错误。这是实现“启动即可用”的基石。

  • GPU 资源显式声明：vllm 服务中 deploy.resources.reservations.devices 明确申请一块 NVIDIA GPU。Docker 会自动将其映射进容器，vLLM 启动时就能识别 cuda:0。不写这一行，即使宿主机有 GPU，容器里也看不到。

  • 日志路径统一归集：所有服务都将日志输出到容器内固定路径（如 /app/logs），再通过 volumes 挂载到宿主机 ./logs/ 下。这样你不用 docker logs -f 逐个看，直接 tail -f ./logs/*/app.log 就能全局观测。

  • restart: unless-stopped + restart_policy：双保险。前者保证容器意外退出后自动拉起；后者在 Swarm 模式下生效（虽本例未用 Swarm，但保留兼容性）。on-failure 表示只在非 0 退出码时重启，避免程序逻辑错误导致无限重启。

3. 健康检查与故障自愈机制

ClawdBot 的健康检查不是简单的端口探测，而是深入到业务语义层。我们来还原一次真实的故障恢复流程：

3.1 健康检查如何工作？

ClawdBot Gateway 内置 /health 端点，它不只是返回 {"status": "ok"}，而是执行三项同步检查：

  1. 自身服务状态：Event Loop 是否卡死、内存使用率是否超阈值（>90%）；
  2. 下游 vLLM 连通性：向 http://vllm:8000/health 发起 GET 请求，验证模型加载完成、API 可调用；
  3. 配置文件完整性：校验 ~/.clawdbot/clawdbot.json 是否 JSON 有效、关键字段是否存在。

只有三项全通过，才返回 HTTP 200；任一失败，返回 503，并在响应体中说明原因（如 "vllm_unreachable"）。Docker 的 healthcheck 正是依赖这个语义化响应。

3.2 模拟一次 GPU 内存溢出故障

假设你在 vLLM 中误配了 max_num_seqs=1024，导致推理时 OOM，vLLM 进程崩溃：

  1. Docker 检测到 vllm 容器退出（exit code ≠ 0）；
  2. 触发 restart_policy，10 秒后重新启动容器；
  3. 新容器启动，开始加载 Qwen3-4B 模型（耗时约 90 秒）；
  4. 加载完成后，vLLM 启动 /health 端点，返回 {"model": "Qwen3-4B-Instruct-2507", "status": "ready"}；
  5. Gateway 的健康检查探针（每 20 秒一次）捕获到该响应，自身 /health 也恢复 200；
  6. Dashboard 检测到 Gateway 健康，自动重连 WebSocket，UI 上显示 “Connected”；
  7. 整个过程无需人工干预，用户最多感知到 2–3 分钟的短暂不可用。

对比传统做法：如果你只是 docker run -d 单个容器，vLLM 崩溃后 Gateway 会持续报错 Gateway not reachable，直到你手动 docker restart。而 Compose 集群让系统拥有了“免疫系统”。

3.3 如何自定义健康检查行为？

你可以在 gateway/config.yaml 中覆盖默认健康策略：

health:
  checks:
    vllm:
      url: http://vllm:8000/health
      timeout: 5000  # 毫秒
      interval: 15000
      failure_threshold: 2
      success_threshold: 1
    disk:
      path: /app/workspace
      min_free_gb: 5

这段配置让 Gateway 在检查 vLLM 外，还监控 /app/workspace 目录剩余空间。当低于 5GB 时，自身健康状态降为 degraded，Dashboard UI 会显示黄色警告图标，但服务仍可用——这是比“非黑即白”更务实的设计。

4. 日志监控与可观测性落地

日志不是“出了问题才去看”，而是系统运行的“生命体征”。ClawdBot 的日志设计遵循三个原则：结构化、可检索、低侵入。

4.1 日志格式标准化

ClawdBot 所有组件（Gateway、vLLM Adapter、Dashboard）默认输出 JSON 格式日志，例如：

{
  "time": "2026-01-25T09:32:14.882Z",
  "level": "info",
  "service": "gateway",
  "event": "request_received",
  "method": "POST",
  "path": "/v1/chat/completions",
  "client_ip": "172.20.0.4",
  "duration_ms": 1248.3,
  "status_code": 200,
  "model_id": "vllm/Qwen3-4B-Instruct-2507"
}

这种格式天然适配 ELK（Elasticsearch + Logstash + Kibana）或 Loki + Grafana。你不需要额外解析，直接按 level、service、duration_ms、status_code 过滤即可。

4.2 本地日志聚合方案（零外部依赖）

如果你不想搭整套 ELK，可以用最简方式实现日志监控：

  1. 安装 lnav（终端日志分析器）：

    # Ubuntu/Debian
sudo apt install lnav

  2. 创建日志视图配置 .lnav/format/clawdbot.json：

    {
  "clawdbot-json": {
    "title": "ClawdBot JSON",
    "description": "ClawdBot structured JSON logs",
    "regex": "^(?P<timestamp>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z) (?P<level>\\w+) (?P<service>\\w+) (?P<event>\\w+)",
    "highlight": [
      { "pattern": "\"level\":\"error\"", "color": "red" },
      { "pattern": "\"duration_ms\":([2-9]\\d{3,}|[1-9]\\d{4,})", "color": "yellow" }
    ]
  }
}

  3. 实时观测所有服务日志：

    # 在 clawdbot-prod/ 目录下执行
lnav ./logs/**/app.log

你会看到彩色高亮的日志流：红色标出 error，黄色标出耗时 >2s 的慢请求。按 :filter /error 可快速定位异常，按 :filter /duration_ms > 3000 查找性能瓶颈。

4.3 关键监控指标建议（Dashboard 必看）

在 Web UI 的 Monitoring 页面（或你自建的 Grafana），重点关注以下 5 个指标：

指标名 说明 健康阈值 数据来源
gateway_request_rate_total 每分钟请求数 ≥ 5（空闲期） Prometheus Exporter
gateway_request_duration_seconds P95 响应延迟 < 2.0s Gateway /metrics
vllm_gpu_utilization GPU 利用率 40%–85%（太低浪费，太高过热） vLLM /metrics
vllm_cache_hit_ratio KV Cache 命中率 > 70%（低则提示 prompt 设计差） vLLM /metrics
clawdbot_device_count 已授权设备数 与实际用户数匹配 Gateway 内存状态

为什么不是看 CPU/Memory？ 因为对于 AI 服务，GPU 利用率、Cache 命中率、推理延迟才是真正的性能瓶颈。CPU 和内存只是基础保障，它们告警往往意味着架构设计已出问题。

5. 模型热切换与配置动态更新

ClawdBot 最强大的能力之一，是不重启服务即可更换模型、调整参数、增删渠道。这背后依赖其配置热重载机制。

5.1 两种配置更新方式对比

方式 触发时机 是否需要 CLI 是否影响在线服务 适用场景
修改 ~/.clawdbot/clawdbot.json + clawdbot config reload 手动执行命令 是 ❌ 否（平滑过渡） 生产环境首选，可控、可审计
Web UI 修改 → 点击 “Save & Apply” 界面操作 ❌ 否 ❌ 否 开发调试、快速验证

两者最终都写入同一份 JSON 文件，并触发 Gateway 的配置监听器。监听器会对比新旧配置的 diff，只重载变更的部分（如只重启 Telegram channel，不中断 Web UI）。

5.2 安全的模型切换实操

假设你想把当前的 Qwen3-4B-Instruct-2507 换成 Phi-4，步骤如下：

  1. 下载 Phi-4 模型到 vLLM 目录：

    cd ./vllm/models
huggingface-cli download microsoft/Phi-4 --local-dir phi-4 --revision main

  2. 更新 clawdbot.json 中的模型配置：

    "models": {
  "mode": "merge",
  "providers": {
    "vllm": {
      "baseUrl": "http://vllm:8000/v1",
      "apiKey": "sk-local",
      "models": [
        {
          "id": "Phi-4",
          "name": "Phi-4"
        }
      ]
    }
  }
}

  3. 执行热重载：

    clawdbot config reload
# 输出： Config reloaded. Models updated: Qwen3-4B-Instruct-2507 → Phi-4

  4. 验证新模型可用：

    clawdbot models list
# 输出中应包含：vllm/Phi-4

整个过程耗时 < 3 秒，已有对话不受影响。这才是企业级 AI 平台应有的敏捷性。

6. 总结：从玩具到生产的关键跨越

部署 ClawdBot，从来不是“运行一个命令就完事”。它是一次对本地 AI 基础设施的重新思考：我们不再满足于“能用”，而是追求“可信、可观、可控”。

  • 可信，体现在 Docker Compose 的健康检查与自动重启策略上——系统能自我诊断、自我修复，把 MTTR（平均修复时间）压缩到分钟级；
  • 可观，体现在结构化日志与关键指标监控上——你不再靠 docker logs 猜问题，而是用 lnav 或 Grafana 看趋势、定根因；
  • 可控，体现在配置热更新与模型热切换上——业务迭代不再需要停服，AI 能力升级如同更新一个 App 插件。

这正是 ClawdBot 区别于其他“一键脚本”的本质：它不提供幻觉般的“全自动”，而是给你一套清晰、透明、可干预的控制平面。你始终是系统的主人，而非 API 的租客。

所以，别再问“ClawdBot 能不能替代 ChatGPT”——它压根不是来比谁更会聊天的。它是为你搭建私有 AI 能力底座的脚手架，是让 Qwen、Phi、Llama 这些顶尖模型，真正成为你团队生产力一部分的那块关键拼图。

现在，打开你的终端，cd 进 clawdbot-prod 目录，执行 docker compose up -d。几秒钟后，访问 http://localhost:8080，输入 token，看着 Dashboard 上绿色的 “All Services Healthy” 状态灯亮起——那一刻，你拥有的不再是一个玩具，而是一个真正属于你的、可信赖的 AI 基础设施。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

# AI助手
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区