# JNPF 整栈离线交付包 现场安装手册

> 本包 = 全栈（业务服务 + 前端页面 cx-web + Redis/PostgreSQL/流程引擎）的
> **linux/amd64 离线镜像** + 编排文件 + 迁移工具。现场**不需要外网、不需要源码、不构建任何镜像**。
> 深入资料在包内 `docs/`：`release-checklist.md`（上线对照 §0，**必须逐项过**）、
> `docker-compose-guide.md`（编排全景）、`server-pg-cutover-checklist.md`（MySQL→PG 割接时序）。

## 1. 前置条件

| 项 | 要求 | 验证 |
|---|---|---|
| 架构 | x86_64 Linux | `uname -m` → `x86_64` |
| Docker | Docker Engine + compose 插件 v2 | `docker compose version` |
| 内存 | **≥12GB 可用**（17 容器全栈；不足会 OOM 连锁：PG crash 循环 + gRPC 超时风暴） | `free -g` |
| 磁盘 | ≥30GB（镜像解压 + PG 数据 + 备份） | `df -h` |
| 工具 | GNU make（可选，无则按本文用裸命令）、curl、python3（≥3.6，DLQ/spool 重放预检脚本 `tasks/audit-event-validate.sh` 依赖）；冒烟另需 openssl + md5sum | `command -v make curl python3 openssl md5sum` |
| 主机名 | `/etc/hosts` 加一行 `127.0.0.1 cx-infra`（ApiDomain 双消费方解析约定） | `getent hosts cx-infra` |
| 端口 | 宿主 **80**（前端页面入口）与 **30000**（API/ApiDomain 直连口）无占用；5432/6379 等**不对外发布** | `ss -ltn` |

## 2. 安装步骤（按序执行）

```bash
# ① 解包并校验完整性
tar xf cx-offline-*.tar && cd cx-offline-*/
make verify                        # = sha256sum -c SHA256SUMS

# ② 导入镜像（含迁移辅助镜像）
make load                          # = docker load -i images/*.tar.gz

# ③ 配置凭据 —— 全部【密码/密钥】改现场专用值；
#    【用户名/角色名】保持默认不改（jnpf_app 等已硬编码进建角色 SQL 与配置模板）
cp .env.example .env && vi .env    # 每个键的生成方法见文件内注释与 docs/release-checklist.md §0.7
#    Nacos 客户端账号（NACOS_CLIENT_*）默认注释=回落 nacos/nacos，交付必须启用并轮换（§0.7/§0.11）
#    ⚠️ COMPOSE_PROFILES=localdb 必须保留（.env.example 默认已带）：栈内 PG 收在该 profile 内，
#       不设则 cx-postgres 根本不启动、全栈无库可连。**升级既有现场时尤其注意**——沿用旧 .env
#       的话这个键不存在，须手工补上（make up 前的 preflight 会拦下并给同样提示）。
#       仅当本环境改连远端共享库（CUSTOMER_DB_HOST 非 cx-postgres）时才注释掉它。

# ④ 数据卷（复用旧卷前先确认卷内数据归属；PG 超管密码只在全新卷 initdb 时生效，见 §0.11）
docker volume create postgres_pgdata
# （原 mq-store 卷创建与 chown 步骤已随 RocketMQ 于 2026-08-10 移除，见补丁 #10）

# ⑤ 数据初始化（二选一）
#    a. 全新环境：起 PG → 建 schema → 建业务角色
docker compose up -d cx-postgres
#    此时容器 unhealthy 属预期（健康检查探测业务库，库由 install.sh 创建）；
#    日志刷 "FATAL: database ... does not exist" 是探测噪音，install 成功后即停、随后转 healthy
( cd migration && ./install.sh && ./create-app-roles.sh )
#    b. MySQL 割接：按 docs/archive/server-pg-cutover-checklist.md 全时序执行（含停机窗口迁数据）

# ⑥ Nacos 配置中心内容就位，并把数据面切成服务名直连（不切必炸——基线不发布数据端口）：
#    datasource.yaml → cx-postgres:5432 / cx-redis；（mq.yaml 已停用，事件总线走 Redis）；
#    FlowDomain → http://cx-flow-engine:31000；ApiDomain → 服务器实际地址
#    逐项对照 docs/release-checklist.md §0.9/§0.10
#    （Nacos 单独已在 ⑤ 起来：浏览器 127.0.0.1:30099/nacos 或经 API 操作）

# ⑦ 起全栈并验证
make up                            # 自动先跑 preflight（校验 ③-⑥ 成果：.env/卷/四库/种子/角色，
                                   #   缺项给修复指引；单独跑 make preflight，跳过 SKIP_PREFLIGHT=1）
make wait                          # 等全部 healthy（冷启动 5-8 分钟）
make smoke                         # 三段冒烟：gateway 登录 + 前端静态 + 经 80 反代登录（admin 种子密码）

# ⑧ 浏览器验证：http://<服务器>/ 应出登录页；登录后任意内页刷新不 404；
#    消息铃铛正常（WebSocket 经 80 的 /websocket/ 反代）
```

