主题
中间件、工具链与系统接口
本页覆盖系统探活/诊断/设置、工具链与中间件安装(内置「安装即运行」模式),以及设置页背后的用户、Git 凭据、个人 API Token、SSH 公钥、审计日志接口。UI 对应页面见 设置页,运维背景见 运维。
探活与诊断
GET /healthz(公开,唯一不在 /api/v1 下的业务路由):
json
{ "ok": true, "version": "1.0.0", "uptimeSec": 3600 }uptimeSec 为源码扩展字段(契约未列)。
GET /system/doctor(登录):探测 14 项外部命令 git bash sh rsync curl docker nginx node npm pnpm go java mvn certbot,用与执行器一致的登录 shell PATH 解析,版本探测 5 秒超时。data 含各命令 {name, found, path, version} 汇总,另含 web:{built, note}(前端产物是否就位,契约未列)。
系统信息
GET /system/info(登录):约 3 秒采样一次的主机快照,不含任何配置细节。data:time、hostname、os、arch、osName、kernel、uptimeSec、load、cpu、memory、disks[]、warnings[]。磁盘项带 status:使用率 ≥75% 或剩余 <2 GiB 记 warn,否则 ok。
系统设置
GET /system/settings(登录)/ PUT /system/settings(admin):
| 字段 | 可写 | 说明 |
|---|---|---|
serverUrl | 是 | 绝对 http(s) URL;传空回落自动推断 |
maxConcurrentRuns | 是 | 1–100,改动立即生效 |
logRetentionDays | 是 | ≥0,0 为不清理 |
logMaxBytes | 是 | >0,单 Run 日志上限 |
hookRateLimitPerMinute | 是 | ≥0,0 为不限 |
visibility | 是 | allReadable / ownerOnly |
notify | 是 | {enabled, url, on},整体写入 |
webRoot / dataDir / shell / allowRegistration | 否 | 只读回显(dataDir/shell 为源码扩展字段) |
PUT 校验失败 → 40000。响应为更新后的完整设置对象。
工具链接口
白名单组件:cc java maven nvm node pnpm go rust certbot。安装通过内置项目 system-toolchain(hookEnabled=false)以一次 Run 执行,日志走通用运行接口。
| 方法与路径 | 权限 | 说明 |
|---|---|---|
GET /system/toolchains | 登录 | 组件清单与探测结果 |
PUT /system/toolchains/{key} | admin | 保存安装参数 |
POST /system/toolchains/install | admin | 触发安装 Run |
GET /system/toolchains/script | admin | 下载 install-toolchains.sh(text/x-shellscript) |
列表 data:supported、platform、components[]、missing[]、scriptPath、scriptUrl、projectKey:"system-toolchain"、mirror:"cn"(扩展字段)、hint、installCmd。组件对象:key/name/note/estimate/installed/version/path/probes,以及 fields[](key,label,default,placeholder,help,value,value 为已保存值)。
PUT body {"fields": {"NODE_VERSION": "22"}}:未知字段 → 40000,空串回落默认值。响应 {key, fields, components}(components 为已保存参数的组件 key 排序列表)。
POST install body:
json
{ "components": ["node", "pnpm"], "dryRun": false, "force": false, "mirror": "cn" }components 空 = 全部缺失组件;mirror 只接受 cn/off(默认 cn);非 Linux 且非 dryRun → 40000。无可安装项时返回 {runId:0, nothingToDo:true, message};否则:
json
{ "runId": 101, "buildNumber": 5, "status": "queued",
"projectKey": "system-toolchain", "components": ["node", "pnpm"],
"dryRun": false, "command": "bash .../install-toolchains.sh",
"logUrl": "/api/v1/runs/101/log" }Run 参数注入已保存 fields + components + MIRROR。
中间件接口
组件与安装模式(详见 中间件管理):
| key | 支持模式 | 默认 |
|---|---|---|
docker | native | native |
postgresql / mysql | docker + native | docker |
redis | docker + native | docker |
elasticsearch | docker | docker |
| 方法与路径 | 权限 | 说明 |
|---|---|---|
GET /system/middleware | 登录 | 清单与状态 |
PUT /system/middleware/{key} | admin | 保存参数与模式 |
POST /system/middleware/install | admin | 触发操作 Run(内置项目 system-middleware) |
GET /system/middleware/script | admin | 下载 install-middleware.sh |
列表在工具链结构上追加 dockerAvailable、dockerVersion、running[]、mirror:"cn"。组件对象追加:installed、running、mode(保存值)、effectiveMode(实际生效)、nativeSupported、probes[]({name,found},缓存 5 秒)。
密码类字段:value 恒为空串,用 set:true/false 表示是否已配置;密文 AES-GCM 存于设置项 middleware.<key>。PUT body {fields, mode} 中密码三态:字段缺省或 "******" = 保留原值,空串 = 清除,其它 = 覆盖;普通字段空串回落默认;未知字段 → 40000。响应 {key, fields, mode}。
POST install body:
json
{ "components": ["redis"], "action": "install",
"mode": "docker", "dryRun": false, "force": false, "mirror": "cn" }action:install(默认)| start | stop | restart | upgrade | logs | remove。components 为空只允许 action=install(操作全部);不支持的组件/模式组合 → 40000;mirror 不做枚举校验,仅 "off" 生效(与工具链不同)。响应在工具链结构上追加 action。Run 参数含解密后的密码与 mode.<key>、action、components(脚本需要真实值,属有意为之,注意 Run 详情的 params 可见性)。
用户管理(admin)
| 方法与路径 | 说明 |
|---|---|
GET /users | 分页列表,keyword 匹配用户名/昵称 |
POST /users | 创建,body {username, password, nickname?, email?, role?} |
PUT /users/{id} | 更新昵称/邮箱/角色/启用状态 |
DELETE /users/{id} | 删除 |
POST /users/{id}/reset-password | body {password},重置后强制改密 |
创建的用户 mustChangePassword=true,role 仅 admin 时保留、否则一律 user。保护规则(均返回 40000,契约写 40300,以源码为准):不能降级/禁用自己,不能降级/禁用/删除最后一个 admin,不能删除自己。删除用户时其项目转归当前操作 admin,其 API Token 级联删除。nickname/email 每次 PUT 均按传值写入(省略即清空)。
Git 凭据
| 方法与路径 | 权限 | 说明 |
|---|---|---|
GET /credentials | 登录 | 自己的 + 全局凭据 |
POST /credentials | 登录 | 创建 |
PUT /credentials/{id} | 属主/admin | 更新 |
DELETE /credentials/{id} | 属主/admin | 删除 |
POST /credentials/test-git | 登录 | 连通性测试 |
创建 body:
json
{ "name": "gitlab-robot", "type": "https_token",
"username": "robot", "secret": "glpat-xxxxxxxx", "global": false }name ≤64;type 为 https_token 或 ssh_key;secret 必填(token 或私钥 PEM),passphrase 可选;global:true 仅 admin 可设(全局凭据 user_id=0,人人可见可用)。响应对象 {id, name, type, username, createdAt}——secret/passphrase 永不回显。更新时 secret/passphrase 仅非空才覆盖。被项目引用的凭据删除 → 40900。
test-git body {gitUrl, credentialId?, branch?}:30 秒超时;branch 已解析但未参与测试。失败也返回 success:true,结果在 data 内:{ok:false, message};成功 {ok:true, message, sampleRefs}(≤20 条引用样例)。
个人 API Token
| 方法与路径 | 权限 | 说明 |
|---|---|---|
GET /tokens | 登录 | 自己的令牌数组(非分页) |
POST /tokens | 登录 | 创建,body {name, expiresInDays?} |
DELETE /tokens/{id} | 登录 | 删除自己的令牌 |
创建响应(token 明文仅此一次,无 lastUsedAt):
json
{ "id": 5, "name": "ci", "prefix": "dk_xxxxx",
"expiresAt": null, "createdAt": "2026-02-01T00:00:00Z",
"token": "dk_xxxxxxxx" }列表项 {id, name, prefix, expiresAt, lastUsedAt, createdAt}。dk_ + 32 位随机字符,仅存 SHA-256;认证语义见 认证与通用约定。
SSH 公钥(契约未列,源码提供)
GET /system/ssh-key(登录):读取当前服务进程用户 ~/.ssh 下 id_ed25519/id_rsa/id_ecdsa 的 .pub,data:{home, keys:[{type, keyPath, publicKey, fingerprint}]}。
POST /system/ssh-key(admin):body {"type":"ed25519"}(或 rsa,4096 位;缺省 ed25519)。对应私钥已存在 → 40900。生成后把公钥配到 Git 服务端即可配合 ssh_key 凭据或免密拉取。
审计日志(admin,契约未列)
GET /audit-logs:分页,action 精确匹配、username 模糊匹配。列表项:{id, userId, username, action, target, detail, ip, createdAt}。登录、触发、令牌调用、设置变更等敏感操作均会落审计。