OpenClaw 部署技术文档

1.1 技术栈

• Web Server Nginx (Alpine)
• Application OpenClaw (ghcr.io/openclaw/openclaw)
• Container Docker Compose
• SSL Let's Encrypt (Certbot)
• Auth Basic Auth + Gateway Token

1.2 网络架构

用户浏览器
    ↓ HTTPS (443) / HTTP (80)
Nginx 反向代理 (docker: nginx)
    ↓ Basic Auth 验证
    ↓ WebSocket Upgrade
OpenClaw Gateway (docker: openclaw:18789)
    ↓
OpenClaw Control UI (SPA)

1.3 容器配置

2.1 核心配置文件

# /home/www/bibook_deploy/services/nginx/conf.d/openclaw.conf

server {
    listen 443 ssl;
    server_name openclaw.bibook.top;

    # --- SSL 证书配置 ---
    ssl_certificate /etc/nginx/ssl/live/bibook.top/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/live/bibook.top/privkey.pem;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
                ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:
                ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_session_tickets off;

    # --- Basic Auth 认证 ---
    auth_basic "OpenClaw Protected";
    auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

    # --- WebSocket 反向代理 ---
    location / {
        proxy_pass http://openclaw:18789;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        
        # 真实 IP 获取
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 超时设置
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

2.2 技术要点说明

• WebSocket 支持：使用 proxy_http_version 1.1 和 Upgrade/Connection 头部
• 超时优化：读写超时设置为 300s，防止长连接断开
• SSL 硬化：禁用弱加密算法，优先使用 ECDHE
• Basic Auth：在 nginx 层面添加第一道防护

2.3 密码文件生成

# 生成 Apache MD5 哈希密码
openssl passwd -apr1 密码

# 输出: $apr1$p5QtGH3G$60P2p8IfpBE5tCMY1cuI8/

# 创建密码文件
echo "用户名:\$apr1\$p5QtGH3G\$60P2p8IfpBE5tCMY1cuI8/" > .htpasswd

3.1 完整配置

# /home/www/bibook_deploy/docker-compose.yml

openclaw:
  image: ghcr.io/openclaw/openclaw
  container_name: ${PROJECT_NAME}-openclaw-${PROJECT_TAG}
  restart: unless-stopped
  ports:
    - "3000:3000"      # Dashboard UI
    - "18789:18789"    # WebSocket Gateway
  environment:
    - OPENCLAW_AUTH_ENABLED=false
    - NODE_ENV=production
    - HOST=0.0.0.0
    - PORT=18789
    - BIND_ADDRESS=0.0.0.0
    - OPENCLAW_HOST=0.0.0.0
    # Gateway Token（用于认证）
    - OPENCLAW_GATEWAY_TOKEN=e8c47a4d81fa897a9a52baa98a486b3cac328285e9316dc7
    # 允许的 Origin（CORS）
    - OPENCLAW_CONTROL_UI_ALLOWED_ORIGINS=https://openclaw.bibook.top,http://openclaw.bibook.top
    # 信任的代理（用于获取真实 IP）
    - OPENCLAW_GATEWAY_TRUSTED_PROXIES=172.18.0.2,172.18.0.1
  volumes:
    - ./storage/openclaw/data:/home/node/.openclaw
    - ./storage/logs/openclaw:/var/log/openclaw
  networks:
    - app-network
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
    interval: 30s
    timeout: 10s
    retries: 5
    start_period: 60s
  deploy:
    resources:
      limits:
        memory: 1.5G      # 内存上限
        cpus: '1.5'       # CPU 上限
      reservations:
        memory: 512M       # 内存预留
        cpus: '0.5'       # CPU 预留

3.2 环境变量详解

3.3 配置文件 (~/.openclaw/openclaw.json)

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "https://openclaw.bibook.top",
        "http://openclaw.bibook.top",
        "https://admin.bibook.top",
        "http://admin.bibook.top",
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ],
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "e8c47a4d81fa897a9a52baa98a486b3cac328285e9316dc7"
    }
  }
}

4.1 双层认证机制

