4. 基础配置入门：配置文件结构、核心参数说明、日志与监控配置、首次启动配置

Risk Gateway 回放对比模块的配置体系是确保对比任务稳定、可追溯、可调试的基石。本章将带你拆解配置文件的骨架，理解每个核心参数的含义，并完成首次启动的完整配置流程。

4.1 配置文件结构

Risk Gateway 采用 YAML 作为默认配置格式，支持多环境隔离。一个标准的配置文件由四个顶级区块组成：gateway、replay、comparison 和 monitoring。

# risk-gateway.yml  — 回放对比模块主配置
gateway:
  mode: "replay"               # 运行模式：replay | live | hybrid
  instance_id: "rg-node-01"    # 节点唯一标识
  listen_port: 8080            # 服务监听端口

replay:
  source: "kafka"              # 流量来源：kafka | file | grpc
  topic: "risk-events-live"    # 源主题
  offset: "latest"             # 消费偏移：latest | earliest | timestamp
  rate_limit: 1000             # 每秒最大回放事件数

comparison:
  engine: "diffy"              # 对比引擎：diffy | custom
  tolerance: 0.05              # 数值容忍度（5%）
  ignore_fields:               # 忽略对比的字段列表
    - "trace_id"
    - "timestamp"
  output: "elasticsearch"      # 结果输出：elasticsearch | file | console

monitoring:
  metrics_port: 9090           # Prometheus 指标端口
  log_level: "info"            # 日志级别：debug | info | warn | error
  log_file: "/var/log/rg/replay.log"
  health_check: true           # 启用健康检查端点

4.2 核心参数说明

下表列出了回放对比模块最关键的参数及其推荐值，帮助你快速定位配置项的作用。

4.3 日志与监控配置

完善的日志与监控是排查回放对比问题的“眼睛”。Risk Gateway 内置了结构化日志和 Prometheus 指标输出，只需简单配置即可接入现有可观测体系。

4.3.1 日志配置详解

日志配置支持按模块独立控制级别，并自动轮转归档。

monitoring:
  log_level: "info"
  log_file: "/var/log/rg/replay.log"
  log_max_size: "100MB"        # 单个日志文件最大大小
  log_max_backups: 10          # 保留的旧日志文件数
  log_max_age: 30              # 日志保留天数
  log_format: "json"           # 输出格式：json | text
  log_fields:                  # 自定义结构化字段
    app: "risk-gateway"
    env: "production"

4.3.2 监控指标与健康检查

开启 health_check: true 后，Risk Gateway 会在 /health 端点暴露以下关键指标：

• replay_events_total — 已回放事件总数
• comparison_mismatch_total — 对比不一致事件总数
• replay_lag_seconds — 回放延迟（秒）
• comparison_duration_milliseconds — 单次对比耗时（毫秒）

4.4 首次启动配置

完成配置文件编写后，按照以下步骤完成 Risk Gateway 的首次启动与验证。

1. 环境检查：确保 Java 11+、Kafka/文件数据源可达、Elasticsearch 或输出目标可用。
2. 配置文件校验：使用内置命令检查 YAML 语法与参数合法性。

# 校验配置文件
./risk-gateway --validate --config conf/risk-gateway.yml

# 预期输出：Configuration validation passed.

3. 启动服务：前台启动观察日志，确认无异常。

./risk-gateway --config conf/risk-gateway.yml

# 启动后关键日志示例
[INFO] [main] RiskGateway - Starting Risk Gateway in REPLAY mode
[INFO] [main] ReplaySource - Connected to Kafka topic: risk-events-live
[INFO] [main] ComparisonEngine - Diffy engine initialized, tolerance=0.05
[INFO] [main] HealthCheck - Health endpoint available at /health

4. 验证健康检查：访问 http://localhost:8080/health，确认返回 {"status":"UP"}。
5. 检查指标端点：访问 http://localhost:9090/metrics，确认 Prometheus 指标正常暴露。

4.5 配置模板速查

以下是一个可直接用于生产环境的精简配置模板，覆盖了最常用的参数组合。

gateway:
  mode: "replay"
  instance_id: "rg-prod-01"
  listen_port: 8080

replay:
  source: "kafka"
  topic: "risk-events-prod"
  offset: "latest"
  rate_limit: 2000

comparison:
  engine: "diffy"
  tolerance: 0.01
  ignore_fields:
    - "trace_id"
    - "timestamp"
    - "request_id"
  output: "elasticsearch"

monitoring:
  metrics_port: 9090
  log_level: "warn"
  log_file: "/var/log/rg/replay.log"
  health_check: true