130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
# 慧愈科技官网部署与恢复手册
|
||
|
||
## 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` 数据卷。
|