feat: first commit
This commit is contained in:
295
docs/配置说明.md
Normal file
295
docs/配置说明.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Redis 序列化结构检测 — 配置说明
|
||||
|
||||
> **双层配置**：工具 jar 内置 `default-config.yaml`（默认） + 业务仓库 `.gitea/config/redis-schema-check-config.yaml`（覆盖）
|
||||
|
||||
---
|
||||
|
||||
## 1. 配置合并机制
|
||||
|
||||
```text
|
||||
jar 内 default-config.yaml（工具仓维护）
|
||||
↓ 深度合并
|
||||
业务仓 redis-schema-check-config.yaml（业务仓维护）
|
||||
↓
|
||||
最终生效配置
|
||||
```
|
||||
|
||||
- 业务配置**仅需写差异项**，不必复制全部默认规则
|
||||
- 升级 jar 时，默认忽略规则/检测模式自动跟随工具版本演进
|
||||
- 业务仓必须存在 `--config` 指定的配置文件（可为仅含 `mode` 的最小文件）
|
||||
|
||||
### 1.1 业务仓最小配置示例
|
||||
|
||||
```yaml
|
||||
# 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. 业务仓完整配置示例
|
||||
|
||||
```yaml
|
||||
# 运行模式
|
||||
# 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` 观察误报情况，确认稳定后再切换：
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
用于屏蔽已知可接受的变更：
|
||||
|
||||
```yaml
|
||||
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. 企微消息格式示例
|
||||
|
||||
```markdown
|
||||
## [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 周，已确认策略）
|
||||
|
||||
业务仓默认配置：
|
||||
|
||||
```yaml
|
||||
mode: notify
|
||||
|
||||
notify:
|
||||
enabled: true
|
||||
webhook_env: WECOM_ROBOT_WEBHOOK
|
||||
|
||||
include_modules:
|
||||
- jnpf-tenant
|
||||
```
|
||||
|
||||
观察满 1 周、确认误报可接受后，手动切换：
|
||||
|
||||
```yaml
|
||||
mode: block
|
||||
block_severities: [P0, P1, P2]
|
||||
include_modules: [] # 扩至全仓
|
||||
```
|
||||
|
||||
### 6.2 全量启用（观察期结束后）
|
||||
|
||||
```yaml
|
||||
mode: block
|
||||
block_severities: [P0, P1, P2]
|
||||
include_modules: [] # 空表示全部模块
|
||||
detection:
|
||||
patterns: [W01, W02, W03, W04, W05]
|
||||
```
|
||||
Reference in New Issue
Block a user