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