lehuo/infra/ubuntu

Ubuntu 26.04 LTS 单机部署包

本目录用于把乐活公益平台部署到一台已安装 Ubuntu 26.04 LTS 的云服务器。Docker 官方已将 Ubuntu 26.04（Resolute）列为 Docker Engine 支持系统：https://docs.docker.com/engine/install/ubuntu/。

该部署包适合初期单机 staging/production：

• 管理后台与 API：https://PUBLIC_HOST
• 私有对象存储签名访问：https://FILES_HOST
• 仅向宿主机发布 80/443；MySQL、Redis、MinIO 与 API 不发布主机端口
• MySQL 8.4、Redis 7.4、MinIO、NestJS API、Vue 管理后台/Nginx 均使用 Docker Compose
• 数据、对象和 Redis 使用独立持久卷
• 自动 migration、上线前备份、HTTPS 冒烟、不可变 Git 提交标签和应用回滚
• 每日 MySQL 备份、SHA-256 校验、30 天本机保留；异地加密同步仍须由运维配置

这不是“已完成生产上线”的证明。真实域名/备案、TLS、微信配置、隐私材料、staging、UAT、告警接收人和异地备份仍是发布阻断项。

1. 云服务器准备

建议最低资源：4 vCPU、8 GiB 内存、100 GiB SSD；测试环境可降低，但生产容量必须以压测结果为准。云安全组仅开放：

• SSH 管理端口（优先限制管理 IP，端口以服务器实际配置为准）
• TCP 80（TLS 跳转/证书验证）
• TCP 443（管理后台、API、小程序请求与签名文件上传）

不要开放 3000、3306、6379、9000 或 9001。Docker 发布端口可能绕过 UFW 规则，因此本 Compose 只发布 80/443；仍需用云安全组做外层限制。

为以下两个不同域名配置 A/AAAA 记录到服务器，并准备覆盖二者的证书（双域名 SAN 或通配证书）：

• admin.example.com：管理后台和 API
• files.example.com：私有对象存储签名上传/下载

2. 放置代码与安装 Docker

sudo install -d -m 0755 /opt/lehuo
sudo git clone --branch main https://gitee.com/climber-ge/wechatapp.git /opt/lehuo/app
cd /opt/lehuo/app
sudo bash ./infra/ubuntu/scripts/install-docker.sh

安装脚本严格检查 Ubuntu 26.04，使用 Docker 官方 apt 仓库，并且不会自动卸载已有容器运行时，也不会自动把普通用户加入等同 root 权限的 docker 用户组。

3. 生成生产环境文件

cd /opt/lehuo/app
sudo bash ./infra/ubuntu/scripts/generate-env.sh \
  --public-host admin.example.com \
  --files-host files.example.com
sudo install -m 0600 /path/to/fullchain.pem /opt/lehuo/shared/tls/fullchain.pem
sudo install -m 0600 /path/to/privkey.pem /opt/lehuo/shared/tls/privkey.pem

生成结果位于 /etc/lehuo/lehuo.env，权限为 600，包含随机数据库密码、Redis 密码、对象存储密钥、会话 pepper、审计 HMAC key 和 32 字节 Base64 字段加密密钥。不要提交、复制到聊天、工单或普通日志。

首次部署时微信参数可以保持空值且 NOTIFICATION_WORKER_ENABLED=false。取得有效 AppID/AppSecret 和全部模板后再填入真实值并重新部署，禁止使用测试值冒充成功。

如果不用自带 MinIO 而使用腾讯 COS 或其他 S3 兼容私有对象存储，应单独评审并修改 Compose 服务，同时保持 Adapter、私有 Bucket、短期签名 URL、最小权限密钥与 CORS 边界。

4. 预检与首次部署

cd /opt/lehuo/app
sudo bash ./infra/ubuntu/scripts/preflight.sh /etc/lehuo/lehuo.env
sudo bash ./infra/ubuntu/scripts/deploy.sh /etc/lehuo/lehuo.env
sudo bash ./infra/ubuntu/scripts/bootstrap-admin.sh /etc/lehuo/lehuo.env

deploy.sh 固定执行：预检 → 以 Git 提交号构建不可变镜像 → 启动数据服务 → 初始化私有 Bucket/CORS/版本控制 →（已有版本时）迁移前备份 → Prisma migration → 部署 API/Nginx → HTTPS/ready/对象存储冒烟。

初始管理员脚本从终端隐藏读取密码，不写入环境文件或 shell history；数据库已有后台凭据时服务端会拒绝重复初始化。

5. 小程序生产地址

在提审的小程序代码中把 apps/miniprogram/miniprogram/app.ts 的 apiBaseUrl 改为：

https://admin.example.com

并在微信公众平台配置 request 合法域名 https://admin.example.com，uploadFile/downloadFile 合法域名 https://files.example.com。体验版/正式版会拒绝 localhost、0.0.0.0 和非 HTTPS 地址。

6. 备份与恢复演练

sudo bash ./infra/ubuntu/scripts/install-backup-timer.sh
sudo systemctl start lehuo-backup.service
sudo journalctl -u lehuo-backup.service --since today

# 恢复到隔离数据库做演练，不覆盖生产库
sudo bash ./infra/ubuntu/scripts/restore.sh \
  /opt/lehuo/backups/lehuo-YYYYMMDDTHHMMSSZ.sql.gz \
  lehuo_restore_test --confirm lehuo_restore_test

备份文件与 .sha256 必须同步到异地加密存储。每季度至少在隔离数据库完成一次恢复演练，核对表数量、关键事实行数、耗时并留存记录。

7. 升级与回滚

cd /opt/lehuo/app
sudo git fetch --all --prune
sudo git switch main
sudo git pull --ff-only

# 把 IMAGE_TAG 更新为本次批准的完整/短 Git commit；禁止 latest
sudo editor /etc/lehuo/lehuo.env
sudo bash ./infra/ubuntu/scripts/deploy.sh /etc/lehuo/lehuo.env

应用异常且 migration 向后兼容时：

sudo bash ./infra/ubuntu/scripts/rollback.sh /etc/lehuo/lehuo.env

回滚脚本只切换本机仍存在的上一版 API/管理后台镜像，不回滚数据库。若 migration 不向后兼容，必须停止发布并按已审批的数据库恢复方案处理，不能盲目执行应用回滚。

8. 日常检查

cd /opt/lehuo/app
sudo docker compose --project-directory infra/ubuntu \
  --env-file /etc/lehuo/lehuo.env -f infra/ubuntu/compose.yaml ps
curl -fsS https://admin.example.com/health/live
curl -fsS https://admin.example.com/health/ready
sudo docker system df
sudo systemctl status lehuo-backup.timer

日志中禁止输出 token、完整手机号、证件、详细地址、儿童信息或服务描述。容器日志轮转、CPU/内存/磁盘/API 5xx/P95、数据库连接、通知死信和备份缺失告警需接入实际有人值守的监控渠道。