cisd/docs/deployment/tms-deployment.md

# 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 管理员凭据

## 2.1 核心原则：先部署预置，再执行初始化

当前 CISD 初始化功能不是完整替代厂商部署手册，而是建立在“基础环境和介质已就绪”的前提上执行客户化步骤。

因此现场应严格分成两个阶段：

### 第一阶段：部署/出厂预置阶段

由运维或出厂人员提前完成，目标是把机器准备成“可接受初始化”的基线环境。

### 第二阶段：CISD 初始化阶段

由 TMS 根据前端输入的客户化参数执行，目标是完成机构号、节点地址、MQ/TLQ、数据库导入、应用配置、WEB 发布和启动验收。

如果第一阶段未完成，第二阶段不应直接试跑。

## 2.2 部署阶段必须提前完成的步骤

以下内容必须在部署阶段完成，不应再依赖 `/api/v1/init/**` 初始化接口去补做。

### 2.2.1 操作系统与基础目录

需要提前完成：
- 系统用户、用户组创建
- 标准收发器运行目录创建
- 目录权限和属主设置
- `/home/cemp4i`、`/home/tms`、`/home/tlq` 等目录存在且可访问

这类动作属于一次性环境准备，不属于客户化初始化。

### 2.2.2 基础软件安装

需要提前完成：
- JDK 安装
- nginx 安装
- RabbitMQ 安装
- TLQ 基础软件安装
- TiDB/MySQL 客户端可用
- `rabbitmqctl`、`rabbitmqadmin`、`mysql`、`unzip` 等命令可用

初始化阶段默认依赖这些命令和软件已经存在。

### 2.2.3 标准收发器介质上传与解压

需要提前完成：
- 企业版 / 间参版标准收发器介质解压到 `/home/cemp4i`
- 直参版介质解压到厂商约定目录
- `cpconfig.cfg`
- `cpackage/toolsh/*.sh`
- `cpackage/rabq/*.sh`
- `cpackage/software/nginx.conf`
- `cpackage/front/front.zip`
- SQL 模板和 JAR 介质文件存在

当前初始化流程假定这些文件已经存在，不负责解压标准介质。

### 2.2.4 平台级凭据预置

需要提前完成：
- 数据库导库账号/密码
- RabbitMQ 管理员账号/密码
- 其他平台级敏感配置

这些凭据不属于前端输入的客户化参数，建议通过：
- 环境变量
- 独立受保护配置文件
- 现场预置脚本

进行管理。

### 2.2.5 防火墙、服务注册和开机自启

需要提前完成：
- 防火墙端口放通
- RabbitMQ/nginx 服务注册
- 必要的开机自启设置

这类动作属于环境级配置，不应放在初始化阶段重复执行。

### 2.2.6 标准收发器部署文档中应提前做的脚本

结合标准收发器部署文档和当前 TMS 初始化边界，以下脚本应视为部署阶段脚本，不纳入初始化主流程：

- `setpd.sh`
- `opencport.sh`
- `install_newpackage.sh`
- `setrabqstart.sh`
- `setxsd.sh`
- `setngservice.sh`
- `pongx.sh`

这些脚本覆盖的通常是：
- 用户与目录准备
- 端口开放
- RabbitMQ 编译/安装/服务化
- nginx 安装/服务化
- 信创依赖和基础环境处理

### 2.2.7 厂商脚本与部署阶段的对应关系

下表用于帮助现场快速判断：哪些脚本应在部署阶段提前执行，哪些不应再放到初始化接口中执行。

| 脚本 | 建议阶段 | 说明 |
|---|---|---|
| `setpd.sh` | 部署阶段 | 用户、目录、权限等基础准备 |
| `opencport.sh` | 部署阶段 | 端口开放，属于系统环境配置 |
| `install_newpackage.sh` | 部署阶段 | RabbitMQ/OTP 安装与编译 |
| `setrabqstart.sh` | 部署阶段 | RabbitMQ 服务启动/服务化准备 |
| `setxsd.sh` | 部署阶段 | 信创/环境依赖准备 |
| `setngservice.sh` | 部署阶段 | nginx 服务注册/服务化 |
| `pongx.sh` | 部署阶段 | 基础环境处理脚本 |
| `setup_nodeps.sh` | 部署阶段 | 基础无依赖环境准备 |
| `setsuseunixodbc.sh` | 部署阶段 | ODBC/基础运行依赖准备 |

