HEL-271: compose 多环境隔离参数化 + 正式 HTTPS 反代（nginx/tls profile）与证书工具

Co-authored-by: multica-agent <github@multica.ai>

deploy/README.md

@@ -46,6 +46,45 @@ docker exec caiwuzongzhang-app python -c "import sqlite3; s=sqlite3.connect('/ap
 docker cp caiwuzongzhang-app:/tmp/b.db ../backups/app.db.$STAMP
 ```
 
+## 3.1 正式环境部署（同宿主机隔离，2026-08-30 首次上线采用）
+
+测试与正式同宿主机并行，靠 compose 项目名/容器名/端口三隔离：
+
+| 项 | 测试环境 | 正式环境 |
+|---|---|---|
+| 目录 | `/home/leefer/caiwuzongzhang-test` | `/home/leefer/caiwuzongzhang-prod` |
+| compose 项目 | `deploy`（默认） | `COMPOSE_PROJECT_NAME=caiwuzongzhang-prod` |
+| 应用容器 | `caiwuzongzhang-app` | `caiwuzongzhang-prod-app` |
+| 端口 | `4173`（对外） | `127.0.0.1:4174`（仅本机，反代上游） |
+| HTTPS | 无 | nginx 反代 `8443`（`COMPOSE_PROFILES=tls`） |
+| 访问 | http://192.168.200.36:4173/ | https://192.168.200.36:8443/ |
+
+首次部署顺序：
+
+```bash
+git clone <repo> /home/leefer/caiwuzongzhang-prod && cd /home/leefer/caiwuzongzhang-prod
+git checkout release/prod
+mkdir -p data/files backups && chown -R 10001:10001 data   # 容器内 app uid
+cd deploy
+cp .env.example .env    # 按下述差异填写
+./tls/gen-cert.sh       # 生成内部 CA + 服务器证书（SAN 含对外 IP）
+TAG=<发布镜像tag> docker compose up -d    # 不带 --build，直接用已验收镜像
+docker logs <应用容器> 2>&1 | grep "shown once"   # 首启一次性初始口令，只出现一次
+```
+
+正式 `.env` 与测试的差异（铁律）：
+
+- `COMPOSE_PROJECT_NAME=caiwuzongzhang-prod`、`APP_CONTAINER_NAME=caiwuzongzhang-prod-app`、`APP_PORT_MAP=127.0.0.1:4174:4173`
+- `COMPOSE_PROFILES=tls`、`PROXY_CONTAINER_NAME=caiwuzongzhang-proxy`、`PROXY_PORT_MAP=8443:8443`
+- `APP_UID=10001` / `APP_GID=10001`（data/ 已 chown 10001）
+- 管理员用户名自定（如 `jinniu-admin`）；**不设** `APP_BOOTSTRAP_ADMIN_PASSWORD`（首启控制台取随机一次性口令，首登立即改密）
+- **不设** `APP_LOGIN_RATE_LIMIT_DISABLED`（限流默认开启）
+
+证书与信任分发：
+
+- `tls/certs/ca.crt` 发给各公司电脑安装到「受信任的根证书颁发机构」（安装指引见交接文档）；`ca.key`/`server.key` 永不离开宿主机。
+- 服务器证书有效期 5 年，到期前用 `./tls/gen-cert.sh` 重签并 `docker compose restart proxy`。
+
 ## 4. 回滚（应用层，5 分钟内）
 
 ```bash
@@ -68,6 +107,16 @@ cd deploy && ./rollback.sh <上一个镜像tag>
 
 cron `*/5 * * * *` 运行 `deploy/monitor.sh`；连续失败或磁盘 ≥80% 时查看 `deploy/ALERT.log` 并按需扩容/清理。容器重启策略 `unless-stopped`。
 
+宿主机 crontab（leefer，2026-08-30 起，正式环境）：
+
+```cron
+15 2 * * * cd /home/leefer/caiwuzongzhang-prod/deploy && CONTAINER=caiwuzongzhang-prod-app ./backup.sh >> backup.log 2>&1
+*/5 * * * * cd /home/leefer/caiwuzongzhang-prod/deploy && CONTAINER=caiwuzongzhang-prod-app HEALTH_URL=http://127.0.0.1:4174/ ./monitor.sh >/dev/null 2>&1
+01 3 1 * * rsync -a /home/leefer/caiwuzongzhang-prod/backups/monthly/ /vol1/caiwuzongzhang-backups/monthly/
+```
+
+（第三行为月度异盘副本：`/vol1` 是与系统盘不同的物理卷；如后续提供真正的异机目标，改为该目标。）
+
 ## 7. 升级数据库
 
 应用启动时自动执行迁移（`MIGRATIONS`，当前版本 10）。迁移只前不改写历史；回退 schema 用对应 down 迁移，先备份后操作。