522 lines
12 KiB
Markdown
522 lines
12 KiB
Markdown
# 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
|
||
```
|