Zeabur 部署

Zeabur 是 01MVP 当前推荐的生产部署路径。应用以 Docker 服务运行在 Zeabur，PostgreSQL 数据库也托管在 Zeabur 项目内，Cloudflare 负责 DNS、HTTPS 和基础安全防护。

部署全程在终端完成，不需要打开 Zeabur Dashboard。

一句话部署

部署 01MVP 到 Zeabur 只需要三步：

安装 Agent Skills

npx zeabur@latest auth login
npx skills add zeabur/agent-skills
npx skills add https://github.com/cloudflare/skills

npx skills 会从 GitHub 下载 skill 文件到本地，教 AI 代理如何操作 Zeabur CLI 和 Cloudflare CLI。只需安装一次即可。

部署项目

在 Claude Code 或其他支持 Agent Skills 的终端中说：

帮我把当前项目部署到 Zeabur，配好 PostgreSQL 数据库，开启定时备份

AI 代理会自动完成：识别框架 → 部署项目 → 创建并配置 PostgreSQL 数据库 → 打开自动备份。

绑定域名

接上一步，或者项目跑起来之后说：

帮我在 Cloudflare 上设置域名 xxx.com 指向这个服务

AI 代理会自动在 Cloudflare DNS 添加 A 记录指向 Zeabur 服务器 IP，并在 Zeabur 上绑定域名。

整个过程只需要几段对话，不需要手动写 Dockerfile（Zeabur 会自动检测 TanStack Start 框架）、不需要手动配数据库连接串、不需要进 Dashboard 贴环境变量。

如果中间遇到问题（比如端口不匹配、服务启动顺序错乱），直接告诉 AI 代理错误现象，它会自动拉日志、诊断并修复。

层级	选择	说明
应用运行时	Zeabur Docker 服务	使用仓库根目录的 `Dockerfile`
数据库	Zeabur PostgreSQL	使用 Zeabur 项目内的内网地址，默认开启自动备份
域名与代理	Cloudflare	A 记录指向 Zeabur 服务器 IP，正式上线后开启代理
统计	Cloudflare Web Analytics / Umami / GA4	不依赖平台内置 Analytics
自动部署	Zeabur Git Deploy	连接 GitHub 仓库后 push 自动部署

数据库：Zeabur PostgreSQL

建议通过 AI Agent 创建数据库，无需手动操作。以下内容供了解配置细节。

Zeabur 项目内可以直接部署 PostgreSQL 服务，和应用运行在同一网络，可以使用内网地址连接，避免数据库连接经过公网。

开启定时备份

Zeabur PostgreSQL 默认可以在 Dashboard 中开启自动备份。建议上线后立即配置：

在 Zeabur Dashboard 找到 PostgreSQL 服务
进入 Backup 选项卡
开启自动备份，设置每日备份时间（建议凌晨低峰期）
备份保留天数按需要设置（推荐 7-14 天）

备份文件存储在 Zeabur 对象存储中，需要恢复时可以在 Backup 页面一键还原。

手动 CLI 部署数据库

如果不用 Agent Skills，也可以手动部署数据库：

# 部署 PostgreSQL
npx zeabur@latest deploy \
  --project-id <project-id> \
  --template POSTGRESQL \
  --json -i=false

# 查看数据库连接信息
npx zeabur@latest service list --project-id <project-id> -i=false --json

然后在应用的环境变量中设置内网 DATABASE_URL：

DATABASE_URL=postgresql://user:pass@<internal-host>:5432/mvp?sslmode=require

环境变量同步

以 .env.prd 为生产变量源，同步到 Zeabur Web 服务。公开 URL 用 Zeabur 的域名变量生成，后续换域名时不需要改镜像里的默认值。

VITE_WEB_URL=https://${ZEABUR_WEB_DOMAIN}
VITE_SERVER_URL=https://${ZEABUR_WEB_DOMAIN}/api

使用 ZEABUR_WEB_DOMAIN，不要直接用 ZEABUR_WEB_URL；后者通常带尾部斜杠，拼接 /api、OAuth 回调或 canonical URL 时容易多出斜杠。

通过 Agent Skills，可以一句话更新环境变量：

把 .env.prd 里的变量同步到生产环境

如果数据库和应用在同一个 Zeabur 项目内，DATABASE_URL 使用内网主机名，不要依赖 port-forward 暴露的公网端口。

Cloudflare 设置

正式上线时，Cloudflare 是域名入口，不是应用运行时。

DNS：A your-domain.com -> <Zeabur server IP>
代理：证书完成后开启小橙云
SSL/TLS：使用 Full 或 Full (Strict)
WAF：先开启托管规则和基础速率限制，观察误伤后再加严格规则
Analytics：可先启用 Cloudflare Web Analytics

不要把 Zeabur 服务名直接当域名暴露。先查服务器 IP：

npx zeabur@latest server list -i=false --json

数据库迁移

生产数据库变更必须使用 migration。当前模板默认使用显式迁移：部署生产代码前运行 vpr @01mvp/product#db:deploy，执行已经提交的 migration 文件。

迁移前确认连接的是生产库（输出主机名和数据库名，不要输出完整密码）：

node -e 'const u=new URL(process.env.DATABASE_URL); console.log(u.host, u.pathname)'

永远先迁移，后部署应用。新代码可能依赖新表结构。

Docker 注意事项

Dockerfile 应保留在仓库根目录，构建上下文也是仓库根目录
ZBPACK_APP_DIR=products/01mvp/apps/web
ZBPACK_DOCKERFILE_NAME=Dockerfile
TanStack Start standalone 只在 Docker 构建中启用
真实密钥只进 Zeabur Variables，不写入 Dockerfile 或 Git
数据库 migration 单独执行，不放进镜像 build
运行时日志用 Zeabur Runtime Logs 检查，不只看构建成功

GitHub 自动部署

Zeabur 支持 Git Deploy。连接 GitHub 仓库后，每次推送指定分支都会自动部署。

npx zeabur@latest service search-repo <keyword> --json -i=false
npx zeabur@latest service deploy --json -i=false \
  --project-id <project-id> \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name main

注意：CLI 的 Git Deploy 流程通常会创建一个 Git 源服务。已有的直接上传服务如果要改成 Git 源，优先在 Zeabur Dashboard 里绑定仓库，或创建新的 Git 服务后再迁移域名，避免误建重复生产入口。

部署后验证

Zeabur deployment 状态为 RUNNING
自定义域名状态为 PROVISIONED
Cloudflare DNS 指向 Zeabur 服务器 IP，并按计划开启代理
Cloudflare Web Analytics 能看到生产域名访问数据
/api/health 返回 healthy，数据库检查为 pass
首页、登录页、AI 页面和文档页返回 200
Runtime Logs 没有缺表、缺环境变量、OAuth origin 错误
PostgreSQL 定时备份已开启
PostgreSQL port-forward 已关闭，避免长期暴露数据库公网端口