第一层：Nginx Basic Auth
    用户名：******
    密码：******
    保护：所有 HTTP/HTTPS 请求

第二层：OpenClaw Gateway Token
    Token：e8c47a4d81fa897a9a52baa98a486b3cac328285e9316dc7
    保护：WebSocket 连接

4.2 认证流程

1. 用户访问 https://openclaw.bibook.top
2. Nginx 验证 Basic Auth 用户名密码
3. 前端页面加载，从 localStorage 读取 token
4. 建立 WebSocket 连接，在查询参数中传递 token
5. OpenClaw Gateway 验证 token，允许连接

4.3 Token 注入方式

<!-- 启动页面：/start -->
<script>
const token = "e8c47a4d81fa897a9a52baa98a486b3cac328285e9316dc7";
localStorage.setItem("openclaw-gateway-token", token);
window.location.href = "/?";
</script>

<!-- WebSocket 连接 -->
const ws = new WebSocket('wss://openclaw.bibook.top/?token=...');

5.1 Certbot 配置

certbot:
  image: certbot/certbot
  container_name: ${PROJECT_NAME}-certbot-${PROJECT_TAG}
  restart: "no"
  entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait \$${!}; done;'"
  volumes:
    - ./services/nginx/ssl:/etc/letsencrypt
    - ./services/nginx/certbot-www:/var/www/certbot

5.2 自动续期机制

• Certbot 每 12 小时检查一次证书续期
• 证书有效期 90 天，自动在到期前 30 天续期
• Nginx 不需要重启，证书更新后自动生效

5.3 申请证书命令

cd /home/www/bibook_deploy
docker compose run --rm certbot certonly --webroot \
  --webroot-path /var/www/certbot \
  -d www.bibook.top -d bibook.top -d admin.bibook.top \
  -d openclaw.bibook.top -d p1.bibook.top -d p3.bibook.top \
  -d bot.bibook.top -d book.bibook.top \
  --email admin@bibook.top --agree-tos --no-eff-email

6.1 资源限制优化

6.2 服务器配置

硬件配置：
- CPU: 4 核
- 内存: 3.6GB
- 磁盘: 40GB (已用 52%)
- 系统负载: 0.03-0.13 (很低)

Docker 版本：27.5.1
存储驱动：overlay2
运行时间：50 天+

6.3 优化建议

• ✅ 使用 Alpine 镜像减小镜像体积
• ✅ 配置合理的内存/CPU 限制
• ✅ 启用容器健康检查
• ✅ 使用 overlay2 存储驱动
• ⚠️ 文件描述符限制建议提升到 65535+

7.1 WebSocket 连接断开

7.2 访问问题

问题：401 Unauthorized
原因：Basic Auth 验证失败
解决：检查用户名密码是否正确

问题：502 Bad Gateway  
原因：OpenClaw 容器未运行
解决：docker ps 检查容器状态

问题：证书警告
原因：SSL 证书即将过期
解决：等待自动续期或手动运行 certbot renew

7.3 日志查看

# 查看 Nginx 日志
docker logs bibook-nginx-prod --tail 100

# 查看 OpenClaw 日志
docker logs bibook-openclaw-prod --tail 100

# 查看容器资源使用
docker stats --no-stream

7.4 重启服务

# 重启单个服务
docker compose restart openclaw

# 重启所有服务
docker compose restart

# 重新创建容器（应用新配置）
docker compose up -d

# 查看 Compose 日志
docker compose logs -f

8.1 访问信息

8.2 认证凭据

8.3 配置文件位置

Docker Compose: /home/www/bibook_deploy/docker-compose.yml
Nginx 配置: /home/www/bibook_deploy/services/nginx/conf.d/openclaw.conf
密码文件: /home/www/bibook_deploy/services/nginx/conf.d/.htpasswd
SSL 证书: /home/www/bibook_deploy/services/nginx/ssl/live/bibook.top/
OpenClaw 配置: /home/www/bibook_deploy/storage/openclaw/data/openclaw.json
日志目录: /home/www/bibook_deploy/storage/logs/