`ql3-trigger` 本机 Trigger 管理

ql3-trigger 是 Edge/Standalone 的一次命令、一次进程管理入口。它复用现有 application scheduler，不启动管理服务、独立 timer 或后台连接。Cluster 不支持此入口。

前置条件

已完成 Fresh Setup、Owner credential、Project/RoleBinding 与 TaskDefinition 配置；
调用者是 strong User；owner、admin、operator 可 put，viewer 只能 inspect/list；
deployment root/子目录属于当前 UID，目录 0700、credential 与 command file 为 0600；
先用 ql3-task 执行 task.inspect command，取得 Task 的 current revision 与 contentDigest；
当前 production Trigger registry 只接受 schema=qinglong/cron@v1。

统一执行形式：

ql3-trigger run --command-file /srv/qinglong3/commands/trigger-create.json

响应未知时只能原样重放同一个 command file。不要修改 mutation、request、时间、Task binding 或 Trigger 内容来“重试”。

创建 Trigger

{
  "schemaVersion": 1,
  "operation": "trigger.put",
  "options": {
    "deploymentRoot": "/srv/qinglong3",
    "databasePath": "/srv/qinglong3/qinglong3.sqlite",
    "profile": "edge",
    "ownerPepperKeyringDirectory": "/srv/qinglong3/owner-keys",
    "credentialFilePath": "/srv/qinglong3/owner-credential.json",
    "busyTimeoutMs": 100
  },
  "request": {
    "projectId": "default",
    "triggerId": "daily-health-check-cron",
    "expectedRevision": null,
    "mutationId": "44444444-4444-4444-8444-444444444441",
    "requestId": "trigger-create-daily-health-check",
    "failureAuditEventId": "44444444-4444-4444-8444-444444444442",
    "taskId": "daily-health-check",
    "taskRevision": 1,
    "taskContentDigest": "REPLACE_WITH_TASK_INSPECT_CONTENT_DIGEST",
    "spec": {
      "schema": "qinglong/cron@v1",
      "config": {
        "expression": "*/5 * * * *",
        "timezone": "Etc/UTC",
        "misfirePolicy": "skip"
      }
    },
    "enabled": true,
    "occurredAtMs": 1785542401000
  }
}

expression 接受有界五段或六段 cron，timezone 必须是运行时支持的 IANA timezone， misfirePolicy 只能是 skip 或 fire_once。首次返回 created；相同文件逐字重放返回 existing。

更新、停用、启用与 repin

先 inspect 当前 Trigger，取得 revision。每次更新都提交新的 trigger.put：

expectedRevision 填当前 Trigger revision；
每次使用新的 mutationId、requestId、failureAuditEventId 和 occurredAtMs；
修改 schedule 或 enabled 会追加新 revision，不存在原地修改；
启用 Trigger 时，taskRevision/taskContentDigest 必须精确匹配当前且 enabled 的 Task head；
Task 更新、停用或重新启用后，旧 Trigger 会自动停止 admission。先 inspect Task，再以新的 Trigger revision 显式 repin；系统不会静默改写绑定；
Task 已变化时仍允许提交 enabled:false 的 Trigger revision，保证 operator 能撤权。此 revision 可以保留历史 Task pin，但再次启用必须改为 current pin。

扫描取得候选后若 Task 发生变化，最终 Run commit 仍会失败关闭；不需要直接清理 schedule 表。

查询一个 Trigger

{
  "schemaVersion": 1,
  "operation": "trigger.inspect",
  "options": {
    "deploymentRoot": "/srv/qinglong3",
    "databasePath": "/srv/qinglong3/qinglong3.sqlite",
    "profile": "edge",
    "ownerPepperKeyringDirectory": "/srv/qinglong3/owner-keys",
    "credentialFilePath": "/srv/qinglong3/owner-credential.json"
  },
  "request": {
    "projectId": "default",
    "triggerId": "daily-health-check-cron",
    "requestId": "trigger-inspect-daily-health-check",
    "auditEventId": "55555555-5555-4555-8555-555555555551",
    "failureAuditEventId": "55555555-5555-4555-8555-555555555552"
  }
}

存在时只返回低敏摘要，不返回 cron expression、timezone 或 misfire policy。部署者应保留受保护的源 command/template，不要把 inspect 当作配置导出。

有界列出 Trigger

trigger.list request 包含 projectId、limit、requestId、auditEventId 与 failureAuditEventId。limit 必须为 1–256；若 nextCursor 非 null，下一页使用新的 request/audit identity，并原样加入：

{ "after": { "triggerId": "daily-health-check-cron" } }

列表按 triggerId 正序稳定翻页，不支持 offset、模糊搜索或无界返回。每页是独立 current-head snapshot。

事务、安全与恢复

put 的 allowed audit、Trigger head/revision、mutation ledger 与 schedule reset 在同一 SQLite 事务提交；credential、Policy 或 Task fence 变化会整体回滚；
exact replay 绑定 actor、Policy fence、Task binding、Trigger spec 和 immutable time；
失败后禁止直接 SQL 修补 Trigger、schedule 或 audit；revision conflict 应重新 inspect 并人工确认；
ql3-trigger 只适用于 Edge/Standalone。Cluster 必须使用 PostgreSQL/RBAC 管理 transport。

4.9 KiB Raw Blame History Unescape Escape

ql3-trigger 本机 Trigger 管理