cisd/docs/plans/2026-03-10-tms-deployment-doc-design.md

TMS Deployment Document Design

Date: 2026-03-10

Goal

维护一份面向现场部署和运维的 TMS 部署手册，覆盖 /home/tms 目录结构、jar 与脚本部署、配置文件、初始化依赖、文件上传目录、启动检查与常见故障定位。

Audience

• 现场运维
• 集成交付人员
• 后端开发/联调人员

Document Style

文档应以“可执行手册”为目标，而不是概念说明。要求：

• 直接给目录和命令
• 标明哪些内容必须预置，哪些由 TMS 初始化处理
• 区分标准版和直参版相关依赖，但不重复解释业务背景
• 每节都有输入、操作、结果或检查点

Scope

纳入部署文档：

• TMS 运行环境要求
• /home/tms 目录结构
• jar、配置、脚本、上传目录部署
• application.yml 关键配置说明
• 标准版初始化脚本 /home/tms/bin/*.sh 的作用和依赖
• 文件上传与 fileId 模型说明
• TMS 启动、停止、状态检查
• 初始化联调前检查
• 常见故障与排查

不纳入：

• CIPS 标准收发器基础安装手册全文复述
• 密码卡详细使用文档
• OpenAPI 业务接口全集说明

Proposed Document Location

建议新增正式手册：

• /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md

README 保留简版入口，完整运维说明进入该文档。

Proposed Structure

1. 文档目的与适用范围
2. 环境要求
3. 部署目录结构
4. 部署物清单
5. /home/tms/config/application.yml 关键配置
6. /home/tms/bin 初始化脚本说明
7. 文件上传与 fileId 约定
8. 启动/停止/状态命令
9. 初始化前置检查
10. 常见故障排查
11. 附录：推荐命令与检查项

Key Content Decisions

1. 明确边界

部署文档必须明确：

• TMS 只负责自身部署和 CISD 初始化编排
• 标准收发器、RabbitMQ、TLQ、TiDB、nginx 的基础安装属于预置层
• 初始化阶段负责客户化配置、落位、导库、发布和启动命令调用

2. 目录结构固定化

文档采用 /home/tms 作为标准路径：

• /home/tms/tms-framework.jar
• /home/tms/config/application.yml
• /home/tms/scripts/tms.sh
• /home/tms/bin/*.sh
• /home/tms/uploads/
• /home/tms/logs/
• /home/tms/run/
• /home/tms/tmp/

3. 配置说明强调初始化相关参数

重点说明：

• tms.file.storage.upload-base-dir
• tms.init.executor.*
• 标准版脚本命令路径
• RabbitMQ 预置管理员账号
• 日志目录、staging 目录

4. 文件上传模型单独成节

必须明确：

• 初始化接口不接收 multipart 文件
• 前端先上传文件，再使用 fileId
• 上传目录与初始化执行器解析规则保持一致

5. 故障排查按常见现场问题组织

优先纳入：

• jar 无法启动
• DB_APPLY 命令为空
• cpconfig 找不到
• fileId 文件找不到
• RabbitMQ 队列创建失败
• nginx 未启动
• WEB 未发布

Output Expectation

产出两类文档：

• README.md 中保留精简入口
• docs/deployment/tms-deployment.md 作为完整部署手册