docs(P1): 引擎加固三件实测报告 + 迁移手册新增三坑(5.19/5.20/5.21)

P1加固实测报告.md 三件各一节(实现/8086实测证据/边界):P1-3 注入负例逐条 curl、
P1-4 C1坑3 不重启回归全链路、P1-5 索引规则正确性+幂等+诚实延迟边界。
迁移手册 5.19 引擎裸拼点清单、5.20 setChangePOInfo 冷态装载、5.21 createTableSql
不建索引;3.1 CCache 行更新为 Caffeine 版。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 12:11:13 +08:00
parent 3fa970adbf
commit ca2a6db0ab
2 changed files with 186 additions and 1 deletions

View File

@@ -105,7 +105,7 @@ com.dsasp.* com.eip4.*
|------|-------------|---------|---------|---------|---------|
| `SpringBeanOsgiServices` | OSGi BundleListener 服务定位器 | `ApplicationContext.getBean(name)` | 72 行 | 43 行 | 注入 `ApplicationContext`,按名取 bean;删除 BundleListener 逻辑 |
| `ScanServiceBeanXml` | OSGi bundle 启动期 SAX 扫描 service XML | no-op(保留 `classList` 契约) | 待查 | 极简 | 业务调用方只用 classList 返回值 |
| `CCache` | Adempiere 缓存(GPL 头 + CacheMgt 注册) | 极简 HashMap 版 | 待查 | 极简 | 调用方只用 Map API,实现可直接换 |
| `CCache` | Adempiere 缓存(GPL 头 + CacheMgt 注册) | **Caffeine 版**(P1-4 由极简 HashMap 升级) | 待查 | 极简 | 调用方只用 Map API;**公共签名零改动**(仍 extends HashMap + 双构造器 + getName/reset),`get/put/remove/size/clear` 覆写代理到内部 Caffeine `Cache`。详见 5.15 |
| `Console` | Vaadin 浏览器控制台推送 | `slf4j` | 待查 | 极简 | 日志语义等价 |
| `InstallOrUpdate` | 启动期按版本跑 install SQL | `isDevDB()=false` 桩 | 待查 | 极简 | 生产环境不触发 |
| `GetServicesFunction` 等 3 个 | Groovy 脚本函数库(约 2,600 行) | Java 桩(仅实现 `findCount`);WS3 回迁 | 约 2,600 行 | 最小桩 | P1/P3 阶段补全真实现 |
@@ -302,6 +302,28 @@ com.dsasp.* com.eip4.*
- **对策**:P1 不在门面做引擎级读写闸(避免误判);**调用方/运维按流定义 XML 审阅确认查询/报表类后放行**,客户库只读纪律下只执行已审阅无写动作的流。P2 补三层防护:①流定义静态扫描(service method 读白名单);②最小权限只读连接;③statement_timeout。
- **影响范围**:所有经 REST 执行的服务流;客户库只读期的流挑选;P2 安全加固(对齐架构第四节安全第 1/3/4 层)。
### 5.19 标识符白名单——引擎裸拼点清单(安全第 1 层落地) [NEW 2026-06-11]
- **现象**:`POJOCRUDServiceImpl.listSelectSpecialCol` 把查询条件 Map 的 key 经 `get_SearchWhereClause(map)` 拼成 WHERE 列名;`ORDER` 键(值 `" ORDER BY ..."`)经 `sql = sql + order` **裸拼**到 SQL 末尾(见 POJOCRUDServiceImpl.java:101/309/318/388)——列名/排序列是残余注入面。
- **根因**:引擎值位置已经 `StringUtil.TO_STRING` 单引号转义,但标识符(列名/排序列/表名)位置无转义概念,只能靠白名单。
- **对策(P1-3 已落地)**:`com.eip4.platform.metadata.security.IdentifierWhitelist` 用「该实体 `SYS_ENTITYATTRIBUTE` 合法列集」做白名单,`EntityController.list` 的查询条件 key、`orderBy`、表名全过白名单,非法 → HTTP 400(不回显载荷);`orderDir` 限 `asc/desc`。保留键放行清单:`page/perPage/asUser/roles/orderBy/orderDir`。**新增列/排序参数进引擎前必过白名单**,这是现代层对引擎裸拼点的纪律。
- **影响范围**:所有经现代层进引擎拼接的标识符;新写 Controller 透传查询条件/排序时必须复用 `IdentifierWhitelist`;详见 platform-metadata/P1加固实测报告.md 第一节。
### 5.20 POInfo 缓存失效靠 setChangePOInfo,冷态需先装载 id_cache [NEW 2026-06-11]
- **现象**:C1 坑 3「POInfo 缓存元数据变更后不失效须重启」。引擎公共静态钩子 `AbstractPOJOInfo.setChangePOInfo(entityId)` 清 `id_cache[entityId]→tableName` 再清 `s_cache[tableName]`;但若 `id_cache` 冷态(该 entityId 未被读过),钩子拿不到 tableName,**清不掉 s_cache**。
- **根因**:`setChangePOInfo` 依赖 `id_cache` 已装载 entityId→tableName 映射;首次读才装载。
- **对策(P1-4 已落地)**:现代层 `PoInfoCacheInvalidator.evictByTable` **先 `POInfo.getPOInfo(table)` 装载映射(顺带拿 entityId)再调 `setChangePOInfo`**,保证冷态也能命中;`evictByEntityId` 用于已知 entityId 的删除场景。接入 `MetaController.createEntity/dropEntity` + 新增 `POST /api/meta/evict/{table}` 运维出口。**全程只用引擎公共 API,不改 com.dsasp**。8086 实测:旁路加列 → 未失效仍 400(复现坑)→ 调 evict(不重启)→ 200(修复)。
- **影响范围**:所有元数据旁路写入(直改 SYS_ENTITYATTRIBUTE 等)后须调失效钩子;CCache 换 Caffeine 后失效语义不变(reset/remove 仍即时生效)。
### 5.21 引擎 createTableSql 只建表不建索引,补索引须现代层后置 [NEW 2026-06-11]
- **现象**:`Entity.createTableSql` 只产 `CREATE TABLE` + 主键 + `unique`(标识符列),**不建普通索引**;外键列(REFERENCEID=36 位 uuid)、审计列 UPDATETIME 无索引,大表首页 count/扫描/排序慢(C3 客户库 34k 行 P95 1.18s)。
- **根因**:引擎 DDL 生成器设计只保证结构正确性,不含查询优化索引。
- **对策(P1-5 已落地)**:`com.eip4.platform.metadata.perf.IndexEnhancer` 现代层后置——建表后按元数据补 `CREATE INDEX IF NOT EXISTS`(外键 uuid 列 + UPDATETIME;**跳过** ISIDENTIFIER/ISCOMBIDENTIFIER 因引擎已建 unique);`BacklogIndexScriptGenerator` 为存量实体**只生成补索引 SQL 落盘,不对客户库执行**(执行排切流期变更窗口)。**不改引擎**。
- **诚实边界**:本地 20k 行口径索引延迟改善边际(planner 小表仍 Seq Scan);真实收益在 34k+ 行 + JOIN/count 档,需客户库副本切流期执行脚本后用 load_p95.py 同口径复测验证。
- **影响范围**:所有动态建表的业务实体;客户库存量补索引执行排变更窗口;新建实体经 MetaController 自动补索引。
## 六、Flowable 升级三坑
> 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10)

