部署¶

生态系统的所有服务都采用同一套部署模型。本页对其加以说明。

此处不含主机的具体信息

服务器地址、用户名、机密配置等运维细节不会出现在这个公开站点上。它们存放在相应仓库内的封闭 runbook 中。

总体模型¶

        互联网
            │
            ▼
   ┌─────────────────┐
   │   edge nginx    │  TLS 终止 · HSTS · 限流
   │    （容器）      │  每个 vhost → 内部服务
   └────────┬────────┘
            │  共享 Docker 网络
   ┌────────┴──────────────────────────────┐
   │                                       │
   ▼                ▼                      ▼
  应用 A           应用 B                静态站点
 (Go + Next)     (Go + Next)            (nginx)
   │                │
   └────────┬───────┘
            ▼
   PostgreSQL · Redis  （共享）

核心原则：

一个 edge，多个 vhost。 对外只有一个 nginx 容器占用 80/443 端口。每个域名各有自己的 server 块，并反向代理到内部服务。
内部服务不对外开放。 应用只监听共享的 Docker 网络，或绑定到 127.0.0.1。外部无法直接访问。
共享基础设施。 一套 PostgreSQL、一套 Redis 服务多个应用；每个应用各有自己的数据库/schema。
Docker Compose——每个应用各有自己的 compose stack，接入共享网络。

Edge nginx¶

edge 负责以下事项：

职责	说明
TLS 终止	Let's Encrypt 证书，自动续期
HSTS	`max-age=63072000; includeSubDomains`
限流	按 zone 划分：`auth`（严格） · `app`（宽松） · `api`
反向代理	vhost → 内部服务
拒绝未知主机	Default server → 直接断开连接

edge 配置由 git 管理

edge nginx 的 conf.d 目录是通过 git 从特定仓库同步而来的。若在主机上 手工修改，下次部署时会被 git reset --hard 覆盖掉。

因此新增或修改 vhost 的正确做法是向仓库提交 commit，再由 CI 分发。

第二种模型——服务持有自己的 vhost

还有一种模型：只与某一个服务相关的 vhost 不放在集中式文件里，而是放在 该服务自己的仓库中，由它的部署流程把配置以独立文件的形式安装到 edge 的 conf.d。

优点：变更在一个仓库内即可闭环，不必等待其他团队部署。前提：配置必须完全自包含——不得依赖定义在其他文件里的限流 zone 或 default server。

本站正是这样运行的——参见本文档平台。

证书¶

Let's Encrypt，使用 certbot 的 webroot 模式。
ACME challenge 通过 80 端口的 /.well-known/acme-challenge/ 路径提供。
续期为自动执行，由 cron 每周运行；成功后重载 nginx。

新增域名时：

把 DNS 指向服务器。
在 80 端口的 ACME 块中加入该域名。
用 certbot 申请证书。
添加 HTTPS vhost，并指向该证书。
执行 nginx -t 检查，然后 reload。

静态站点（文档门户）¶

文档站点都是预先构建好的静态 HTML。运行它们最简单的做法是：

用 MkDocs 构建出 site/；
把产物复制到服务器；
由一个轻量的 nginx:alpine 容器提供服务；
再由 edge nginx 反向代理过去。

由于没有应用运行时，资源占用低，可出故障的地方也少。

本站就是这样运行的——详见本文档平台页面。

应用部署¶

应用侧目前存在两种模型：

模型	说明
在主机上构建	CI 把仓库同步到主机，执行 `docker compose build && up -d`
经由 registry	CI 构建镜像并推送到 registry，主机执行 `pull && up -d`

总体趋势是减少依赖——已有从外部 registry 改为直接在主机构建的案例。

增量部署：CI 根据改动路径（paths-filter）判断需要重建哪些服务。一个应用的改动不会波及其他应用。

回滚¶

静态站点——把上一次构建的归档解开还原。
应用——回到上一个镜像 tag（可用 <SVC>_IMAGE_TAG 变量固定版本）。

健康检查¶

每个服务都有 /health endpoint。compose 的 healthcheck 会检查 PostgreSQL、 Redis 等基础设施是否就绪，待其就绪后再启动应用。

部署检查清单¶

[ ] DNS 指向正确
[ ] 证书已签发，并纳入自动续期
[ ] edge vhost 已添加，且已提交到仓库
[ ] nginx -t 通过
[ ] 内部服务未对外开放
[ ] /health 有响应
[ ] 机密配置经环境变量提供，仓库中不存在
[ ] 回滚方式明确

自动化的详细内容请见 CI/CD 页面。