编辑 | blame | 历史 | 原始文档

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. 安装步骤（按序执行）

# ① 解包并校验完整性
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. 常见问题