API 参考（全量）#

本页覆盖以下源码中暴露的全部 HTTP 路由：

• crates/dockrev-api/src/api/mod.rs
• crates/dockrev-supervisor/src/app.rs

鉴权模型#

• 公开接口：无需认证头。
• Forward Auth：入口代理可透传来自身份提供方的可信用户/组头；Dockrev 仍自行决定受保护接口是返回数据还是 401 auth_required。
• Dockrev 鉴权：Dockrev 读取 DOCKREV_AUTH_ALLOWED_USER 与 DOCKREV_AUTH_ALLOWED_GROUP；两者各只接受一个值，同时配置时命中任意一个即可通过。
• Webhook Secret：X-Dockrev-Webhook-Secret 必须与服务端配置一致。
• GitHub Signature：X-Hub-Signature-256 + X-GitHub-Event + X-GitHub-Delivery。

Dockrev API（/api/*）#

1) Core#

2) Stacks / Services / Version inference#

3) Discovery / Check / Runtime scan / Update#

GET /api/discovery/projects 的 status 可为 active、stopped、missing 或 invalid。stopped 表示保存的 Compose 文件仍可读且可解析，但当前没有运行容器；关联 Stack 保持未归档，可使用既有生命周期接口启动。扫描 job 的 summary 包含 stacksStopped，动作可为 marked_stopped。仅所有保存文件均为 ENOENT 时才会以 auto_archive_compose_files_missing 自动归档；混合缺失、权限/I-O 或解析异常保持 invalid。人工归档不会被扫描解除。

• POST /api/updates 契约：

  • scope=service：必须显式携带 serviceId + targetTag + targetDigest + pullTags。
  • scope=stack|all：必须显式携带 targets[]，元素为 { serviceId, targetTag, targetDigest, pullTags }。
  • 同一服务仍可继续使用 mode=dry-run 做预检查。

• 服务生命周期契约：

  • GET /api/stacks/{stack_id}/lifecycle-status 聚合 Stack 内服务状态，并返回覆盖任一服务的 queued/running update、rollback、service lifecycle 或 stack lifecycle 任务。
  • POST /api/stacks/{stack_id}/lifecycle 请求体同样为 { "action": "start" | "stop" | "restart" }。Compose V2 启动执行项目级 up -d --pull never --no-recreate，Compose V1 执行项目级 start；停止和重启执行项目级对应命令。
  • GET /api/services/{service_id}/lifecycle-status 返回 state=running|stopped|partial|unknown，并在存在同服务更新、回滚或生命周期任务时返回 activeJob。
  • POST /api/services/{service_id}/lifecycle 请求体为 { "action": "start" | "stop" | "restart" }。Compose V2 启动执行 up -d --pull never --no-recreate --no-deps，Compose V1 执行 start（仅启动已有容器）；两者都不会拉取镜像、替换已有容器或启动依赖服务。Compose V1 不存在容器时返回不可用。停止和重启分别执行对应 Compose 命令。
  • Stack 生命周期锁定其中全部服务，与 update、rollback 和 service lifecycle 双向互斥；冲突返回 409 和 existingJobId。Dockrev 自身服务以及包含 Dockrev 的 Stack 不支持普通生命周期接口。

4) Jobs / Events#

5) Ignores / Service settings / Notifications / Settings#

• POST /api/notifications/test 从 2026-03-05 起将测试通知下游 payload 切换为 v2（breaking）：
  • 不再发送旧字段 type/ts/message。
  • 基础结构：schema/kind/sentAt/channel/human/debug。
  • Web Push 会额外附带顶层 title/body，用于 Service Worker 直接展示通知。
  • 文本渲染按通道能力：Telegram/Email 带代码块，Web Push 仅自然语言（无代码块）。

6) GitHub Packages (GHCR) integration#

GHCR webhook deliveries SSE#

• GET /api/github-packages/webhook/deliveries/events 返回 text/event-stream，事件名固定为 github_packages_delivery_event 与 github_packages_delivery_events_error。
• 支持 query afterId 与 Last-Event-ID 续传；服务端取两者最大值作为 cursor。
• 未提供 cursor 时，默认 tail-follow：从当前最新 delivery event id 开始，仅追随后续新事件。
• 建议前端在收到 delivery 事件或 error 事件后重新请求当前收件箱列表，以保持分页、筛选和 summary 一致。

7) Web Push / Webhooks / Deploy checks#

Supervisor API（base path 默认 /supervisor）#

• GET /supervisor/self-upgrade 在 state=running 时会返回可选字段 request（mode + rollbackOnFailure），用于页面恢复当前运行按钮状态；空闲/历史状态下该字段可缺省。

示例请求#

触发全量检查#

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Forwarded-User: ops' \
  -d '{"scope":"all"}' \
  http://127.0.0.1:50883/api/checks

外部 webhook 触发 update#

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Dockrev-Webhook-Secret: change-me' \
  -d '{"action":"update","scope":"stack","stackId":"stk_xxx","targets":[{"serviceId":"svc_web","targetTag":"latest","targetDigest":"sha256:abc123","pullTags":["v1.1.2"]}],"allowArchMismatch":false,"backupMode":"inherit"}' \
  http://127.0.0.1:50883/api/webhooks/trigger

说明：POST /api/webhooks/trigger 在 action=update 时会拒绝未携带 targets[] 的旧 payload，返回 400 invalid_argument。 webhook update 同样支持 scope=service，但仍需显式提供 serviceId，并在 targets[] 中给出对应 { serviceId, targetTag, targetDigest, pullTags }。

查询 supervisor 状态#

分页查询任务#

GET /api/jobs 支持不透明 cursor、limit（默认 100，最大 200）、type（逗号分隔）、status、stackId 与 serviceId。响应按 createdAt DESC, id DESC 稳定排序，并在有下一页时返回 nextCursor；无效游标返回 400 invalid_jobs_cursor。

curl -H 'X-Forwarded-User: ops' \
  http://127.0.0.1:50883/supervisor/self-upgrade