`ql3-task` 本机 TaskDefinition 管理

ql3-task 是 Edge/Standalone 的一次命令、一次进程管理入口。它不启动管理服务；成功输出不包含 Task spec、命令参数、SecretRef、credential、pepper 或本机路径。

前置条件

已完成 Fresh Setup、Owner credential 交付与 Project/RoleBinding 配置；
调用者是 strong User；owner、admin、operator 可 create/update，viewer 只能 inspect/list；
deployment root/子目录属于当前 UID，目录 0700、credential 与 command file 为 0600；
当前 production Task registry 只接受 kind=command、schema=qinglong/command@v1。

统一执行形式：

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

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

创建 Task

{
  "schemaVersion": 1,
  "operation": "task.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",
    "taskId": "daily-health-check",
    "expectedRevision": null,
    "mutationId": "11111111-1111-4111-8111-111111111111",
    "requestId": "task-create-daily-health-check",
    "failureAuditEventId": "11111111-1111-4111-8111-111111111112",
    "name": "Daily health check",
    "description": "Print a bounded local health marker",
    "kind": "command",
    "spec": {
      "schema": "qinglong/command@v1",
      "config": {
        "command": {
          "kind": "argv",
          "file": "/usr/bin/printf",
          "args": ["health-check\\n"]
        }
      }
    },
    "labels": { "team": "operations" },
    "enabled": true,
    "occurredAtMs": 1785542400000
  }
}

occurredAtMs 是 immutable command 语义的一部分，必须在创建 command file 时固定；不得用每次执行时的当前时间替换。首次返回 created，结果未知后逐字重放返回 existing。

更新、停用与重新启用

先 inspect 当前 Task，取得 revision。随后创建新的 task.put command：

expectedRevision 填当前 revision；
每次使用全新的 mutationId、requestId、failureAuditEventId 和 occurredAtMs；
修改 name/description/spec/labels 或 enabled；
停用设 enabled:false，重新启用设 enabled:true。

成功返回 updated 和递增 revision。不存在原地修改或 delete；历史 revision 继续解释已经固定到旧 revision 的 Run。expectedRevision 冲突时不要盲重试，重新 inspect 并人工确认差异。

查询一个 Task

{
  "schemaVersion": 1,
  "operation": "task.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",
    "taskId": "daily-health-check",
    "requestId": "task-inspect-daily-health-check",
    "auditEventId": "22222222-2222-4222-8222-222222222221",
    "failureAuditEventId": "22222222-2222-4222-8222-222222222222"
  }
}

已授权但不存在返回 found:false。存在时仅返回低敏摘要，不返回 spec.config；需要更新的部署者应保留自己受保护的源 command/template，不能把 inspect 当作明文配置导出。

有界列出 Task

{
  "schemaVersion": 1,
  "operation": "task.list",
  "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",
    "limit": 32,
    "requestId": "task-list-default-first-page",
    "auditEventId": "33333333-3333-4333-8333-333333333331",
    "failureAuditEventId": "33333333-3333-4333-8333-333333333332"
  }
}

limit 必须为 1–256。若 nextCursor 非 null，下一页使用新的 request/audit identity，并把 cursor 原样放入 request：

{ "after": { "taskId": "daily-health-check" } }

列表按 taskId 正序稳定翻页，不支持 offset、模糊搜索或无界返回。每页是独立 current-head snapshot；若翻页期间有更新，需要严格同一时点清单时从第一页重新查询。

事务、安全与恢复

create/update 的 allowed audit、Task head、immutable revision、mutation ledger 和可执行 command revision 在同一 SQLite 事务提交；credential 或 Policy 在授权后变化会整体回滚；
authentication/authorization/fence/semantic/revision/audit 冲突均失败关闭；禁止直接 SQL 修补；
成功输出的 contentDigest 可用于变更审核，但不是可反推出 spec 的备份；
ql3-task 只适用于 Edge/Standalone。Cluster 必须使用后续 PostgreSQL 管理 transport，不得把本机 credential/SQLite 文件挂入集群 Pod 作为替代入口。

5.2 KiB Raw Blame History Unescape Escape

ql3-task 本机 TaskDefinition 管理