## 3. 上线放行门禁

冒烟通过后，**逐项过 `docs/release-checklist.md` §0（0.1–0.15）**：PG max_connections、
凭据轮换与一致性对照表、端口暴露面复查（`ss -ltn` 应只见 80、30000 与 127.0.0.1:30099）、
FrontDomain 指现场前端地址（§0.14）、（§0.15，`make preflight` 会
非阻断提示）、备份 cron（`migration/backup.sh`，含 nacos_config；宿主文件存储目录另行文件级备份）。

## 4. 日常运维速查

| 目的 | 命令 |
|---|---|
| 状态 / 日志 | `make ps` / `make logs s=cx-lims` |
| 重启 / 停止 | `make restart` / `make down`（pgdata 外部卷永不删除） |
| 进 PG | `docker exec -it cx-postgres psql -U postgres -d jnpf_init` |
| 备份 | `BACKUP_DIR=/data/pg-backup ./migration/backup.sh`（配 cron 见 migration/README） |
| 镜像溯源 | `images/manifest.txt`（digest/ID/构建 commit） |

## 5. 常见问题

- **业务容器 3-5 分钟才 healthy**：healthcheck start_period=180s，冷启动属正常，别急着判故障。
- **全栈起不来 + PG 日志 `all server processes terminated`**：内存不足（前置 ≥12GB 硬要求）。
- **登录/取配置 403 或 unknown user**：`.env` 的 NACOS_CLIENT_* 与 Nacos 用户库密码不一致（§0.11）。
- **业务报 `password authentication failed`**：`.env` 与 Nacos `datasource.yaml`/角色实际密码不同步——
  按 §0.11 铁律顺序：定稿 .env → 跑 create-app-roles.sh → 同步 datasource.yaml → 重启消费方。
- **文件上传成功但预览 502**：Nacos `system-config.yaml` 的 `config.ApiDomain` 未指现场地址，改后重启 cx-file。
- **页面打不开或接口 502**：`docker compose logs cx-web` 看 nginx 报错——upstream 连不上多半是
  gateway 还在冷启动（`make wait` 等 healthy）；页面样式/接口地址异常先查 `_app.config.js`
  是否被改动（默认三地址全空=同源，勿乱填）。反代规则在 `docker/frontend/nginx.conf`（挂载文件，
  改完 `docker compose restart cx-web` 即生效，无需镜像）。
- **启用 HTTPS（三步，零构建）**：① 证书放 `docker/frontend/certs/{server.crt,server.key}`
  ② `docker-compose.yml` 里 cx-web 解开 `"443:443"` 与 certs 挂载两行注释
  ③ `docker/frontend/nginx.conf` 解开文末 443 server 块注释，`docker compose up -d cx-web`。