主题
核心概念
本页定义全文使用的术语。每个概念给出精确定义与深入章节链接。
项目(Project)
构建 + 部署的单元。拥有唯一 key、工作目录、有序命令列表、环境变量与 Secret,可选启用 Git 准备阶段与依赖构建。 项目适合「拉代码 → 构建 → 发布 → 重启 → 健康检查」这类重复性发布流程。详见 项目章。
任务(Task)
一次性运维作业的单元:勘察、改配置、清缓存、导数据。没有 Git 准备、没有依赖构建,步骤就是按顺序跑的 Shell。 任务与项目共用运行表、日志与 Hook。详见 任务章。
划分原则:要拉代码构建的是项目,只跑一件事的是任务。把巡检脚本做成项目不会报错,但会背上用不到的 Git/依赖语义,且命令 ID 不稳定;真实迁移教训见 HuLa 案例。
运行(Run)
一次触发产生一条 Run,有两个编号:
| 编号 | 含义 | 用途 |
|---|---|---|
| 运行 ID(runId) | 全局自增 | deploy logs <runId>、deploy stop <runId>、WS 跟随 |
| 构建号(buildNumber) | 项目/任务内第几次 | 日志头部 === Deploy Run #N ===、版本追溯 |
状态七态:queued、running、success、failed、timeout、error、canceled。 进入队列不代表成功;自动化必须等终态。详见 运行生命周期。
命令与步骤(Command / Step)
项目的基本执行单元叫命令,任务的叫步骤;字段结构相同(name/script/排序/启用/失败策略/工作目录覆盖/超时/Shell 覆盖),但 ID 语义不同:
- 项目命令 ID 每次
project update重新生成:选择性运行前必须重新project get读 ID。 - 任务步骤 ID 是位置序号(1 起),update 后不变:
task run --step-id N可直接引用。
失败策略 failStrategy:abort(默认,失败即中止)或 continue(忽略该步失败继续)。
工作目录(Workdir)
命令执行时的 cwd。默认 ${WORKSPACE_ROOT}/${PROJECT_KEY}(任务为 ${WORKSPACE_ROOT}/${TASK_KEY}), WORKSPACE_ROOT 即服务端配置的 workspaces 根目录。支持占位变量展开,命令级可覆盖。详见 项目定义。
环境变量与 Secret
项目/任务可配置普通变量与 Secret(envs 中 isSecret: true)。Secret 加密存储、读取不回显、在运行日志中自动遮蔽。 优先级由低到高:系统环境 → 普通变量 → Secret → 内置变量 → 触发参数(需开启「允许参数覆盖」)。详见 环境变量与 Secret。
凭据(Credential)与令牌(Token)
三种容易混淆的 secret:
| 名称 | 前缀/形态 | 用途 |
|---|---|---|
| Git 凭据 | https_token / ssh_key 等 | Git 准备阶段拉私有仓库;加密存服务端,可测试连接 |
| API Token | dk_ | CLI/脚本长期鉴权,可撤销;推荐自动化使用 |
| Hook Token | hk_ | 触发运行的 webhook 令牌,只存哈希,明文仅创建时展示一次 |
登录 JWT 会过期(默认 168 小时),无人值守流程请用 API Token。详见 凭据与 API Token。
并发策略与依赖
- 并发策略
concurrency:queue(同目标串行排队,默认)、allow(并行)、cancelPrev(先取消在跑的同目标运行)。 - 依赖构建:项目分
app/lib两类,dependencies声明前置项目;--with-dependencies触发时按拓扑序先建依赖,同一管道内去重、失败阻断。详见 依赖构建。
可见性(Visibility)与角色
服务端全局设置:allReadable(他人项目只读可见)或 ownerOnly(他人不可见)。 角色 admin/user;编辑与执行始终仅限 owner 或 admin。详见 用户、角色与可见性。
中间件与工具链
管理员可在服务端一键安装的基础设施:中间件(Docker、PostgreSQL、MySQL、Redis、Elasticsearch)与工具链(C/C++、Java、Maven、nvm、Node、pnpm、Go、Rust、Certbot)。 安装以普通 Run 执行、有日志可预演;实装仅 Linux 服务端。详见 工具链与中间件章。
术语对照速查
| 术语 | 英文/字段 | 深入 |
|---|---|---|
| 项目 | project / kind: app|lib | 05 |
| 任务 | task / steps | 06 |
| 运行 | run / runId、buildNumber | 07 |
| 命令/步骤 | command / step | 05.3、06.2 |
| 钩子 | hook / hk_ | 07.4 |
| 自检 | doctor | 09.4 |