## 2.3 标准版初始化阶段执行的步骤

以下内容属于客户化初始化，保留在 `/api/v1/init/**` 流程中执行。

### 2.3.1 配置渲染

包括：
- `cpconfig.cfg` 渲染
- 机构号、节点地址、组织名称等客户化字段写入

### 2.3.2 license 和输入文件处理

包括：
- 收发器 license 上传
- TLQ license / 配置包上传
- CFMQ 配置上传
- 通过 `fileId` 暂存并按目标路径落位

### 2.3.3 MQ/TLQ 客户化初始化

包括：
- `SET_RABBITMQ`
- `SET_TLQ`
- `TLQ_CONF_APPLY`
- RabbitMQ 通道账号和队列初始化

说明：
- 标准版 RabbitMQ 用户/队列初始化是客户化动作
- 但 RabbitMQ 软件本体安装、服务注册必须提前完成

### 2.3.4 数据库初始化

包括：
- `DB_RENDER`
- `DB_APPLY`

说明：
- 当前 TMS 负责渲染 SQL 和触发导库命令
- 但数据库客户端可用、导库凭据可用，必须由部署阶段保证

### 2.3.5 应用、nginx 和 WEB 客户化

包括：
- `DEPLOY_RECEIVER`
- `APP_MQ_CREDENTIALS_APPLY`
- `NGINX_CONFIG_APPLY`
- `WEB_CONFIG_APPLY`

说明：
- 这些步骤处理的是客户化配置和发布
- 不是安装 nginx 或解压标准介质

### 2.3.6 启动和校验

包括：
- `START_CMSP_CMTP`
- `START_NGINX`
- `POST_CHECK`
- `VERIFY`

说明：
- 当前初始化阶段负责启动和验收
- 但对应启动脚本、停止脚本、运行用户和目标路径需要提前准备好

### 2.3.7 厂商脚本与初始化阶段的对应关系

下表用于说明：哪些厂商脚本仍在初始化阶段使用，哪些脚本已经被当前 TMS 内置逻辑替代。

| 脚本/能力 | 当前阶段 | 当前处理方式 |
|---|---|---|
| `setfraq.sh` | 初始化阶段 | 仍由 TMS 调用，用于切换标准版 `RABBITMQ` 模式 |
| `setftq.sh` | 初始化阶段 | 仍由 TMS 调用，用于切换 `TLQ` 或 `RABBITMQ_TLQ` 模式 |
| `settlq.sh` | 初始化阶段 | 仍由 TMS 调用，用于落位和替换 TLQ 配置 |
| `setuprabq.sh` | 初始化阶段 | 由 TMS staging 后执行，不直接污染源脚本 |
| `addrabq_R_01.sh` / `addrabq_R_02.sh` | 初始化阶段 | 由 TMS staging 后执行，按节点选择 |
| `setsql.sh` | 初始化阶段 | 已不再作为主导入口；当前改为 `DB_RENDER + DB_APPLY` |
| `setsptp.sh` | 初始化阶段 | 仍由 TMS 调用，用于标准收发器应用部署 |
| `setweb.sh` | 初始化阶段 | 当前由 TMS 内置 `WEB_CONFIG_APPLY` 替代 |
| `setngx.sh` | 初始化阶段 | 当前由 TMS 内置 `NGINX_CONFIG_APPLY` 替代 |

需要注意：
- `setweb.sh` 和 `setngx.sh` 所代表的“WEB 发布”和“nginx 配置发布”仍属于初始化阶段动作
- 只是当前代码不再直接执行这两个脚本，而是由 TMS 内置逻辑完成

## 2.4 分版本预置清单

本节在通用边界之外，再按版本给出一份现场可直接对照的清单，帮助运维快速判断：
- 当前设备属于哪个版本
- 初始化前必须先准备好哪些内容
- 初始化阶段还会继续执行哪些客户化动作

### 2.4.1 企业版预置清单

适用范围：
- `ENTERPRISE + RABBITMQ`
- `ENTERPRISE + TLQ`

