#部署上线一个 Web 项目

这是一条可以从头照着做的部署流程。我们用 GitHub 仓库 snowykami/neo-blog 做例子，把博客服务从源码构建成镜像，发布到集群，再为前端创建访问入口。

neo-blog 是一个前后端分离项目：

开始前先确认三件事，缺一项都可能让后面的步骤卡住：

• 平台 API 和 worker 都在运行。
• 已经配置可用的运行集群。
• 已经配置镜像站，并且构建任务有权限推送镜像。

#1. 创建项目空间

进入“项目空间”，创建一个新的空间。这个空间用来放博客的前端、后端、数据配置和访问入口。

建议这样填：

创建完成后，进入这个项目空间继续操作。

#2. 创建应用

在项目空间里创建两个应用：

数据不用急着单独建应用。neo-blog 默认可以把数据放在后端的 /app/data，第一次上线时优先用后端部署配置里的数据卷解决；之后需要外部 PostgreSQL，再接入单独数据库服务。

#3. 绑定 GitHub 仓库

进入前端或后端应用的仓库设置，选择 GitHub，绑定：

snowykami/neo-blog

建议先确认：

同一个仓库只需要绑定一次。前端和后端部署配置都可以引用这个仓库，只是 Dockerfile 和构建上下文不同。

#4. 创建后端部署配置

先创建后端，因为前端需要知道后端地址。

后端环境变量至少建议设置：

如果先用 SQLite，给后端加一个数据卷：

#5. 创建前端部署配置

前端使用仓库里的 web/Dockerfile。

Dockerfile Build Args 会作为 BuildKit build-arg 传入 Dockerfile 的 ARG 指令，并随每次构建记录保存快照。它适合放 EMBED_WEB=true、VERSION=${{ github.sha }}、构建模式这类非密钥值；密码、Token、私有 npm 凭据等敏感值请放到项目空间“构建变量”里的密钥项。

前端环境变量建议设置：

如果平台展示的后端服务名不是 neo-blog-backend，用部署后的 Service 名替换 BACKEND_URL。

#6. 触发构建并发布

先构建后端，再构建前端。

推荐顺序：

1. 在后端部署配置里点击“触发构建”。
2. 等构建状态变成成功。
3. 创建后端 Release，等待运行状态正常。
4. 在前端部署配置里点击“触发构建”。
5. 等前端构建成功后创建 Release。
6. 打开应用部署列表，确认前端和后端都处于正常状态。

如果构建失败，先看构建日志末尾。常见原因：

#7. 创建访问入口

只给前端创建访问入口。后端保持集群内访问即可。

创建后，等访问入口状态正常，再打开：

https://blog.example.com

如果页面能打开，但登录、文章或接口请求异常，优先检查前端的 BACKEND_URL 和后端的 BASE_URL。

#8. 确认跑通后再打开自动化

第一次上线建议手动构建、手动发布。确认没有问题后，再逐步打开：

• 仓库 Webhook 自动触发构建。
• 构建成功后自动发布。
• 分支匹配，例如只让 main 自动发布生产环境。
• 标签匹配，例如 v* 发布稳定版本。

逐项开启后，每一步出了问题都容易定位，回滚也更清楚。