Skip to content

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)。

相关章节 ​

示例约定 ​

本章所有示例中的令牌一律使用占位符 dk_xxxxxxxx(API Token)与 hk_xxxxxxxx(Hook Token),服务端地址以 http://127.0.0.1:10055 为例。真实令牌只在创建时返回一次,请替换为你自己的值。