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

1. 生产部署前准备

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

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

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. 启动与验收

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 站点配置需要同步设置请求体上限，并为大图处理保留合理超时：

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 环境文件注入。

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：

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. 恢复流程

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

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

恢复后检查：

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

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

6. 素材回收站清理

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

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

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

7. 回滚应用

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

8. 从 Git 仓库发布更新

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

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 数据卷。

4.6 KiB Raw Permalink Blame History Unescape Escape