自动构建（Railpack）

自动构建（Railpack） 让 Pier 能够直接从 Git 仓库编译你的项目 —— 无需 Dockerfile、无需 buildpack 配置、也无需特定语言的脚手架。Pier 会调用 Railpack CLI（Railway 的开源构建器，也是 Nixpacks 的活跃继任者），它与 moby/buildkit 守护进程通信，生成一个 OCI 镜像，随后 Pier 会像运行其他任何服务一样运行它。

启用前须知

自动构建比其他部署方式要重得多。在主机上编译用户代码与运行预构建容器有着截然不同的资源开销：

	Dockerfile / Compose / Docker 镜像	自动构建（Railpack）
最低内存	512 MB	4 GB（Rust 需 8 GB）
可用磁盘	每个栈几 GB	40+ GB（BuildKit 缓存）
首次部署	数秒	1–10 分钟

如果你的 VPS 内存少于 4 GB，请改用 Dockerfile 或 Docker 镜像来源 —— 否则创建资源的表单会显示一条强警告，并且构建很可能会因 OOM 而被杀掉自身或主机上的其他进程。

支持的语言

Railpack 会从常见的标志文件自动检测项目类型。以下任何一种都无需任何配置：

语言 / 框架	检测依据
Node.js / Bun / Deno	`package.json`、`bun.lockb`、`deno.json`
Python	`requirements.txt`、`pyproject.toml`、`Pipfile`
Go	`go.mod`
Rust	`Cargo.toml`
PHP	`composer.json`
Java	`pom.xml`、`build.gradle`
Ruby	`Gemfile`
Elixir	`mix.exs`
Vite / Astro / Create React App	打包器配置 + 构建输出目录

底层工作原理

克隆 —— Pier 使用与其他 Git 来源（公开、部署密钥或 GitHub App）相同的 git 机制，将配置好的分支克隆到一个临时目录中。
检测 + 规划 —— railpack build 会分析源码树并生成一张 BuildKit LLB 图。与分层的 Dockerfile 不同，这张图是完全并行的 —— 相互独立的步骤会并发执行，而缓存是基于内容寻址的，而非逐行进行的。
构建 —— BuildKit 针对由 install.sh 启动的守护进程容器执行该图，生成一个标签为 pier-railpack/<service-id>:<deploy-id> 的 OCI 镜像。
运行 —— Pier 会合成一个指向新镜像的小型 docker-compose.yml，并将其交给与 Dockerfile 构建相同的 docker compose up 流程。Traefik 标签、自动 SSL、端口分配以及栈网络全部复用 —— 唯一新增的只有构建步骤。

自定义配置

对于需要覆盖默认行为的项目，在仓库根目录放置一个 railpack.json 即可 —— Railpack 会自动识别它，而 Pier 无需感知其存在。示例：

{
  "providers": ["node"],
  "buildAptPackages": ["libpq-dev"],
  "deploy": {
    "startCommand": "node dist/server.js"
  }
}

完整参考文档位于 railpack.com/configuration/file。

调优旋钮

三个环境变量（在 systemd 单元中或 install.sh 之前设置）以及一个 UI 标签页控制着自动构建的行为：

PIER_RAILPACK_MAX_PARALLEL_BUILDS=N —— 限制并发构建数量（默认 1）。也可在控制台的 设置 → 自动构建（Railpack） 中编辑。
PIER_BUILDKIT_MEMORY=4g —— moby/buildkit 容器的内存上限（默认 4g）。
PIER_SKIP_RAILPACK=1 —— 完全跳过预置流程。该卡片仍会保留在 UI 中，但构建尝试会显示一条明确的 “railpack binary not found” 消息。

故障排查

railpack binary not found in PATH 该主机是带着 PIER_SKIP_RAILPACK=1 安装的，或者 install.sh 未能下载发布版二进制文件。请在不带跳过标志的情况下重新运行 install.sh，或者从 github.com/railwayapp/railpack/releases 手动将二进制文件安装到 /usr/local/bin/railpack。

build failed (exit 137) —— OOM 被杀 你的构建超出了可用内存。要么将 VPS 升级到 4 GB 以上（Rust 需 8 GB），要么用更低的 PIER_BUILDKIT_MEMORY 约束 BuildKit，使其快速失败，而不是把相邻进程饿死。当主机内存少于 4 GB 时，Pier UI 会用一个红色横幅来呈现这一状态。

构建一直处于排队状态 为保护主机，Pier 默认将并发构建数限制为 1。如果多个用户同时部署，其余的会等待。如果你的主机有富余内存，可在 设置 → 自动构建（Railpack） 中提高该上限。

Could not detect language Railpack 未找到它能识别的标志文件。要么添加预期的锁文件（例如 npm 项目的 package-lock.json），要么放置一个声明了 providers 的 railpack.json，要么退回到使用 Dockerfile 来源。