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

12 KiB
Raw Permalink Blame History

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):

-- 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 绿。

五、复跑命令

# 起服务(端口 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