Skip to content

中间件、工具链与系统接口 ​

本页覆盖系统探活/诊断/设置、工具链与中间件安装(内置「安装即运行」模式),以及设置页背后的用户、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/installadmin触发安装 Run
GET /system/toolchains/scriptadmin下载 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支持模式默认
dockernativenative
postgresql / mysqldocker + nativedocker
redisdocker + nativedocker
elasticsearchdockerdocker
方法与路径权限说明
GET /system/middleware登录清单与状态
PUT /system/middleware/{key}admin保存参数与模式
POST /system/middleware/installadmin触发操作 Run(内置项目 system-middleware)
GET /system/middleware/scriptadmin下载 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-passwordbody {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}。登录、触发、令牌调用、设置变更等敏感操作均会落审计。