主题
项目定义
最小定义
json
{
"key": "my-app",
"name": "我的应用",
"workdir": "/srv/deploy/workspaces/my-app",
"commands": [
{ "name": "构建", "script": "make build" },
{ "name": "发布", "script": "make install" }
]
}key 全局唯一、创建后不可改;保留 key new 不可用(与网页新建路由冲突)。 字段名与 API 一致:deploy project get <key> --json 导出的内容改一改就能再建。
字段总表
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
key | string | 必填 | 唯一标识;字母数字与 -_. 等,禁止 new |
name | string | 必填 | 显示名称 |
description | string | 空 | 备注 |
kind | string | app | app 可部署应用 / lib 构建安装型库项目 |
dependencies | string[] | [] | 前置项目 key 列表,见 依赖构建 |
workdir | string | ${WORKSPACE_ROOT}/${PROJECT_KEY} | 工作目录,支持占位展开 |
shell | string | auto | 项目级解释器;命令级可覆盖 |
concurrency | string | queue | queue / allow / cancelPrev |
timeoutSec | int | 0 | 整体超时秒数,0 不限时;命令级可覆盖 |
hookEnabled | bool | false | 是否允许 Hook 触发 |
allowEnvOverride | bool | false | 是否允许触发参数覆盖变量 |
useGit | bool | false | 启用 Git 准备阶段 |
gitUrl / gitBranch | string | 空 | 仓库地址与分支 |
gitCredentialId | int? | null | 凭据 ID(私有仓库) |
gitSubdir | string | 空 | 仓库子目录作为工作目录 |
gitDepth | int | 0 | clone 深度,0 完整 |
gitClean | bool | false | 准备阶段 git clean -fdx |
gitSubmodule | bool | false | 更新子模块 |
commands | object[] | [] | 有序命令,见 命令与脚本 |
envs | object[] | [] | {key,value,isSecret};创建时可用 env 简写映射 |
archived | bool | false | 归档标记,见 更新、归档与删除 |
只读返回字段:id、ownerId/ownerName、canEdit、lastRunAt/lastRunStatus、runCount、createdAt/updatedAt。 列表接口不返回 commands 与 envs,详情才返回。
workdir 展开
默认值 ${WORKSPACE_ROOT}/${PROJECT_KEY} 中的占位符在执行前展开: WORKSPACE_ROOT(服务端 workspaces 根)、PROJECT_KEY、PROJECT_NAME;任务对应 TASK_KEY、TASK_NAME。 也可以写绝对路径把项目指到工作区之外(例如直接操作 /srv/apps/...),但 Git 准备阶段要求目录为空或已是该仓库的工作区。
shell 选择
auto 的解析顺序:Unix 为 bash -lc → sh;Windows 为 pwsh → powershell → cmd。 优先级:命令级 shellOverride > 项目级 shell > 服务端全局配置。 注意 Unix 走登录 Shell:工具 PATH 要写在 /etc/profile 或 profile.d,只改 ~/.bashrc 不生效。
平台差异:
| 行为 | Linux | Windows |
|---|---|---|
| 默认解释器 | bash -lc | PowerShell(-NoProfile -Command,优先 pwsh) |
| 变量引用 | ${BUILD_NUMBER} | $env:BUILD_NUMBER |
| 进程树取消 | 进程组信号 | taskkill /T /F |
并发与超时
queue:同一目标串行排队(默认);allow:允许并行;cancelPrev:新运行先取消同目标在跑运行。- 全局另有并发闸门
maxConcurrentRuns(默认 5,系统设置可热调)。 timeoutSec作用于整次运行;单命令可用自己的timeoutSec覆盖;Git 准备阶段单独超时(默认 600s)。
详见 运行生命周期与并发。
创建方式对照
| 方式 | 入口 |
|---|---|
| CLI flag | deploy project create --key … --command … |
| CLI JSON | deploy project create --file project.json(命令可 scriptFile) |
| CLI 向导 | 不带必需参数的 deploy project create |
| 网页 | /projects/new 表单 |
| API | POST /api/v1/projects |
字段语义各入口一致;--file 中显式 flag 覆盖同名字段、--command 整体取代文件 commands。