Files
eip4-platform/platform-metadata/P1加固实测报告.md
zhengwr ca2a6db0ab 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>
2026-06-11 12:11:13 +08:00

164 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```