PDF API Key 安全指南：服务端鉴权、轮换与日志脱敏

搜索“PDF API Key”“API 密钥安全”“Bearer Token”时，真正目标通常不是手工导出一份文件，而是建立能够处理真实数据、版本和持续交付的业务文档流程。

PDF 生成请求可能携带客户、财务和人事数据。若 API Key 出现在前端 bundle、Git 仓库或日志中，攻击者就可能调用接口并暴露业务信息。

本文面向接入 KeepMot 或其他 PDF API 的后端、平台、安全、DevOps 和负责生产凭据的开发团队，目标是把密钥限制在受控服务端，区分环境与权限，建立轮换、撤销、监控和泄露响应流程。最终交付安全的 PDF API 调用架构、密钥库存、轮换计划、日志规则、告警和事件处置清单，并让每份文件都能回溯到明确业务记录。

一、为什么这个场景适合模板化 PDF？

密钥不是普通配置字符串。它可能长期有效、拥有付费能力并访问敏感生成请求。复制到浏览器、工单或调试日志后，很难确认谁已经看到。

二、先定义数据字段与边界

key_id 与 owner：注明权威来源、数据类型和稳定业务含义。
environment：区分必填、可选、空字符串、零值与 null。
created_at 与 expires_at：准备正常值和最长合法值验证换行与分页。
status 与 scope：明确日期、时区、币种、单位或枚举格式。
secret_store_reference：定义异常与缺失时的阻断或回退规则。
last_used_at 与 source_service：记录校验责任，不能让模板猜测业务事实。
rotation_due_at：加入多语言、特殊符号或真实设备测试样本。
revoked_at 与 incident_id：规定文件命名、排序、版本和归档关联。

字段必须有示例、边界和责任系统。金额需要精度，日期需要时区，数组需要排序与最大数量，编号需要唯一规则；模板只负责表达已经批准的数据。

三、端到端实施流程

第1步：只在受控后端创建调用路径

先把“只在受控后端创建调用路径”写成可执行规则，明确数据负责人、批准人和异常处理人。对于安全的 PDF API 调用架构、密钥库存、轮换计划、日志规则、告警和事件处置清单，职责越早明确，后续返工越少。

第2步：把密钥存入 Secret Manager 或受限环境变量

处理“把密钥存入 Secret Manager 或受限环境变量”时，记录选择依据并保存代表性样本。模板或接口变化后，可用同一依据重新验证。

第3步：区分开发测试生产账号与 key

围绕“区分开发测试生产账号与 key”准备正常、空值、最长文本和最大数组，确认真实边界不会造成截断或错误分页。

第4步：日志只记录 key_id 和 request_id 不记录 secret

执行“日志只记录 key_id 和 request_id 不记录 secret”时设置业务标识、超时和失败分支；只有有效 PDF 完成验收后，才标记本次动作成功。

第5步：定期轮换并支持双 key 过渡

验收“定期轮换并支持双 key 过渡”不能只看第一页，还要检查金额、页序、字体、条码、打印或交互状态等场景细节。

第6步：泄露时立即撤销审计调用并替换凭据

最后通过“泄露时立即撤销审计调用并替换凭据”形成追溯闭环，保存业务 ID、模板版本、生成时间、页数、摘要与投递结果。

四、三个关键设计决定

1. 浏览器是否直接调用

生产密钥不应进入浏览器；前端请求自己的后端，由后端验证业务权限再调用 PDF API。

2. 一个 key 多服务还是分开

按服务和环境分开有利于最小权限、用量归属和单独撤销。

3. 轮换是否允许重叠

短期双 key 过渡可避免停机，但必须有明确截止并验证旧 key 已停用。

五、用 KeepMot 生成与维护

KeepMot 生产 API 使用 Authorization: Bearer API_KEY。密钥应从服务端安全存储读取，请求成功返回 PDF 字节；认证失败按 401 处理。

针对 PDF API Key，可在 KeepMot Studio 维护模板，通过 Template API 提交 template_id 与业务数据；程序拥有完整版式时使用 JSON Render，已有网页资产时使用 HTML to PDF。也可以从模板库开始。

六、上线验收清单

前端代码不含 secret：保存源系统核对作为证据。
仓库和 CI 输出已扫描：保存真实页面样本作为证据。
环境账号彼此隔离：保存边界测试结果作为证据。
日志只记录 key_id：保存响应与文件头作为证据。
轮换与撤销经过测试：保存模板版本和摘要作为证据。
异常用量有告警：保存补发或重放记录作为证据。

七、常见风险

风险 1：把 key 写入 JavaScript bundle

“把 key 写入 JavaScript bundle”会让早期看似灵活的实现快速积累维护成本，应在数据合同或状态机中直接阻止。

风险 2：提交 .env 到仓库

出现“提交 .env 到仓库”时，页面可能仍然看似正常。必须同时核对源记录、关键标识与最终文件。

风险 3：在错误追踪中记录 Authorization 头

“在错误追踪中记录 Authorization 头”往往只在边界数据出现，应保存触发样本并让无法安全生成的内容明确失败。

风险 4：所有服务共用一个长期 key

“所有服务共用一个长期 key”可能造成交付、隐私或运营事故，应缩小敏感数据范围并保留必要审计记录。

风险 5：发现泄露后只删除代码不撤销 key

针对“发现泄露后只删除代码不撤销 key”，先区分数据、版式、投递和版本问题，再制定纠正、重试、撤销或补发规则。

八、批量与日常运营

监控按 key_id 的调用量、来源服务、错误率和时间分布。异常峰值触发告警；离职、服务下线或权限变化立即撤销。定期扫描代码与日志中的密钥格式。

批量任务应有输入清单、上限、幂等键和失败分类。只重放受影响的记录，避免一次超时重复全部文件；日志记录请求 ID、模板版本和结果，但不保存 API Key、密码或不必要个人数据。

九、常见问题 FAQ

Q：API Key 可以放前端吗？ A：不可以，浏览器代码与网络请求会暴露凭据。

Q：环境变量足够安全吗？ A：比硬编码好，但仍需访问控制、日志保护和轮换；优先使用 Secret Manager。

Q：多久轮换一次？ A：按组织政策、风险和有效期决定，并在泄露或人员变化时立即轮换。

Q：如何无停机轮换？ A：短期同时允许新旧 key，先部署新 key，验证后撤销旧 key。

Q：日志需要记录什么？ A：记录 key_id、request_id、服务、状态和延迟，不记录 secret 或完整敏感 payload。

Q：怀疑泄露怎么办？ A：立即撤销、创建新 key、审计历史调用、评估数据影响并按事件流程报告。

十、总结

API Key 安全依赖最小暴露、环境隔离、可轮换和可审计；密钥只要离开受控后端，就应视为可能泄露。