实战手册Skills案例库工具库代码模板指南
部署指南
00 / 00

Zeabur 部署

用 Agent Skills 一句话部署 Muse 到 Zeabur，包含 PostgreSQL 定时备份和 Cloudflare 域名配置。

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

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

一句话部署

部署 Muse 到 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 上绑定域名。

整个过程只需要几段对话。Muse 已经提供 products/muse/Dockerfile，Zeabur 使用仓库根目录作为构建上下文，再通过这个 Dockerfile 构建 Muse Web 镜像。

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

推荐架构

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

服务 ID 与重复服务

Zeabur 的 Service ID 对应某一个具体服务实例。删除重建、迁移 Git Deploy、从模板重新创建服务后，旧 ID 会失效。部署、查日志、同步变量或排障前，先确认当前服务名、Service ID、绑定域名和最近一次 deployment：

npx zeabur@latest service list --project-id <project-id> -i=false --json
npx zeabur@latest deployment list --service-id <service-id> --env-id <env-id> -i=false --json

继续部署到已有服务时要传当前 --service-id。省略 --service-id 通常会创建一个新服务，容易出现代码部署成功但域名仍指向旧服务的情况。

如果项目的 .agents、AGENTS.md 或运维文档记录了 Zeabur Service ID，服务重建后也要一起更新，避免 AI 代理或脚本查到过期服务。

数据库：Zeabur PostgreSQL

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

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

开启定时备份

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

  1. 在 Zeabur Dashboard 找到 PostgreSQL 服务
  2. 进入 Backup 选项卡
  3. 开启自动备份，设置每日备份时间（建议凌晨低峰期）
  4. 备份保留天数按需要设置（推荐 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

环境变量同步

生产变量以 Zeabur Web 服务的 Variables 为准。公开 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，可以一句话更新环境变量：

把当前 Muse 生产环境变量同步到 Zeabur Web 服务，并确认 DATABASE_URL 使用 Zeabur PostgreSQL 内网地址

如果数据库和应用在同一个 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。当前模板默认使用显式迁移：部署生产代码前，在带生产 DATABASE_URL 的环境里运行 vpr @muse/product#db:deploy，执行已经提交的 migration 文件。

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

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

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

Docker 注意事项

  • 构建上下文是仓库根目录
  • Dockerfile 路径是 products/muse/Dockerfile
  • ZBPACK_APP_DIR=products/muse/apps/web
  • ZBPACK_DOCKERFILE_PATH=products/muse/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/chat 和文档页返回 200
  • Runtime Logs 没有缺表、缺环境变量、OAuth origin 错误
  • PostgreSQL 定时备份已开启
  • PostgreSQL port-forward 已关闭，避免长期暴露数据库公网端口

想和其他创造者交流？

这篇文档有问题？

On this page

一句话部署推荐架构服务 ID 与重复服务数据库：Zeabur PostgreSQL开启定时备份手动 CLI 部署数据库环境变量同步Cloudflare 设置数据库迁移Docker 注意事项GitHub 自动部署部署后验证