Skip to content

项目与任务接口 ​

项目(构建 + 部署,可有 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}/archiveowner/admin归档/取消归档,body {"archived":true}
GET/projects/{key}/commands可见命令数组(按 sortOrder 升序)
POST/projects/{key}/commandsowner/admin新增命令,sortOrder 取当前最大值 +1
POST/projects/{key}/commands/reorderowner/adminbody {"ids":[3,1,2]},按数组顺序重排
PUT/commands/{id}owner/admin修改单条命令
DELETE/commands/{id}owner/admin删除单条命令
GET/projects/{key}/envs可见变量数组(契约未列此路由,源码已注册)
PUT/projects/{key}/envsowner/admin整体替换,body {"envs":[EnvVarInput]}
POST/projects/{key}/preview可见预演脚本与环境变量,不执行
POST/projects/{key}/runowner/admin触发运行,见 运行与日志接口
GET/POST/projects/{key}/hooks可见 / owner/adminHook 令牌,见 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}空串保留原值
shellauto/bash/sh/pwsh/cmd,默认 auto空串保留原值
timeoutSec≥0,0=不限传了就写,省略即归零
concurrencyqueue(默认)/allow/cancelPrev空串保留原值;非法值 40000
hookEnabled / archived / allowEnvOverride / useGit / gitClean / gitSubmodule布尔,前两者默认 true指针语义:不传=不动,传 false 才生效
kindapp(默认)/ 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 的命令运行时跳过
failStrategyabort(默认,失败中止)/ 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}/archiveowner/adminbody {"archived":true}
POST/tasks/{key}/preview可见预演脚本
POST/tasks/{key}/runowner/admin触发,见 运行与日志接口
GET/POST/tasks/{key}/hooks可见 / owner/adminHook 令牌,见 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 段。