View File

@@ -0,0 +1,163 @@
# P1 引擎加固三件套实测报告(P1-3 / P1-4 / P1-5)
> 版本 v1.0(2026-06-11)| 范围:eip4-platform 现代层引擎加固三件
> 环境:本地自举库 `localhost:5433/eip4m0`,服务 **端口 8086**(profile=local),M2 Mac,JDK 17
> 起服务:`mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=local -Dspring-boot.run.arguments=--server.port=8086`
> 纪律证据:全模块 `mvn test` 绿 + ArchUnit 绿(`com.dsasp` 不依赖 `com.eip4`);`com.dsasp.*` 保真层公共签名零修改(CCache 仅换内部实现)
> 单测合计:**32 个**(P1-3:16 / P1-4:10 / P1-5:6)
---
## 一、P1-3 标识符白名单(安全第 1 层,最优先)
### 实现
依据《架构设计》(docs/架构设计.md)第四节:列名/表名/排序列必须存在于该实体 `SYS_ENTITYATTRIBUTE` 元数据,否则拒绝——「元数据即白名单,零维护零误杀」。
| 类 | 职责 |
|----|------|
| `com.eip4.platform.metadata.security.IdentifierWhitelist` | 从引擎 `POInfo.getPOInfo(table)`(已走 POInfo 缓存)取合法列集,叠一层 Caffeine 缓存归一化大写列名;`tableExists` 校验表在 `SYS_ENTITY`;`requireLegalColumn`/`requireLegalTable` 失败抛 `IllegalIdentifierException` |
| `IllegalIdentifierException` | 报错只描述「哪类参数非法 + 哪个实体」,**绝不回显用户拼接内容**(避免反射式信息泄露);表名回显也只放行 `[A-Z0-9_]` |
| `IdentifierWhitelistExceptionHandler` | `@RestControllerAdvice` 统一转 **HTTP 400** + `{status:1,msg}`(amis 约定) |
`EntityController.list` 入口全部过白名单:
- **表名**:`requireLegalTable(table)`——非法表名不进引擎拼接;
- **查询条件 key**(amis filter 透传):逐个 `requireLegalColumn(...,"查询条件")`;
- **排序参数**:新增 `orderBy`/`orderDir` 形参,`orderBy` 过白名单、`orderDir` 限 `asc/desc`,合法后才按引擎 `ORDER` 键安全装配 `" ORDER BY <col> <dir>"`(引擎将其裸拼到 SQL 末尾,故必须先过白名单);
- **保留键放行清单**:`page/perPage/asUser/roles/orderBy/orderDir`——协议/控制参数,不当列名校验(但各自做语义校验)。
### 实测证据(8086 本地库 curl 实测)
| # | 请求 | 期望 | 实测 |
|---|------|------|------|
| 1 | `GET /api/entity/EIP4PT_ALLTYPE/list?CODE=X`(合法表+合法列) | 200 | **HTTP 200** ✅ |
| 2 | `GET /api/entity/NOSUCH_TABLE/list` | 400 | **400** `{"status":1,"msg":"非法实体或元数据不存在: NOSUCH_TABLE"}` ✅ |
| 3 | 列名注入 `CODE' OR 1=1--`(URL 编码进 query key) | 400 | **400** `"查询条件含非法列标识符,已拒绝(必须是实体 EIP4PT_ALLTYPE 的已登记列)"` ✅ |
| 3b | 列名注入 `CODE;DROP TABLE X` | 400 | **400**(同上文案);`psql` 确认 `eip4pt_alltype` 物理表仍在,注入未生效 ✅ |
| 4 | ORDER BY 注入 `orderBy=CODE; DROP TABLE EIP4PT_ALLTYPE` | 400 | **400** `"排序列含非法列标识符,已拒绝..."` ✅ |
| 5 | 非法排序方向 `orderDir=evil` | 400 | **400** `"排序方向非法,只允许 asc/desc"`(不回显 `evil`) ✅ |
| 6 | 合法排序 `orderBy=CODE&orderDir=desc` | 200 | **HTTP 200** ✅ |
| 7 | 保留键 `asUser=ADMIN&roles=R1` | 200 | **HTTP 200**(保留键放行,不当列校验) ✅ |
| 8 | 非法列 `NONEXIST_COL=1` | 400 | **400**(查询条件路径) ✅ |
**单测 16 个**:`IdentifierWhitelistTest`(10:合法/非法列、`' OR 1=1--`/`;DROP` 进列名与排序参数负例、合法/非法表、报错不回显载荷、归一化、失效后重读)+ `EntityControllerWhitelistTest`(6:非法表/非法列/非法排序方向拒绝、合法放行并安全装配 ORDER 串、保留键不过白名单、异常处理器转 400)。
### 边界
- `orderBy` 当前支持单列;多列排序如未来开放,需对每列分别过白名单(规则已就绪,扩展点在 `applyOrder`)。
- 字段投影(`RETURN_COLUMNS_LIST`):当前 list 入口未开放显式投影参数,投影列若未来开放须复用 `requireLegalColumn`(语义同查询条件)。
---
## 二、P1-4 POInfo Caffeine 缓存 + 失效钩子
### 实现
**缓存**:`com.dsasp.server.common.dataDic.bean.CCache` 内部实现由「极简 HashMap 版」换 **Caffeine**(`com.github.ben-manes.caffeine:caffeine`,版本走 Spring Boot 3.3.13 BOM = 3.1.8)。
- **公共签名一行不动**:仍 `extends HashMap<K,V>`、两个构造器 `(name,cap)`/`(name,cap,expireMinutes)`、`getName()`/`reset()` 原样;`get/put/remove/containsKey/size/clear` 被覆写为代理到内部 Caffeine `Cache`,故 4 处 call site(`AbstractPOJOInfo` 的 `s_cache`/`id_cache`、`Enumerate`、`SysConfig`)**零改动**全部受益。
- 默认无过期(元数据缓存语义,靠失效钩子主动失效,与原 PoC 行为一致);`expireMinutes>0` 时启用写后过期。`maximumSize=max(initialCapacity,256)`。
**失效钩子**:`com.eip4.platform.metadata.perf.PoInfoCacheInvalidator`(现代层,**不改 com.dsasp**)。选「显式 evict」而非 AOP——侵入最小,不引 aspectj 织入,失效点就在 `com.eip4` 元数据写调用点旁。失效经引擎既有公共静态钩子 `AbstractPOJOInfo.setChangePOInfo(entityId)`;为保证缓存冷态也命中,先 `POInfo.getPOInfo(table)` 装载映射再调钩子。接入点:
- `MetaController.createEntity` 建表后 → `evictByTable`;
- `MetaController.dropEntity` 删除后 → `evictByEntityId`;
- 新增 `POST /api/meta/evict/{table}` 运维出口(元数据旁路变更后免重启失效)。
### 实测证据(C1 坑 3 回归:8086 不重启验证)
旁路改元数据 + 不重启即生效全链路:
| 步骤 | 动作 | 结果 |
|------|------|------|
| 1 | `list` 用 `NEWCOL` 过滤(此列尚不存在)→ 缓存 POInfo | **400**(列非法) |
| 2 | `psql` 旁路向 `SYS_ENTITYATTRIBUTE` 加列 `NEWCOL` + `ALTER TABLE` 加物理列 | — |
| 3 | **未失效**,再用 `NEWCOL` 过滤 | **仍 400**(复现 C1 坑 3 现象:缓存不失效) |
| 4 | `POST /api/meta/evict/EIP4HD_IDXCHK`(不重启) | **200** `{"status":0,"msg":"evicted EIP4HD_IDXCHK"}` |
| 5 | 失效后再用 `NEWCOL` 过滤 | **200**(新元数据生效) |
**结论**:C1 坑 3「POInfo 缓存元数据变更后不失效须重启」**已修复**——失效钩子调用后无需重启即反映新元数据。
**单测 10 个**:`CCacheCaffeineTest`(6:put/get 往返、remove、reset 返回原大小、getName 保持、null 键值安全、带过期构造器)+ `PoInfoCacheInvalidatorTest`(4:按 entityId 精确/全量 evict、钩子调 setChangePOInfo 清引擎缓存、空入参不抛)。
### 边界 / 与架构条款的差距(诚实记录)
架构第三节留口:「元数据缓存走 **Spring Cache 抽象**,多实例横扩时换 Redis 只改配置」。**当前实现为 Caffeine 直用,未走 Spring Cache 抽象**,原因:
- `CCache` 的公共签名(`extends HashMap` + 4 处静态字段 `new CCache<>(...)` 直引 + `s_cache.get/put`)锁死了——在「不破坏公共签名」前提下无法把它替换为 Spring `@Cacheable` 抽象(那要求改调用方为方法级缓存注解或注入 `CacheManager`,即改 `com.dsasp` 源码,违反保真层纪律)。
- 故按任务约定:**实现为 Caffeine 直用,在此写清差距与后续路径**,不硬造破坏签名的抽象。
- **后续路径**(多实例横扩触发时):(a)新增 `com.eip4` 侧 `CacheManager`(Caffeine→Redis 可配),让 CCache 内部 `delegate` 从 `CacheManager` 取(仍不改签名);或(b)在切流前评估把元数据缓存上移到现代层服务,旧 CCache 退化为穿透。当前单实例部署形态下 Caffeine 直用即满足,Redis 留口不在 P1 兑现。
---
## 三、P1-5 DDL 索引增强(现代层后置,不改引擎)
### 实现
引擎 `Entity.createTableSql` 只建表 + 主键/唯一约束,**不建普通索引**(架构第五节改造点;C3 客户库实测 34k 行表首页 P95 1.18s、38k 行复杂视图 4.6s,无索引是主因之一)。
| 类 | 职责 |
|----|------|
| `com.eip4.platform.metadata.perf.IndexEnhancer` | 按元数据生成/执行 `CREATE INDEX IF NOT EXISTS`。规则:**外键列**(`REFERENCEID` 为 36 位 uuid)+ **审计列 UPDATETIME**;**跳过** `ISIDENTIFIER`/`ISCOMBIDENTIFIER`(引擎已建 unique 覆盖);幂等 `IF NOT EXISTS`;索引名 `IDX_<表>_<列>` 截断到 PG 上限 63 字节 |
| `BacklogIndexScriptGenerator` | 存量补索引脚本生成器:扫 `SYS_ENTITY` 按同规则**只落盘成 .sql 文件,不对客户库执行**(客户库执行排切流期变更窗口) |
接入点:`MetaController.createEntity` 在 `executeCreateSql` 之后调 `enhanceForNewEntity`(新实体自动补索引);新增 `POST /api/meta/backlog-index`(生成脚本落盘;`execute=true` 仅本地库实际执行)。
### 实测证据(8086 本地库)
**新建实体自动补索引 + 规则正确性**(控制实体 `EIP4HD_IDXCHK`:含 FK uuid 列 `PARENT_REF`、标识符列 `CODE`、审计列 `UPDATETIME`):
生成脚本(`POST /api/meta/backlog-index?prefix=EIP4HD_&execute=true`):
```sql
-- EIP4HD_IDXCHK (2 索引)
CREATE INDEX IF NOT EXISTS IDX_EIP4HD_IDXCHK_PARENT_REF ON EIP4HD_IDXCHK (PARENT_REF);
CREATE INDEX IF NOT EXISTS IDX_EIP4HD_IDXCHK_UPDATETIME ON EIP4HD_IDXCHK (UPDATETIME);
```
`psql` 索引落地(只对 FK + UPDATETIME 建,**跳过** `CODE`——引擎已建 `eip4hd_idxchk_code_key` unique、跳过 PK/普通列 `TITLE`):
```
idx_eip4hd_idxchk_parent_ref | ... (parent_ref)
idx_eip4hd_idxchk_updatetime | ... (updatetime)
eip4hd_idxchk_code_key | UNIQUE ... (code) ← 引擎建,IndexEnhancer 不重复
eip4hd_idxchk_pkey | UNIQUE ... (pk)
```
**幂等性**:再次执行 `execute=true` 无报错,索引数仍 2(`IF NOT EXISTS` 生效)。
### 延迟对比与边界(诚实记录)
控制实体灌 20,000 行,`UPDATETIME` 过滤 / `ORDER BY UPDATETIME LIMIT 20`,建索引前后 p95:
| 口径 | 无索引 p95 | 有索引 p95 |
|------|-----------:|-----------:|
| `UPDATETIME=值` 过滤(list 端点,30 次) | 1.81 ms | 1.42 ms |
**诚实边界**:本地 20k 行 / M2 单机 / 单值过滤口径下,索引带来的延迟改善**边际**(planner 对 20k 行仍选 Seq Scan / top-N heapsort,因小表全扫已很便宜)。这与 C3 基线结论一致——**索引增强的真实收益在 34k+ 行 + JOIN/LATERAL/全表 count 的客户库档**(`HR_ATTENDLOG` 34k P95 1.18s、`PM_PAYMENTAPPLY` 38k 4.6s 那一档),非本地小数据可量化。本地实测的价值是**证明索引按规则正确生成、落地、幂等、planner 可识别**;延迟量化收益的正式锚点需在客户库副本(192.168.20.68:5435)切流期变更窗口执行补索引脚本后,用 `tools/loadtest/load_p95.py` 同口径复测。
**存量补索引执行边界**:`BacklogIndexScriptGenerator` 默认只落盘;客户库执行**排切流期变更窗口**由 DBA 跑(脚本 `IF NOT EXISTS` 幂等,可分批/可中断重跑)。
**单测 6 个**:`IndexEnhancerTest`(外键 uuid 列建索引、UPDATETIME 建索引、标识符列跳过、普通/基础类型不建、混合列只对外键和 UPDATETIME 建、索引名超长截断到 63)。
---
## 四、环境边界说明(实测期遇到的本地库不稳定)
本地 `eip4m0` 为**自举可重建的共享环境**,实测期被并行作业多次重置(`SYS_ENTITY` 在 8 行 SYS_* 与 21 行 EIP4PT_* 间反复)。三件加固的 e2e 证据均在对应数据态下采集完毕;P1-4 / P1-5 的 e2e 改用**自控制实体 `EIP4HD_IDXCHK`**(直插元数据,免受重置影响)采集,确定性强。三件的**单测(32 个)不依赖库,稳定复跑**;全模块 `mvn test` + ArchUnit 绿。
## 五、复跑命令
```bash
# 起服务(端口 8086;8084/8085 是别人的,勿动)
cd eip4-platform
mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=local \
-Dspring-boot.run.arguments=--server.port=8086
# 单测
mvn test # 全模块 + ArchUnit
mvn test -pl platform-metadata # P1-3/4/5 现代层单测
mvn test -pl platform-legacy-core -Dtest=CCacheCaffeineTest # P1-4 CCache
# P1-3 注入负例(见上文表逐条 curl)
# P1-5 存量补索引脚本(落盘;execute=true 仅本地库)
curl -X POST 'http://localhost:8086/api/meta/backlog-index' \
--data-urlencode 'out=/abs/path/backlog-index.sql' \
--data-urlencode 'prefix=EIP4PT_' --data-urlencode 'execute=false' -G
```