Skip to content

项目定义 ​

最小定义 ​

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 导出的内容改一改就能再建。

字段总表 ​

字段类型默认说明
keystring必填唯一标识;字母数字与 -_. 等,禁止 new
namestring必填显示名称
descriptionstring空备注
kindstringappapp 可部署应用 / lib 构建安装型库项目
dependenciesstring[][]前置项目 key 列表,见 依赖构建
workdirstring${WORKSPACE_ROOT}/${PROJECT_KEY}工作目录,支持占位展开
shellstringauto项目级解释器;命令级可覆盖
concurrencystringqueuequeue / allow / cancelPrev
timeoutSecint0整体超时秒数,0 不限时;命令级可覆盖
hookEnabledboolfalse是否允许 Hook 触发
allowEnvOverrideboolfalse是否允许触发参数覆盖变量
useGitboolfalse启用 Git 准备阶段
gitUrl / gitBranchstring空仓库地址与分支
gitCredentialIdint?null凭据 ID(私有仓库)
gitSubdirstring空仓库子目录作为工作目录
gitDepthint0clone 深度,0 完整
gitCleanboolfalse准备阶段 git clean -fdx
gitSubmoduleboolfalse更新子模块
commandsobject[][]有序命令,见 命令与脚本
envsobject[][]{key,value,isSecret};创建时可用 env 简写映射
archivedboolfalse归档标记,见 更新、归档与删除

只读返回字段: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 不生效。

平台差异:

行为LinuxWindows
默认解释器bash -lcPowerShell(-NoProfile -Command,优先 pwsh)
变量引用${BUILD_NUMBER}$env:BUILD_NUMBER
进程树取消进程组信号taskkill /T /F

并发与超时 ​

  • queue:同一目标串行排队(默认);allow:允许并行;cancelPrev:新运行先取消同目标在跑运行。
  • 全局另有并发闸门 maxConcurrentRuns(默认 5,系统设置可热调)。
  • timeoutSec 作用于整次运行;单命令可用自己的 timeoutSec 覆盖;Git 准备阶段单独超时(默认 600s)。

详见 运行生命周期与并发。

创建方式对照 ​

方式入口
CLI flagdeploy project create --key … --command …
CLI JSONdeploy project create --file project.json(命令可 scriptFile)
CLI 向导不带必需参数的 deploy project create
网页/projects/new 表单
APIPOST /api/v1/projects

字段语义各入口一致;--file 中显式 flag 覆盖同名字段、--command 整体取代文件 commands。