DeepSeek API 返回 401 时如何排查鉴权配置链路

调用 DeepSeek API 时收到 401，通常不是模型服务异常，也不是网络不通，而是鉴权链路中某个环节没有把正确的 API Key 送到服务端。排查时应按“请求头格式 → Key 注入方式 → 配置读取顺序 → 中间层改写”的顺序逐层核对，而不是先怀疑模型或网络。

重要说明：本文不掌握 DeepSeek 官方文档的一手引用，以下涉及的请求头格式、API 端点、模型名称等均为示例，用于说明排查方法。实际调用时，请务必以 DeepSeek 官方文档（API 参考与鉴权说明）为准，替换为账号实际可用且官方确认的端点、模型与请求头格式。

第一层：确认 Authorization 请求头格式

多数 Bearer Token 类 API 的鉴权请求头形如：

Authorization: Bearer

注意：上述格式为通用示例，DeepSeek API 的实际鉴权头格式请以官方文档为准。

常见错误包括：缺少 Bearer 前缀、Bearer 与 Key 之间缺少空格、Key 前后混入换行或空格、把 Key 直接放在 Authorization 值中而不加前缀。这些都会导致服务端无法解析凭证，返回 401。

排查时不要只看代码里拼接的字符串，应打印实际发出的请求头（注意脱敏），确认最终值符合官方文档要求的格式。如果使用 SDK，检查是否重复设置了 Authorization，导致后设置的值覆盖了 SDK 自动生成的鉴权头。

第二层：核对 API Key 的注入方式

Key 可能来自环境变量、配置文件、密钥管理服务或启动参数。不同注入方式的风险点不同：

  • 环境变量：确认变量名拼写正确，且进程实际继承到了该变量。容器、systemd、IDE 运行配置都可能与 shell 环境不一致。
  • 配置文件：确认读取的是预期文件，而不是项目根目录下另一份旧配置。
  • 密钥管理服务：确认拉取成功且没有把占位符或空字符串当作 Key 使用。

一个实用做法是在启动日志中输出 Key 的长度和首尾各几位（脱敏），而不是输出完整 Key。长度为 0 或明显异常时，说明注入环节已经失败。

第三层：理清环境变量与配置文件的读取顺序

很多项目同时支持环境变量和配置文件，并约定“环境变量优先”或“配置文件优先”。如果两者同时存在且值不同，实际生效的可能是你不期望的那一个。排查时应确认：

  1. 代码中读取 Key 的优先级逻辑；
  2. 当前运行环境中哪些来源实际存在；
  3. 最终被使用的值来自哪个来源。

建议在鉴权失败时打印“Key 来源”标记（如 env / file / default），而不是只打印 Key 本身。这样能快速定位是配置覆盖问题还是 Key 本身失效。

第四层：检查代理与网关是否改写请求头

如果请求经过反向代理、API 网关或企业出口代理，鉴权头可能在中间层被改写或丢弃。常见情况包括：

  • 网关配置了统一的鉴权头替换策略，覆盖了客户端传入的 Authorization；
  • 代理对请求头大小写或特殊字符处理不一致；
  • 中间层对请求做了重定向，导致鉴权头在跳转后丢失。

排查方法是绕过代理直连 API 端点做对比测试。如果直连成功、经代理失败，问题就在中间层，应检查代理的请求头转发规则，而不是继续修改业务代码。

用最小请求验证 Key 是否生效

在逐层排查之前，建议先用最小请求确认 Key 本身是否可用。以下 curl 命令为示例，其中的端点、模型名和请求头格式均需替换为 DeepSeek 官方文档确认的实际值：

# 示例：请将 URL、模型名和请求头替换为官方文档确认的值
curl https:// \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{"model":"","messages":[{"role":"user","content":"ping"}]}'

如果最小请求成功，说明 Key 有效、网络可达，问题出在业务代码的配置链路；如果最小请求同样返回 401，则优先检查 Key 是否过期、被撤销或复制时混入多余字符。

避免误判为模型或网络问题

401 是鉴权失败的状态码，与模型是否存在、网络是否稳定没有直接关系。收到 401 时不要先去换模型名或重试网络，而应先确认请求头是否被正确构造和传递。把鉴权链路拆成“格式、注入、读取顺序、中间层”四段逐一排除，通常能在较短时间内定位到具体环节。

工程上建议把 Key 校验前置到服务启动阶段：启动时用最小请求做一次探活，失败则快速报错并输出 Key 来源与长度，避免带病运行到业务请求阶段才暴露鉴权问题。

探活注意事项：启动探活会产生一次真实的 API 调用，可能产生费用或消耗配额。建议使用权限最小化的 Key 进行探活，并控制探活频率，避免不必要的调用。如果官方文档提供了轻量级的鉴权校验方式（如列出模型等只读接口），优先使用该方式。