第16章：部署 —— 自托管 Docker 与 Encore Cloud

同一套代码，两条部署路：encore build docker 产出标准镜像自己托管，或 git push encore 交给托管控制面（应用仍跑在你自己的云账号里）。本章讲清两条路的完整流程与选型，并附 CLI 命令全景速查。

一、路线总览

代码在两条路线上零修改——SQLDatabase("order") 到底连本地 Docker、RDS 还是自建 PG，由环境决定。

二、自托管：encore build docker

构建

encore build docker myapp:v1.0
# --base <image>   自定义基础镜像
# --push           构建后推远端仓库

产物是标准 OCI 镜像：K8s、Cloud Run、Fargate、docker compose、裸机 systemd 都能跑。

infra-config.json：告诉镜像基础设施在哪

{
  "$schema": "https://encore.dev/schemas/infra.schema.json",
  "metadata": {
    "app_id": "uptime",
    "cloud": "gcp",
    "base_url": "https://api.example.com",
    "env_name": "production",
    "env_type": "production"
  },
  "sql_servers": [
    {
      "host": "db.internal:5432",
      "databases": {
        "monitor": { "username": "app", "password": {"$env": "DB_PASSWORD"} },
        "site":    { "username": "app", "password": {"$env": "DB_PASSWORD"} }
      }
    }
  ],
  "secrets": {
    "SlackWebhookURL": {"$env": "SLACK_WEBHOOK_URL"}
  }
}

要点：

• 每个 SQLDatabase 声明都要有对应条目——静态分析知道应用需要哪些库，缺配会在启动时报清晰错误；
• 敏感值一律 {"$env": "VAR"} 走环境变量注入，配置文件里不落明文；
• 用到 Pub/Sub / 对象存储 / 缓存的应用，同样在此配置对应的云服务（SQS/SNS、GCS/S3、Redis）连接信息——schema 里各有专门段落；
• Cron 调度在自托管镜像内置执行，无需外部调度器。

运行

docker run -p 8080:8080 \
  -e DB_PASSWORD=xxx \
  -e SLACK_WEBHOOK_URL=https://hooks.slack.com/... \
  myapp:v1.0

一镜多环境

同一镜像 + 不同 infra-config/环境变量 = 不同环境。禁止"本地一份代码、生产一份代码"——环境差异只允许存在于配置。这条纪律配合 appMeta().environment（第 6 章）按环境分流，覆盖绝大多数"生产特殊逻辑"需求。

参考运维形态（本机 B2B 项目）

小规模自托管未必要上 K8s：130 服务器上用 systemd user unit 直接跑 encore run --listen 0.0.0.0:4100（linger 开启保证开机自启），部署脚本 = git pull + 重启 unit。对内部工具而言，"encore run + systemd"是成本最低的可用形态；正式生产再上镜像化。

三、Encore Cloud

首次接入

encore auth signup        # 或 login
encore app link           # 已有应用关联云端（app create 时也可直接创建关联）
git push encore           # 推送即构建部署

encore 是 CLI 自动配置的 git remote。推送后在 Cloud Dashboard 看构建、环境与部署流水。

BYOC：应用跑在你的云账号

Encore Cloud 不是"把应用托管在 Encore 的服务器上"，而是控制面/数据面分离：

• 控制面（Encore 侧）：构建、编排、Dashboard、观测聚合；
• 数据面（你的 AWS/GCP）：通过你授权的 IAM 角色，自动开通 RDS / Cloud SQL、SQS+SNS / Pub/Sub、Fargate / Cloud Run / GKE、S3 / GCS、Secrets Manager 等，应用与数据都在你的账号里。

免费档部署在 Encore 托管的共享环境（staging-$APP_ID.encr.app），适合体验与个人项目；生产接自己的云账号。

平台能力清单

出海合规注意（本机项目实测经验） 免费档只跑在海外机房：如果上游依赖有出口 IP 白名单（分销网关、银行接口），要先实测连通性；真实用户数据出境还有合规审查问题。国内业务的生产部署优先考虑自托管或云账号选国内区。

四、数据库迁移在部署中的位置

两条路线一致：应用启动时自动执行未应用的迁移。这意味着：

• 部署顺序天然安全：新版本容器起来先跑迁移再服务流量；
• 迁移必须向后兼容滚动发布（旧实例还在跑时新迁移已执行）：加列可以，删列/改类型要走两步发布（先停用后删除）；
• 回滚代码不回滚 schema——迁移只有 .up.sql，设计时按"只进不退"思维写。

五、CLI 命令全景速查

# 运行与测试
encore run [--debug] [--watch=true] [--listen host:port]
encore test [目录]

# 应用管理
encore app create / clone <app-id> / link <app-id> / init

# 账号
encore auth signup / login / logout / whoami

# daemon
encore daemon            # 重启（疑难杂症第一招）
encore daemon env        # 环境诊断

# 数据库
encore db shell <db> [--env=name] [--write --admin --superuser]
encore db conn-uri <db> [--env=name]
encore db proxy [--env=name]
encore db reset <服务名...>

# 生成
encore gen client <app-id> [--env=name] [--lang=...] [--output=...] [--services=...]

# 日志
encore logs [--env=prod] [--json]

# 密钥
encore secret set --type <prod|dev|pr|local> <名>
encore secret list / archive <id> / unarchive <id>

# 构建与集群
encore build docker <tag> [--base ...] [--push]
encore k8s configure --env=<name>       # 写 kubectl 配置

# VPN（私有环境访问）
encore vpn start / status / stop

# 版本
encore version / version update

# AI 相关（第 18、19 章详解）
encore llm-rules init
encore mcp start / run

六、常见误区

1. infra-config.json 漏配某个数据库——启动即报错，照错误信息补齐（这是特性：缺配显性化）。
2. 配置文件里写明文密码——一律 {"$env"}。
3. 迁移里删列/改类型一步到位——滚动发布期间旧代码还在读，两步走。
4. 以为 Encore Cloud = 应用托管在 Encore——BYOC 模式下应用与数据在你自己的云账号。
5. 免费档直接接生产上游——海外出口 IP 可能进不了白名单，先实测。
6. 每个环境维护一份代码分支——环境差异只进配置与 appMeta() 分流。

七、实践练习

1. 给第 14 章 uptime 项目写 infra-config.json（两库 + SlackWebhookURL），encore build docker 构建并本地 docker run 起来（连本地 PG 容器）。
2. 故意删掉 site 库的配置段，观察启动错误信息——熟悉"缺配报错"的样子。
3. 注册 Encore Cloud 免费档，git push encore 部署 uptime，在 Cloud Dashboard 里看一次线上 trace。
4. 设计一个"给 orders 表删除废弃列"的两步发布方案：第一步发什么、第二步发什么、之间隔多久。
5. 把 encore gen client --env=staging 生成的客户端接到本地前端，体会多环境客户端切换。

八、总结

1. 两条部署路零代码差异：自托管拿标准镜像 + infra-config.json；Encore Cloud git push encore 全托管。
2. infra-config 的原则：结构由应用模型校验（缺配报错）、敏感值走 $env、一镜多环境。
3. BYOC = 控制面在 Encore、应用与数据在你的云账号；免费档跑海外共享环境，注意白名单与合规。
4. 迁移随启动自动执行，schema 变更按"向后兼容 + 两步发布"设计。
5. CLI 速查表值得打印贴墙——日常高频是 run / test / db shell / logs / secret / gen client / build docker。

请继续阅读：第17章:AI 原生开发（一）。

原始资料引用

• Self-Hosting / Docker Build
• Infra Configuration Schema
• Encore Cloud Platform

Related Documents

• 第15章:测试与前端集成
• 第17章:AI 原生开发（一）