全栈应用服务器 > 使用指南 > 一键部署 > 部署配置文件

部署配置文件

最近更新时间: 2026-09-03 15:55:05

部署配置文件

一键部署默认读取仓库根目录下的 .qiniu/deploy.yaml。在新建部署页面中，也可以指定仓库内的其他相对路径。配置文件必须是单个 YAML 文档，大小不超过 64 KiB，协议版本必须为 1。

配置示例

version: 1
workingDirectory: apps/web
installCommand: npm ci
startCommand: npm run start -- --host 0.0.0.0 --port 3000
port: 3000
healthcheck:
  path: /health
  timeoutSeconds: 60

字段说明

字段	必填	说明
`version`	是	配置协议版本，当前只能填写 `1`。
`workingDirectory`	否	命令执行目录，相对于仓库根目录；省略时使用 `.`。不能填写绝对路径或逃逸仓库的路径。
`installCommand`	是	安装依赖的命令，例如 `npm ci` 或 `pip install -r requirements.txt`。
`startCommand`	是	启动长期运行 HTTP 服务的命令。
`port`	是	应用监听的 TCP 端口，范围为 `1`～`65535`。
`healthcheck.path`	否	就绪检查请求的 HTTP 路径，省略时为 `/`；不能包含域名、查询参数或片段。
`healthcheck.timeoutSeconds`	否	就绪检查最长等待时间，省略时为 `60` 秒，必须为正数。平台最多等待 `300` 秒，超过 `300` 秒时按 `300` 秒执行。

运行要求

启动命令必须以前台方式运行服务，不能启动后立即退出。
服务必须监听 0.0.0.0:<port>；只监听 127.0.0.1 会导致公网健康检查失败。
健康检查路径应返回成功 HTTP 状态，建议使用不需要登录的轻量接口。
安装命令和启动命令会在 Sandbox 的非特权部署用户和 workingDirectory 中执行。
不要在仓库文件、命令参数或应用输出中写入 API Key、Secret 或 GitHub Token。

配置校验

平台会拒绝未知字段、多文档 YAML、无效 UTF-8、路径穿越、非法端口和不安全的健康检查路径。配置校验失败时不会创建 Sandbox，也不会执行安装或启动命令。

平台会为配置文件生成 configHash，并将它与 Commit SHA 一起绑定到 Revision。修改配置后需要重新创建或重新部署，历史 Revision 不会被修改。

以上内容是否对您有帮助？