部署阶段必须完成：
- 标准版介质已解压到 `/home/cemp4i`
- `/home/cemp4i/cpconfig.cfg`、`/home/cemp4i/cpackage/toolsh/*.sh`、`/home/cemp4i/cpackage/sql_script/*`、`/home/cemp4i/cpackage/front/front.zip` 已存在
- JDK、nginx、RabbitMQ、TLQ、数据库客户端已安装
- `/home/tms`、`/home/cemp4i`、`/home/tlq` 目录及权限已准备
- 数据库导库凭据、RabbitMQ 管理员凭据已预置
- `standard-db-apply-command`、`standard-app-start-command`、`standard-nginx-start-command`、`standard-post-check-command` 对应脚本已部署

按支持方式补充要求：

| 支持方式 | 部署前额外要求 | 初始化阶段仍会执行 |
|---|---|---|
| `RABBITMQ` | RabbitMQ 服务可用，`rabbitmqctl`、`rabbitmqadmin` 可执行 | `SET_RABBITMQ`、RabbitMQ 用户和队列初始化、应用 MQ 账号写回 |
| `TLQ` | TLQ 基础软件和目录可用，`/home/tlq` 可写 | `SET_TLQ`、`TLQ_CONF_APPLY`、TLQ 配置包落位 |

企业版初始化阶段不会补做：
- RabbitMQ/TLQ 软件安装
- nginx 安装和服务注册
- 数据库账号创建
- 标准介质解压

### 2.4.2 间参版预置清单

适用范围：
- `INDIRECT + RABBITMQ`
- `INDIRECT + RABBITMQ_TLQ`

部署阶段必须完成：
- 标准版介质已解压到 `/home/cemp4i`
- 间参版对应的 `setsptp.sh`、`setfraq.sh`、`setftq.sh`、`settlq.sh`、RabbitMQ 脚本、SQL 模板已齐备
- JDK、nginx、RabbitMQ、TLQ、数据库客户端已安装
- `/home/tms`、`/home/cemp4i`、`/home/tlq` 目录及权限已准备
- 数据库导库凭据、RabbitMQ 管理员凭据已预置
- TMS 所依赖的标准初始化辅助脚本已部署到 `/home/tms/bin`

按支持方式补充要求：

| 支持方式 | 部署前额外要求 | 初始化阶段仍会执行 |
|---|---|---|
| `RABBITMQ` | RabbitMQ 服务可用 | `SET_RABBITMQ`、RabbitMQ 用户和队列初始化、应用 MQ 账号写回 |
| `RABBITMQ_TLQ` | RabbitMQ 和 TLQ 都要提前可用 | `SET_TLQ`、`TLQ_CONF_APPLY`，同时仍会执行 RabbitMQ 用户和队列初始化 |

需要特别说明：
- 间参版不存在“纯 TLQ”初始化模式
- `RABBITMQ_TLQ` 不是替代 RabbitMQ，而是 RabbitMQ 与 TLQ 共存
- 因此如果现场只准备了 TLQ、没有准备 RabbitMQ，间参版 `RABBITMQ_TLQ` 初始化仍会失败

### 2.4.3 轻量直参版预置清单

适用范围：
- `DIRECT + RABBITMQ_TLQ`
- `DIRECT + RABBITMQ_CFMQ`

部署阶段必须完成：
- 直参版介质已按厂商要求解压到约定目录
- 直参版 `cpconfig.cfg` 已在厂商约定位置存在
- 直参版数据库脚本目录、TLQ/CFMQ 相关目录、签名服务依赖目录已存在
- JDK、RabbitMQ、TLQ 或 CFMQ、数据库客户端已安装
- 数据库导库凭据、RabbitMQ 管理员凭据已预置
- 直参版初始化依赖的目标路径具备写权限

按支持方式补充要求：

| 支持方式 | 部署前额外要求 | 初始化阶段仍会执行 |
|---|---|---|
| `RABBITMQ_TLQ` | RabbitMQ 与 TLQ 运行环境都已就绪 | `MQ_USER_APPLY`、`DB_INIT`、`TLQ_INIT_CFG` |
| `RABBITMQ_CFMQ` | RabbitMQ 与 CFMQ 运行环境都已就绪 | `MQ_USER_APPLY`、`DB_INIT`、`CFMQ_APPLY` |

