私有仓库（SSH Deploy Key）

通过 SSH deploy key 从私有 Git 仓库部署 —— 仓库范围、只读。

Application #git#ssh#private#deploy-key#repository

使用 SSH deploy key 从私有 Git 仓库部署。你生成密钥对，将公钥注册为仓库上的 deploy key，将私钥粘贴到 Pier —— Pier 通过 SSH 克隆，构建 Dockerfile 并运行容器。当你想要仓库范围、可撤销、只读访问时私有仓库的推荐身份验证方法。

使用 Pier 部署

1 打开 Pier 控制台，点击 Add service。
2 从模板列表中选择 Private Repository (Deploy Key)。
3 选择版本、设置服务名称，Pier 会自动配置容器、存储和端口。
4 如需 HTTPS，请绑定域名。Traefik 会自动签发 Let's Encrypt 证书。

什么是私有仓库（Deploy Key）模板？

使用 SSH deploy key —— 范围限定为 Git 主机上单个仓库的密钥对 —— 将私有 Git 仓库部署到 Pier。你在本地生成密钥对，在你的仓库设置上注册公钥为 deploy key（只读即可），并在创建服务时将私钥粘贴到 Pier。Pier 通过 SSH 克隆仓库、构建 Dockerfile、运行容器。

与使用个人访问 token (PAT) 或 SSH 用户密钥相比，每仓库 deploy key 严格更好 —— 范围窄、独立可撤销，泄露仅妥协该一个仓库，不是你的整个账户。

Pier 如何部署它

你提供：

Git SSH URL（例如 [email protected]:myorg/myrepo.git）
分支（或标签 / commit SHA）
deploy 密钥对的 SSH 私钥
Dockerfile 路径和容器端口

Pier 将私钥加密存储在其数据库中，仅在克隆时解密，通过 SSH 执行浅 git clone，运行 docker buildx build，并启动容器。BuildKit 缓存 + Traefik HTTPS 与其他 Git/Dockerfile 模板相同地工作。

从服务设置生成 webhook URL 并将其添加到你的 Git 主机（webhook 是普通 HTTP POST 且不需要 SSH 身份验证）以进行推送部署。

何时不要使用本模板

如果仓库是公共的，使用公共仓库模板 —— 不需要密钥。如果你在一个组织下有许多私有仓库并想要单一身份验证表面，GitHub App auth（下一个模板）扩展更好。对于非 Dockerfile 自动构建，使用指向 Git URL 的 Railpack。对于预构建镜像，使用 Docker 镜像。Deploy Key 是少数私有仓库的正确答案，其中每仓库范围身份验证很重要。

核心功能

仓库范围访问

Deploy key 范围限定为一个仓库（在 GitHub 上）或一个项目（在 GitLab 上）。妥协仅影响该仓库，不影响你的整个账户。

默认只读

Deploy key 可以作为只读添加 —— Pier 只需克隆，不需要推送。

与任何 Git 主机一起工作

GitHub、GitLab、Bitbucket、Gitea、Forgejo、sourcehut —— 任何带 SSH 访问和 deploy key 支持的地方。

每服务密钥对

每个 Pier 服务生成一个新的密钥对。每个都从 Git 主机独立可撤销。

Dockerfile 驱动构建

与公共仓库模板相同的构建引擎 —— Dockerfile + BuildKit + Traefik HTTPS。

Webhook redeploy

将 Pier webhook URL 添加到你的 Git 主机；推送触发 redeploy。

应用场景

私有应用代码

你的私有应用程序在 Git 主机上的主仓库。Pier 通过 SSH 克隆、构建、发布。

客户 / 客户端项目

客户端项目的仓库不应该访问你的其他仓库。Deploy key 隔离它。

Fork / 私有镜像

上游项目的私有 fork —— deploy key 让 Pier 只读访问，而不触及你的账户范围 token。

多仓库 monorepo 分解

带 N 个服务的单个 Pier 实例，每个指向不同的私有仓库，每个有自己的 deploy key。

审计友好

每服务密钥意味着撤销是粒度的 —— 解雇承包商，删除密钥，完成。

代码示例

生成 deploy key (ed25519) bash

ssh-keygen -t ed25519 -C "pier-deploy-myrepo" -f ~/.ssh/myrepo_deploy
# 文件：~/.ssh/myrepo_deploy（私钥），~/.ssh/myrepo_deploy.pub（公钥）

在 GitHub 上注册公钥 text

仓库 → 设置 → Deploy keys → 添加 deploy key
  标题：pier-deploy
  密钥：（粘贴 myrepo_deploy.pub 的内容）
  ✔ 允许只读（默认；除非需要否则不授予写）
→ 添加

将私钥粘贴到 Pier text

Pier → 创建服务 → 私有仓库（Deploy Key）
  Git URL (SSH): [email protected]:myorg/myrepo.git
  分支：main
  私钥：（粘贴 ~/.ssh/myrepo_deploy 的内容）
  Dockerfile 路径：/Dockerfile
  端口：3000
→ 部署

旋转密钥（撤销 + 重新生成） bash

# 1. 生成新密钥对
ssh-keygen -t ed25519 -f ~/.ssh/myrepo_deploy_v2

# 2. 在 GitHub 上添加新公钥，删除旧的
# 3. 更新 Pier 服务的私钥，redeploy
# 4. 旧密钥死了；只有新的工作

对比

vs 公共仓库模板（本目录）	对实际上是公共的仓库使用公共 —— 无需身份验证。对私有仓库使用 Deploy Key。
vs GitHub App 模板（本目录）	GitHub App 身份验证在一个组织下的许多私有仓库上扩展更好（一个应用授权多个仓库）。Deploy Key 是每仓库的。对于少数私有仓库，Deploy Key 更简单。
vs HTTPS 上的个人访问 token (PAT)	PAT 工作但通过 PAT 的身份验证给 Pier 访问所有你的私有仓库。Deploy Key 范围限定为一个仓库 —— 严格更好的安全性。
vs GitLab 项目访问 Token	GitLab 项目级别的 PAT 在范围上像 deploy key。任一身份验证方法在 Pier 上都工作；SSH deploy key 更通用。

常见问题

ed25519 还是 RSA？

如果你的 Git 主机支持，始终 ed25519（GitHub、GitLab、Bitbucket 都支持）。比 RSA 更小、更快、更好的安全性。

私钥住在哪里？

在 Pier 数据库中加密，仅在克隆时解密。它从不出现在日志或导出中。

密钥可以是读写吗？

是，如果你在 Git 主机端授予写，但 Pier 只需要读。默认为只读。

如果我在 Pier 中丢失私钥怎么办？

旋转 —— 生成新密钥对，注册新公钥，更新 Pier 存储的私钥，从 Git 主机删除旧公钥。

每部署或共享密钥对？

每部署。每个 Pier 服务应该有自己的密钥对。不要跨服务重用密钥。

机器人 / 系统账户 deploy key？

GitHub 还允许机器用户 PAT 进行多仓库访问。对于少数私有仓库，每仓库 deploy key 更简单。

webhook 如何设置？

与公共仓库相同的流程 —— Pier 生成 webhook URL，你将其粘贴到 Git 主机的仓库设置。webhook 本身不需要 SSH 身份验证。

在你的 VPS 上部署

部署此服务 →