feat: 初始化慧遇书院官网一期

docs/部署与恢复手册.md

@@ -0,0 +1,119 @@
+# 慧愈科技官网部署与恢复手册
+
+## 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、请求体大小限制与访问日志。
+
+## 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` 数据卷。