在日志进入 Loki 前过滤密钥：Grafana Alloy 的配置与版本边界

原文作者：Romain Gaillard，Grafana Labs，2025 年 3 月 21 日。本文把当时的实验版文章与 2026-10-08 读取的 Alloy v1.20（latest）官方组件文档分开说明。原文及配图依授权转载，作者与版权归属保留。

日志脱敏组件能在日志写入 Loki 前，按 Gitleaks 规则扫描日志行并替换疑似密钥。这是纵深防护：应用仍应避免把凭据写进日志，过滤组件也不应被当作唯一保密措施。

数据流与原文截图

来源文章展示了日志进入 Loki 后的脱敏标记，以及按标记查询并触发告警的截图。它们是 Grafana 示例界面，不是本文或读者环境的测试结果。

把 2025 年实验版与当前 GA 分开

2025 年文章写作时，组件要求 Alloy 1.5.0 或更高版本，并需通过 –stability.level experimental 启动。文章中的 types、include_generic 和组件级 allowlist 是当时接口的一部分。

# 来源文章中的历史启动参数；只用于标明版本背景，不要套用到当前配置
--stability.level experimental

截至本文核验时，Grafana Alloy v1.20 官方文档把 loki.secretfilter 标为 GA。当前参数表包含 rate、processing_timeout、drop_on_timeout、label_timed_out、origin_label、redact_percent、redact_with 和 gitleaks_config；旧文章中的 types 与 include_generic 不属于该参数表。当前规则筛选与允许列表应写在 Gitleaks TOML 配置中。不要把不同版本片段拼成一个未经验证的配置。

历史实验接口的参数含义

2025 年文章中的 gitleaks_config 指向 Gitleaks TOML；若不指定，使用当时嵌入的默认规则。types 用规则 ID 前缀筛选，例如 grafana 会匹配 grafana-api-key、grafana-cloud-api-token 等类型。redact_with 可在占位符中加入规则名和秘密值哈希。include_generic 控制是否启用 generic-api-key 规则；当时因熵检测支持有限，它默认关闭以减少误报。allowlist 是原实验接口的额外正则白名单。原文称默认配置包含接近两百条正则，因此全量扫描可能增加资源成本；该数量和规则内容随版本变化。

# 来源文章中的最小实验片段；它只展示过滤组件连接
loki.secretfilter "" {
  forward_to = <RECEIVER_LIST>
}

原文完整示例还使用 PATH_TARGETS 占位符，并把写入端指向 loki.write.local_loki，但那段博客片段没有声明完整的写入组件。不能把最小片段或有占位符的历史配置直接当作可运行管道。来源文章也建议查询脱敏标记发现过滤启用前已经泄露的日志，并及时轮换对应密钥；2025 年文章把秘密相关指标列作路线图，而当前 GA 文档已提供脱敏计数、绕过数、超时和处理时长指标。

当前文档的数据路径示例

下面是 v1.20 文档的完整组件连接示例。路径和 Loki 地址仍是占位符，落地前需要固定 Alloy 版本、配置正确的接收端并在隔离环境验证；本文未启动服务，也未发送日志。

local.file_match "local_logs" {
  path_targets = "<PATH_TARGETS>"
}

loki.source.file "local_logs" {
  targets    = local.file_match.local_logs.targets
  forward_to = [loki.secretfilter.secret_filter.receiver]
}

loki.secretfilter "secret_filter" {
  forward_to  = [loki.write.local_loki.receiver]
  redact_with = "<ALLOY-REDACTED-SECRET:$SECRET_NAME:$SECRET_HASH>"
  // 可选：gitleaks_config = "/etc/alloy/gitleaks.toml"
}

loki.write "local_loki" {
  endpoint {
    url = "<LOKI_ENDPOINT>"
  }
}

历史文章的版本还展示了单独的 loki.secretfilter 片段和路径占位符；那段片段本身并未声明写入端，不能单独直接运行。当前文档示例也需要替换所有占位值。

规则、脱敏策略与资源开销

• gitleaks_config 指定自定义 TOML 文件。当前文档建议从默认规则集扩展，并固定自定义规则文件，因为嵌入的默认规则可能随 Alloy 版本变化。
• 当前规则配置可包含规则、allowlists 和 extend。为自定义规则设置 keywords 可先筛掉无关日志，减少每条规则执行正则表达式的成本。
• 若设置 redact_with，命中值替换为模板，可使用 SECRET_NAME 和 SECRET_HASH。没有模板时，redact_percent 控制遮盖比例；默认约 80%，仍会显示部分原值。设置为 100 才是完整替换。
• rate 小于 1 时，未被抽中的日志行会原样通过，没有检测也没有脱敏。采样能降低 CPU 成本，但会漏掉其中的秘密。
• processing_timeout 默认 0（不设超时）。超时默认仍转发日志行，并只遮盖超时前已经发现的值。drop_on_timeout=true 会丢弃超时日志行；这可能造成数据丢失。label_timed_out=true 可为被转发的超时行添加标签。
• 正则会漏报或误报；PII 不在通用检测范围内。组件只扫描日志行，不扫描 Loki 标签或其他元数据。

逐步上线并观察 Alloy 资源使用和组件计数器。原文建议按已知生态收窄检测类型；当前文档还建议把过滤组件放在减少日志量的处理步骤之后。需要将遗漏、误报、CPU 成本和日志完整性作为明确取舍，而不是宣称“启用后就不会泄密”。

静态核验与版本限制

本文静态比对了 2025 年实验文章与当前 v1.20 GA 组件文档中的参数、数据流和风险。没有执行 Alloy、连接 Loki、构建镜像或运行配置；图中示例截图和代码输出均来自原文，不代表本文实测。

来源与版权：Romain Gaillard，《How to redact secrets from logs with Grafana Alloy and Loki》，Grafana Labs Blog，2025-03-21；当前参数依据 Grafana Alloy v1.20（latest）官方文档，2026-10-08 查阅。原文与截图依据另行取得的转载许可使用；来源页面未标开放许可，版权归 Grafana Labs。补充流程图由未完纪原创，按 CC BY-SA 4.0 许可发布。