自定义规则文件是扩展系统检测/识别能力的关键配置。本节说明如何规范管理 .rule、.yml 或 .json 格式的规则文件，确保业务逻辑与系统升级互不干扰。
7.4.1 文件存放规范
建议采用以下目录结构，避免升级时被覆盖：
/opt/app/rules/
├── custom/ # 用户自定义规则（必须放这里）
│ ├── production/ # 生产环境规则
│ └── test/ # 测试规则
├── builtin/ # 系统内置规则（只读，勿动）
└── backup/ # 自动备份目录命名约定：{业务}_{序号}_{版本号}.{扩展名}
示例：payment_001_v2.rule、api_whitelist_003.yml
7.4.2 基本操作
新增规则
- 在
custom/下新建文件，确保编码为 UTF-8（无 BOM） - 首行添加注释说明：
# 创建人：张三，日期：2024-01-15，用途：拦截XX攻击 - 执行语法检查命令（如有）：
./bin/check_rules.sh custom/payment_001_v2.rule - 通过管理界面「规则管理」→「加载本地文件」生效，或重启服务（视系统而定）
修改规则
- 严禁直接修改
builtin/目录下的系统规则 - 如需覆盖内置规则，在
custom/下创建同名文件，系统会优先加载custom/目录 - 修改前务必执行备份：
cp custom/payment_001_v2.rule backup/payment_001_v2_$(date +%Y%m%d).rule
删除/停用
- 不要直接删除文件，建议重命名为
.rule.bak或修改规则状态为enabled: false - 保留至少 30 天后再物理删除，防止误删后无法恢复
7.4.3 规则文件格式示例
以 YAML 格式为例，必须包含三个基础字段：
rule_id: custom_payment_001 # 全局唯一标识，建议加 custom_ 前缀
enabled: true # 开关，方便临时停用
priority: 100 # 优先级，数字越小越先匹配（1-999）
match_conditions:
- field: url
operator: contains
value: "/api/pay"
action:
type: block # 可选：block/pass/log/redirect
message: "检测到异常支付请求"常见错误：
- 使用 Tab 缩进（必须用空格）
rule_id重复导致加载失败- 正则表达式未转义特殊字符（如
\d要写为\\d）
7.4.4 版本控制建议
如果团队多人维护，建议将 custom/ 目录纳入 Git 管理：
cd /opt/app/rules/custom
git init
git add .
git commit -m "初始化支付模块规则"
# 建议每日下班前提交，备注清楚修改原因批量导入/导出
- 导出：
tar czvf rules_backup_$(date +%F).tar.gz custom/ - 导入：将文件上传至
custom/后，执行热加载命令（如curl -X POST http://localhost:8080/api/reload），避免重启服务
7.4.5 排错与验证
规则未生效排查步骤：
- 查看系统日志（通常在
logs/rules.log），搜索rule_id确认是否加载成功 - 检查文件权限：
chmod 644 custom/*.rule（确保运行用户可读） - 使用测试工具验证：
./bin/test_rule.sh -f custom/payment_001_v2.rule -t "测试请求数据"
性能注意：单文件规则数超过 500 条时建议拆分为多个文件，避免单次匹配耗时过长。
实践提示：首次生产环境部署时，建议先将 action 设为 log（仅记录不阻断），观察 24 小时无误判后再改为 block，避免误拦截影响业务。