定时任务模块 (Scheduler)

SayClaw 定时任务模块基于 robfig/cron/v3 构建，负责实例初始化、健康检查、用量同步、服务器监控、配置漂移检测等全自动化运维任务。

---

架构概览

admin-api (Go)
├── scheduler/
│   ├── engine.go           ← cron 注册 + goroutine 池 + 并发控制
│   ├── queue.go            ← 事件驱动队列 Worker（扫 task_queue 表）
│   └── jobs/
│       ├── init_instance.go     ← 认领后自动初始化实例
│       ├── health_check.go      ← 实例健康检查
│       ├── token_usage.go       ← LiteLLM 用量同步
│       ├── server_metrics.go    ← 服务器资源采集
│       ├── config_sync.go       ← 实例配置漂移检测
│       ├── auto_recovery.go     ← 故障自动恢复
│       ├── key_balance.go       ← API Key 余额告警
│       ├── daily_cleanup.go     ← 闲置实例标记
│       └── db_backup.go         ← 数据库定时备份

---

数据库表

task_queue — 事件驱动队列

CREATE TABLE task_queue (
  id          VARCHAR(36) PRIMARY KEY,
  type        VARCHAR(64) NOT NULL,
  payload     JSON,
  status      ENUM('pending','running','done','failed') DEFAULT 'pending',
  attempts    INT DEFAULT 0,
  error       TEXT,
  created_at  DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  updated_at  DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
);

job_runs — 定时任务运行记录

CREATE TABLE job_runs (
  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
  job_name    VARCHAR(64) NOT NULL,
  status      ENUM('ok','error','skipped') NOT NULL,
  duration_ms INT,
  detail      TEXT,
  ran_at      DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  INDEX idx_job_ran (job_name, ran_at)
);

server_metrics — 服务器资源快照

CREATE TABLE server_metrics (
  id            BIGINT AUTO_INCREMENT PRIMARY KEY,
  server_id     VARCHAR(36) NOT NULL,
  cpu_pct       FLOAT,
  mem_used_mb   INT,
  mem_total_mb  INT,
  disk_used_gb  FLOAT,
  disk_total_gb FLOAT,
  load_1m       FLOAT,
  sampled_at    DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  INDEX idx_server_time (server_id, sampled_at)
);

usage_daily — 实例用量日报

CREATE TABLE usage_daily (
  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
  instance_id VARCHAR(100) NOT NULL,
  date        DATE NOT NULL,
  requests    INT DEFAULT 0,
  tokens      BIGINT DEFAULT 0,
  cost_usd    DECIMAL(10,6) DEFAULT 0,
  updated_at  DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_inst_date (instance_id, date)
);

---

任务清单

#	任务名	触发方式	频率	说明
1	init_instance	事件（claim 后立即入队）	< 10 秒	SSH 初始化实例配置、写 BOOTSTRAP.md、重启服务
2	health_check	cron	每 5 分钟	HTTP 检查所有实例 gateway，更新 health_status / fail_count
3	token_usage_sync	cron	每 15 分钟	从 LiteLLM 同步各 virtual key 用量，写 usage_daily
4	server_metrics	cron	每 5 分钟	SSH 采集 CPU / 内存 / 磁盘，写 server_metrics
5	config_sync	cron	每 30 分钟	SSH 读取实际 openclaw.json，与 DB 对比，记录漂移
6	auto_recovery	cron	每 10 分钟	fail_count ≥ 3 的实例自动 SSH restart
7	key_balance_alert	cron	每小时	LiteLLM virtual key 余额 < $10 时 TG 告警
8	idle_instance_mark	cron	每天 03:00	7 天无对话的实例标记为 idle
9	db_backup	cron	每天 04:00	mysqldump 全库，本地保留 7 天
10	pending_task_retry	cron	每分钟	扫 task_queue 中 failed & attempts < 3 的任务重试

---

关键流程：认领 → 自动初始化

用户 POST /me/instances/claim 成功后，系统立即将初始化任务写入 task_queue，Worker 在 10 秒内完成 SSH 部署，无需人工干预。

用户认领实例
     ↓
claimInstanceHandler
① INSERT user_instances
② INSERT task_queue { type: "init_instance", payload: { instance_id, user_id, tg_user_id } }
     ↓ (异步 < 10s)
queue.go Worker
③ 读取 oc_instances.config_json → config_path / service_name / server_id
④ SSH → 写 openclaw.json (dmPolicy + allowFrom)
⑤ SSH → 写 BOOTSTRAP.md（引导用户完成 AI 个性化设置）
⑥ SSH → systemctl restart {service_name}
⑦ task_queue.status = 'done'

注意： 若用户尚未配置 TG Bot（无 tg_bot_token），初始化跳过 channels 写入，仅执行 BOOTSTRAP.md 和 restart，等用户后续通过 tg-setup 自助配置。

---

健康检查状态机

unknown → running（首次检查成功）
running → unknown（连续失败 1 次）
unknown → failed（fail_count ≥ 3）
failed  → running（auto_recovery 重启成功）
running → idle（7 天无对话，daily_cleanup 标记）

---

配置漂移检测

config_sync 任务每 30 分钟 SSH 读取各实例的 openclaw.json，与 DB 中 oc_instances.config_json 比对以下字段：

• channels.telegram.botToken
• agents.defaults.model.primary
• gateway.dmPolicy / allowFrom

若发现不一致，写入 job_runs.detail，并（可选）自动覆写修正。

---

API 接口（规划）

方法	路径	说明
GET	/api/v1/admin/job-runs	查看最近任务运行记录
GET	/api/v1/admin/task-queue	查看 pending/failed 队列
POST	/api/v1/admin/task-queue/:id/retry	手动重试失败任务
GET	/api/v1/admin/server-metrics/:id	查看服务器历史指标
GET	/api/v1/admin/usage-daily	查看用量日报

---

实现优先级

阶段	任务	状态
P0	建 4 张 DB 表	待实现
P0	init_instance worker（解决认领后无响应）	待实现
P0	claimInstanceHandler 写队列	待实现
P1	health_check + auto_recovery	待实现
P1	server_metrics + token_usage_sync	待实现
P2	config_sync + key_balance_alert	待实现
P2	idle_instance_mark + db_backup	待实现
P3	Admin 后台可视化页面	待实现