09. Docker 部署指南#

课程信息

难度等级：🔴 高级

阅读时间：30 分钟

前置知识：了解 Docker 基础概念、已完成快速开始（03-快速开始指南）

本篇你将学会： 用 Docker 部署 OpenClaw 到服务器、配置 docker-compose、管理数据持久化、设置自动更新

谁需要看这篇？ 如果你只是在自己电脑上用，不需要看这篇。这篇是给想把 OpenClaw 部署到远程服务器（比如云服务器）的人准备的

为什么用 Docker 部署 OpenClaw？#

官方文档：docs.openclaw.ai/install/docker

Docker 部署的优势#

什么时候不需要 Docker#

经验法则：本地开发用原生安装，远程部署用 Docker。

Docker 基础环境准备#

安装 Docker#

Linux（推荐 Ubuntu 22.04+）#

macOS#

Windows#

# 方法一：Docker Desktop（推荐）
# 从 https://www.docker.com/products/docker-desktop/ 下载安装
# 需要开启 WSL2 或 Hyper-V

# 方法二：winget
winget install Docker.DockerDesktop

# 安装后重启，验证
docker --version
docker compose version

系统要求#

验证 Docker 环境#

注意：本文全部使用 docker compose（v2 语法），不是 docker-compose（v1 已弃用）。

官方 Docker 镜像使用#

拉取官方镜像#

从仓库 Dockerfile 构建镜像#

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

镜像标签说明#

快速启动单容器#

docker-compose 完整配置详解#

基础版：只跑 Gateway#

进阶版：Gateway + 数据库 + Redis#

启动和管理#

环境变量配置大全#

.env 文件模板#

环境变量优先级#

敏感信息处理#

数据持久化（Volumes 配置）#

为什么需要 Volumes#

关键数据目录#

Named Volumes vs Bind Mounts#

查看和管理 Volumes#

网络配置#

端口映射#

安全提示：生产环境建议绑定 127.0.0.1，通过反向代理暴露服务，不要直接把端口开放到公网。只有 Gateway（18789）需要对外暴露，其他端口仅在需要时映射。

反向代理 Forwarded Headers 安全提示（v2026.4.x+）：OpenClaw 现在会检查转发头（X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto）的一致性。即使请求通过 loopback 到达，如果携带了指向非本地来源的转发头，Gateway 会将该请求视为远程请求，不再享有 loopback 本地信任。反向代理必须覆盖（而非追加）来自客户端的转发头。如果使用 trusted-proxy 认证模式，需要在 gateway.trustedProxies 中配置代理 IP，且不能使用 loopback 地址。详见 10-安全配置指南。

Docker 网络模式#

容器间通信#

连接宿主机服务#

生产环境部署最佳实践#

Nginx 反向代理配置#

SSL/TLS 证书配置#

# /etc/caddy/Caddyfile
openclaw.yourdomain.com {
    reverse_proxy 127.0.0.1:18789
}

日志管理#

Docker 日志驱动配置#

查看和分析日志#

集中式日志（生产推荐）#

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

健康检查#

云平台部署#

AWS 部署#

EC2 + Docker Compose#

AWS ECS（容器服务）#

GCP 部署#

Cloud Run（Serverless）#

GCE（虚拟机）#

Azure 部署#

Azure Container Instances#

阿里云部署#

ECS + Docker#

VPS 部署（Hetzner / Vultr / DigitalOcean）#

远程访问方案#

Agent 沙箱（Docker 隔离）#

沙箱模式#

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        // "non-main" — 非主会话在 Docker 沙箱中运行（推荐）
        // "all"      — 所有会话都在沙箱中运行
        // "off"      — 关闭沙箱
        "mode": "non-main",
        "image": "openclaw:sandbox"
      }
    }
  }
}

沙箱镜像类型#

构建沙箱镜像#

Podman Rootless 替代方案#

详细的 Podman 部署文档见 docs.openclaw.ai/install/podman。

自动更新和 CI/CD#

Watchtower 自动更新#

GitHub Actions CI/CD#

手动更新流程#

性能调优和资源限制#

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

容器资源限制#

Docker 守护进程优化#

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "storage-driver": "overlay2",
  "default-ulimits": {
    "nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 }
  }
}

监控资源使用#

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

备份和恢复#

全量备份脚本#

恢复流程#

定时备份（Cron）#

常见 Docker 问题排查#

镜像构建失败#

容器无法启动#

端口冲突#

权限问题#

内存不足（OOM Killed）#

网络连接问题#

数据卷挂载问题#

Docker Compose 版本问题#

快速参考卡片#

常用命令速查#

部署方案对比#

下一步#