直参版与标准版的差异：
- 不走标准版 `/home/cemp4i/cpackage/toolsh/*.sh` 主链
- 不走标准版 `DB_RENDER + DB_APPLY`
- 不走标准版 `WEB_CONFIG_APPLY`、`NGINX_CONFIG_APPLY`
- 初始化更依赖直参版厂商目录结构和配置文件落位

### 2.4.4 现场使用建议

现场可以按以下顺序判断：
1. 先看设备预制版本是 `ENTERPRISE`、`INDIRECT` 还是 `DIRECT`
2. 再看该版本下的支持方式是 `RABBITMQ`、`TLQ`、`RABBITMQ_TLQ` 还是 `RABBITMQ_CFMQ`
3. 先完成本节对应版本的预置项
4. 再进入 `/api/v1/init/template -> /preview -> /tasks -> /execute` 初始化流程

如果当前版本对应的预置项没有完成，不要直接尝试执行初始化任务。

## 2.5 不应再由初始化阶段执行的内容

为了避免把“环境搭建”与“客户化初始化”混在一起，以下动作不应再由初始化阶段重复承担：

- 创建系统用户和用户组
- 批量创建基础目录
- 安装或编译 RabbitMQ
- 安装或编译 nginx
- 开放系统端口
- 解压标准收发器完整介质
- 创建数据库导库账号
- 创建 RabbitMQ 管理员账号
- 注册 systemd / rc.local 服务

这些动作应在出厂或部署阶段完成。

## 3. 环境要求

### 3.1 操作系统

推荐环境：
- CentOS 或兼容 Linux 发行版

### 3.2 Java

运行时要求：
- JDK 17

检查命令：

```bash
java -version
```

### 3.3 网络与端口

TMS 默认监听端口：
- `8088`

检查命令：

```bash
ss -lntp | grep 8088
```

