主题
API 参考
本章是 deploy 服务端 HTTP API 的完整参考,覆盖 deploy-server/internal/api/server.go 注册的全部路由。
契约版本
接口契约为 v1(冻结),事实来源是仓库内的 docs/API设计.md;本章逐条核对过真实路由表与 handler 实现,契约与源码不一致处以源码为准,并在相应页面注明差异。契约未列出的新增路由(任务、审计日志、SSH 公钥等)同样以源码为准。
通用约定速览
| 项 | 约定 |
|---|---|
| Base path | /api/v1 |
| 编码 | UTF-8,Content-Type: application/json,字段 camelCase |
| 响应封装 | {success, data, errorCode, errorMessage, showType} |
| 认证 | Authorization: <token>(裸 token)或 Authorization: Bearer <token>;JWT 与 dk_ API Token 均可 |
| 成功判定 | 看 success 字段,不看 HTTP 状态码:除 401 外业务失败一律 HTTP 200 |
| 分页 | ?page=1&pageSize=20,pageSize 上限 200 |
详见 认证与通用约定。
阅读顺序
| 页面 | 内容 |
|---|---|
| 01 认证与通用约定 | 响应封装、错误码、JWT 与 API Token、登录/初始化接口、分页、可见性与权限 |
| 02 项目与任务接口 | projects / tasks 的 CRUD、命令与步骤、环境变量、预览、归档、依赖 |
| 03 运行与日志接口 | 触发运行、runs 列表/详情/取消/重跑、HTTP 增量日志、WebSocket 实时日志 |
| 04 Hook 接口 | Hook 令牌管理、免登录触发、同步/异步、限流 |
| 05 中间件、工具链与系统接口 | middleware / toolchain / system、用户管理、Git 凭据、个人 API Token、SSH 公钥、审计日志 |
建议先读 01 掌握响应封装与权限模型,再按需查阅其余页面。自动化脚本作者最常用的是 03(触发与日志)与 04(Hook)。
相关章节
- 术语与概念:核心概念
- 命令行用法(API 的封装):CLI
- 字段语义的业务背景:项目定义、任务定义
- Hook 的 CI 集成场景:HTTP Hook
- 中间件面板操作:中间件、系统设置
- 令牌与暴露面安全:安全加固
示例约定
本章所有示例中的令牌一律使用占位符 dk_xxxxxxxx(API Token)与 hk_xxxxxxxx(Hook Token),服务端地址以 http://127.0.0.1:10055 为例。真实令牌只在创建时返回一次,请替换为你自己的值。