cisd/docs/plans/2026-03-02-cisd-init-onhost-validation-and-rollback.md

CISD 初始化真机联调与回滚手册

• 日期：2026-03-02
• 适用版本：ENTERPRISE / INDIRECT / DIRECT
• 适用代码基线：已包含 APP_MQ_CREDENTIALS_APPLY、direct_db_init、tlq_init_cfg

1. 目的

1. 在目标设备上完成初始化关键路径联调。
2. 验证三类版本在“预部署完成后，仅做客户化初始化”的边界下可稳定运行。
3. 提供失败后的快速回滚与重试指引。

2. 关键实现映射（联调前必须确认）

1. 企业/间参步骤链： RENDER_CONFIG -> SET_(RABBITMQ|TLQ) -> MQ_USER_APPLY -> MQ_QUEUE_APPLY -> DB_INIT -> DEPLOY_RECEIVER -> APP_MQ_CREDENTIALS_APPLY -> VERIFY
2. 轻量化直参（TLQ）步骤链： RENDER_CONFIG -> MQ_USER_APPLY -> DB_INIT(direct_db_init) -> TLQ_INIT_CFG(tlq_init_cfg) -> VERIFY
3. 轻量化直参（CFMQ）步骤链： RENDER_CONFIG -> MQ_USER_APPLY -> DB_INIT(direct_db_init) -> CFMQ_APPLY -> VERIFY
4. 通道账号密码写回应用配置时默认加密： DESede(3DES) + secretKey=ABCDEFGHIJKLMN1234567890 + HEX(upper)。

3. 联调前置检查

3.1 环境变量基线

在 TMS 进程环境确认以下参数：

echo "$TMS_CISD_PRESET_PRODUCT_TYPE"
echo "$TMS_INIT_EXECUTOR_MODE"
echo "$TMS_INIT_EXECUTOR_STANDARD_CPCONFIG_PATH"
echo "$TMS_INIT_EXECUTOR_DIRECT_DB_SCRIPT_DIR"
echo "$TMS_INIT_EXECUTOR_DIRECT_TLQ_INIT_CFG_DIR"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_APP_CONFIG_PATTERN_1"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_APP_CONFIG_PATTERN_2"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_ENCRYPT_ENABLED"
echo "$TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_SECRET_KEY"

建议值：

1. TMS_INIT_EXECUTOR_MODE=LOCAL
2. TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_ENCRYPT_ENABLED=true
3. TMS_INIT_EXECUTOR_STANDARD_RABBIT_CREDENTIAL_SECRET_KEY 与现场收发器解密密钥一致。

3.2 目录与脚本存在性

ls -l /home/cmep4i/cpconfig.cfg
ls -l /home/cmep4i/cpackage/toolsh/{setfraq.sh,setftq.sh,setsql.sh,setsptp.sh}
ls -l /opt/CAE_Install_Base_Resource/DB/setsql.sh
ls -l /opt/CAE_Install_App_Resource/CAE/init_cfg.sh

3.3 MQ 与配置文件可写性

ls -l /home/cmep4i/cmsp/application-prd*.properties
ls -l /home/cmep4i/cmtp/application-prd*.properties
which rabbitmqctl
which rabbitmqadmin

4. 联调执行清单（统一流程）

4.1 接口执行顺序

1. GET /api/v1/device/status
2. POST /api/v1/init/preview
3. POST /api/v1/init/task
4. POST /api/v1/init/task/{taskId}/execute
5. GET /api/v1/init/task/{taskId}/steps
6. 失败时逐步查看日志：GET /api/v1/init/task/{taskId}/steps/{stepNo}/log

4.2 用例矩阵（最小集合）

1. 企业版 + RabbitMQ
2. 企业版 + TLQ
3. 间参版 + RabbitMQ
4. 轻量化直参 + RABBITMQ_TLQ（必须带 directTlq 三字段）
5. 轻量化直参 + RABBITMQ_CFMQ

4.3 直参 TLQ 请求体附加字段

{
  "directTlq": {
    "localNodeSeq": "A",
    "upstreamInstitutions": "CIPSCNSHXXX;CIPSCNWXXXX",
    "upstreamCocCount": 2
  }
}

5. 关键验收点

1. RENDER_CONFIG 后，cpconfig.cfg 中机构号、节点、签名参数、MQ_TYPE 已替换。
2. MQ_USER_APPLY 后，RabbitMQ 中存在通道用户，且具备目标 vhost 权限。
3. MQ_QUEUE_APPLY 后，业务队列创建成功（企业/间参）。
4. APP_MQ_CREDENTIALS_APPLY 后，spring.rabbitmq.username/password 已更新且为密文（非明文）。
5. DB_INIT 生成或替换的 SQL 文件可执行，无路径/权限错误。
6. VERIFY 成功，任务最终状态 SUCCESS。

6. 失败定位顺序

1. 配置错误：版本预置、环境变量、路径。
2. 权限错误：TMS 进程用户对脚本和配置文件不可写。
3. 脚本依赖缺失：rabbitmqctl/rabbitmqadmin、Java、数据库客户端。
4. 参数不完整：直参 TLQ 缺 directTlq 字段。
5. 密钥不一致：写回密文与收发器解密密钥不匹配导致 MQ 连接失败。

7. 回滚策略（按层次）

7.1 执行前备份（强制）

TS=$(date +%Y%m%d%H%M%S)
mkdir -p /tmp/cisd-init-backup-$TS
cp -a /home/cmep4i/cpconfig.cfg /tmp/cisd-init-backup-$TS/
cp -a /home/cmep4i/cmsp/application-prd*.properties /tmp/cisd-init-backup-$TS/ 2>/dev/null || true
cp -a /home/cmep4i/cmtp/application-prd*.properties /tmp/cisd-init-backup-$TS/ 2>/dev/null || true
echo "/tmp/cisd-init-backup-$TS"

7.2 配置回滚

cp -a /tmp/cisd-init-backup-<TS>/cpconfig.cfg /home/cmep4i/cpconfig.cfg
cp -a /tmp/cisd-init-backup-<TS>/application-prd*.properties /home/cmep4i/cmsp/ 2>/dev/null || true
cp -a /tmp/cisd-init-backup-<TS>/application-prd*.properties /home/cmep4i/cmtp/ 2>/dev/null || true

7.3 MQ 回滚（按需）

# 删除通道用户（示例）
rabbitmqctl delete_user <channelUsername>

# 删除业务队列（示例，按实际创建队列名执行）
rabbitmqadmin --username=admin --password=admin --vhost=/ delete queue name=<queueName>
rabbitmqadmin --username=admin --password=admin --vhost=/RQ delete queue name=<queueName>

7.4 数据库回滚（按实际 SQL 执行情况）

1. 若仅生成 SQL 未执行：删除临时生成物即可。
2. 若已执行入库：使用预先准备的回滚 SQL 或从数据库备份恢复。
3. 严禁在无备份情况下直接清库重建。

8. 重试策略

1. 先回滚配置和 MQ 变更，再重建任务重试，不复用失败任务。
2. 每次仅变更一个变量（如路径、密钥、账号），避免多变量同时变化。
3. 连续两次同一步失败，先停止重试，导出该步骤日志并人工排查根因。

9. 交付物归档

每次联调需归档：

1. taskId、版本类型、请求参数（脱敏后）。
2. 步骤执行日志目录：/tmp/tms-init-logs/<taskId>/。
3. 回滚操作记录（是否执行、执行人、时间）。
4. 最终结论：通过/失败及根因。