Docker Hub 预构建镜像配置指南
本文档说明如何设置 GitHub Actions 自动构建和推送预构建的 Docker 镜像到 Docker Hub。
前置要求
- Docker Hub 账户 - 注册地址
- GitHub 仓库 - 需要有 GitHub 账户和仓库权限
- 访问令牌 - 在 Docker Hub 和 GitHub 上分别创建
步骤 1：在 Docker Hub 创建账户和仓库
- 访问 Docker Hub
- 注册或登录账户
- 创建新的公开仓库，命名为
openclaw-cn- 描述：
Openclaw 中文版 - 私有化部署的 AI 智能助手 - 访问权限：Public
- 描述：
步骤 2：生成 Docker Hub 访问令牌
- 登录 Docker Hub
- 进入 Account Settings → Security → Access Tokens
- 点击 New Access Token
- 输入名称：
openclaw-cn-github-actions - 权限选择：
Read, Write和Delete - 点击 Generate
- 复制生成的令牌（仅显示一次）
步骤 3：添加 GitHub Secrets
- 进入 GitHub 仓库
- 进入 Settings → Secrets and variables → Actions
- 点击 New repository secret，创建以下两个 secrets：
Secret 1: DOCKERHUB_USERNAME
- 名称：
DOCKERHUB_USERNAME - 值：
jiulingyun803
Secret 2: DOCKERHUB_TOKEN
- 名称：
DOCKERHUB_TOKEN - 值：在步骤 2 生成的访问令牌
步骤 4：验证 GitHub Actions Workflow
- 进入 GitHub 仓库的 Actions 标签页
- 找到 Build and Push Multi-Architecture Docker Images workflow
- 确认 workflow 已启用
- 当你推送代码或发布新版本标签时，workflow 会自动触发
镜像标签说明
GitHub Actions 会自动为构建的镜像打上以下标签：
| 触发条件 | 镜像标签 | 示例 |
|---|---|---|
推送到 main 分支 | latest | jiulingyun803/openclaw-cn:latest |
| 推送版本标签 | 版本号 | jiulingyun803/openclaw-cn:v2026.1.31 |
| 推送分支提交 | 分支-SHA | jiulingyun803/openclaw-cn:main-abc1234 |
| 拉取请求 | 不推送到 Docker Hub | （本地构建测试） |
使用预构建的镜像
方法 1：使用 Docker Compose
编辑 .env 文件：
bash
OPENCLAW_IMAGE=jiulingyun803/openclaw-cn:latest然后运行：
bash
docker compose up -d openclaw-cn-gateway方法 2：直接使用 Docker 运行
bash
docker run -d \
--name openclaw-gateway \
-p 18789:18789 \
-v ~/.openclaw:/home/node/.openclaw \
-v ~/clawd:/home/node/clawd \
jiulingyun803/openclaw-cn:latest \
node dist/index.js gateway --bind 0.0.0.0 --port 18789方法 3：使用改进的 docker-setup.sh
bash
export OPENCLAW_IMAGE="jiulingyun803/openclaw-cn:latest"
./docker-setup.sh支持的架构
预构建镜像支持以下架构：
- linux/amd64 - Intel/AMD 64位处理器（大多数服务器和现代电脑）
- linux/arm64 - ARM 64位处理器（Apple Silicon Mac、树莓派 4/5、华为云鲲鹏等）
Docker 会自动选择匹配的镜像版本。
构建时间和存储
- 首次构建：约 10-20 分钟（两个架构并行）
- 缓存构建：约 2-5 分钟（使用 GitHub Actions 缓存）
- 镜像大小：约 500-600 MB（包含完整构建环境和生产依赖）
故障排查
问题 1：Workflow 失败显示 "unauthorized"
解决方案：
- 检查 GitHub Secrets 中的用户名和令牌是否正确
- 在 Docker Hub 重新生成令牌（旧令牌可能已过期）
- 确保令牌具有
Read, Write, Delete权限
问题 2：推送到 Docker Hub 失败
解决方案：
- 检查 Docker Hub 仓库是否已创建且为公开
- 确保仓库名称为
openclaw-cn（workflow 中硬编码） - 查看 GitHub Actions 的完整日志以获取详细错误信息
问题 3：ARM64 架构构建超时
解决方案：
- 增加 GitHub Actions 的超时时间（目前为默认值）
- 优化 Dockerfile 以加快构建速度
- 考虑分别为 amd64 和 arm64 运行构建（取消并行构建）
自动更新工作流
镜像将在以下情况自动构建和推送：
- 推送到 main 分支 → 构建
latest标签 - 发布新版本标签 → 构建版本号标签（如
v2026.1.31） - 手动触发 → 通过 GitHub Actions UI 的 "Run workflow" 按钮
后续改进
- [ ] 配置镜像扫描和漏洞检测
- [ ] 添加 Docker Hub 自动更新描述和 README
- [ ] 配置镜像签名和验证
- [ ] 添加体积优化和最小化基础镜像
- [ ] 配置多个镜像标签策略（stable, beta, dev）