# 🔄 OpenClaw Auto Rollback

智能自动备份与自动回滚工具，专为 OpenClaw 设计。特别适用于**黑盒子服务器**（无显示器）和**出差场景**，提供出行模式自动守护功能。

基于 [OpenClaw Config Guardian](https://www.npmjs.com/package/openclaw-config-guardian) 的核心备份/回滚能力，增加了智能健康监测和自动恢复功能。

## ✨ 核心功能

| 功能 | 说明 |
|------|------|
| 🔄 **自动备份** | 定时自动备份 OpenClaw 配置文件 |
| ✈️ **出行模式** | 专为无人值守场景设计，自动监测 + 自动回滚 |
| 🏥 **健康检测** | 深度检测 Gateway 状态（进程 + API） |
| 🚨 **自动回滚** | Gateway 异常时自动回滚到最后已知良好配置 |
| 🌐 **Web UI** | 图形化界面管理备份和出行模式 |
| ⚡ **一键回滚** | 手动快速恢复到任意备份点 |
| 🧹 **自动清理** | 自动保留最近 N 个备份，删除旧备份 |

## 🚀 快速安装

```bash
npm install -g openclaw-auto-rollback
```

安装后自动创建默认配置和备份目录。

## 📖 使用方式

### 命令行 (CLI)

全局安装后，使用 `oar` 简写命令：

```bash
# 查看 Gateway 状态和出行模式信息
oar status

# 立即创建备份
oar backup

# 列出所有备份
oar list

# 回滚到指定备份
oar restore backup-2024-01-15T08-30-00-000Z

# 删除指定备份
oar delete backup-2024-01-15T08-30-00-000Z

# 启动 Web UI
oar webui

# 查看/修改配置
oar config
```

### ✈️ 出行模式 (Travel Mode)

专为黑盒子服务器或出差场景设计：

```bash
# 开启出行模式
oar travel-mode on

# 设置检查间隔：10分钟 / 2小时 / 8小时
oar travel-interval 120

# 启动守护进程（后台运行）
oar daemon

# 手动触发一次出行模式检测
# （在 Web UI 中操作或调用 API）
```

**出行模式工作原理：**

1. **定时检测** → 按设定间隔检查 Gateway 健康状态
2. **正常时备份** → Gateway 健康 → 自动创建备份，标记为 "known-good"
3. **异常时回滚** → Gateway 异常 → 自动回滚到最后 "known-good" 备份
4. **自动恢复** → 回滚后 Gateway 重新启动，服务恢复

### Web UI

```bash
oar webui
```

访问 http://localhost:3738

Web UI 提供：
- 📊 实时 Gateway 健康状态
- ✈️ 出行模式开关和配置
- 📦 备份列表管理（创建/回滚/删除）
- ⚙️ 自动备份设置

## ⚙️ 配置

配置文件位置：`~/.openclaw/extensions/openclaw-auto-rollback/config.json`

```json
{
  "autoBackup": true,
  "maxBackups": 10,
  "webUIPort": 3738,
  "backupItems": [],
  "travelMode": false,
  "travelModeInterval": 120,
  "travelModeMaxBackups": 20
}
```

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `autoBackup` | 启用普通定时备份 | `true` |
| `maxBackups` | 普通备份最大保留数 | `10` |
| `webUIPort` | Web UI 端口 | `3738` |
| `backupItems` | 自定义备份项（空数组=自动扫描） | `[]` |
| `travelMode` | 启用出行模式 | `false` |
| `travelModeInterval` | 出行模式检查间隔（分钟） | `120` |
| `travelModeMaxBackups` | 出行模式最大备份数 | `20` |

### 检查间隔选项

| 间隔 | 适用场景 |
|------|----------|
| **10 分钟** | 高频监控，重要生产环境 |
| **2 小时** | 推荐，平衡检测频率和资源消耗 |
| **8 小时** | 低频监控，开发/测试环境 |

## 🔒 安全机制

- **回滚前紧急备份**: 每次回滚前自动创建当前配置快照
- **关键配置验证**: 回滚后验证 `openclaw.json` 有效性
- **安全覆盖**: 只覆盖备份中的文件，不删除现有文件
- **连续失败保护**: 记录连续失败次数，避免频繁回滚
- **备份标记**: 出行模式备份标记 Gateway 健康状态

## 📁 备份内容

自动扫描并备份以下文件类型：
- `.md` - Markdown 配置文件
- `.json` - JSON 配置文件
- `.yaml` / `.yml` - YAML 配置文件
- `.toml` - TOML 配置文件
- `.ini` / `.conf` / `.config` - 其他配置文件

## 🔌 API 接口

Web UI 提供 REST API：

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/config` | GET/POST | 获取/更新配置 |
| `/api/backups` | GET | 获取备份列表 |
| `/api/backup` | POST | 立即执行备份 |
| `/api/restore` | POST | 回滚到指定备份 |
| `/api/status` | GET | 获取 Gateway 深度健康状态 |
| `/api/last-good-backup` | GET | 获取最后已知良好备份 |
| `/api/travel-mode/check` | POST | 手动触发出行模式检测 |

## 🏗️ 技术架构

```
openclaw-auto-rollback/
├── src/
│   ├── core.ts      # 核心引擎（备份/回滚/健康检测）
│   ├── daemon.ts    # 守护进程（定时任务 + 出行模式）
│   ├── webui.ts     # Web 服务（Express + API）
│   ├── cli.ts       # 命令行接口
│   └── index.ts     # 模块导出
├── webui/
│   └── index.html   # 可视化仪表盘
├── bin/
│   └── cli.js       # CLI 入口
└── skills/
    └── auto-rollback/
        └── SKILL.md # OpenClaw 技能定义
```

## 📝 与 Config Guardian 的区别

| 特性 | Config Guardian | Auto Rollback |
|------|----------------|---------------|
| 核心功能 | 定时备份 + 手动回滚 | 智能监测 + 自动回滚 |
| 出行模式 | ❌ 不支持 | ✅ 核心功能 |
| 自动回滚 | ❌ 不支持 | ✅ Gateway 异常时自动回滚 |
| 健康检测 | 基础进程检测 | 深度检测（进程 + API） |
| Web UI 端口 | 3737 | 3738 |
| CLI 命令 | `ocg` | `oar` |
| 适用场景 | 日常手动管理 | 无人值守/出差/黑盒子 |

## 🤝 依赖

- Node.js >= 18.0.0
- express ^4.18.2
- node-cron ^3.0.3

## 📄 License

MIT

## 📋 更新日志

### v1.0.6 (2026-06-11)
- **修复**: 出行模式检测结果不刷新
  - 修复点击"立即检测"后 UI 仍显示旧结果（"异常"）的问题
  - 后端 `/api/travel-mode/check` 接口现在正确保存 `lastCheckTime` 和 `lastCheckResult`
- **修复**: Windows 路径分隔符导致排除逻辑异常
  - `shouldExclude` 函数统一处理 `\` 和 `/` 路径分隔符，确保 Windows 下排除规则正确生效
- **优化**: Web UI 显示自动备份时间
  - 在"自动备份设置"卡片显示"下次自动备份：每天凌晨 2:00"

### v1.0.5 (2026-06-11)
- **修复**: Windows 健康检测逻辑优化
  - **端口检测优先**: 重写健康检测逻辑，端口通了直接认为 Gateway 健康（最可靠）
  - **修复进程名检测**: Windows 下 Gateway 可能是 `node.exe` 运行，原逻辑总是检测失败
  - **双方法端口检测**: Windows 先用 `Test-NetConnection`，失败再用 `TcpClient`
  - 同时兼容 Windows / Linux / macOS

### v1.0.4 (2026-06-11)
- **修复**: Windows 健康检测机制
  - 修复 Web UI 在 Windows 下错误显示 Gateway 已停止的问题
  - 进程检测：Windows 使用 `tasklist` 代替 `pgrep`（Linux 命令）
  - 端口检测：Windows 使用 PowerShell `TcpClient` 代替 `curl`
  - CLI 检测：Windows 下自动隐藏命令行窗口 (`windowsHide: true`)
  - 完全跨平台支持：Windows / Linux / macOS

### v1.0.3 (2026-06-11)
- **修复**: Windows 路径兼容性问题
  - 修复 `oar webui` 在 Windows PowerShell 下启动失败的问题
  - 使用 `pathToFileURL` 转换 ESM 导入路径，支持 Windows 绝对路径 (`C:\...`)
  - 修复守护进程启动时的路径转换问题

### v1.0.2 (2026-06-09)
- 普通备份每天凌晨2点执行
- 备份目录分离（regular/travel-mode）
- 各自独立数量限制

### v1.0.1 (2026-06-09)
- 守护进程自动启动
- HTTP 深度健康检测（能识别 token 被改导致的 401/403）

### v1.0.0 (2026-06-09)
- 初始版本，基于 Config Guardian 1.0.16
- 新增出行模式

## 🔗 相关项目

- [OpenClaw Config Guardian](https://www.npmjs.com/package/openclaw-config-guardian) - 基础备份回滚工具