后台任务队列 (Task Queue)

SayClaw Admin 内置后台任务队列，统一管理对单台或多台服务器的异步操作。所有后台任务均持久化于 admin_tasks 表，可追溯、可重试。

架构

HTTP 请求 / 业务操作
       ↓
  enqueueTask()
       ↓
  admin_tasks（MySQL）
       ↓
  taskWorker goroutine（每3秒轮询）
       ↓
  execOnServer()（本地 or SSH）
       ↓
  任务结果写回 admin_tasks

数据库表

CREATE TABLE admin_tasks (
  id          VARCHAR(36) PRIMARY KEY,
  type        VARCHAR(64) NOT NULL,
  server_id   VARCHAR(36),
  payload     JSON,
  status      ENUM('pending','running','done','failed') DEFAULT 'pending',
  result      TEXT,
  error       TEXT,
  created_at  DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  updated_at  DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  INDEX idx_status (status),
  INDEX idx_server (server_id)
);

任务类型

type	说明
exec_command	在指定 server 上执行 shell 命令
restart_service	重启 systemd 服务
deploy_config	写入配置文件
health_check	检查实例 gateway 状态

多服务器路由

• server_id == "" 或 server_id == LOCAL_SERVER_ID → 本地执行
• 否则 → SSH 到目标 server（使用 /root/.ssh/id_ed25519）

func execOnServer(serverID, command string) (string, error) {
    if serverID == "" || serverID == os.Getenv("LOCAL_SERVER_ID") {
        return execLocal(command)
    }
    return execSSH(serverID, command)
}

API

方法	路径	说明
POST	/api/v1/admin/tasks	入队新任务
GET	/api/v1/admin/tasks/:id	查询任务状态
GET	/api/v1/admin/tasks?status=pending	列出任务

---

术语统一补充（2026-03-05）

• 若历史实现存在 admin_tasks，建议在迁移期提供兼容层，最终收敛到 task_queue。
• 任务状态字段与重试策略应与 Scheduler 文档保持一致。