feat:CISD配置初始化

2026-03-11 14:23:11 +08:00
parent 1c254aaba9
commit d02c6530e8
58 changed files with 10699 additions and 1281 deletions
@@ -0,0 +1,521 @@
+# TMS 部署手册
+
+## 1. 文档目的
+
+本文档用于说明如何在 CentOS Linux 主机上按标准运行路径 `/home/tms` 部署 TMS，以及如何准备 CISD 初始化所需的相关脚本、目录、文件和配置。
+
+本文档覆盖以下内容：
+- TMS jar 包部署
+- `/home/tms` 运行目录结构
+- 外部配置文件
+- `/home/tms/bin` 下的标准初始化辅助脚本
+- 文件上传与 `fileId` 存储规则
+- 启动、停止、状态检查
+- 初始化前置检查和常见故障排查
+
+本文档不替代厂商提供的 CIPS 部署手册。中间件和标准收发器基础安装仍属于预置工作。
+
+## 2. 部署边界
+
+TMS 负责：
+- 提供 internal/openapi HTTP 服务
+- 管理 CISD 初始化任务
+- 渲染客户化配置
+- 调用已配置的初始化后置脚本
+- 按 `fileId` 解析上传文件
+
+预置层负责：
+- JDK 安装
+- TiDB/MySQL 客户端可用
+- RabbitMQ/TLQ/nginx 安装
+- 标准收发器介质解压到 `/home/cemp4i`
+- 直参版介质解压到厂商约定目录
+- 数据库凭据和 RabbitMQ 管理员凭据
+
+## 3. 环境要求
+
+### 3.1 操作系统
+
+推荐环境：
+- CentOS 或兼容 Linux 发行版
+
+### 3.2 Java
+
+运行时要求：
+- JDK 17
+
+检查命令：
+
+```bash
+java -version
+```
+
+### 3.3 网络与端口
+
+TMS 默认监听端口：
+- `8080`
+
+检查命令：
+
+```bash
+ss -lntp | grep 8080
+```
+
+### 3.4 建议具备的系统命令
+
+建议系统具备以下命令：
+- `java`
+- `bash`
+- `curl`
+- `jq`
+- `mysql`
+- `pgrep`
+- `unzip`
+
+可选但推荐：
+- `ss`
+- `lsof`
+
+## 4. 标准运行目录结构
+
+TMS 统一部署到 `/home/tms`：
+
+```text
+/home/tms
+├── tms-framework.jar
+├── bin
+│   ├── apply_standard_db.sh
+│   ├── start_standard_apps.sh
+│   ├── start_standard_nginx.sh
+│   └── check_standard_runtime.sh
+├── config
+│   └── application.yml
+├── logs
+│   ├── tms-framework.out.log
+│   └── tms-framework.err.log
+├── run
+│   └── tms-framework.pid
+├── scripts
+│   └── tms.sh
+├── tmp
+│   └── tms-init-logs
+└── uploads
+    └── <fileId>
+        └── <originalFilename>
+```
+
+目录用途：
+- `/home/tms/bin`：初始化后置辅助脚本目录，由 `tms.init.executor.*command` 引用
+- `/home/tms/config`：Spring Boot 外部配置目录
+- `/home/tms/logs`：TMS 运行日志
+- `/home/tms/run`：PID 文件目录
+- `/home/tms/scripts`：TMS 启停控制脚本目录
+- `/home/tms/tmp`：初始化执行日志和临时目录
+- `/home/tms/uploads`：上传文件目录，初始化阶段按 `fileId` 解析
+
+## 5. 部署物来源映射
+
+| 部署目标 | 仓库来源 |
+|---|---|
+| `/home/tms/tms-framework.jar` | `target/tms-framework-*.jar` |
+| `/home/tms/scripts/tms.sh` | `scripts/tms.sh` |
+| `/home/tms/bin/apply_standard_db.sh` | `scripts/standard-init/apply_standard_db.sh` |
+| `/home/tms/bin/start_standard_apps.sh` | `scripts/standard-init/start_standard_apps.sh` |
+| `/home/tms/bin/start_standard_nginx.sh` | `scripts/standard-init/start_standard_nginx.sh` |
+| `/home/tms/bin/check_standard_runtime.sh` | `scripts/standard-init/check_standard_runtime.sh` |
+| `/home/tms/config/application.yml` | 由 `config/application.yml.example` 复制生成 |
+
+## 6. 部署步骤
+
+### 6.1 构建 jar 包
+
+```bash
+cd /Users/waner/Work/CISD/文档/tms-framework
+mvn -q -DskipTests package
+```
+
+### 6.2 创建运行目录
+
+```bash
+sudo mkdir -p /home/tms/{bin,config,scripts,logs,run,tmp,uploads}
+sudo chown -R "$(whoami)":"$(whoami)" /home/tms
+```
+
+### 6.3 拷贝运行文件
+
+```bash
+cp target/tms-framework-*.jar /home/tms/tms-framework.jar
+cp scripts/tms.sh /home/tms/scripts/tms.sh
+cp scripts/standard-init/*.sh /home/tms/bin/
+cp config/application.yml.example /home/tms/config/application.yml
+chmod +x /home/tms/scripts/tms.sh
+chmod +x /home/tms/bin/*.sh
+```
+
+### 6.4 检查部署结果
+
+```bash
+ls -l /home/tms/tms-framework.jar
+ls -l /home/tms/scripts/tms.sh
+ls -l /home/tms/bin
+ls -l /home/tms/config/application.yml
+```
+
+## 7. 外部配置文件
+
+TMS 从以下位置加载外部配置：
+- `/home/tms/config/application.yml`
+
+运行控制脚本：
+- [tms.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/tms.sh)
+
+### 7.1 最低必配项
+
+至少需要检查并设置：
+
+```yaml
+tms:
+  security:
+    internal-token: change-me-internal-token
+  file:
+    storage:
+      upload-base-dir: /home/tms/uploads
+      max-file-size-bytes: 104857600
+  init:
+    executor:
+      mode: LOCAL
+      log-dir: /home/tms/tmp/tms-init-logs
+      upload-base-dir: /home/tms/uploads
+      staging-root-dir: /home/tmp/tms-init-staging
+      standard-db-apply-command: /home/tms/bin/apply_standard_db.sh
+      standard-app-start-command: /home/tms/bin/start_standard_apps.sh
+      standard-nginx-start-command: /home/tms/bin/start_standard_nginx.sh
+      standard-post-check-command: /home/tms/bin/check_standard_runtime.sh
+```
+
+### 7.2 必须保持一致的配置
+
+以下两个路径必须保持一致：
+- `tms.file.storage.upload-base-dir`
+- `tms.init.executor.upload-base-dir`
+
+如果两者不一致，会出现“上传成功，但初始化执行阶段找不到文件”的问题。
+
+### 7.3 标准版初始化关键配置
+
+标准版初始化重点配置项：
+- `standard-home-dir`：默认 `/home/cemp4i`
+- `standard-cpconfig-path`：标准版 `cpconfig.cfg` 路径
+- `standard-db-script-base-dir`：默认 `${standard-home-dir}/cpackage`
+- `standard-db-load-dir`：默认 `${standard-home-dir}/mysql/loadfilepath`
+- `standard-nginx-template-path`：nginx 模板路径
+- `standard-web-front-zip-path`：默认 `${standard-home-dir}/cpackage/front/front.zip`
+- `standard-web-target-dir`：默认 `/usr/local/nginx/html`
+- `standard-web-organization-json-path`：默认 `/usr/local/nginx/html/organization.json`
+
+### 7.4 不建议直接写入 application.yml 的凭据
+
+除非现场策略允许，否则不建议把以下信息直接写进 `/home/tms/config/application.yml`：
+- `apply_standard_db.sh` 使用的数据库密码
+- 跨主机共享的数据库用户名
+- 辅助脚本依赖的其他敏感环境变量
+
+推荐方式：
+- 在启动 TMS 前通过环境变量导出
+- 或通过独立受保护的环境文件，由辅助脚本自行加载
+
+## 8. 标准初始化辅助脚本
+
+这些脚本部署到 `/home/tms/bin`，由 TMS 初始化执行器在标准版流程中调用。
+
+### 8.1 `apply_standard_db.sh`
+
+来源：
+- [apply_standard_db.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/standard-init/apply_standard_db.sh)
+
+作用：
+- 不存在时创建 `CMEP` 数据库
+- 导入 `SCHEMA-DDL.sql`
+- 导入 `CMEP.sql`
+- 导入 `UP-ORG-INFO.sql`
+
+必需环境变量：
+- `DB_USER`
+- `DB_PASSWORD`
+
+可选环境变量：
+- `DB_HOST`，默认 `127.0.0.1`
+- `DB_PORT`，默认 `4000`
+- `DB_NAME`，默认 `CMEP`
+- `LOAD_DIR`，默认 `/home/cemp4i/mysql/loadfilepath`
+
+示例：
+
+```bash
+export DB_USER=app_user
+export DB_PASSWORD='secret'
+/home/tms/bin/apply_standard_db.sh
+```
+
+### 8.2 `start_standard_apps.sh`
+
+来源：
+- [start_standard_apps.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/standard-init/start_standard_apps.sh)
+
+作用：
+- 启动 CMSP
+- 启动 CMTP
+
+依赖：
+- `/home/cemp4i/cmsp/start_cmsp.sh`
+- `/home/cemp4i/cmtp/start_cmtp.sh`
+- 用户 `cmep4i`
+
+### 8.3 `start_standard_nginx.sh`
+
+来源：
+- [start_standard_nginx.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/standard-init/start_standard_nginx.sh)
+
+作用：
+- 如果 nginx 已运行则执行 reload
+- 如果 nginx 未运行则按 `/usr/local/nginx/conf/nginx.conf` 启动
+
+依赖：
+- `/usr/local/nginx/sbin/nginx`
+
+### 8.4 `check_standard_runtime.sh`
+
+来源：
+- [check_standard_runtime.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/standard-init/check_standard_runtime.sh)
+
+作用：
+- 检查 CMSP 进程是否存在
+- 检查 CMTP 进程是否存在
+- 检查 nginx 进程是否存在
+- 检查 `/usr/local/nginx/html/organization.json` 是否存在
+
+该脚本仅用于初始化后的结果校验，不负责修复。
+
+## 9. 文件上传与 `fileId` 模型
+
+### 9.1 核心原则
+
+CISD 初始化接口本身不接收 multipart 文件。
+
+前端正确流程是：
+1. 用户选择文件
+2. 前端先调用文件上传接口
+3. 后端返回 `fileId`
+4. 前端在初始化 JSON 中提交 `fileId`
+
+### 9.2 存储结构
+
+上传文件统一保存为：
+
+```text
+/home/tms/uploads/<fileId>/<originalFilename>
+```
+
+### 9.3 初始化常用文件字段
+
+初始化请求中常见的文件引用字段：
+- `licenses.receiverLicenseFileId`
+- `mq.tlqLicenseFileId`
+- `mq.cfmqConfigFileId`
+- `licenses.cfgZipFileId`
+
+### 9.4 初始化执行阶段的解析规则
+
+执行器会依次尝试解析：
+- `/home/tms/uploads/<fileId>`
+- `/home/tms/uploads/<fileId>/<preferredFileName>`
+
+因此文件上传服务和初始化执行器必须使用同一个上传根目录。
+
+## 10. 启动、停止与状态检查
+
+### 10.1 启动
+
+```bash
+/home/tms/scripts/tms.sh start
+```
+
+### 10.2 停止
+
+```bash
+/home/tms/scripts/tms.sh stop
+```
+
+### 10.3 重启
+
+```bash
+/home/tms/scripts/tms.sh restart
+```
+
+### 10.4 状态
+
+```bash
+/home/tms/scripts/tms.sh status
+```
+
+### 10.5 运行日志
+
+主要日志：
+- `/home/tms/logs/tms-framework.out.log`
+- `/home/tms/logs/tms-framework.err.log`
+
+常用查看命令：
+
+```bash
+tail -n 100 /home/tms/logs/tms-framework.out.log
+tail -n 100 /home/tms/logs/tms-framework.err.log
+```
+
+## 11. 初始化前置检查
+
+预检查脚本：
+- [cisd_init_precheck.sh](/Users/waner/Work/CISD/文档/tms-framework/scripts/cisd_init_precheck.sh)
+
+执行方式：
+
+```bash
+chmod +x /Users/waner/Work/CISD/文档/tms-framework/scripts/cisd_init_precheck.sh
+PRODUCT_TYPE=ENTERPRISE /Users/waner/Work/CISD/文档/tms-framework/scripts/cisd_init_precheck.sh
+```
+
+检查内容包括：
+- 产品类型是否合法
+- 执行模式是否正确
+- 日志目录是否可写
+- 标准版基础文件是否存在
+- RabbitMQ 工具是否可用
+- 直参版场景下的脚本目录是否存在
+
+建议在首次联调前执行一次。
+
+## 12. 初始化运行期目录与日志
+
+### 12.1 初始化步骤日志
+
+由以下配置控制：
+- `tms.init.executor.log-dir`
+
+推荐路径：
+- `/home/tms/tmp/tms-init-logs`
+
+### 12.2 初始化 staging 目录
+
+由以下配置控制：
+- `tms.init.executor.staging-root-dir`
+
+默认路径：
+- `/home/tmp/tms-init-staging`
+
+staging 中通常包含：
+- 渲染后的 `cpconfig.cfg`
+- 暂存的 license / 配置文件
+- 渲染后的 SQL 包
+- 渲染后的 nginx 配置
+- 暂存的 web 静态资源
+
+## 13. 常见故障排查
+
+### 13.1 TMS 无法启动
+
+现象：
+- `tms.sh start` 失败
+- 未生成 PID 文件
+
+检查：
+
+```bash
+java -version
+ls -l /home/tms/tms-framework.jar
+ls -l /home/tms/config/application.yml
+tail -n 200 /home/tms/logs/tms-framework.err.log
+```
+
+### 13.2 `DB_APPLY` 报错 `standardDbApplyCommand is blank`
+
+含义：
+- SQL 已经渲染并复制成功
+- 但未配置真实导库命令
+
+修复：
+- 确保 `/home/tms/config/application.yml` 中存在：
+
+```yaml
+standard-db-apply-command: /home/tms/bin/apply_standard_db.sh
+```
+
+- 确保脚本存在并可执行
+- 确保 `DB_USER`、`DB_PASSWORD` 已经提供
+
+### 13.3 `cpconfig not found`
+
+检查：
+- `standard-cpconfig-path`
+- 直参版 `cfgZipFileId`
+- 标准版介质是否已解压到 `/home/cemp4i/cpconfig.cfg`
+
+### 13.4 初始化阶段按 `fileId` 找不到文件
+
+现象：
+- 步骤日志显示已尝试 `/home/tms/uploads/...`
+- 但所有候选路径都不存在
+
+检查命令：
+
+```bash
+find /home/tms/uploads -maxdepth 2 -type f | sort
+```
+
+重点确认：
+- 上传接口的落盘根目录是否正确
+- 初始化请求中的 `fileId` 是否与上传返回值一致
+- `tms.file.storage.upload-base-dir` 是否与 `tms.init.executor.upload-base-dir` 一致
+
+### 13.5 RabbitMQ 命令或队列步骤失败
+
+检查：
+- `rabbitmqctl`
+- `rabbitmqadmin`
+- `standard-rabbit-setup-script-path`
+- `standard-rabbit-queue-script-path`
+- 步骤日志内容
+
+### 13.6 WEB 发布或 nginx 启动失败
+
+检查：
+
+```bash
+ls -l /home/cemp4i/cpackage/front/front.zip
+ls -l /usr/local/nginx/conf/nginx.conf
+ls -l /usr/local/nginx/html
+pgrep -f '/usr/local/nginx/sbin/nginx'
+```
+
+同时确认：
+- `/home/tms/bin/start_standard_nginx.sh` 存在
+- `standard-web-front-zip-path` 指向正确的标准版前端包
+- 发布后 `organization.json` 已生成
+
+## 14. 推荐的本机检查命令
+
+```bash
+/home/tms/scripts/tms.sh status
+ss -lntp | grep 8080
+curl -s http://127.0.0.1:8080/api/v1/device/status
+find /home/tms/uploads -maxdepth 2 -type f | sort
+ls -l /home/tms/bin
+ls -l /home/tms/config/application.yml
+```
+
+对标准初始化辅助脚本做语法检查：
+
+```bash
+bash -n /home/tms/bin/apply_standard_db.sh
+bash -n /home/tms/bin/start_standard_apps.sh
+bash -n /home/tms/bin/start_standard_nginx.sh
+bash -n /home/tms/bin/check_standard_runtime.sh
+```