主题
项目与任务接口
项目(构建 + 部署,可有 Git 准备与依赖构建)与任务(一次性运维作业,无 Git、无依赖)共用执行引擎、Run 表、日志与 Hook,权限模型也一致(见 认证与通用约定)。概念背景见 项目定义 与 任务定义。
项目路由总览
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /projects | 登录 | 分页列表,不含 commands/envs/dependencyPlan/dependents |
| POST | /projects | 登录 | 创建,key 唯一(重复 40900),owner 为当前用户 |
| GET | /projects/{key} | 可见 | 详情,含 commands/envs/dependencyPlan/dependents |
| PUT | /projects/{key} | owner/admin | 更新(语义见下) |
| DELETE | /projects/{key} | owner/admin | 删除,连带 runs、steps、命令、变量、Hook 令牌与日志文件 |
| POST | /projects/{key}/archive | owner/admin | 归档/取消归档,body {"archived":true} |
| GET | /projects/{key}/commands | 可见 | 命令数组(按 sortOrder 升序) |
| POST | /projects/{key}/commands | owner/admin | 新增命令,sortOrder 取当前最大值 +1 |
| POST | /projects/{key}/commands/reorder | owner/admin | body {"ids":[3,1,2]},按数组顺序重排 |
| PUT | /commands/{id} | owner/admin | 修改单条命令 |
| DELETE | /commands/{id} | owner/admin | 删除单条命令 |
| GET | /projects/{key}/envs | 可见 | 变量数组(契约未列此路由,源码已注册) |
| PUT | /projects/{key}/envs | owner/admin | 整体替换,body {"envs":[EnvVarInput]} |
| POST | /projects/{key}/preview | 可见 | 预演脚本与环境变量,不执行 |
| POST | /projects/{key}/run | owner/admin | 触发运行,见 运行与日志接口 |
| GET/POST | /projects/{key}/hooks | 可见 / owner/admin | Hook 令牌,见 Hook 接口 |
列表查询参数:page、pageSize、keyword(key/name 模糊)、mine=true(只看自己的)、kind=app|lib、archived 三态(不传/false=未归档,true/1=已归档,all=全部)。按 updatedAt 降序。
ProjectInput 字段
POST /projects 与 PUT /projects/{key} 共用同一载荷,commands 与 envs 可内联一次提交:
json
{
"key": "my-app", "name": "我的应用", "description": "",
"workdir": "/srv/deploy/workspaces/my-app",
"shell": "auto", "timeoutSec": 0, "concurrency": "queue",
"hookEnabled": true, "archived": false, "allowEnvOverride": true,
"kind": "app", "dependencies": ["tio-boot-admin"],
"useGit": false, "gitUrl": "", "gitBranch": "main", "gitCredentialId": null,
"gitSubdir": "", "gitDepth": 0, "gitClean": false, "gitSubmodule": false,
"commands": [{ "name": "构建", "script": "make build", "sortOrder": 1 }],
"envs": [{ "key": "MODE", "value": "prod", "isSecret": false }]
}| 字段 | 取值 / 默认 | 更新(PUT)语义 |
|---|---|---|
key | 字母数字开头,可含 ._-,1–64 字符 | 不可改(仅创建时校验) |
name | 必填(创建) | 空串保留原值 |
description | 字符串 | 传了就写,省略即清空 |
workdir | 缺省 ${WORKSPACE_ROOT}/${PROJECT_KEY} | 空串保留原值 |
shell | auto/bash/sh/pwsh/cmd,默认 auto | 空串保留原值 |
timeoutSec | ≥0,0=不限 | 传了就写,省略即归零 |
concurrency | queue(默认)/allow/cancelPrev | 空串保留原值;非法值 40000 |
hookEnabled / archived / allowEnvOverride / useGit / gitClean / gitSubmodule | 布尔,前两者默认 true | 指针语义:不传=不动,传 false 才生效 |
kind | app(默认)/ lib | 空串保留原值 |
dependencies | 项目 key 数组 | 不传=不动,[]=清空 |
gitUrl / gitSubdir / gitDepth / gitCredentialId | 字符串/整数/可空 id | 传了就写,省略即清空(gitCredentialId 省略置 null) |
gitBranch | 默认 main | 空串保留原值 |
commands / envs | 内联数组 | 不传=不动,[]=清空;传了即整体对齐 |
useGit=true 时 gitUrl 必填,否则 40000。创建/更新成功均返回完整详情(含 commands/envs/dependencyPlan/dependents)。
命令与命令 ID
Command 对象:
| 字段 | 说明 |
|---|---|
id / projectId | 数据库行 ID / 所属项目 |
name / script | 名称 / 脚本正文(script 不可为空,40000) |
sortOrder | 执行顺序,1 起;内联提交时传 0 按数组下标 +1 |
enabled | 默认 true;false 的命令运行时跳过 |
failStrategy | abort(默认,失败中止)/ continue(失败继续) |
workdirOverride / timeoutSec / shellOverride | 命令级覆盖,空/0=用项目值 |
createdAt / updatedAt | 时间戳 |
ID 语义(与任务步骤的关键区别):命令 ID 是数据库行 ID。整体提交 commands 时服务端按「带 id 且匹配 → 原地更新(ID 不变);不带 id → 新建(分配新 ID);未提交 → 删除」对齐。因此:
- CLI
deploy project update重新提交命令列表时不带 id,命令会被整体删除重建,ID 每次 update 重新生成——选择性运行(commandIds)前必须重新GET /projects/{key}读最新 ID。 - Web 编辑页提交时保留 id,ID 不变。
- 任务步骤没有行 ID,ID 就是位置序号,update 后不变(见下)。
PUT /commands/{id} 单条更新:name/script/failStrategy 空串保留原值,enabled 不传保留,workdirOverride/timeoutSec/shellOverride 传了就写,sortOrder 非 0 才改。
环境变量与 Secret
EnvVar 对象:{id, key, value, isSecret}。任务变量同构但无 id。
isSecret=true的变量value一律返回空串,密文 AES-GCM 落库;前端显示占位符******。- 提交时 Secret 的
value为******或空串 → 沿用原密文;非空新值 → 重新加密。 key不得含=、空格、制表符、换行(例如把MODE=prod整串当 key 的简写会被拒绝,40000);空 key 行直接忽略。PUT /projects/{key}/envs与内联envs都是整体替换:未提交的变量被删除。- 任务变量额外校验重名(
40000);项目变量不做重名校验(同名按行覆盖)。
json
{ "envs": [
{ "key": "MODE", "value": "prod", "isSecret": false },
{ "key": "API_KEY", "value": "******", "isSecret": true }
] }预览
POST /projects/{key}/preview(契约小标题误写为 GET,实际路由是 POST),body 可省略或 {"branch":"main","env":{"TAG":"v1.2.3"}}。返回将要执行的脚本与变量(Secret 脱敏),不执行:
json
{
"workdir": "/srv/deploy/workspaces/my-app",
"git": { "enabled": false, "url": "", "branch": "main", "subdir": "" },
"envs": [{ "id": 5, "key": "MODE", "value": "prod", "isSecret": false }],
"builtinEnvs": [
{ "key": "PROJECT_KEY", "value": "my-app" },
{ "key": "BUILD_NUMBER", "value": "(assigned at run time)" }
],
"script": "# 1. 构建\ncd /srv/deploy/workspaces/my-app\nmake build\n"
}类型与依赖
kind:app(应用项目,默认)/ lib(构建项目)。类型只影响默认命令与图标,任何未归档项目都可被选为依赖。
- 依赖必须存在、不能是自己、加入后不成环,违反返回
40000。 - 允许依赖已归档项目(保存不拦),但触发时拒绝并说明哪个依赖归档了。
- 详情返回
dependencyPlan(递归展开的构建顺序,{ok, error?, order:[{key,name,kind,archived,order}]})与dependents(谁依赖了我)。 - 触发时
withDependencies=true按拓扑序先构建依赖,同一项目只构建一次;详见 运行与日志接口。
任务路由总览
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /tasks | 登录 | 分页列表(含 stepCount,不含 steps/envs) |
| POST | /tasks | 登录 | 创建,key 唯一,steps/envs 内联 |
| GET | /tasks/{key} | 可见 | 详情,含 steps/envs |
| PUT | /tasks/{key} | owner/admin | 更新 |
| DELETE | /tasks/{key} | owner/admin | 删除,连带 runs、Hook 令牌与 tasks/<key> 日志目录 |
| POST | /tasks/{key}/archive | owner/admin | body {"archived":true} |
| POST | /tasks/{key}/preview | 可见 | 预演脚本 |
| POST | /tasks/{key}/run | owner/admin | 触发,见 运行与日志接口 |
| GET/POST | /tasks/{key}/hooks | 可见 / owner/admin | Hook 令牌,见 Hook 接口 |
列表参数与项目一致(page/pageSize/keyword/mine/archived 三态),没有 kind。任务没有单条步骤的 CRUD 与排序接口——步骤与变量只能内联整体保存。
TaskInput 与步骤 ID
json
{
"key": "clean-cache", "name": "清缓存", "description": "",
"workdir": "${WORKSPACE_ROOT}/${TASK_KEY}",
"shell": "auto", "timeoutSec": 0, "concurrency": "queue",
"hookEnabled": true, "allowEnvOverride": true,
"steps": [{ "name": "清理", "script": "rm -rf /tmp/cache/*", "sortOrder": 1 }],
"envs": [{ "key": "TARGET", "value": "/tmp/cache", "isSecret": false }]
}字段与 ProjectInput 同构,去掉 Git/kind/dependencies 相关项。更新语义:name/workdir/shell/concurrency 空串保留原值;description/timeoutSec 传了就写;布尔指针不传不动;steps/envs 不传不动、[] 清空、传了整体替换。key 不可改。
步骤字段与命令相同(name/script/sortOrder/enabled/failStrategy/workdirOverride/timeoutSec/shellOverride),但没有 id 字段:
- 步骤 ID = 位置序号(sortOrder,1 起),每次保存按数组位置重新编号,位置不变则编号不变,update 后稳定。
- 空脚本的步骤被丢弃;只填名字没填脚本返回
40000(名字脚本全空的行静默忽略)。 - 触发时
commandIds引用的就是位置序号,越界返回40000。
任务预览返回 {workdir, envs, builtinEnvs, script},内置变量为 TASK_KEY/TASK_NAME/WORKDIR/BUILD_NUMBER/DEPLOY_SERVER_URL,无 Git 段。