OpenClaw零停机更新与滚动升级

前言

在生产环境中升级 OpenClaw，最大的风险就是服务中断。用户正在进行的对话可能被打断，Webhook 回调可能丢失消息。本文将介绍几种零停机或最小停机时间的升级方案，帮助你在不影响用户体验的情况下完成版本更新。

一、升级前准备

1.1 检查当前版本和目标版本

# 查看当前运行版本
openclaw version

# 查看可用的最新版本
openclaw update check

# 输出示例
# 当前版本: 1.2.0
# 最新版本: 1.3.0
# 更新类型: 功能更新 (minor)
# 变更日志: https://openclaw.com/changelog/1.3.0

1.2 阅读变更日志

在升级前务必阅读目标版本的变更日志，特别关注：

Breaking Changes：是否有不兼容的配置格式变更
数据库迁移：是否需要迁移数据格式
依赖变更：是否需要更新 Node.js 版本或其他依赖
新增配置项：是否有需要手动添加的新配置

# 查看版本间的变更摘要
openclaw update changelog --from 1.2.0 --to 1.3.0

1.3 创建升级前备份

# 完整备份（必须步骤）
openclaw backup create --output /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz

# 验证备份完整性
openclaw backup verify /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz

1.4 在测试环境验证

# 在测试环境先行升级和验证
OPENCLAW_ENV=staging openclaw update --to 1.3.0
OPENCLAW_ENV=staging openclaw doctor

二、PM2 零停机重载

如果使用 PM2 管理 OpenClaw，可以利用 PM2 的 reload 功能实现零停机更新。

2.1 基本流程

# 步骤1：升级 OpenClaw 包
npm install -g [email protected]

# 步骤2：使用 PM2 reload（零停机重载）
pm2 reload openclaw

# 步骤3：验证新版本
openclaw version
curl -s http://localhost:18789/health | jq '.version'

2.2 PM2 reload vs restart 的区别

操作	停机时间	原理
`pm2 restart`	约 5-15 秒	先停止旧进程，再启动新进程
`pm2 reload`	接近 0	先启动新进程，等待就绪后再停止旧进程

2.3 配置优雅重载

为了让 PM2 reload 正常工作，需要配置优雅关闭：

// openclaw-ecosystem.config.js
module.exports = {
  apps: [{
    name: "openclaw",
    script: "openclaw",
    args: "up",
    // 优雅关闭等待时间（毫秒）
    kill_timeout: 15000,
    // 新进程就绪等待时间
    listen_timeout: 20000,
    // 等待就绪信号
    wait_ready: true,
    // 重载时最大内存
    max_memory_restart: "512M"
  }]
};

OpenClaw 在启动完成并通过健康检查后会发送就绪信号，PM2 收到信号后才会停止旧进程。

2.4 监控重载过程

# 实时观察重载过程
pm2 logs openclaw --lines 20

# 查看进程状态变化
watch -n 1 pm2 status

三、Systemd 优雅重启

3.1 使用 ExecReload

在 Systemd 服务文件中配置重载命令：

# /etc/systemd/system/openclaw.service
[Service]
ExecStart=/usr/local/bin/openclaw up
ExecReload=/bin/kill -SIGUSR2 $MAINPID
ExecStop=/bin/kill -SIGTERM $MAINPID

# 优雅关闭超时
TimeoutStopSec=30

Restart=always
RestartSec=5

# 升级流程
npm install -g [email protected]
sudo systemctl daemon-reload
sudo systemctl reload openclaw

# 如果 reload 不支持，使用 restart
sudo systemctl restart openclaw

3.2 Systemd 的停机时间

Systemd 的 restart 会有短暂停机。如果需要零停机，建议使用双实例方案或搭配 Nginx。

四、蓝绿部署方案

蓝绿部署是实现真正零停机的经典方案，同时运行新旧两个版本，通过流量切换完成升级。

4.1 架构说明

用户请求 → Nginx → ┬─ Blue (旧版本 v1.2.0)  端口 18789
                    └─ Green (新版本 v1.3.0) 端口 18790

4.2 部署步骤

# 步骤1：当前生产环境（Blue）在端口 18789 运行
# 确认当前状态
curl -s http://localhost:18789/health

