feat: add test environment deployment workflow

2026-07-28 14:48:46 +08:00
parent 099e05fb56
commit bab4b85bed
8 changed files with 454 additions and 14 deletions
@@ -0,0 +1,97 @@
+# 测试服务器部署
+
+该目录交付给运行宿主机 Nginx 和 Docker Compose 的测试服务器。后端由阿里云 ACR 拉取，用户端和管理端均在本机构建后上传为静态文件。
+
+## 一次性准备
+
+1. 在服务器创建目录：
+
+   ```bash
+   sudo mkdir -p /site/email-unlimit/{frontend/releases,admin/releases,backend,backups}
+   sudo chown -R "$USER":"$USER" /site/email-unlimit
+   ```
+
+2. 上传 `deploy/server/docker-compose.yml` 到 `/site/email-unlimit/docker-compose.yml`，复制 `deploy/server/backend/.env.example` 为 `/site/email-unlimit/backend/.env`，填写真实值并执行：
+
+   ```bash
+   chmod 600 /site/email-unlimit/backend/.env
+   ```
+
+3. 使用 ACR 只读凭据在服务器登录私有镜像仓库：
+
+   ```bash
+   docker login <ALIYUN_REGISTRY>
+   ```
+
+4. 将 `deploy/nginx/email-unlimit.conf` 安装到宿主机 Nginx 的 `http` 上下文包含目录。确认通配符证书路径与文件名后，执行：
+
+   ```bash
+   sudo nginx -t && sudo systemctl reload nginx
+   ```
+
+5. 在 `/site/email-unlimit` 启动数据服务和后端：
+
+   ```bash
+   docker compose --env-file backend/.env up -d
+   docker compose --env-file backend/.env ps
+   curl --fail http://127.0.0.1:3000/health
+   ```
+
+   `backend/.env` 同时是 Docker Compose 的变量来源和后端容器的环境文件，因此之后所有 Compose 命令都必须带上 `--env-file backend/.env`。
+
+## 本机构建与静态发布
+
+构建时用户端必须使用测试收件域名，且两个前端均保持空 API 基址以使用同域反向代理：
+
+```powershell
+$env:VITE_APP_DOMAIN = "test-mail.shenjianl.cn"
+$env:VITE_API_BASE_URL = ""
+Set-Location frontend
+pnpm build
+
+Set-Location ..\admin
+pnpm build
+```
+
+将两个 `dist` 分别上传到服务器的 `frontend/releases/<版本>` 和 `admin/releases/<版本>`。确认上传完整后，在服务器原子切换当前版本：
+
+```bash
+cd /site/email-unlimit
+ln -sfn releases/<版本> frontend/current
+ln -sfn releases/<版本> admin/current
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+## 后端发布与回滚
+
+GitHub 镜像仓库创建 `v*` 标签后，工作流将构建并推送 `linux/amd64` 镜像到 ACR。把 `/site/email-unlimit/backend/.env` 中的 `IMAGE_TAG` 更新为相同版本，然后执行：
+
+```bash
+cd /site/email-unlimit
+docker compose --env-file backend/.env pull backend
+docker compose --env-file backend/.env up -d --no-deps backend
+docker compose --env-file backend/.env logs --tail=100 backend
+curl --fail http://127.0.0.1:3000/health
+```
+
+回滚时将 `IMAGE_TAG` 改回上一镜像版本后重复相同命令。
+
+## DNS 与网络
+
+- `A test-mail.shenjianl.cn` 指向服务器公网 IP。
+- `MX test-mail.shenjianl.cn` 指向 `test-mail.shenjianl.cn`，优先级为 10。
+- `A admin-mail.shenjianl.cn` 指向同一公网 IP。
+- 安全组与防火墙仅放行 TCP `80`、`443`、`25`；不公开 `3000`、`3306`、`6379`。
+- 确认云厂商允许入站 TCP 25。建议将公网 IP 的 PTR 设为 `test-mail.shenjianl.cn`。
+
+## 备份
+
+每日从 MySQL 容器导出一次一致性备份到 `/site/email-unlimit/backups`，保留 7 天：
+
+```bash
+docker compose --env-file /site/email-unlimit/backend/.env exec -T mysql sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \
+  | gzip > "/site/email-unlimit/backups/email-unlimit-$(date +%F).sql.gz"
+find /site/email-unlimit/backups -type f -name 'email-unlimit-*.sql.gz' -mtime +7 -delete
+```
+
+将上面的命令放入宿主机 cron 或 systemd timer。MySQL 数据卷与 Redis AOF 卷由 Docker 持久化。