LangChain 调用大模型时 API Key 通过环境变量注入但日志脱敏失效的排查

文章导读
API Key 走环境变量注入后,日志里仍然出现明文密钥,最可能的方向不是 LangChain 本身没有脱敏,而是日志链路里有某一层拿到了完整的请求体或环境变量快照,并且在 LangChain 的脱敏逻辑之前就写了日志。常见位置包括 HTTP 请求日志、LangSmith 或 Tracing 回调、自定义回调处理器、底层 HTTPX 客户端日志、以及启动脚本里对 env 的 dump。先不要急着改
📋 目录
  1. Ⅰ 先判断密钥是从哪一层漏出来的
  2. Ⅱ 检查点:按三层逐项确认
  3. Ⅲ 处理动作:按泄露位置分别处理
  4. Ⅳ 分支排查清单
A A

API Key 走环境变量注入后,日志里仍然出现明文密钥,最可能的方向不是 LangChain 本身没有脱敏,而是日志链路里有某一层拿到了完整的请求体或环境变量快照,并且在 LangChain 的脱敏逻辑之前就写了日志。常见位置包括 HTTP 请求日志、LangSmith 或 Tracing 回调、自定义回调处理器、底层 HTTPX 客户端日志、以及启动脚本里对 env 的 dump。先不要急着改 LangChain 配置,先把日志里密钥出现的上下文找出来,确认是请求头、请求体、回调事件还是环境变量快照,再决定在哪一层处理。

先判断密钥是从哪一层漏出来的

在 LangChain 里,OpenAI/Anthropic 等 ChatModel 调用时,API Key 通常通过环境变量读取,并由 SDK 放进 HTTP Authorization 头。LangChain 的 callback 系统能看到事件名和部分输入输出,但默认不会把完整 headers 写进日志。如果你在日志里看到明文 Key,往往不是 LangChain 打印的,而是下面几种情况之一:

  • 启动了 langchain.debug = True 或设置了 LANGCHAIN_VERBOSE,某些回调实现会打印完整的请求参数。
  • 业务代码自己写了日志,把 model 对象、kwargs 或 invoke() 的入参直接传给 logger。
  • 集成了 LangSmith,而 LangSmith 的 trace 数据里包含原始请求头,如果日志采集系统把 trace 数据原样落盘,Key 就跟着出去了。
  • 底层 HTTPX 或 urllib3 开了 debug 级别日志,打印了完整请求头和响应头。
  • 进程启动脚本里执行过 export SOME_KEY=...,随后某个日志采集组件把当前环境变量快照写入日志。

因此排查第一步是搜索日志里 Key 的上下文。例如 Key 出现的那一行前后有没有 HTTP/1.1、Authorization、StreamingResponse、on_chat_model_start 这类关键词。如果没有上下文,先临时把 logger 格式改成包含调用栈的格式,再复现一次。

检查点:按三层逐项确认

1. LangChain 回调层是否打印了完整输入

检查代码是否设置过全局 debug 或 verbose 标志,以及自定义回调是否把 invoke_params 或 inputs 直接序列化。

# 检查 LangChain 全局状态
import langchain
print('debug =', getattr(langchain, 'debug', False))
print('verbose =', getattr(langchain, 'verbose', False))

# 如果开启了,先关掉
# langchain.debug = False
# langchain.verbose = False

如果项目里使用了 BaseCallbackHandler,检查对应方法的参数里是否包含 inputs、invoke_params 或 output,并且在写入日志前没有过滤。

2. 日志采集层是否捕获了请求头或请求体

很多团队会使用中间件记录所有外部 HTTP 请求的 method、url、headers、body。这个中间件如果拦截到 LangChain 对模型 provider 的调用,就会把 Authorization: Bearer sk-... 原样打印。

  • 搜 Authorization 和 Bearer 这两个关键词,能快速确认是不是请求头泄露。
  • 搜 api_key、openai_api_key、anthropic_api_key 等参数名,确认是不是请求体泄露。
  • 如果日志里同时出现完整环境变量列表,需要检查启动脚本和系统日志采集器。

3. LangSmith 或 Tracing 组件是否把原始数据带回日志

如果使用了 LangSmith,trace 链路里会记录请求和回包。LangSmith 的 SDK 通常会自动脱敏,但如果你把 trace 数据接入了自己的日志平台,且日志平台没有做字段过滤,那么密钥可能从这条链路出现。

需要检查两点:一是在 LangSmith 控制台里查看 trace 的输入输出中是否包含原始 key;二是检查日志数据源里是否有 langsmith 或 trace 相关的字段。如果确认是 LangSmith 导致,先关闭 trace 写入本地日志,再考虑是否要在日志平台侧添加脱敏规则。

