132 lines
6.1 KiB
Markdown
132 lines
6.1 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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. 生成生产环境文件
|
||
|
||
```bash
|
||
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. 预检与首次部署
|
||
|
||
```bash
|
||
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` 改为：
|
||
|
||
```text
|
||
https://admin.example.com
|
||
```
|
||
|
||
并在微信公众平台配置 request 合法域名 `https://admin.example.com`，uploadFile/downloadFile 合法域名 `https://files.example.com`。体验版/正式版会拒绝 localhost、`0.0.0.0` 和非 HTTPS 地址。
|
||
|
||
## 6. 备份与恢复演练
|
||
|
||
```bash
|
||
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. 升级与回滚
|
||
|
||
```bash
|
||
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 向后兼容时：
|
||
|
||
```bash
|
||
sudo bash ./infra/ubuntu/scripts/rollback.sh /etc/lehuo/lehuo.env
|
||
```
|
||
|
||
回滚脚本只切换本机仍存在的上一版 API/管理后台镜像，不回滚数据库。若 migration 不向后兼容，必须停止发布并按已审批的数据库恢复方案处理，不能盲目执行应用回滚。
|
||
|
||
## 8. 日常检查
|
||
|
||
```bash
|
||
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、数据库连接、通知死信和备份缺失告警需接入实际有人值守的监控渠道。
|