### 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
│   ├── stop_standard_apps.sh
│   ├── stop_standard_nginx.sh
│   ├── stop_standard_rabbitmq.sh
│   ├── check_standard_runtime.sh
│   └── resource-restore
│       ├── apply-resource-backup.sh
│       ├── restore-db.sh
│       └── replay-mq.sh
├── config
│   └── application.yml
├── gateway
│   ├── gm
│   │   ├── start.sh
│   │   ├── nginx.conf
│   │   └── config/http/tms.conf
│   ├── tls13
│   │   ├── start.sh
│   │   ├── nginx.conf
│   │   └── conf.d/tms.conf
│   └── logs
├── logs
│   ├── tms-framework.out.log
│   └── tms-framework.err.log
├── root-sbin
│   ├── tms-prepare-standard-permissions
│   ├── tms-rabbitmqctl
│   └── tms-run-standard-vendor-step
├── 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/gateway`：TMS 独立网关配置、启动脚本和日志目录
- `/home/tms/logs`：TMS 运行日志
- `/home/tms/root-sbin`：root 受控脚本的部署包暂存目录，实际执行位置为 `/usr/local/sbin`
- `/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/stop_standard_apps.sh` | `scripts/standard-init/stop_standard_apps.sh` |
| `/home/tms/bin/start_standard_nginx.sh` | `scripts/standard-init/start_standard_nginx.sh` |
| `/home/tms/bin/stop_standard_nginx.sh` | `scripts/standard-init/stop_standard_nginx.sh` |
| `/home/tms/bin/stop_standard_rabbitmq.sh` | `scripts/standard-init/stop_standard_rabbitmq.sh` |
| `/home/tms/bin/check_standard_runtime.sh` | `scripts/standard-init/check_standard_runtime.sh` |
| `/home/tms/bin/resource-restore/apply-resource-backup.sh` | `scripts/resource-restore/apply-resource-backup.sh` |
| `/home/tms/bin/resource-restore/restore-db.sh` | `scripts/resource-restore/restore-db.sh` |
| `/home/tms/bin/resource-restore/replay-mq.sh` | `scripts/resource-restore/replay-mq.sh` |
| `/home/tms/root-sbin/tms-run-standard-vendor-step` | `scripts/standard-init/root-sbin/tms-run-standard-vendor-step` |
| `/home/tms/root-sbin/tms-prepare-standard-permissions` | `scripts/standard-init/root-sbin/tms-prepare-standard-permissions` |
| `/home/tms/root-sbin/tms-rabbitmqctl` | `scripts/standard-init/root-sbin/tms-rabbitmqctl` |
| `/usr/local/sbin/tms-run-standard-vendor-step` | 由 `/home/tms/root-sbin/tms-run-standard-vendor-step` 复制安装 |
| `/usr/local/sbin/tms-prepare-standard-permissions` | 由 `/home/tms/root-sbin/tms-prepare-standard-permissions` 复制安装 |
| `/usr/local/sbin/tms-rabbitmqctl` | 由 `/home/tms/root-sbin/tms-rabbitmqctl` 复制安装 |
| `/home/tms/gateway/tls13/start.sh` | `deployment/tms-gateway/tls13/start.sh` |
| `/home/tms/gateway/tls13/nginx.conf` | `deployment/tms-gateway/tls13/nginx.conf` |
| `/home/tms/gateway/tls13/conf.d/tms.conf` | `deployment/tms-gateway/tls13/conf.d/tms.conf` |
| `/home/tms/gateway/gm/start.sh` | `deployment/tms-gateway/gm/start.sh` |
| `/home/tms/gateway/gm/nginx.conf` | `deployment/tms-gateway/gm/nginx.conf` |
| `/home/tms/gateway/gm/config/http/tms.conf` | `deployment/tms-gateway/gm/config/http/tms.conf` |
| `/home/tms/config/application.yml` | 由 `config/application.yml.example` 复制生成 |

`scripts/cisd_init_precheck.sh` 和 `scripts/pcie_realcard_smoke.sh` 属于诊断脚本，不作为 TMS 常驻运行脚本默认部署。现场需要时可复制到 `/home/tms/tools/` 临时执行。

## 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,libs,root-sbin,tools}
sudo mkdir -p /home/tms/bin/resource-restore
sudo mkdir -p /home/tms/gateway/{tls13,gm,logs/tls13,logs/gm}
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 scripts/resource-restore/*.sh /home/tms/bin/resource-restore/
cp scripts/standard-init/root-sbin/* /home/tms/root-sbin/
cp -R deployment/tms-gateway/tls13/* /home/tms/gateway/tls13/
cp -R deployment/tms-gateway/gm/* /home/tms/gateway/gm/
cp config/application.yml.example /home/tms/config/application.yml
chmod +x /home/tms/scripts/tms.sh
chmod +x /home/tms/bin/*.sh
chmod +x /home/tms/bin/resource-restore/*.sh
chmod +x /home/tms/gateway/tls13/start.sh
chmod +x /home/tms/gateway/gm/start.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`
- 显式设置 `SPRING_PROFILES_ACTIVE` 时，额外加载 `/home/tms/config/application-\${SPRING_PROFILES_ACTIVE}.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/cmep4i`
- `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`
- `standard-vendor-step-runner-command`：默认 `/usr/local/sbin/tms-run-standard-vendor-step`，用于 `SET_RABBITMQ`、`SET_TLQ`、`TLQ_CONF_APPLY`、`DEPLOY_RECEIVER`
- `rabbitmq-ctl-command`：默认 `sudo -n /usr/local/sbin/tms-rabbitmqctl`，初始化和资源恢复统一通过 root 受控 wrapper 调用 RabbitMQ CLI

### 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/cmep4i/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/cmep4i/cmsp/start_cmsp.sh`
- `/home/cmep4i/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` 是否存在

该脚本仅用于初始化后的结果校验，不负责修复。

### 8.5 `tms-run-standard-vendor-step`

来源：
- [tms-run-standard-vendor-step](/Users/waner/Work/CISD/文档/tms-framework/scripts/standard-init/root-sbin/tms-run-standard-vendor-step)

部署位置：
- `/usr/local/sbin/tms-run-standard-vendor-step`

作用：
- 作为 root 拥有的受控入口，按固定参数执行标准 vendor 脚本
- 内部切换到 `cmep4i` 用户后执行 `/home/cmep4i/cpackage/toolsh/*.sh`
- 当前只允许 `setfraq`、`setftq`、`settlq`、`setsptp`

部署命令：

```bash
sudo cp scripts/standard-init/root-sbin/tms-run-standard-vendor-step /usr/local/sbin/tms-run-standard-vendor-step
sudo chown root:root /usr/local/sbin/tms-run-standard-vendor-step
sudo chmod 755 /usr/local/sbin/tms-run-standard-vendor-step
```

