Skip to content

认证与通用约定 ​

请求约定 ​

  • 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静默
1warning
2error
3notification

HTTP 200 陷阱 ​

除 401 外,「资源不存在」「参数错误」「无权限」「冲突」「限流」全部是 HTTP 200,只是 success=false。因此:

  • 不能用 HTTP 状态码判断成功与否;
  • 不能用 try/catch 捕获业务错误(PowerShell Invoke-RestMethod、Go http.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 给出具体字段)2002
40100未认证 / token 失效4010
40300无权限2002
40400资源不存在2002
40900冲突(key 重复、名称重复、被引用、已初始化)2002
42900触发过频(Hook 限流、登录失败锁定)2001
50000服务端内部错误(真实原因写日志,响应脱敏)2002

认证方式 ​

令牌放在 Authorization 头,服务端同时接受裸 token 与 Bearer <token>(前缀大小写不敏感):

http
Authorization: dk_xxxxxxxx
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
凭据形态签发有效期适用
JWT三段式字符串bootstrap / login默认 168 小时(tokenTtlHours 配置)浏览器会话
API Tokendk_ + 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:

字段说明
tokenJWT
expiresAtUnix 秒
userUser 对象(见下)

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)统一接受:

参数默认说明
page1从 1 开始,小于 1 按 1
pageSize20小于 1 按 20,大于 200 按 200

响应 data:

json
{ "list": [], "total": 0, "page": 1, "pageSize": 20 }

keyword 为模糊搜索(LIKE),各接口匹配范围不同:

接口keyword 匹配字段
GET /usersusername / nickname / email
GET /projects、GET /taskskey / 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。