Skip to content

核心概念 ​

本页定义全文使用的术语。每个概念给出精确定义与深入章节链接。

项目(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 Tokendk_CLI/脚本长期鉴权,可撤销;推荐自动化使用
Hook Tokenhk_触发运行的 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|lib05
任务task / steps06
运行run / runId、buildNumber07
命令/步骤command / step05.3、06.2
钩子hook / hk_07.4
自检doctor09.4