企业官网建设流程全解析

如何安全部署 RetainPDF：凭据引用、API Key 鉴权与自托管隐私保护的完整指南

【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译，适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdf

RetainPDF 是一款开源的PDF 翻译工具，能在保留版面、公式与结构的前提下完成 PDF 翻译，特别适合科研论文与技术文档。当你在自己的服务器上自托管部署时，安全配置就成了第一道必修课：既要防止未授权访问你的后端 API，又不能让模型厂商的 API Key 或 OCR 密钥散落在任务配置里。

RetainPDF 翻译后的 PDF 页面：原文的版面、图表与公式结构被完整保留

本文带你从零理解 RetainPDF 的三层安全模型：后端 API Key 鉴权 → 凭据引用（credential_ref）机制 → 自托管隐私边界，并给出一份可照做的检查清单。

🧩 先分清两类 Key：最容易踩的坑

很多新手部署失败，是因为混淆了这两把钥匙：

后端 API Key 是进入 RetainPDF 的"门禁卡"，模型密钥则是"内部通行证"——后者永远不应明文出现在任务请求或日志里。

自托管环境下，你的 PDF 原文与翻译产物全部保留在本机数据目录，这是自托管的最大隐私优势

🔑 一键配置后端 API Key 鉴权

第 1 步：准备鉴权配置文件

仓库提供了配置模板 auth.local.example.json，复制为backend/api/auth.local.json并填入强随机密钥：

{ "api_keys": ["replace-with-your-backend-key"], "max_running_jobs": 4, "simple_port": 42000 }

加载优先级为：显式环境变量RUST_API_KEYS>auth.local.json。配置文件位置详见 local-dev.md。

第 2 步：调用时携带请求头

除GET /health外，所有接口都需要请求头X-API-Key。鉴权逻辑实现在 auth.rs 中：内部 Agent 服务还可使用带作用域的x-retainpdf-agent-capability能力令牌，按方法与路径做细粒度授权，而不是共用一把"万能钥匙"。

第 3 步：非回环监听前必须更换密钥

默认只监听回环地址127.0.0.1:41000。如果需要局域网访问（--host 0.0.0.0），必须先设置强随机的RUST_API_KEYS——启动器与 Rust 服务都会拒绝在非回环监听时沿用默认开发 key。这一设计能从根上避免"默认密钥暴露到局域网"的经典事故。

🗝️ 凭据引用机制：API Key 不落盘、不回显

这是 RetainPDF 自托管部署中最值得了解的设计。模型与 OCR 密钥统一存放在后端拥有的凭据保险库（credential vault）中，完整契约见 credentials.md。

核心规则只有三条：

1. 密钥只提交一次。创建凭据时提交一次密钥，接口只返回元数据和一个不透明的credential_ref（凭据引用）；
2. 列表与查询永不回显。任何 GET 响应都不返回密钥或可反推的掩码值；
3. 用引用代替明文。创建翻译任务时传translation.credential_ref，OCR 任务传ocr.credential_ref，后端在启动 worker 前一刻才解析密钥并注入到 provider 专用环境变量。

保险库的物理防护同样到位：数据目录权限0700、文件权限0600（POSIX），多进程通过文件锁串行化写入（实现见 credential_vault.py）；任务的日志与持久化状态也会用已解析的密钥做脱敏清洗，避免密钥出现在日志文件里。

版本冲突保护：每条凭据带revision，更新时携带expected_credential_revision做乐观锁校验，并发修改会返回409 CREDENTIAL_REVISION_CONFLICT；被任务引用中的凭据默认禁止删除，需显式force=true才可强制移除。

🛡️ 自托管隐私保护：7 项部署检查清单

• 只监听回环，或更换强密钥后再暴露端口
• auth.local.json权限设为600，不提交到版本库
• 模型/OCR 密钥一律走凭据引用，不使用内联明文字段
• 数据根目录（RUST_API_DATA_ROOT）放在非公开路径：上传件、任务工作目录与 SQLite 数据库都在其下（结构见 storage.md）
• Docker 交付时核对三件套：Compose 实际读取的是 app.env、web.env 与 auth.local.json，且api_keys必须与FRONT_X_API_KEY配对
• 接口只返回相对路径，避免把本机绝对路径泄露给前端
• 错误响应不含敏感信息：凭据相关错误码（如CREDENTIAL_REF_NOT_FOUND、CREDENTIAL_IN_USE）统一走 错误契约，响应体绝不包含密钥或保险库路径

项目级的安全职责与边界约定汇总在 security/README.md：不提交 API token、密码、真实数据库或用户 PDF——这也是你自己部署时应当遵守的底线。

✅ 部署后快速验证

1. 健康检查：直接访问GET /health，无需鉴权即可确认可用性；
2. 鉴权生效：不带X-API-Key请求任务接口应返回401，携带正确 key 才放行；
3. 凭据闭环：通过凭据接口创建一条引用，再发起一次 OCR-only 任务，确认任务请求中只有credential_ref而无明文；
4. 错误码自检：故意使用过期 revision 更新凭据，应收到409而非静默成功。

总结

RetainPDF 的安全模型可以浓缩为一句话：回环优先的监听策略守住网络边界，X-API-Key守住 API 边界，凭据引用守住密钥边界。自托管部署时只要遵循"强随机密钥 + 凭据引用 + 受限数据目录"这三条主线，就能在享受保留版面 PDF 翻译能力的同时，把隐私风险降到最低。

【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译，适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdf