主题
认证与通用约定
请求约定
- Base path:
/api/v1,下文路径均省略该前缀。 - 编码 UTF-8,请求体
Content-Type: application/json,字段命名 camelCase。 - 时间字段为 RFC3339 字符串(如
2026-01-01T10:00:00+08:00);expiresAt(登录/初始化响应)为 Unix 秒。
响应封装
所有接口统一返回信封 {success, data, errorCode, errorMessage, showType}。
成功(HTTP 200):
json
{ "success": true, "data": { } }业务失败(HTTP 200):
json
{ "success": false, "data": null, "errorCode": 40900, "errorMessage": "project key already exists: my-app", "showType": 2 }认证失败(HTTP 401,唯一的非 200 业务错误,前端据此清 token 跳登录):
json
{ "success": false, "data": null, "errorCode": 40100, "errorMessage": "not logged in or session expired", "showType": 0 }showType 沿用 Ant Design Pro 模板枚举:
| showType | 含义 |
|---|---|
0 | 静默 |
1 | warning |
2 | error |
3 | notification |
HTTP 200 陷阱
除 401 外,「资源不存在」「参数错误」「无权限」「冲突」「限流」全部是 HTTP 200,只是 success=false。因此:
- 不能用 HTTP 状态码判断成功与否;
- 不能用
try/catch捕获业务错误(PowerShellInvoke-RestMethod、Gohttp.Get都不会因success=false报错)。
正确姿势是先解析响应体再看 success:
bash
resp=$(curl -s -H "Authorization: dk_xxxxxxxx" http://127.0.0.1:10055/api/v1/projects/my-app)
echo "$resp" | grep -q '"success":true' || { echo "业务失败:$resp"; exit 1; }错误码
数值与含义核实自 internal/api/response.go:
| errorCode | 含义 | HTTP 状态 | showType |
|---|---|---|---|
40000 | 参数校验失败(errorMessage 给出具体字段) | 200 | 2 |
40100 | 未认证 / token 失效 | 401 | 0 |
40300 | 无权限 | 200 | 2 |
40400 | 资源不存在 | 200 | 2 |
40900 | 冲突(key 重复、名称重复、被引用、已初始化) | 200 | 2 |
42900 | 触发过频(Hook 限流、登录失败锁定) | 200 | 1 |
50000 | 服务端内部错误(真实原因写日志,响应脱敏) | 200 | 2 |
认证方式
令牌放在 Authorization 头,服务端同时接受裸 token 与 Bearer <token>(前缀大小写不敏感):
http
Authorization: dk_xxxxxxxx
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...| 凭据 | 形态 | 签发 | 有效期 | 适用 |
|---|---|---|---|---|
| JWT | 三段式字符串 | bootstrap / login | 默认 168 小时(tokenTtlHours 配置) | 浏览器会话 |
| API Token | dk_ + 32 位随机串 | POST /tokens | 创建时 expiresInDays 指定,缺省永不过期 | CLI、CI、第三方脚本 |
- 服务端按
dk_前缀分流:API Token 只存 SHA-256 哈希,明文仅创建时返回一次;prefix为明文前 8 位,用于列表识别。 - JWT 无黑名单:
logout与change-password都不会使旧 token 失效。 - 账号被禁用时:JWT 请求返回
40300;API Token 请求返回40100(HTTP 401)。 - WebSocket 不能自定义 Header,token 走 query,见 运行与日志接口。
认证接口
GET /auth/bootstrap-status(公开)
是否已完成初始化(系统里有没有用户)。data:
json
{ "initialized": false }POST /auth/bootstrap(公开,仅未初始化时可用)
创建第一个管理员并直接签发 token。已初始化时返回 40900。
json
{ "username": "admin", "password": "xxxxxxxx" }约束:username 3–32 字符,password 8–128 字符,否则 40000。data:
| 字段 | 说明 |
|---|---|
token | JWT |
expiresAt | Unix 秒 |
user | User 对象(见下) |
POST /auth/login(公开)
json
{ "username": "admin", "password": "xxxxxxxx" }data:{token, expiresAt, mustChangePassword, user}。密码错 → 40100(HTTP 401);账号禁用 → 40300。
登录失败限流:同一用户名连续失败 5 次锁定 10 分钟,期间返回 42900(内存计数,服务重启清零)。
GET /auth/me(登录)
data 为当前 User 对象。
POST /auth/logout(登录)
无状态 JWT,仅记审计日志。data: null,旧 token 仍有效。
POST /auth/change-password(登录)
json
{ "oldPassword": "xxxxxxxx", "newPassword": "yyyyyyyy" }新密码 8–128 字符且必须与旧密码不同;旧密码错误返回 40000。成功后 mustChangePassword 置 false,旧 token 仍有效。data: null。
User 对象
json
{
"id": 1, "username": "admin", "nickname": "Admin", "email": "",
"role": "admin", "status": "active", "mustChangePassword": false,
"lastLoginAt": "2026-01-01T10:00:00+08:00",
"createdAt": "2026-01-01T10:00:00+08:00"
}role:admin | user;status:active | disabled。管理员新建/重置密码的用户 mustChangePassword=true。
分页与搜索
分页列表接口(users / projects / tasks / runs / audit-logs)统一接受:
| 参数 | 默认 | 说明 |
|---|---|---|
page | 1 | 从 1 开始,小于 1 按 1 |
pageSize | 20 | 小于 1 按 20,大于 200 按 200 |
响应 data:
json
{ "list": [], "total": 0, "page": 1, "pageSize": 20 }keyword 为模糊搜索(LIKE),各接口匹配范围不同:
| 接口 | keyword 匹配字段 |
|---|---|
GET /users | username / nickname / email |
GET /projects、GET /tasks | key / name |
GET /audit-logs | 用 username 参数模糊匹配,另有 action 精确匹配 |
tokens / credentials / hooks 列表不分页,直接返回数组。
可见性与编辑权限
系统设置 visibility 决定非 owner 的登录用户能看到什么(项目、任务、运行一致):
| visibility | 其他登录用户 |
|---|---|
allReadable(默认) | 只读可见:能看列表/详情/日志,不能改、不能触发 |
ownerOnly | 完全不可见:列表自动过滤,按 key/id 访问返回 40400 |
- 编辑/执行权限 = owner 或 admin。
canEdit由服务端算好放在项目/任务对象里,调用方不必自行判断。 - 不可见与不存在都返回
40400(不泄露资源是否存在);可见但无权修改/执行返回40300。 - admin 不受 visibility 限制,始终全量可见、可编辑。
- 用户管理、系统设置写入、工具链/中间件安装、审计日志、SSH 公钥生成等接口仅 admin,非管理员返回
40300。
CORS 仅对 http://localhost:*、http://127.0.0.1:*、http://192.168.*、http://10.* 的 Origin 放开;生产环境前端由本服务托管,属同源,不触发 CORS。