代理凭据编码验证：避免 407 错误与密钥泄露

同一组代理账号密码在一个工具中成功、换到另一个工具却返回 407，原因往往不是账号失效，而是凭据穿过了不同的解析边界。独立的用户名字段可能需要原始值，URL 中的用户信息却可能需要百分号编码；Shell、CI 或配置文件还可能在客户端收到参数前再次处理特殊字符。

本指南提供一套受控验收方法，适用于获得授权的数据采集、浏览器测试、广告验证与市场研究。目标不是寻找一条“所有工具通用”的编码规则，而是证明每个配置入口实际接收什么，同时让生产密钥远离代码、日志与测试证据。

最常见的三个故障边界

配置边界：客户端可能提供独立的 server、username、password 字段，也可能只接受组合凭据或完整代理 URL。这些入口的解码规则未必相同。

序列化边界：冒号、@、百分号、空格、反斜杠与非 ASCII 字符在 URL 中可能有结构含义。该编码时不编码会失败，重复编码同样会失败。

执行边界：交互式 Shell、CI 变量、YAML、JSON 与命令包装器可能先修改引号、转义或换行。

必须分别测试这三层。仅凭 407 无法判断是哪一层改变了凭据。

优先使用结构化凭据字段

客户端若支持独立字段，应优先使用。Playwright 的代理配置可将服务器、用户名和密码分开提供，避免把秘密放入 URL，也明确了职责边界：应用传入逻辑值，客户端负责协议序列化。

const browser = await chromium.launch({
  proxy: {
    server: process.env.PROXY_SERVER!,
    username: process.env.PROXY_USERNAME!,
    password: process.env.PROXY_PASSWORD!,
  },
});

环境变量应来自获批的密钥存储，不要打印整个配置对象。独立字段仍需验证，但不应在文档没有要求时自行预编码密码。

识别客户端明确规定的解码行为

curl 对代理凭据有明确规则：代理凭据字符串中的用户名和密码在使用前会进行 URL 解码，因此可以用编码形式表达 @ 等分隔字符，用户名中的冒号也必须避免被当成账号与密码的分隔符。这个规则只代表 curl 的契约，不能机械套用到所有 SDK。

curl --proxy "$PROXY_SERVER" \
  --proxy-user "$PROXY_USERPASS" \
  --fail-with-body "$AUTHORIZED_TEST_URL"

组合值应在受保护的配置层中生成，不要把真实密码粘贴到命令历史、工单或示例。若 API 已提供独立字段，除非文档明确要求，否则不要先编码密码。

构建一次性字符矩阵

请供应商或凭据管理员在隔离账户中创建短期测试凭据。每次只改变一类字符，不要一次混入所有复杂字符。

只使用合成值，在证据中保存用例编号与单向指纹，不保存测试密钥本身。

七步验收流程

1. 先证明干净基线

用简单的一次性凭据通过供应商支持的客户端请求获批测试地址，记录代理路由、预期区域、目标状态和脱敏出口指纹。基线失败时先停止，继续做编码实验无法隔离问题。

2. 固定其他变量

保持端点、协议、认证方式、目标、区域与请求完全不变，每次只测试一种字符类别。

3. 先测结构化配置

把原始逻辑值传入独立字段。成功结果可作为该客户端的参考；失败时先检查配置加载与密钥注入，不要立即增加编码。

4. 仅在必须时测试序列化形式

代理 URL 或文档规定的组合字段只编码对应 URL 组件，不要编码整条 URL，也不要把已编码值复用到原始密码字段。

5. 对比本地与 CI

用参数数组在本地运行同一用例，再在 CI 中运行。若仅 CI 失败，检查 YAML 引号、变量插值、尾随换行和密钥遮罩。生产流程应避免依赖交互式命令行。

6. 给故障正确分层

• 配置解析错误：尚未联网客户端就拒绝值；
• 解析或连接错误：代理端点没有被访问；
• 隧道或 TLS 错误：认证可能成功，但下一跳失败；
• HTTP 407：代理没有接受收到的认证；
• 目标响应：代理链路完成，目标站点已应答。

在归因到账户权限前，先确认供应商是否观察到本次尝试。可结合代理认证 407 排错指南逐层检查。

7. 固化已验证契约

记录配置入口、输入属于逻辑值还是序列化值、唯一编码责任方、已测运行时版本与脱敏规则。将一次性凭据字符矩阵加入持续集成。

不泄密地识别重复编码

不要记录认证头或完整代理 URL。分别计算逻辑测试值和应用序列化结果的单向指纹，并记录长度、字符类别用例和负责的代码路径。

若百分号先被编码，随后又被第二层编码，接收端只解码一次就可能得到错误密码。正确修复方式是明确唯一的序列化责任方，而不是随意再增加一次解码。

建议证据字段

test_case_id
client_name
client_version
configuration_surface
runner_type
logical_value_fingerprint
serialized_value_fingerprint
expected_proxy_route
provider_attempt_observed
result_class
http_status
exit_fingerprint
redaction_check
timestamp

记录中不得出现代理密码、完整用户名、认证头、Cookie 或完整代理 URL。参考代理 HAR 凭据脱敏指南控制证据；如果密钥意外进入日志，应立即执行代理凭据轮换流程。

发布检查清单

• [ ] 凭据为短期、限权、可丢弃测试凭据。
• [ ] 特殊字符测试前，简单基线已经成功。
• [ ] 端点、路由、协议和目标保持固定。
• [ ] 优先使用独立账号密码字段。
• [ ] 只对文档指定的组件编码。
• [ ] 只有一个层负责序列化。
• [ ] 本地与 CI 执行路径分别验证。
• [ ] 命令历史与进程输出不含秘密。
• [ ] 日志已脱敏代理 URL 和认证材料。
• [ ] 先给故障分层，再决定是否轮换凭据。
• [ ] 强制代理失败时关闭，不得静默直连。
• [ ] 供应商与目标允许本次测试流量。

常见问题

所有特殊字符都应百分号编码吗？

不应该。是否编码取决于配置入口。URL 组件可能需要编码，而独立密码字段通常需要原始逻辑值。必须遵循具体客户端契约并实测。

HTTP 407 一定代表密码错误吗？

不一定。它表示代理没有接受提交的认证，但解析、编码、认证方案、账户策略或密钥注入都可能改变实际提交值。

可以抓取发出的认证头吗？

应避免抓取真实认证材料。使用一次性凭据、能脱敏的客户端诊断与供应商侧尝试确认。任何意外捕获都应按凭据泄露处理。

为什么本地命令成功，CI 却失败？

Shell、YAML 解析器、变量存储或包装器可能以不同方式处理特殊字符和尾随换行。应比较指纹与配置边界，而不是打印秘密。

合规说明

代理只能用于合法且获得授权的测试与采集。遵守目标服务条款、robots 指令、隐私和数据保护要求、速率限制与供应商政策。凭据验证必须使用获批账户和一次性密钥，不得用于猜测密码、绕过访问控制、隐藏违规活动或未经许可获取数据。