# 慧愈科技官网部署与恢复手册

## 1. 生产部署前准备

1. 准备 2 核 2 GB、40—80 GB SSD 的 Linux 服务器，并配置 1—2 GB Swap。
2. 安装 Docker Engine 与 Docker Compose Plugin。
3. 首次部署从 Git 仓库拉取代码，并固定到明确版本标签；生产服务器只在发布窗口构建，不执行日常开发构建。
4. 根据 `.env.docker.example` 创建 `.env.docker`，替换管理员密码和不少于 32 字符的会话密钥。
5. 设置 `SITE_URL=https://正式域名`、`NUXT_SESSION_COOKIE_SECURE=true`。
6. 将 `BACKUP_HOST_DIR` 指向另一块磁盘或已挂载的异机目录，不能与 Docker 数据卷共存于同一故障域。

推荐目录与首次拉取方式：

```bash
sudo mkdir -p /srv/huiyu
sudo chown "$USER":"$USER" /srv/huiyu
git clone https://git.huiyushuyuan.cn/GuangYu/guanwang.git /srv/huiyu
cd /srv/huiyu
cp .env.docker.example .env.docker
chmod 600 .env.docker
```

编辑 `.env.docker` 后再启动。该文件包含生产密钥，已被 `.gitignore` 排除，禁止提交到仓库。

## 2. 启动与验收

```bash
docker compose build --pull
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:3000/api/health
docker compose logs --tail=100 web
```

容器必须显示 `healthy`。随后通过 Nginx 配置域名、HTTPS、请求体大小限制与访问日志。

图片上传允许单张最大 20 MB。Nginx 站点配置需要同步设置请求体上限，并为大图处理保留合理超时：

```nginx
client_max_body_size 20m;
proxy_read_timeout 120s;
proxy_send_timeout 120s;
```

修改后执行 `nginx -t`，确认通过再平滑重载 Nginx。若使用其他反向代理，也要把对应上传上限设置为至少 20 MB。

## 3. 数据目录

- SQLite：Docker 数据卷中的 `/app/data/db/huiyu.sqlite`
- 原图：`/app/data/uploads/original`
- WebP 与缩略图：`/app/data/uploads/derived`
- 回收站：`/app/data/uploads/trash`
- 加密备份：宿主机 `BACKUP_HOST_DIR`

不要对数据库文件直接复制热备，也不要运行 `docker compose down -v`。

## 4. 备份计划

设置独立保存的 `BACKUP_ENCRYPTION_PASSWORD`，建议通过服务器密钥管理或 root-only 环境文件注入。

```bash
BACKUP_ENCRYPTION_PASSWORD='从密钥管理读取' sh scripts/backup.sh daily
BACKUP_ENCRYPTION_PASSWORD='从密钥管理读取' sh scripts/backup.sh weekly
BACKUP_ENCRYPTION_PASSWORD='从密钥管理读取' sh scripts/backup.sh monthly
```

脚本会使用 SQLite 在线备份，打包数据库和全部素材，使用 AES-256-CBC + PBKDF2 加密，并在落盘后立即解密列目录校验。保留策略为每日 7 天、每周 28 天、每月 186 天。

建议 Cron：

```cron
15 3 * * * cd /srv/huiyu && /usr/local/bin/run-huiyu-backup daily
25 3 * * 0 cd /srv/huiyu && /usr/local/bin/run-huiyu-backup weekly
35 3 1 * * cd /srv/huiyu && /usr/local/bin/run-huiyu-backup monthly
```

`run-huiyu-backup` 应从安全位置读取加密密码，不把密码直接写进 crontab。

## 5. 恢复流程

恢复会先自动生成一份当前数据备份，然后停止应用、校验备份数据库、覆盖数据库和素材并重新启动。

```bash
CONFIRM_RESTORE=yes \
BACKUP_ENCRYPTION_PASSWORD='从密钥管理读取' \
sh scripts/restore.sh /绝对路径/huiyu-daily-YYYYMMDD-HHMMSS-PID.tar.gz.enc
```

恢复后检查：

```bash
docker compose ps
curl -fsS http://127.0.0.1:3000/api/health
docker compose logs --tail=100 web
```

再检查首页、后台登录、最近发布内容和至少一张上传图片。每月选择最近备份在测试服务器演练一次。

## 6. 素材回收站清理

后台删除只移动到回收站，默认 30 天后才允许物理清理：

```bash
MEDIA_TRASH_RETENTION_DAYS=30 sh scripts/purge-media-trash.sh
```

被草稿或已发布页面引用的素材不能移入回收站。

## 7. 回滚应用

生产镜像必须使用不可变版本号，例如 `huiyu-official-site:2026.08.10-1`。应用代码回滚时保留数据卷不变；如果版本包含不兼容迁移，先按第 4 节备份，再按对应版本的迁移说明操作。

## 8. 从 Git 仓库发布更新

发布前先创建备份，再以明确提交或版本标签更新；不要在生产服务器直接编辑代码。

```bash
cd /srv/huiyu
BACKUP_ENCRYPTION_PASSWORD='从密钥管理读取' sh scripts/backup.sh daily
git fetch --prune --tags origin
git checkout main
git pull --ff-only origin main
docker compose build --pull
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:3000/api/health
```

若健康检查或页面验收失败，先保留现场日志，再切回上一版本标签并重新构建；不要删除 `huiyu_official_site_data` 数据卷。