76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
# 部署与运维手册（与 `release/prod` 基线一致）
|
||
|
||
最后核对：2026-08-30，总工 HEL-270 上线前总验收。本手册是测试与正式环境唯一的部署/回滚/备份/巡检操作依据，取代散落在宿主机 `DEPLOYMENT.txt` 里的历史记录（旧记录仅作存档）。
|
||
|
||
## 1. 物料与目录
|
||
|
||
| 物料 | 说明 |
|
||
|---|---|
|
||
| `deploy/Dockerfile` | python:3.12-slim-bookworm，非 root（uid 10001 `app`），只读根文件系统 |
|
||
| `deploy/compose.yaml` | cap_drop ALL、no-new-privileges、pids 128、mem 512m、cpu 1.0、healthcheck |
|
||
| `deploy/.env.example` | 配置模板；`deploy/.env` 已 gitignore，口令永不入库 |
|
||
| `deploy/deploy.sh` | `TAG=<tag> ./deploy.sh`，默认镜像 tag=当前提交 sha |
|
||
| `deploy/rollback.sh` | `./rollback.sh <tag>`，只换应用不动数据 |
|
||
| `deploy/backup.sh` | 在线热备 + 保留策略（30 天日备 + 12 个月月备） |
|
||
| `deploy/monitor.sh` | 每 5 分钟健康 + 磁盘 ≥80% 告警，写 `ALERT.log` |
|
||
|
||
数据目录：`deploy/../data/`（`app.db` + `files/`）。银行原始文件按 SHA-256 内容哈希不可变保存，任何操作不得改写。
|
||
|
||
## 2. 正式配置铁律
|
||
|
||
- **不得出现 `admin/admin123`**：`APP_BOOTSTRAP_ADMIN_PASSWORD` 正式环境不设值，首启由控制台读取随机生成的一次性初始口令，首登立即改密；管理员用户名避开 `admin`。
|
||
- **登录失败限流默认开启**（5 次/10 分钟锁账号+IP）。`APP_LOGIN_RATE_LIMIT_DISABLED=1` 仅限本地调试，正式 .env 不得携带。
|
||
- 密钥/口令/证书私钥不进仓库、不进评论、不进任务元数据。
|
||
- **HTTPS**：正式暴露一律经反向代理（推荐同机 Caddy 容器，内网自签或内部 CA 证书，反代到容器 4173）；不占用 NAS 系统 nginx 的 80/443。公司电脑分发根证书即可。
|
||
- **日志**：容器 stdout 走 docker json-file，限幅 `max-size=10m, max-file=3`（daemon 或 compose `logging` 配置）；审计日志在库内（append-only 触发器保护）。
|
||
|
||
## 3. 部署步骤（测试与正式一致）
|
||
|
||
```bash
|
||
git fetch && git checkout release/prod && git pull
|
||
cd deploy
|
||
cp .env.example .env # 首次；按上面铁律填写
|
||
TAG=$(git rev-parse --short HEAD) ./deploy.sh
|
||
curl -fsS http://127.0.0.1:4173/ >/dev/null && echo healthy
|
||
```
|
||
|
||
部署前手工备份（四件套 + 镜像 tag 存档）：
|
||
|
||
```bash
|
||
STAMP=$(date +%Y%m%d-%H%M%S)
|
||
tar -C .. -czf ../backups/source-$STAMP.tar.gz --exclude='../data' --exclude='../.git' .
|
||
cp .env ../backups/env-$STAMP
|
||
docker exec caiwuzongzhang-app python -c "import sqlite3; s=sqlite3.connect('/app/data/app.db'); d=sqlite3.connect('/tmp/b.db'); s.backup(d); d.close(); s.close()"
|
||
docker cp caiwuzongzhang-app:/tmp/b.db ../backups/app.db.$STAMP
|
||
```
|
||
|
||
## 4. 回滚（应用层，5 分钟内）
|
||
|
||
```bash
|
||
cd deploy && ./rollback.sh <上一个镜像tag>
|
||
```
|
||
|
||
数据层恢复见下节。两套动作互不干扰：应用回滚不改数据；数据恢复不换镜像。
|
||
|
||
## 5. 备份与恢复演练
|
||
|
||
- 备份：cron `15 2 * * *` 运行 `deploy/backup.sh`；月结后再手动跑一次。
|
||
- 恢复步骤（已演练，隔离环境验证）：
|
||
1. `mkdir -p /tmp/restore/data && cp backups/daily/app.db.<stamp> /tmp/restore/data/app.db`
|
||
2. `tar -C /tmp/restore/data -xzf backups/daily/files.<stamp>.tar.gz`（解出 `files/`）
|
||
3. 用一份独立 `deploy-restore` 目录（`.env` 指向 `/tmp/restore`、端口错开）`docker compose up -d --build`
|
||
4. 核对：`PRAGMA integrity_check`、各表行数、金额合计、`source_files` 哈希清单与生产一致后才可顶替。
|
||
- 演练频率：上线前 1 次（HEL-270 已做），之后每季度 1 次，结果记入本文件末尾。
|
||
|
||
## 6. 巡检与告警
|
||
|
||
cron `*/5 * * * *` 运行 `deploy/monitor.sh`；连续失败或磁盘 ≥80% 时查看 `deploy/ALERT.log` 并按需扩容/清理。容器重启策略 `unless-stopped`。
|
||
|
||
## 7. 升级数据库
|
||
|
||
应用启动时自动执行迁移（`MIGRATIONS`，当前版本 10）。迁移只前不改写历史；回退 schema 用对应 down 迁移，先备份后操作。
|
||
|
||
## 8. 演练记录
|
||
|
||
- 2026-08-30 HEL-270：备份恢复演练 + 版本回滚演练各 1 次，隔离环境完成，原始证据未改动。详见 HEL-270 验收评论。
|