Docker Compose 部署 OpenClaw：从单机到生产级集群的完整指南

1. 从单机到集群为什么我们需要一个生产级的 OpenClaw 部署方案如果你最近在折腾 AI 应用尤其是想自己搞一个能调用各种大模型、集成各种工具的智能体平台那“OpenClaw”这个名字你肯定不陌生。它就像一个功能强大的“AI 副驾驶”框架能帮你把 GPT、Claude、本地模型甚至各种 API 工具串联起来实现自动化工作流。很多朋友在本地用docker run或者直接跑源码体验一下基础功能就满足了。但一旦你想把它用起来比如给团队用、或者部署到服务器上长期运行马上就会遇到一堆头疼事环境依赖冲突、配置文件散落各处、服务挂了得手动重启、想加个 Redis 缓存或者数据库都得重新折腾一遍。这就是为什么我今天要跟你详细聊聊如何用Docker Compose把 OpenClaw 从一个“玩具”升级为“生产级”的分布式爬虫平台这里“爬虫”更广义地指代其自动化数据抓取与处理能力。我见过太多人卡在部署这一步不是端口冲突就是容器网络不通最后只能放弃。实际上一套好的容器化方案能让你像搭积木一样管理 OpenClaw 的各个组件实现高可用、易扩展和运维自动化。接下来我不会只给你一个干巴巴的docker-compose.yml文件而是会拆解每一个配置项背后的设计逻辑分享我在实际部署中踩过的坑和验证过的优化技巧让你真正掌握从零到一构建稳健 OpenClaw 服务集群的方法。2. 生产级部署的核心诉求与架构设计在动手写一行 Docker 配置之前我们必须先想清楚一个“生产级”的 OpenClaw 到底需要什么它和我们在笔记本上快速体验的版本有本质区别。2.1 明确生产环境的四大核心需求首先高可用性是最基本的要求。这意味着核心服务如 Web UI、API 网关、模型调度器不能有单点故障。简单跑一个容器宿主机重启或者容器崩溃服务就中断了这绝对不行。我们需要设计多副本、健康检查以及故障自动恢复机制。其次配置与数据持久化是保证服务可维护性的关键。OpenClaw 运行需要模型文件、技能插件配置、对话历史、用户数据等。这些绝不能存放在容易丢失的容器内部文件系统中。我们必须通过卷Volume或绑定挂载Bind Mount的方式将关键数据持久化到宿主机或网络存储上确保升级、重启甚至迁移容器时数据完好无损。第三可观测性与日志聚合。当服务出问题时你需要快速定位是哪个组件、哪行代码、哪个模型调用导致了异常。生产环境下日志不能再简单地输出到容器的标准输出然后被 Docker 日志驱动收集就完事了。我们需要将 OpenClaw 自身日志、模型服务日志、访问日志等统一收集、结构化存储并配合监控指标如请求延迟、错误率、GPU 显存使用率进行告警。第四安全与网络隔离。OpenClaw 可能会访问内部数据库、调用敏感 API其 Web 服务也可能暴露在公网。我们需要在容器层面做好网络规划区分前端、后端、数据库等不同网络区域并妥善管理敏感信息如 API Keys、数据库密码绝不能硬编码在镜像或配置文件里。2.2 基于 Docker Compose 的分布式架构蓝图基于以上需求我设计了一个分层、模块化的架构用 Docker Compose 来编排。这个架构的核心思想是“服务拆分”和“依赖外置”。服务拆分是指我们不把 OpenClaw 的所有功能塞进一个“巨无霸”容器。相反我们将其拆分为多个独立的服务openclaw-core: 核心服务包含 Web UI 和主要 API。这是用户交互的入口。openclaw-worker: 工作节点负责执行具体的技能Skills和模型调用。你可以根据负载水平轻松扩展多个worker实例。model-service-*: 模型服务层。例如一个服务专门跑Llama.cpp一个服务连接 OpenAI 兼容的 API如 LocalAI 或 vLLM。这样模型服务的生命周期、资源隔离和版本升级就与 OpenClaw 核心解耦了。redis: 作为缓存和消息队列Celery broker。用于存储会话状态、管理任务队列实现core与worker之间的异步通信。postgres(可选): 用于持久化存储结构化数据如用户信息、对话历史、技能配置元数据等。如果数据量不大用 SQLite 也可以但 PostgreSQL 在并发和可靠性上更胜一筹。依赖外置是指将 Redis、PostgreSQL 甚至模型文件都作为外部依赖服务或卷来管理而不是打包进 OpenClaw 镜像。这样做的好处是每个服务都可以独立升级、伸缩和备份。整个系统的数据流大致是这样的用户通过openclaw-core的 WebUI 或 API 发起请求 -core将任务发布到redis队列 - 某个空闲的openclaw-worker从队列获取任务 -worker根据任务类型调用对应的model-service或执行本地技能 - 结果写回redis或postgres-core将结果返回给用户。这个流程天然支持分布式和横向扩展。3. 手把手构建 Docker Compose 编排文件理解了架构我们现在来编写核心的docker-compose.yml文件。我会逐部分解释并给出生产环境的最佳实践配置。3.1 网络与卷定义打好基础设施的地基首先定义网络和持久化卷这是服务间通信和数据持久化的基础。version: 3.8 networks: openclaw-net: driver: bridge # 为网络指定一个自定义的子网避免与宿主机或其他Docker网络冲突 ipam: config: - subnet: 172.22.0.0/24 volumes: openclaw_data: # 使用命名卷由Docker管理存储位置适合存储应用数据 driver: local postgres_data: # 数据库数据单独存储 driver: local redis_data: # Redis数据持久化 driver: local model_cache: # 用于缓存从网上下载的模型文件避免重复下载 driver: local注意对于生产环境更推荐将postgres_data和redis_data这类关键数据卷配置为使用driver: local并指定具体路径或者直接使用 NFS、Ceph 等支持多主机访问的驱动以便于备份和迁移。简单的driver: local在单机部署时够用。3.2 核心服务配置OpenClaw Core 与 Worker接下来是 OpenClaw 自身的服务。这里有一个关键点我们需要一个基础镜像并让core和worker都基于它。services: openclaw-core: build: context: ./openclaw dockerfile: Dockerfile container_name: openclaw-core hostname: openclaw-core restart: unless-stopped ports: - 3000:3000 # WebUI 端口 - 8080:8080 # API 端口 (假设) environment: - NODE_ENVproduction - REDIS_URLredis://redis:6379/0 - DATABASE_URLpostgresql://postgres:your_secure_passwordpostgres:5432/openclaw - OPENCLAW_API_KEY${OPENCLAW_API_KEY:-} # 从环境变量文件读取 - OPENCLAW_MODEL_ENDPOINT_LLAMAhttp://model-service-llama:8080/v1 volumes: - openclaw_data:/app/data - ./config:/app/config:ro # 挂载本地配置文件ro表示只读 - ./logs/core:/app/logs networks: - openclaw-net depends_on: - redis - postgres - model-service-llama healthcheck: test: [CMD, curl, -f, http://localhost:3000/health] interval: 30s timeout: 10s retries: 3 start_period: 40s openclaw-worker: build: context: ./openclaw dockerfile: Dockerfile container_name: openclaw-worker-1 hostname: openclaw-worker-1 restart: unless-stopped environment: - NODE_ENVproduction - ROLEworker - REDIS_URLredis://redis:6379/0 - DATABASE_URLpostgresql://postgres:your_secure_passwordpostgres:5432/openclaw volumes: - openclaw_data:/app/data - ./config:/app/config:ro - ./logs/worker:/app/logs networks: - openclaw-net depends_on: - redis - postgres deploy: replicas: 2 # 使用Docker Swarm模式时可以指定副本数普通compose运行时此字段无效但表达了扩展意图。 # 普通compose下想启动多个worker可以将其定义复制一份并修改container_name和hostname或者使用scale命令。关键配置解读与避坑指南build上下文我假设你的项目根目录下有一个./openclaw文件夹里面包含了 OpenClaw 的源码和Dockerfile。这样编排文件更清晰。环境变量ROLE这是我在Dockerfile或 OpenClaw 启动脚本中会读取的一个变量用于决定容器是启动coreWeb服务还是worker后台任务处理。这是一种常见的多角色镜像模式。depends_on它只控制启动顺序不保证依赖服务已“就绪”。这就是为什么我们需要healthcheck。上面为openclaw-core配置了健康检查只有当它自己能通过/health端点返回成功时Docker 才认为它是健康的。其他服务如 Postgres, Redis也应该配置健康检查这样depends_on结合健康检查才能真正实现“等待就绪”。端口暴露只将必要的端口如 WebUI 的 3000映射到宿主机。API端口8080可以考虑不映射而是通过反向代理如 Nginx来访问增加安全性。敏感信息管理像DATABASE_URL中的密码、OPENCLAW_API_KEY绝对不要写死在docker-compose.yml里。示例中使用了${OPENCLAW_API_KEY:-}语法它会尝试从名为.env的环境变量文件中读取。你需要在项目根目录创建.env文件并确保它被.gitignore排除内容如下OPENCLAW_API_KEYyour_super_secret_api_key_here POSTGRES_PASSWORDyour_secure_password然后在docker-compose.yml中引用DATABASE_URLpostgresql://postgres:${POSTGRES_PASSWORD}postgres:5432/openclaw。3.3 依赖服务配置数据库、缓存与模型服务现在配置外围的支撑服务。postgres: image: postgres:15-alpine container_name: openclaw-postgres restart: unless-stopped environment: POSTGRES_DB: openclaw POSTGRES_USER: postgres POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro # 初始化脚本 networks: - openclaw-net healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: openclaw-redis restart: unless-stopped command: redis-server --appendonly yes # 开启AOF持久化 volumes: - redis_data:/data networks: - openclaw-net healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 model-service-llama: image: ghcr.io/ggerganov/llama.cpp:server-latest container_name: openclaw-llama-server restart: unless-stopped ports: - 8081:8080 # 将容器内8080映射到宿主机的8081避免与openclaw-core的API端口冲突 environment: - MODEL/models/llama-2-7b.gguf - N_GPU_LAYERS20 # 根据你的GPU调整 - CONTEXT_SIZE4096 volumes: - model_cache:/models # 假设模型文件已预先下载到宿主机的某个目录并挂载到/model_cache再软链接或复制到/models - ./models:/models:ro # 另一种方式直接挂载宿主机的模型目录 networks: - openclaw-net deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] # 申请GPU资源需要nvidia-container-toolkit关键配置解读与避坑指南PostgreSQL 初始化通过./init.sql挂载你可以在数据库首次启动时自动创建表、索引或初始化数据。这对于确保应用所需的数据库结构就绪非常有用。Redis 持久化--appendonly yes开启了 AOF 持久化即使容器重启只要数据卷 (redis_data) 还在数据就不会丢失。对于任务队列这种场景这很重要可以避免任务丢失。模型服务这里以llama.cpp的 server 镜像为例。这是最容易出问题的地方。首先模型文件 (llama-2-7b.gguf) 需要你提前准备好。我强烈建议在宿主机上维护一个统一的模型存储目录然后通过卷挂载给不同的模型服务容器使用避免每个容器都下载一遍浪费磁盘空间和网络带宽。GPU 支持如果你想让模型服务使用 GPU需要在宿主机上安装nvidia-container-toolkit并在docker-compose.yml中像上面那样配置deploy.resources。同时llama.cpp服务器的镜像可能需要支持 CUDA 的版本注意选择正确的镜像标签。端口规划模型服务的端口映射到宿主机一个非标准端口如 8081主要是为了调试方便。在生产中这些内部服务模型服务、Redis、Postgres的端口不应该直接暴露给宿主机只应在openclaw-net这个自定义网络内互通。这样可以减少攻击面。外部访问只通过openclaw-core的 WebUI 或 API 网关。4. 编写 OpenClaw 的 Dockerfile 与配置Docker Compose 定义了服务关系但每个服务具体怎么构建取决于Dockerfile。下面是一个 OpenClaw 多角色镜像的Dockerfile示例它可以根据环境变量启动不同的进程。# ./openclaw/Dockerfile FROM node:18-slim AS builder WORKDIR /app # 复制依赖定义文件 COPY package*.json ./ COPY yarn.lock ./ # 安装依赖包括devDependencies用于构建 RUN yarn install --frozen-lockfile # 复制源码并构建 COPY . . RUN yarn build # 生产运行阶段 FROM node:18-slim AS runner WORKDIR /app ENV NODE_ENVproduction # 安装仅运行时需要的依赖 COPY package*.json ./ COPY yarn.lock ./ RUN yarn install --frozen-lockfile --production # 从构建阶段复制构建产物和必要的文件 COPY --frombuilder /app/dist ./dist COPY --frombuilder /app/node_modules ./node_modules # 复制配置文件模板、启动脚本等 COPY docker-entrypoint.sh ./ COPY config/config.production.example.json ./config/ # 创建非root用户运行增强安全性 RUN addgroup --system --gid 1001 openclaw \ adduser --system --uid 1001 openclaw USER openclaw # 声明数据卷方便持久化 VOLUME [/app/data, /app/logs] # 使用入口点脚本根据环境变量决定启动模式 ENTRYPOINT [./docker-entrypoint.sh]对应的入口点脚本docker-entrypoint.sh#!/bin/sh set -e # 根据 ROLE 环境变量启动不同的进程 if [ $ROLE worker ]; then echo Starting OpenClaw worker... exec node dist/worker.js else # 默认为 core 角色 echo Starting OpenClaw core (webapi)... # 可以在这里运行数据库迁移等前置操作 # node dist/migrate.js exec node dist/server.js fi关键配置解读与避坑指南多阶段构建使用builder阶段安装所有依赖并构建在runner阶段只复制运行所需的最小文件集。这可以显著减小最终镜像的体积提高安全性因为构建工具不会留在生产镜像中。非 Root 用户使用USER openclaw指令让容器以非 root 用户运行这是一个重要的安全最佳实践可以限制容器被入侵后的影响范围。配置管理将配置文件如config.production.example.json复制到镜像中。在容器启动时可以通过环境变量或挂载外部配置文件的方式来覆盖它。更灵活的做法是在docker-compose.yml中完全通过volumes挂载一个外部的config目录这样修改配置无需重建镜像。数据卷声明VOLUME指令声明了/app/data和/app/logs为卷。这有两个作用一是文档化告诉使用者这些路径用于存储持久化数据二是即使运行时不指定-v挂载Docker 也会自动创建匿名卷防止数据丢失在可写层虽然生产环境一定要显式挂载命名卷。5. 部署、运维与故障排查实战有了编排文件和镜像我们就可以部署了。但部署只是开始运维才是重头戏。5.1 一键启动与日常操作在包含docker-compose.yml的目录下执行以下命令# 1. 构建镜像并启动所有服务后台运行 docker-compose up -d --build # 2. 查看所有容器状态 docker-compose ps # 3. 查看特定服务的日志实时跟踪 docker-compose logs -f openclaw-core # 4. 进入某个容器的shell用于调试 docker-compose exec openclaw-core /bin/sh # 5. 停止所有服务 docker-compose down # 6. 停止服务并删除数据卷危险会丢失所有数据 # docker-compose down -v # 7. 重启某个服务例如修改了worker的配置后 docker-compose restart openclaw-worker # 8. 扩展worker实例数量假设你在compose文件中定义了worker服务 docker-compose up -d --scale openclaw-worker35.2 生产环境必须考虑的进阶配置资源限制在docker-compose.yml中为每个服务添加deploy.resources.limits防止某个容器耗尽宿主机资源。services: openclaw-core: # ... deploy: resources: limits: cpus: 1.0 memory: 1G日志驱动与收集默认的json-file日志驱动可能不够。可以配置为journald如果宿主机用 systemd或syslog。更好的做法是使用Fluentd、Loki等日志收集器。可以在docker-compose.yml全局或服务级配置logging: driver: json-file options: max-size: 10m max-file: 3使用反向代理不要将 OpenClaw 的端口直接暴露给公网。使用 Nginx 或 Traefik 作为反向代理可以提供 HTTPS、负载均衡、访问控制、速率限制等能力。这通常需要在 Docker Compose 中添加一个nginx或traefik服务。备份策略定期备份postgres_data和openclaw_data卷。可以使用docker run --volumes-from临时容器来执行备份命令或者直接备份宿主机上 Docker 管理的卷目录通常位于/var/lib/docker/volumes/。5.3 常见故障排查链路当你遇到问题比如 OpenClaw WebUI 打不开可以按照以下链路排查检查容器状态docker-compose ps。确认所有服务的状态都是Up。如果有Exit或Restarting进入下一步。查看错误日志docker-compose logs [service-name]。这是最重要的信息源。常见错误数据库连接失败检查DATABASE_URL环境变量、PostgreSQL 容器是否健康、网络是否互通docker-compose exec openclaw-core ping postgres。Redis 连接失败类似数据库检查REDIS_URL和 Redis 容器状态。模型服务连接失败检查OPENCLAW_MODEL_ENDPOINT_LLAMA的 URL 和端口是否正确模型服务容器是否健康模型文件路径是否存在。端口冲突检查宿主机端口3000 8080等是否已被其他程序占用。检查网络docker network inspect openclaw_openclaw-net网络名通常是项目名_网络名。确认所有服务都在同一个网络中并且有正确的 IP 地址。进入容器内部调试docker-compose exec openclaw-core /bin/sh。在容器内尝试执行curl http://redis:6379或curl http://postgres:5432虽然不能直接 curl 数据库但可以测通断验证服务间通信。检查卷挂载docker inspect openclaw-core查看Mounts部分确认数据卷是否正确挂载权限是否正确尤其是以非 root 用户运行时挂载的宿主机目录需要有相应权限。一个我踩过的具体坑是OpenClaw Worker 一直报错无法从 Redis 获取任务。日志显示连接 Redis 超时。排查后发现在docker-compose.yml中Worker 服务依赖了 Redis但 Redis 容器虽然启动了其服务却未完全就绪加载 AOF 文件较慢。depends_on只保证了启动顺序没保证就绪状态。解决方案为 Redis 服务添加了上面提到的healthcheck并在 Worker 服务的启动命令或应用代码中增加对 Redis 连接的重试逻辑问题得以解决。6. 从 Compose 走向更高阶的编排Docker Compose 非常适合单机部署和小型生产环境。当你的 OpenClaw 平台需要面对更高并发、要求真正的多节点高可用时就需要考虑更强大的编排工具比如Kubernetes (K8s)。将现有的 Docker Compose 配置迁移到 K8s 是一个自然的演进路径。你可以将每个service转换为一个 K8sDeployment用于无状态服务如openclaw-core,openclaw-worker或StatefulSet用于有状态服务如postgres,redis。docker-compose.yml中的networks对应 K8s 的Service和Ingressvolumes对应PersistentVolumeClaim(PVC)。在 K8s 中你可以轻松实现自动扩缩容根据 CPU/内存使用率或自定义指标如任务队列长度自动增加或减少openclaw-worker的 Pod 数量。滚动更新与回滚无缝更新 OpenClaw 版本如果出现问题可以一键回滚到上一个稳定版本。更精细的资源管理与调度将 GPU 密集型任务模型服务调度到带有 GPU 的节点将 IO 密集型任务调度到 SSD 存储节点。强大的服务发现与负载均衡无需手动管理 IP 和端口。虽然 K8s 的学习曲线更陡峭但它为 OpenClaw 这类分布式应用提供了企业级的运维能力。如果你的业务在增长提前规划容器编排的演进路线是很有价值的。你可以先从 Docker Compose 稳定运行开始同时将 K8s 的 manifest 文件如deployment.yaml,service.yaml作为另一个版本的部署描述符来维护为未来平滑过渡做好准备。