# 步骤2：在新端口启动新版本（Green）
OPENCLAW_PORT=18790 openclaw up -d --name openclaw-green --config ~/.config/openclaw/openclaw.production.json5

# 步骤3：等待 Green 环境就绪
sleep 20
curl -s http://localhost:18790/health

# 步骤4：验证 Green 环境功能正常
openclaw doctor --port 18790

# 步骤5：切换 Nginx 流量到 Green

修改 Nginx 配置将流量指向新端口：

upstream openclaw_backend {
    # 切换前：指向 Blue
    # server 127.0.0.1:18789;
    # 切换后：指向 Green
    server 127.0.0.1:18790;
}

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://openclaw_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 重载 Nginx 配置（零停机）
sudo nginx -t && sudo nginx -s reload

# 步骤6：确认流量已切换
curl -s https://openclaw.yourdomain.com/health | jq '.version'
# 应返回 "1.3.0"

# 步骤7：停止旧版本（Blue）
openclaw stop --name openclaw-blue

4.3 快速回滚

如果新版本出现问题，只需将 Nginx 切换回旧端口：

# 修改 Nginx upstream 指向旧版本端口
# server 127.0.0.1:18789;
sudo nginx -s reload

五、Docker 滚动升级

5.1 使用 Docker Compose

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:1.3.0
    deploy:
      update_config:
        parallelism: 1
        delay: 30s
        order: start-first    # 先启动新容器，再停止旧容器
        failure_action: rollback
      rollback_config:
        parallelism: 1
        delay: 10s
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:18789/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/root/.openclaw
    restart: always

# 拉取新镜像并滚动更新
docker compose pull
docker compose up -d

# Docker Compose 会：
# 1. 启动新容器
# 2. 等待健康检查通过
# 3. 停止旧容器

5.2 Docker Swarm 滚动升级

# 更新服务镜像
docker service update --image openclaw/openclaw:1.3.0 openclaw

# 监控升级进度
docker service ps openclaw --format "table {{.ID}}\t{{.Image}}\t{{.CurrentState}}"

六、数据迁移处理

6.1 自动迁移

OpenClaw 在版本升级时会自动检测并执行必要的数据迁移：

# 启动时自动迁移
openclaw up
# [INFO] 检测到数据格式需要迁移: v1.2 → v1.3
# [INFO] 正在备份当前数据...
# [INFO] 执行迁移: migrate_sessions_v1.3
# [INFO] 迁移完成，共处理 156 条会话记录

6.2 手动迁移

如果自动迁移失败，可以手动执行：

# 查看待执行的迁移
openclaw migrate status

# 执行迁移
openclaw migrate run

# 回滚迁移
openclaw migrate rollback --to 1.2.0

七、升级检查清单

每次升级前，按照以下检查清单执行：

升级检查清单：v1.2.0 → v1.3.0
================================
□ 阅读变更日志，确认无 Breaking Changes
□ 创建完整备份
□ 在测试环境验证新版本
□ 确认测试环境频道连接正常
□ 确认测试环境消息收发正常
□ 确认测试环境技能执行正常
□ 通知团队升级计划和时间窗口
□ 选择流量最低的时段执行升级
□ 执行升级
□ 验证生产环境健康检查通过
□ 验证所有频道已重新连接
□ 发送测试消息确认功能正常
□ 监控 30 分钟确认无异常
□ 升级完成，记录升级日志

八、回滚方案

8.1 快速回滚

# 方案一：PM2 环境降级
npm install -g [email protected]
pm2 reload openclaw

# 方案二：从备份恢复
openclaw stop
openclaw backup restore /backup/openclaw-pre-upgrade-20260314.tar.gz
npm install -g [email protected]
openclaw up -d

8.2 回滚后检查

# 确认版本
openclaw version  # 应显示 1.2.0

# 运行诊断
openclaw doctor

# 确认数据完整
openclaw stats --period 1h

零停机升级不是一次性的工作，而是需要标准化流程和持续演练的运维实践。选择适合你部署规模的升级方案，并在每次升级前做好充分准备，就能最大限度地降低升级风险。