sudoers 建议：

```sudoers
Defaults:tms !requiretty

tms ALL=(root) NOPASSWD: \
  /usr/local/sbin/tms-rabbitmqctl *, \
  /usr/local/sbin/tms-run-standard-vendor-step setfraq, \
  /usr/local/sbin/tms-run-standard-vendor-step setftq, \
  /usr/local/sbin/tms-run-standard-vendor-step settlq, \
  /usr/local/sbin/tms-run-standard-vendor-step setsptp
```

验证：

```bash
su - tms
sudo -n /usr/local/sbin/tms-run-standard-vendor-step setsptp
ls -l /home/cmep4i/cmsp /home/cmep4i/cmtp
```

执行后 `/home/cmep4i` 下由 vendor 脚本生成或替换的文件应保持为 `cmep4i` 可访问，不应再由 `tms` 直接写成 `tms:tms`。

## 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
```

## 10.6 TMS 独立网关（可选）

当现场需要为 `tms-framework` 单独提供 HTTPS 入口时，建议新增独立 TMS 网关，而不是接管标准收发器现有 `/usr/local/nginx`。

这套独立网关的定位是：

- 只服务 TMS 前端和 TMS API
- 独立于标准收发器现有 Nginx
- 不参与 `START_NGINX`、`STOP_NGINX`、`POST_CHECK`

标准收发器现有 Nginx 仍然保持：

- 配置路径：`/usr/local/nginx/conf/nginx.conf`
- Web 发布目录：`/usr/local/nginx/html`
- 默认标准 Web 验收入口：`8000`

### 10.6.1 推荐端口

推荐保留如下边界：

- 标准收发器现有 Web：`8000`
- TMS TLS 1.3 网关：`443`
- TMS 国密网关：`8443`
- TMS 后端：`127.0.0.1:8088`

因此在启用独立网关前，建议先检查：

```bash
ss -lntp | grep -E ':443|:8443|:8000|:8088'
```

### 10.6.2 推荐目录

建议按如下结构部署：

```text
/home/tms
├── web
│   └── dist
└── gateway
    ├── tls13
    ├── gm
    └── logs
        ├── tls13
        └── gm
