mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-21 01:32:44 +08:00
145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# `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`。
|
||
|
||
统一执行形式：
|
||
|
||
```sh
|
||
ql3-task run --command-file /srv/qinglong3/commands/task-create.json
|
||
```
|
||
|
||
响应未知时只能原样重放同一个 command file。不要修改 mutation、request、时间或 Task 内容
|
||
来“重试”。
|
||
|
||
## 创建 Task
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```json
|
||
{ "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 作为替代入口。
|