跳到主要内容

Guardian 守护系统

概述​

Guardian 是 SayClaw 平台的核心安全守护模块，通过 10 个检查维度 对全平台基础设施进行周期性巡检，自动检测异常并尝试修复。

检查维度​

维度编号频率说明
OneAPI 守护guardian_oneapi每 5 分钟检查 OneAPI 服务健康状态
OC 配置守护guardian_oc_auth每 5 分钟检查 OC 实例的 auth-profiles 和 model 前缀配置
Session 守护guardian_session每 5 分钟检查 OC 实例的 session 状态，自动修复过期 session
WebChat 守护guardian_webchat每 5 分钟检查 WebChat Portal API 健康状态
端口一致性guardian_port每小时 :05检查 OC 实例端口与数据库记录是否一致
实例日志检查guardian_oc_logs每 15 分钟 :02扫描 OC 实例 journalctl 日志中的关键错误
TG Token 唯一性guardian_tg_token每小时 :10全局检查 Telegram Bot Token 是否有重复
Models 完整性guardian_models_check每小时 :15检查 models 配置是否完整，primary model 是否在列表中
进程一致性guardian_process_check每小时 :20检查服务器上的 openclaw 进程是否都属于已注册的 systemd service

数据库表​

guardian_events​

存储所有检查维度产生的异常事件和修复记录。

字段类型说明
idINT AUTO_INCREMENT主键
dimensionVARCHAR(50)维度名称
target_idVARCHAR(100)检查目标（实例ID/服务器ID）
statusVARCHAR(20)状态：success / failed
problemTEXT问题描述
action_takenTEXT采取的修复措施
extraTEXT额外信息（JSON）
created_atDATETIME事件时间

job_runs​

存储所有定时任务的执行记录。

字段类型说明
idINT AUTO_INCREMENT主键
jobVARCHAR(100)任务名称
statusVARCHAR(20)执行状态
messageTEXT执行结果详情
duration_msINT执行耗时（毫秒）
ran_atDATETIME执行时间

API 端点​

GET /api/v1/guardian/stats​

返回所有维度的统计数据和最新执行状态。

响应示例：

{
  "code": "0000",
  "data": {
    "today": {
      "total_events": 20,
      "success": 0,
      "failed": 20,
      "success_rate": 0
    },
    "dimensions": [
      {
        "dimension": "guardian_oneapi",
        "label": "OneAPI 守护",
        "status": "healthy",
        "today_total": 0,
        "today_success": 0,
        "today_failed": 0,
        "last_check_at": "2026-03-11T18:50:15+09:00"
      }
    ],
    "job_runs": [
      {
        "job": "guardian_oneapi",
        "label": "OneAPI 守护",
        "status": "success",
        "message": "OneAPI healthy",
        "duration_ms": 2,
        "ran_at": "2026-03-11T18:50:15+09:00"
      }
    ]
  }
}

GET /api/v1/guardian/events​

分页查询异常事件记录，支持按维度、状态、目标ID筛选。

参数：

  • page (int): 页码，默认 1
  • page_size (int): 每页条数，默认 20
  • dimension (string): 按维度筛选
  • status (string): 按状态筛选
  • target_id (string): 按目标ID筛选

修复历史​

2026-03-12 修复记录​

  1. WebChat Guardian curl 命令修复：-sf flag 导致 HTTP 404 时返回错误码，改为 -s
  2. llm_self_heal collation 冲突：统一 9 个表的 collation 为 utf8mb4_0900_ai_ci
  3. Guardian API 字段名错误：job_runs 查询从 created_at 修正为 ran_at
  4. Telegram Bot Token 冲突：ai-jp-01 残留的 openclaw-gateway 与 ai-jp-02 Instance 02 共用同一个 bot token，导致 409 Conflict 和 Unknown model 错误。已删除 ai-jp-01 上的残留实例

新增 4 个检查维度​

为解决上述 bot token 冲突等问题未被及时发现的监控盲区，新增了以下维度：

  • 实例日志检查：扫描 journalctl 中的 Unknown model、FailoverError、409 Conflict 等关键错误
  • TG Token 唯一性：全局检查 Telegram bot token 是否有重复
  • Models 完整性：检查 models 配置不为空，primary model 在列表中存在
  • 进程一致性：检查服务器上的 openclaw 进程是否都属于已注册的 systemd service