```

说明：

- `/home/tms/web/dist`：TMS 前端构建产物
- `/home/tms/gateway/tls13`：TLS 1.3 网关配置
- `/home/tms/gateway/gm`：国密网关配置
- `/home/tms/gateway/logs/*`：对应网关日志

### 10.6.3 仓库模板位置

仓库已提供两套模板：

- TLS 1.3：
  - `deployment/tms-gateway/tls13/nginx.conf`
  - `deployment/tms-gateway/tls13/conf.d/tms.conf`
  - `deployment/tms-gateway/tls13/start.sh`
  - `deployment/tms-gateway/tls13/README.md`
- 国密：
  - `deployment/tms-gateway/gm/nginx.conf`
  - `deployment/tms-gateway/gm/config/http/tms.conf`
  - `deployment/tms-gateway/gm/start.sh`
  - `deployment/tms-gateway/gm/README.md`

部署时建议将模板复制到：

- `/home/tms/gateway/tls13`
- `/home/tms/gateway/gm`

### 10.6.4 前端发布目录

TMS 前端建议统一发布到：

```text
/home/tms/web/dist
```

不建议继续沿用其他项目使用过的 `/app/hsm/vue` 命名。

网关容器建议统一将：

```text
/home/tms/web
```

挂载到容器：

```text
/app
```

这样容器内静态资源根目录仍保持：

```text
/app/dist
```

### 10.6.5 后端代理约定

独立网关统一代理到：

```text
http://127.0.0.1:8088
```

需要放行的核心路由：

- `/`
- `/api/v1/`
- `/swagger-ui.html`
- `/swagger-ui/`
- `/v3/api-docs/`

特别注意：

- TMS 接口本身挂在 `/api/v1/**`
- 网关 `proxy_pass` 不应把 `/api/v1/` 前缀错误改写掉
- 若网关误把 `/api/v1/device/status` 转成 `/device/status`，后端会返回 404

因此后续修改网关配置时，应保持“原始请求路径透传到 TMS 后端”这一约束。

### 10.6.6 证书与镜像

TLS 1.3 网关：

- 默认使用 `nginx:latest`
- 证书目录：`/home/tms/gateway/tls13/certs`
- 默认文件名：
  - `rsa.dev.pem`
  - `rsa.dev.key`

国密网关：

- 默认使用 `gateway.lib:latest`
- 证书目录：`/home/tms/gateway/gm/certs`
- 默认文件名：
  - `sm2.sig.pem`
  - `sm2.sig.key`
  - `sm2.enc.pem`
  - `sm2.enc.key`
  - `rsa.dev.pem`
  - `rsa.dev.key`

补充说明：

- TLS 1.3 网关默认读取自己的 `/home/tms/gateway/tls13/certs`
- 国密网关默认读取自己的 `/home/tms/gateway/gm/certs`
- 如果现场希望 TLS 1.3 直接复用国密目录中的 RSA 证书，可在启动 TLS 1.3 网关时额外指定 `CERT_DIR=/home/tms/gateway/gm/certs`

如果现场为离线部署，可参考：

```bash
docker load -i /Users/waner/Work/CISD/文档/manager/tls13/tls13.tar
docker load -i /Users/waner/Work/CISD/文档/manager/gateway.tar
```

### 10.6.7 启动与验收

TLS 1.3 网关：

```bash
cd /home/tms/gateway/tls13
bash start.sh
```

国密网关：

```bash
cd /home/tms/gateway/gm
bash start.sh
```

TLS 1.3 验收可先检查：

```bash
curl -k https://127.0.0.1/
curl -k https://127.0.0.1/swagger-ui.html
curl -k https://127.0.0.1/api/v1/device/status
```

国密入口建议使用现场指定的国密兼容浏览器或客户端进行验证。

### 10.6.8 与标准收发器 Nginx 的边界

本独立网关方案不改变以下既有边界：

- 不写入 `/usr/local/nginx/conf/nginx.conf`
- 不使用 `/usr/local/nginx/html`
- 不替代标准收发器 Web 发布流程
- 不改变标准收发器初始化和 reset 当前逻辑

换句话说：

- 标准收发器 Nginx 继续服务标准产品自身的 Web
- TMS 独立网关只负责 TMS 自己的前端和 API

## 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 工具是否可用
- 直参版场景下的脚本目录是否存在
- 标准介质与初始化依赖是否已经完成预置

建议在首次联调前执行一次。

## 11.1 现场建议的执行顺序

建议按以下顺序实施：

### 步骤 1：完成部署阶段预置

至少确认：
- 基础软件已安装
- 标准介质已解压
- 运行目录和用户已准备
- 平台级凭据已准备
- `/home/tms` 已部署完毕

### 步骤 2：执行本机预检查

执行：

```bash
PRODUCT_TYPE=ENTERPRISE /Users/waner/Work/CISD/文档/tms-framework/scripts/cisd_init_precheck.sh
```

或按实际产品类型设置：
- `ENTERPRISE`
- `INDIRECT`
- `DIRECT`

### 步骤 3：启动 TMS

执行：

```bash
/home/tms/scripts/tms.sh start
```

### 步骤 4：通过前端或接口执行初始化

在确认预置无误后，再执行：
- 文件上传
- 初始化预检
- 创建初始化任务
- 执行初始化任务

## 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 8088
curl -s http://127.0.0.1:8088/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/stop_standard_apps.sh
bash -n /home/tms/bin/start_standard_nginx.sh
bash -n /home/tms/bin/stop_standard_nginx.sh
bash -n /home/tms/bin/stop_standard_rabbitmq.sh
bash -n /home/tms/bin/check_standard_runtime.sh
```

如启用当前第一版资源备份恢复能力，再额外检查：

```bash
ls -l /home/tms/bin/resource-restore
bash -n /home/tms/bin/resource-restore/apply-resource-backup.sh
bash -n /home/tms/bin/resource-restore/restore-db.sh
bash -n /home/tms/bin/resource-restore/replay-mq.sh
which mysql
which mysqldump
```

当前第一版资源恢复只覆盖：
- `TMS_CONFIG`
- `TMS_DB`
- `CMEP_DB`
- `CP_CONFIG`
- `RECEIVER_LICENSE`
- `MQ_REPLAY`

当前第一版明确不覆盖：
- nginx / web / uploads
- RabbitMQ / TLQ / CFMQ 运行时文件
- 机构库