LangChain 调用大模型时 API Key 通过环境变量注入但日志脱敏失效的排查

处理动作:按泄露位置分别处理

不要在发现密钥泄露后只加一个正则替换。正则替换能盖住日志输出,但可能在别的位置继续泄露。按下面顺序处理:

  1. 关闭不必要的调试输出。 把 langchain.debug 和 verbose 设为 False,并检查所有 logging.basicConfig(level=logging.DEBUG) 是否把 HTTPX 的 logger 也拉到了 DEBUG。
  2. 在调用入口统一脱敏。 写一个工具函数,在进入 LangChain 调用前替换 key,或者确保 logger 的 filter 能看到明文但不输出明文。
  3. 禁止打印请求参数和返回体。 如果自定义 callback 里需要记录输入输出,先移除 invoke_params 或其中与密钥相关的字段,只记录 message 数量和模型名称。
  4. 检查启动脚本和 CI/CD 日志。 如果启动脚本里有 env 或 printenv 的输出,以及 CI 日志里打印环境变量,需要单独处理。
  5. 开启日志脱敏 filter。 在 logger 层增加 filter,常见的做法是匹配 sk-[A-Za-z0-9]+ 这类模式并替换为 ***,但必须同时在日志平台侧加字段过滤,避免原始数据已经落到存储后才被 replace。

下面是一个可在日志层使用的脱敏 filter 示例,放在 logger 初始化处执行。它匹配常见的 OpenAI 风格密钥格式,也覆盖 Authorization 头中的 Bearer 值,但需要根据你的实际 key 格式调整正则。

import logging
import re

class ApiKeyFilter(logging.Filter):
    def filter(self, record):
        if isinstance(record.msg, str):
            record.msg = re.sub(r'(Bearer\s+)(sk-[A-Za-z0-9_-]+)', r'\1***', record.msg)
            record.msg = re.sub(r'(api[_-]?key\s*[=:]\s*)([A-Za-z0-9_-]+)', r'\1***', record.msg, flags=re.I)
        return True

# 挂到所有可能打印请求日志的 logger 上
for name in ['openai', 'httpx', 'httpcore', 'langchain', 'langsmith']:
    logger = logging.getLogger(name)
    logger.addFilter(ApiKeyFilter())

这段代码通常在项目入口处(如 main.py 或 app 初始化)执行,用于本地日志脱敏。注意它不会自动清理已经写入文件的历史日志,也不会阻止日志采集器在 filter 生效前把原始记录发送出去,因此生产环境需要在日志平台侧设置同样的字段级脱敏,并验证过滤结果。

分支排查清单

如果按上面检查仍然找不到出处,可以按以下分支排查:

  • 日志里只有 Key,没有上下文: 临时把 root logger 的格式改为 '%(process)d %(threadName)s %(name)s %(funcName)s %(message)s',然后复现一次,看 Key 出现在哪个 logger 的哪个函数。
  • Key 出现在 HTTP 请求日志中: 检查是否有 requests、httpx 的 event hook 或中间件在打印 headers。如果是 FastAPI/Flask 中间件,需要在中间件里对 Authorization 字段先做脱敏再记录。
  • Key 出现在 LangChain 回传的 token 使用信息中: 某些 provider 或回调会在 usage_metadata 之外附带原始请求参数,检查自定义回调的 on_llm_start 中拿到的是否是 prompts 而不是 invoke_params。
  • Key 出现在 trace 或 span 中: 检查是否是 OTel instrumentation 自动捕获了 HTTP headers。如果是,需要设置 OTel 的 http.headers 脱敏,或关闭对模型 provider 的 HTTP 追踪。
  • Key 出现在启动日志中: 检查 `.env` 文件是否被 cat、Docker Compose 是否打印了 environment、K8s 事件是否把 secret 显示在事件描述里。

完成一层处置后,验证方式不是只看页面日志,而是同时检查本地日志文件、日志采集 agent 的输出、以及日志平台内的搜索索引。建议做一次最小复现:只运行一个调用 OpenAI 的 Python 脚本,设置环境变量,观察日志输出,确认脱敏 filter 是否在写入日志之前生效。如果最小复现没问题,再逐步引入中间件和回调,找到泄露层。

最后提醒一点:环境变量注入本身没问题,问题通常出在日志链路里的某一层看到并打印了完整环境变量或请求头。不要因为这次脱敏失效,就把 Key 改成硬编码或放在代码仓库里,那会带来更大的泄露面。先在日志层做过滤,同时排查所有能把环境变量快照写进日志的工具。