7.2 KiB
7.2 KiB
Redis 序列化结构检测 — 配置说明
双层配置：工具 jar 内置
default-config.yaml（默认） + 业务仓库.gitea/config/redis-schema-check-config.yaml（覆盖）
1. 配置合并机制
jar 内 default-config.yaml（工具仓维护）
↓ 深度合并
业务仓 redis-schema-check-config.yaml（业务仓维护）
↓
最终生效配置
- 业务配置仅需写差异项，不必复制全部默认规则
- 升级 jar 时，默认忽略规则/检测模式自动跟随工具版本演进
- 业务仓必须存在
--config指定的配置文件（可为仅含mode的最小文件）
1.1 业务仓最小配置示例
# jnpf-java-cloud/.gitea/config/redis-schema-check-config.yaml
mode: notify
notify:
enabled: true
webhook_env: WECOM_ROBOT_WEBHOOK
include_modules:
- jnpf-tenant
1.2 工具内置默认配置（jar 内 default-config.yaml）
由 redisCheck 仓库维护，随 jar 发布，包含：
detection.patterns（W01~W03）ignore.key_patterns（锁/计数器/token）block_severities（P0/P1/P2）detection.min_confidence、max_field_depth等
2. 业务仓完整配置示例
# 运行模式
# notify - 仅通知，不阻断流水线
# block - 按 block_severities 阻断流水线（exit 1）
mode: notify
# block 模式下触发 exit 1 的严重级别（全部阻断：P0/P1/P2）
block_severities:
- P0
- P1
- P2
# 是否扫描测试代码（已确认：不扫描）
scan_test_sources: false
# 源码扫描根目录（仅 main，不含 test）
source_roots:
- "src/main/java"
# 通知配置
notify:
enabled: true
# 从环境变量读取 Webhook URL
webhook_env: WECOM_ROBOT_WEBHOOK
# 无变更时是否也发通知（一般 false）
notify_on_clean: false
# 消息标题前缀
title_prefix: "[Redis结构变更]"
# 忽略规则
ignore:
# 忽略的 key 模式（glob）
key_patterns:
- "*:lock"
- "*:lock:*"
- "loginCount:*"
- "Authorization:*"
- "Authorization:login:session:*"
# 忽略的文件路径模式
file_patterns:
- "**/test/**"
# 忽略的写入方法（类全名#方法名）
writer_methods: []
# 检测规则
detection:
# 启用的写入模式
patterns:
- W01 # redisUtil.insert + JSON.toJSONString
- W02 # redisTemplate.opsForValue().set + JSON.toJSONString
- W03 # stringRedisTemplate + JsonUtil.getObjectToString
# - W04 # redisTemplate 直写对象（Phase 2）
# - W05 # opsForHash().put（Phase 2）
# 类型推断最低置信度，低于此值仅输出 P2 提示
min_confidence: 0.6
# 字段展开最大深度（防止循环引用死循环）
max_field_depth: 8
# 严重级别覆盖（可选）
severity_overrides:
FIELD_ADDED: P1
WRITE_POINT_ADDED: P2
# 人工补充映射（自动推断失败或需精确指定时使用）
manual_mappings:
- id: tenant-db-content
writer_method: "jnpf.util.TenantDbContentCacheHelper#cacheSuccess"
key_pattern: "tenant:db:content:*"
value_type: "jnpf.util.TenantDbContentCacheHelper.CacheEnvelope"
description: "租户库信息缓存"
- id: attendance-base-setting
writer_method: "jnpf.attendance.service.impl.AttendanceBaseSettingServiceImpl#getStringAttendanceBaseSettingMap"
key_pattern: "fbt:attendance:base_setting:cache:*"
value_type: "java.util.Map"
description: "考勤基础设置缓存（Map<String, AttendanceBaseSetting>）"
# 抑制规则（已知误报）
suppressions:
- id: ignore-export-progress
key_pattern: "file:download:user:progress:*"
reason: "导出进度缓存，结构变更不影响业务读取"
# 模块过滤（可选，默认扫描全部模块）
include_modules:
- jnpf-tenant
- jnpf-ftb
- jnpf-file
- fantaibao-data-analysis
# exclude_modules: []
3. 配置项说明
3.1 mode
| 值 | 行为 |
|---|---|
notify |
检测到变更 → 发企微 → exit 0 |
block |
检测到 block_severities 中的级别 → 发企微 → exit 1 |
3.2 block_severities
默认 ["P0", "P1", "P2"]，block 模式下任意级别变更均 exit 1。
建议上线初期仍使用 mode: notify 观察误报情况，确认稳定后再切换：
mode: block
block_severities:
- P0
- P1
- P2
3.3 notify
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled |
boolean | true | 是否发企微 |
webhook_env |
string | WECOM_ROBOT_WEBHOOK | 环境变量名 |
notify_on_clean |
boolean | false | 无变更时是否通知 |
title_prefix |
string | [Redis结构变更] | 消息标题前缀 |
3.4 ignore.key_patterns
支持 glob：
*匹配单层**匹配多层
常见内置忽略（代码层也有硬编码兜底）：
- 分布式锁 key
- 登录计数
- session/token
3.5 detection.patterns
| 模式 | 说明 | 阶段 |
|---|---|---|
| W01 | redisUtil.insert(key, JSON.toJSONString(x), ttl) |
Phase 1 |
| W02 | redisTemplate.opsForValue().set(key, JSON.toJSONString(x), ...) |
Phase 1 |
| W03 | stringRedisTemplate.opsForValue().set(key, JsonUtil.getObjectToString(x), ...) |
Phase 1 |
| W04 | redisTemplate.opsForValue().set(key, obj, ...) |
Phase 2 |
| W05 | redisTemplate.opsForHash().put(key, field, obj) |
Phase 2 |
3.6 manual_mappings
当自动推断不准确时使用。匹配优先级 高于 自动推断。
| 字段 | 必填 | 说明 |
|---|---|---|
id |
是 | 唯一标识 |
writer_method |
否 | 类全名#方法名，精确匹配写入点 |
key_pattern |
否 | 精确 key 模式 |
value_type |
否 | 强制指定 value 类型 |
description |
否 | 备注 |
3.7 suppressions
用于屏蔽已知可接受的变更：
suppressions:
- id: my-suppression
writer_method: "com.example.FooService#cacheBar"
change_types:
- FIELD_ADDED
reason: "新增字段向后兼容"
4. 环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
WECOM_ROBOT_WEBHOOK |
notify.enabled=true 时必填 | 企微机器人 Webhook 完整 URL |
在 Gitea 仓库 Settings → Secrets 中配置。
5. 企微消息格式示例
## [Redis结构变更] jnpf-java-cloud
> 分支: feature/tenant-cache
> 提交: a1b2c3d → e4f5g6h
> 提交人: zhangsan
> 时间: 2026-07-13 14:00:00
> 模式: notify
### P0 - 顶层结构包装变更
- **Key**: `tenant:db:content:*`
- **位置**: `TenantDbContentCacheHelper#cacheSuccess:92`
- **变更**:
- `dbName` → `vo.dbName`（字段路径迁移）
- `linkList` → `vo.linkList`（字段路径迁移）
- 新增顶层字段 `expiresAtMs`
- **影响**: 旧缓存反序列化可能失败，需评估缓存刷新策略
6. 推荐上线配置
6.1 观察期（第 1 周，已确认策略）
业务仓默认配置：
mode: notify
notify:
enabled: true
webhook_env: WECOM_ROBOT_WEBHOOK
include_modules:
- jnpf-tenant
观察满 1 周、确认误报可接受后，手动切换：
mode: block
block_severities: [P0, P1, P2]
include_modules: [] # 扩至全仓
6.2 全量启用（观察期结束后）
mode: block
block_severities: [P0, P1, P2]
include_modules: [] # 空表示全部模块
detection:
patterns: [W01, W02, W03, W04, W05]