zgw
699310e61d
Use the business project and captured site predicates, validate single-stock proposals, and skip unsupported scopes without changing Legacy. Add the guarded V3.3 SQL upgrade, CMD operations, regression tests and deployment runbook.
194 lines
8.3 KiB
Markdown
194 lines
8.3 KiB
Markdown
# FT546WMS 影子 v3 现场操作手册
|
||
|
||
已部署 V3/V3.1/V3.2 的现场升级到 V3.3，请先使用 [V3.3 升级和回滚步骤](SHADOW_V33_DEPLOYMENT.md)。下面保留最初 v2 到 v3 的历史操作说明，不要把“当前现场已有 v2”套用于已升级现场。
|
||
|
||
## 1. 这次部署做什么
|
||
|
||
目标分支：`test/ft546wms-shadow-v3-20260903`。
|
||
|
||
影子 v3 只观察算法建议，不改变 Legacy 分配结果。入库、自动出库、手动出库仍由原存储过程执行一次，原返回码、返回消息、库位和异常保持不变。正常业务请求只做固定大小的内存登记，不等待影子线程，也不在调用线程执行影子数据库、文件或同步日志操作。
|
||
|
||
影子后台会读取业务表，并且只写 `alg.*` 对象。它可能增加数据库 CPU 和 I/O，因此仍需低峰部署、监控和随时回滚。
|
||
|
||
## 2. 固定安全边界
|
||
|
||
- 现场只允许一个 FT546WMS JVM，稳定版和影子版不能同时运行。
|
||
- 仓库固定为 `01`；原始数据中的 `1` 与 `01` 等价，`W02` 只用于诊断，不能覆盖配置。
|
||
- SQL Server 必须使用 Windows 集成认证；脚本不接收用户名和密码。
|
||
- 当前现场已有 v2 包，安装必须使用 `upgrade`，不能使用 `clean`。
|
||
- v2 到 v3 升级保留 `alg.decision_log`；发现未知 `alg` 对象、清单不完整或 manifest 不匹配时脚本会停止。
|
||
- 影子失败、过期、并发、超时、配置错误或输入缺失均 fail-open：Legacy 继续，影子样本作废。
|
||
- 不执行正式 ACTIVE 切换，不增加 WCS/PDA/理库/预留/回放功能。
|
||
|
||
## 3. 部署前准备
|
||
|
||
现场负责人先记录：
|
||
|
||
- SQL Server 名称和数据库名；
|
||
- 当前 v2 测试开始时间和时区；
|
||
- IDEA 当前 Run Configuration；
|
||
- 当前稳定实例 PID 和端口；
|
||
- 本次交付给出的精确 v3 提交号 `<V3_COMMIT>`；
|
||
- 应用日志目录。
|
||
|
||
部署前先导出现有 v2 证据。不要卸载 v2：
|
||
|
||
```cmd
|
||
cd /d C:\project\FT546WMS-SHANDOW
|
||
call scripts\shadow-v3-export.cmd C:\project\FT546WMS-SHANDOW "<SQL_SERVER>" "<DATABASE>" "<V2_START_UTC>" "C:\project\FT546WMS-v2-before-v3" "<LOG_DIR>"
|
||
```
|
||
|
||
如果当前代码还没有 v3 导出脚本，先用既有导出方式保存 `alg.decision_log`、诊断结果、日志、分支和提交号，再继续。
|
||
|
||
## 4. 按顺序部署 v3
|
||
|
||
### 第一步：停止 IDEA 中的 v2 稳定实例
|
||
|
||
记录停止时间，在 IDEA 点 Stop。用下面命令确认最多只有一个相关 JVM，最好为 0：
|
||
|
||
```cmd
|
||
jps -lv | findstr /I "RuoYiApplication FT546WMS"
|
||
```
|
||
|
||
停止和重新启动之间会有一次短暂停机，这是计划内中断。不要同时启动两个实例来消除停机，否则可能重复执行定时任务、消费或外部回调。
|
||
|
||
### 第二步：同步精确分支和提交
|
||
|
||
```cmd
|
||
cd /d C:\project\FT546WMS-SHANDOW
|
||
git fetch origin
|
||
git switch test/ft546wms-shadow-v3-20260903
|
||
git pull --ff-only
|
||
git rev-parse HEAD
|
||
git status --porcelain
|
||
```
|
||
|
||
`git rev-parse HEAD` 必须等于交付的 `<V3_COMMIT>`，`git status --porcelain` 必须没有输出。若不一致，停止部署。
|
||
|
||
### 第三步：执行只读预检
|
||
|
||
```cmd
|
||
call scripts\shadow-v3-preflight.cmd C:\project\FT546WMS-SHANDOW <V3_COMMIT> "<SQL_SERVER>" "<DATABASE>"
|
||
```
|
||
|
||
只有看到 `PREFLIGHT_OK` 才能继续。预检检查分支、精确提交、干净工作树、main 祖先、JVM 数量、SQL 连接、v2/v3 manifest 和当前快照；它不修改数据库。
|
||
|
||
### 第四步：升级数据库包
|
||
|
||
当前现场是 v2，只执行：
|
||
|
||
```cmd
|
||
call scripts\shadow-v3-install.cmd "<SQL_SERVER>" "<DATABASE>" upgrade
|
||
```
|
||
|
||
只有全新测试数据库、确认没有 `alg` schema 时才允许使用 `clean`。现场生产库不要使用 `clean`。
|
||
|
||
### 第五步：设置 IDEA 环境变量
|
||
|
||
在影子 Run Configuration 中使用：
|
||
|
||
```text
|
||
FORTUCKY_SHADOW_ENABLED=true
|
||
FORTUCKY_ALGORITHM_MODE=SHADOW
|
||
FORTUCKY_ALGORITHM_DATABASE_WRITES_ENABLED=true
|
||
FORTUCKY_ALGORITHM_WAREHOUSE_ID=01
|
||
FORTUCKY_SHADOW_TIMEOUT_SECONDS=3
|
||
FORTUCKY_SHADOW_SNAPSHOT_MAX_AGE_SECONDS=60
|
||
FORTUCKY_SHADOW_QUIET_INTERVAL_MILLIS=1000
|
||
```
|
||
|
||
不要设置 `ACTIVE`，不要添加数据库密码，不要设置 replay、tidy、reservation 或 WCS callback 开关。
|
||
|
||
### 第六步：只启动一次影子实例
|
||
|
||
在 IDEA 启动 v3。不要重复点击 Run。启动时后台会认领唯一实例并建立第一代快照；认领或刷新失败只会关闭影子可用性，不应阻止 Legacy 启动。
|
||
|
||
启动后检查：
|
||
|
||
```cmd
|
||
jps -lv | findstr /I "RuoYiApplication FT546WMS"
|
||
```
|
||
|
||
只能看到一个 FT546WMS JVM。
|
||
|
||
### 第七步：做只读和受控业务检查
|
||
|
||
先完成登录、页面查询等只读检查，再由现场人员执行一笔受控入库、一笔自动出库和一笔手动出库。确认：
|
||
|
||
- Legacy 返回码、消息、库位和设备动作与稳定流程一致；
|
||
- 没有相同存储过程重复执行；
|
||
- `alg.shadow_snapshot_state` 为仓库 `01` 的 `PUBLISHED`；
|
||
- `alg.shadow_instance_heartbeat` 只有当前实例；
|
||
- `alg.decision_log` 出现新的计划/比较记录；
|
||
- 应用日志中的影子 warning 不包含业务载荷或异常消息。
|
||
|
||
## 5. 立即停止条件
|
||
|
||
出现任一情况立即执行第 7 节回滚：
|
||
|
||
- Legacy 结果、响应码、消息、库位或设备动作改变；
|
||
- 同一个 Legacy 存储过程疑似执行两次；
|
||
- 出现第二个 FT546WMS JVM；
|
||
- `alg` 之外出现本次部署造成的数据写入或新对象；
|
||
- WMS、WCS、PDA 或现场作业异常；
|
||
- 正常接口延迟或数据库 CPU、I/O、锁等待超过现场阈值；
|
||
- 快照长时间不是 `PUBLISHED`，或 `ERROR_*` 指标持续增长。
|
||
|
||
单条 `shadow_failure` 表示该影子样本失败开放，不等于 Legacy 失败；但必须记录时间并纳入分析。
|
||
|
||
## 6. 连续观察和七天导出
|
||
|
||
至少连续观察 7 天，覆盖正常业务高峰、入库、自动出库和手动出库。期间不要重放业务来补影子样本。
|
||
|
||
观察结束后运行：
|
||
|
||
```cmd
|
||
cd /d C:\project\FT546WMS-SHANDOW
|
||
call scripts\shadow-v3-export.cmd C:\project\FT546WMS-SHANDOW "<SQL_SERVER>" "<DATABASE>" "<V3_START_UTC>" "C:\project\FT546WMS-shadow-v3-export" "<LOG_DIR>"
|
||
```
|
||
|
||
成功时显示 `EXPORT_OK`。输出目录包含：
|
||
|
||
- `deployment.txt`：分支、提交、工作树；
|
||
- `runtime-processes.txt`：JVM 进程；
|
||
- `environment-variable-names.txt`：仅环境变量名，不含值；
|
||
- `sql-diagnostics.txt`：manifest、快照、心跳、输入覆盖、阻塞；
|
||
- `comparison-detail.txt`：比较汇总和完整决策行；
|
||
- `runtime-metrics.txt`：准入、跳过、错误和时延桶；
|
||
- `inventory-parity.txt`：Legacy 与已发布快照库存差异计数；
|
||
- `shadow-warnings.txt`：日志目录中的结构化影子 warning。
|
||
|
||
把整个输出目录压缩后交给分析，不要包含密码、令牌或与测试无关的个人信息。只有七天数据通过分析后，才讨论正式切换；本分支本身不执行 ACTIVE 切换。
|
||
|
||
## 7. 回滚
|
||
|
||
首选回滚只关闭影子，不卸载数据库对象：
|
||
|
||
1. 在 IDEA 停止 v3，记录停止时间；
|
||
2. 设置 `FORTUCKY_SHADOW_ENABLED=false`；
|
||
3. 完整重启一次；
|
||
4. 检查只有一个 JVM；
|
||
5. 做登录、查询、受控入库和出库冒烟检查。
|
||
|
||
更彻底的应用回滚是停止 v3，切回现场原稳定源码/提交并用原 Run Configuration 启动。无论哪种方式，都先恢复业务服务，再处理数据库对象。
|
||
|
||
`alg.*` 可以保留供取证，稳定 Legacy 不依赖它。不要把卸载当作紧急回滚步骤。
|
||
|
||
## 8. 可选卸载
|
||
|
||
只有满足全部条件才卸载：影子实例已停止、稳定服务已恢复、七天证据已导出并备份、DBA 已确认维护窗口。
|
||
|
||
```cmd
|
||
call scripts\shadow-v3-uninstall.cmd "<SQL_SERVER>" "<DATABASE>" CONFIRM_UNINSTALL
|
||
```
|
||
|
||
卸载器只接受精确口令 `CONFIRM_UNINSTALL`，并由 SQL 包再次校验 v3 manifest 和完整对象白名单。发现未知/缺失对象时会在删除前停止。不要修改 manifest 或脚本绕过保护。
|
||
|
||
## 9. 自动化验证与残余风险
|
||
|
||
- 本地单元/静态测试不能替代 SQL Server 2016 备份副本演练。
|
||
- `READ UNCOMMITTED` 只用于观察，可能看到业务事务中间状态。
|
||
- 单线程容量一队列限制影子后台并发，但不能消除数据库资源竞争。
|
||
- 3 秒 worker 等待超时不等于 JDBC/SQL Server 一定在 3 秒内完成取消或回滚。
|
||
- 影子调用线程不等待后台，但主机和数据库资源竞争仍可能间接影响 Legacy，需要现场监控。
|