主题
项目与任务管理
项目与任务的分工
项目(/projects)用于「拉代码 + 构建 + 部署」的应用交付; 任务(/tasks)用于「跑一件事」:压测、巡检、清缓存等,不拉代码、不参与依赖构建。 两者的列表、编辑、详情页面完全同构,本页以项目为主线,差异集中在一节说明。 字段的服务端语义见项目定义与任务定义。
列表页操作
| 操作 | 说明 |
|---|---|
| 搜索 | 按 Key 或名称关键字过滤;项目列表还可按类型(应用 / 构建)过滤 |
| 归档切换 | 分段按钮:未归档(active)/ 已归档(archived)/ 全部(all),默认只看未归档 |
| 只看我的 | 工具栏按钮,仅显示自己归属的项目 / 任务 |
| 执行 | 触发一次运行并跳转运行详情。有依赖的项目显示下拉按钮:「含依赖执行(推荐)」或「仅执行本项目」;任务无此区分 |
| 详情 / 编辑 | 进入详情页 / 编辑页 |
| 归档 / 恢复 | 已归档对象不能再执行,恢复后可继续使用 |
| 删除 | 二次确认后删除,连带删除运行历史与日志文件,不可恢复 |
编辑、归档、删除仅对归属者(canEdit)或 admin 显示;已归档行的「执行」按钮置灰。 新建入口在工具栏右侧(/projects/new、/tasks/new)。
编辑页:Git 准备卡片(仅项目)
开关 useGit 关闭时平台不拉代码,直接在工作目录执行命令。开启后:
| 字段 | 说明 |
|---|---|
| gitUrl | 仓库地址,开启 Git 后必填。新建时会根据地址自动推断 Key、名称与工作目录 |
| gitBranch | 分支 / Tag / Commit,默认 main |
| gitCredentialId | Git 凭据下拉(HTTPS Token / SSH Key),公开仓库可留空;在凭据管理创建 |
| gitSubdir | 仓库子目录,monorepo 场景(如 apps/web) |
| gitDepth | 浅克隆深度,0 表示完整克隆 |
| gitClean | 拉取前执行 git clean -fdx,会删除所有未跟踪文件,慎用 |
| gitSubmodule | 递归拉取子模块 |
若环境自检发现服务器缺少 git,卡片内会给出警告提示。
编辑页:基本信息卡片(项目与任务相同)
| 字段 | 说明 |
|---|---|
| key | 唯一标识,用于 URL 与 Hook;字母开头,可含字母数字 _ -,最长 64 位;创建后不可改;new 为保留字 |
| name | 显示名称,必填 |
| workdir | 工作目录,必填;新建时自动预填 /srv/workspaces/<key>,手动改过则不再覆盖 |
| concurrency | 并发策略:queue 排队(默认)/ allow 允许并行 / cancelPrev 取消上一次 |
| shell | auto(默认,按平台自选)/ bash / sh / pwsh / cmd |
| timeoutSec | 默认超时秒数,0 表示不限制 |
| description | 描述,可选 |
| hookEnabled | 是否允许 Hook 触发,默认开 |
| allowEnvOverride | 是否允许触发时通过 env 参数覆盖环境变量,默认开 |
编辑页:项目类型与依赖构建(仅项目)
- kind:app 应用项目(默认)或 lib 构建项目(产出制品供其他项目依赖)。
- dependencies:多选依赖项目;任何项目都可被依赖,已归档的候选项置灰。
- 编辑已有项目时展示依赖构建顺序(如
lib-a → lib-b → 本项目); 依赖成环或不可用时给出红色错误提示,含依赖执行会被服务端拒绝。
编辑页:环境变量与命令 / 步骤
环境变量卡片(两者相同):每行 key / value / isSecret。 Secret 变量编辑时显示占位符 ******,不改则提交时沿用原值; 详情页与运行日志不回显明文。优先级说明见卡片内提示与项目定义。
命令列表(项目叫「命令」,任务叫「步骤」,同一个编辑器组件)按顺序执行:
| 字段 | 说明 |
|---|---|
| name | 命令 / 步骤名称 |
| script | 脚本内容 |
| enabled | 是否启用,停用的行跳过 |
| failStrategy | 失败策略:abort 中止(默认)/ continue 继续 |
| workdirOverride | 覆盖本条命令的工作目录,可选 |
| timeoutSec | 覆盖本条命令的超时,0 用项目默认 |
| shellOverride | 覆盖本条命令的 Shell,可选 |
保存时按当前排列顺序重排 sortOrder,空行自动丢弃。
项目与任务差异速查
| 维度 | 项目 | 任务 |
|---|---|---|
| Git 准备卡片 | 有 | 无 |
| 类型与依赖构建卡片 | 有(kind / dependencies) | 无 |
| 脚本列表 | 命令(commands) | 步骤(steps) |
| 执行方式 | 可含依赖执行 | 直接执行 |
| 列表列 | 类型图标、依赖、Git 信息 | 步骤数 |
| Key 自动推断 | 可从 gitUrl 推断 | 仅按手填 Key 联动名称与工作目录 |
详情页:运行与历史
- 顶部「执行」按钮:有依赖的项目为下拉按钮(含依赖 / 仅本项目);已归档或无权限时置灰。
- 基本信息、环境变量(Secret 打码)、命令 / 步骤表;命令行可展开看脚本, 并提供「单独执行」——只跑这一条命令。
- 依赖关系提示:本项目的依赖构建顺序、以及「被哪些项目依赖」。
- 运行历史表:构建号、状态、触发方式 / 触发人、分支、耗时、开始时间,点击进运行详情。
详情页:Hook Token 管理(内嵌)
项目与任务详情页都内嵌 Hook Token 卡片,无独立路由:
- 点「新建 Hook Token」,填名称与有效天数(留空永不过期)。
- 创建成功后弹窗展示明文 token,仅此一次——服务端只存哈希,关闭弹窗后无法再查看, 请立即复制保存。
- 列表展示名称、前缀、启用状态、过期时间、调用次数、最近使用时间与来源 IP。
- 「重置」生成新 token,旧 token 立即失效;「删除」使调用方立刻失败,均有二次确认。
卡片内附可复制的 curl 示例:POST /api/v1/hooks/{token},也支持 X-Deploy-Token 请求头方式与 ?wait=true / "async": false 同步等待。详见 HTTP Hook。
归档与删除的区别
| 操作 | 数据 | 可执行 | 可逆 |
|---|---|---|---|
| 归档 | 定义、运行历史、日志全部保留 | 否(按钮置灰,Hook 拒绝) | 是,随时恢复 |
| 删除 | 定义、运行历史与日志文件连带删除 | - | 否,不可恢复 |
临时停用的项目建议归档而非删除;被其他项目依赖的对象删除前应先看详情页的 「被依赖」提示,避免依赖方含依赖执行失败。