Coolify 公开 Git 仓库部署与构建日志检查

目标

把一个可匿名克隆的公开 Git 仓库配置为 Coolify Application，完成首次部署，并从部署日志确认构建与启动过程。本文只适用于公开 HTTPS 仓库；私有仓库应选择官方文档列出的 GitHub App、Deploy Key 或其他受支持连接方式。

适用环境与准备

• 软件条目当前记录版本：Coolify v4.4.6（核对日期：2026-10-22）。
• 依据同日访问的 Coolify 官方滚动文档整理。官方文档没有在这些页面标注对应的精确应用版本；本稿步骤按该日期文档版本说明，不代表已在 v4.4.6 实例完成 GUI 实测，升级后菜单名称可能变化。
• 需要可登录的 Coolify 实例、至少一台已添加的部署服务器、一个可通过 HTTPS 匿名克隆的公开仓库，以及适配仓库的构建配置。首次尝试优先使用测试项目和不会影响生产数据的应用。
• 选择服务器和部署会消耗该服务器的构建、磁盘及运行资源。公开域名还需要正确的 DNS/代理配置；只想先验证部署时可按实例提供的测试域名说明操作。

操作步骤

1. 准备仓库地址并选择公开仓库方式

1. 从代码托管平台复制仓库的 HTTPS clone URL，例如 https://github.com/owner/project.git。确认仓库无需登录即可克隆；不要在 URL 中嵌入令牌、密码或个人访问凭据。
2. 在 Coolify 打开一个项目；没有合适项目时先创建一个测试项目。
3. 选择 + New > Public Repository，并按提示选择用于运行应用的服务器。
4. 粘贴 HTTPS 地址并选择 Check Repository。检查加载出的仓库和分支；若 URL 带有分支路径，Coolify 可能预选该分支，部署前仍应核对。

2. 选择构建方式并配置应用

1. 选择与仓库内容相符的 Build pack：框架可自动识别时选 Nixpacks 或 Railpack；已构建好的静态文件选 Static；仓库提供单个 Dockerfile 时选 Dockerfile；仓库以 Compose 管理多个服务时选 Docker Compose。Railpack 在官方文档中标为 Beta。
2. 按仓库结构设置基础目录及该构建方式所需的命令或文件路径。若应用源码不在仓库根目录，先检查根目录设置，再处理构建错误。
3. 对非 Compose Application，在 Ports Exposes 填入应用进程实际监听的容器端口；不要把主机端口或数据库端口误作应用端口。需要外部访问时配置域名，并确认 DNS/代理指向所选服务器。
4. 保存配置后检查 General 中显示的仓库、分支和构建方式是否与预期一致。

3. 部署并检查日志

1. 选择 Deploy 发起首次部署。部署会进入 Coolify 队列；等待该操作结束，避免因尚在队列中而重复点击。
2. 在应用页打开 Deployment Logs，选择本次部署记录。
3. 检查日志中的所选源版本、镜像构建或拉取、生成配置和容器操作。先定位第一条失败命令及其上下文，不只看最后的退出状态。
4. 部署成功后打开配置的域名或测试 URL，确认应用返回预期页面。仅有构建成功不代表应用已能从外部访问。

预期结果

部署记录显示成功，日志对应所选仓库版本并完成所需镜像与容器操作；配置域名可访问应用。本文依据官方文档整理，未连接或操作真实服务器，也未声称本教程步骤经过实测。

常见问题与恢复

• Check Repository 失败： 再核对 URL 是否为 HTTPS clone 地址以及仓库是否公开可匿名克隆。私有仓库不适用 Public Repository；不要把访问令牌发给他人或写进仓库 URL，改用官方支持的私有仓库连接类型。
• 分支或代码版本不对： 在部署前核对 Coolify 识别的分支；确认目标分支确实包含应用代码和构建文件，再重新发起部署。
• 找不到构建文件或依赖： 确认基础目录与仓库布局一致，并核对所选 Build pack。静态文件、单一 Dockerfile 和多服务 Compose 项目需要不同构建方式。
• 构建日志报错： 打开本次 Deployment Logs，从第一条失败命令开始排查仓库依赖、构建命令和文件路径。修正配置后再 Deploy；失败的源代码构建不会替换当前正在运行的应用，但后续步骤的失败影响取决于替换路径和健康检查配置。
• 部署成功但域名打不开： 核对非 Compose 应用的容器监听端口、域名配置、DNS 与代理状态。先用实例提供的测试地址区分应用端口问题和自定义域名问题。
• 直接仓库地址无法自动部署新提交： 公开仓库 URL 本身不会配置自动部署。按官方指南额外配置手动 Git webhook，或改用支持所需自动配置的 Git App/外部工作流。

FAQ

公开仓库需要先添加 GitHub App 吗？
无需。匿名可克隆的 HTTPS 仓库可以使用 Public Repository；需要私有仓库访问或集成能力时，按官方对应指南配置其它来源方式。

为什么 Check Repository 能通过，构建仍失败？
该检查用于加载仓库和分支，不保证项目依赖、构建方式、基础目录或命令一定正确；这些问题需结合本次 Deployment Logs 排查。

Public Repository 会自动部署每次提交吗？
不会。官方文档明确说明，仅填公开仓库 URL 不会启用自动部署；需要另行配置 webhook 或外部工作流。

来源与核验范围

核验日期：2026-10-22（Asia/Shanghai）。访问 Coolify 官方文档站返回 403；为核对页面内容，读取了 Coolify 官方文档仓库 coollabsio/coolify-docs 的公开源码。读取时 main 分支提交为 44ea7dcc2548ec6fd65e744f8dd5856ba5990e39（2026-10-22T15:52:23Z）。以下为对应官方文档页面，链接用于读者查阅当前版本：

• Public Repositories：HTTPS 地址、Check Repository、分支与部署流程。
• Choose a Deployment Method：公开仓库、构建方式、端口与日志核对。
• Build applications：Build pack/strategy 及构建方式适用场景。
• Deploy applications：Deployment Logs、日志字段及失败后的排查入口。
• Coolify 文档源码：public-repositories.mdx
• Coolify 软件条目：本稿关联的站内软件记录。