拓冰网站定制 
如何安全部署 RetainPDF凭据引用、API Key 鉴权与自托管隐私保护的完整指南【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdfRetainPDF 是一款开源的PDF 翻译工具能在保留版面、公式与结构的前提下完成 PDF 翻译特别适合科研论文与技术文档。当你在自己的服务器上自托管部署时安全配置就成了第一道必修课既要防止未授权访问你的后端 API又不能让模型厂商的 API Key 或 OCR 密钥散落在任务配置里。RetainPDF 翻译后的 PDF 页面原文的版面、图表与公式结构被完整保留本文带你从零理解 RetainPDF 的三层安全模型后端 API Key 鉴权 → 凭据引用credential_ref机制 → 自托管隐私边界并给出一份可照做的检查清单。 先分清两类 Key最容易踩的坑很多新手部署失败是因为混淆了这两把钥匙Key 类型作用存放位置后端 API KeyRUST_API_KEYS访问 RetainPDF Rust API 的白名单密钥除健康检查外所有接口都要求携带环境变量或auth.local.json模型 / OCR 密钥DeepSeek、MinerU、Paddle 等调用第三方翻译与 OCR 服务凭据保险库通过凭据引用间接使用后端 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_KEYSauth.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。核心规则只有三条密钥只提交一次。创建凭据时提交一次密钥接口只返回元数据和一个不透明的credential_ref凭据引用列表与查询永不回显。任何 GET 响应都不返回密钥或可反推的掩码值用引用代替明文。创建翻译任务时传translation.credential_refOCR 任务传ocr.credential_ref后端在启动 worker 前一刻才解析密钥并注入到 provider 专用环境变量。保险库的物理防护同样到位数据目录权限0700、文件权限0600POSIX多进程通过文件锁串行化写入实现见 credential_vault.py任务的日志与持久化状态也会用已解析的密钥做脱敏清洗避免密钥出现在日志文件里。版本冲突保护每条凭据带revision更新时携带expected_credential_revision做乐观锁校验并发修改会返回409 CREDENTIAL_REVISION_CONFLICT被任务引用中的凭据默认禁止删除需显式forcetrue才可强制移除。️ 自托管隐私保护7 项部署检查清单只监听回环或更换强密钥后再暴露端口auth.local.json权限设为600不提交到版本库模型/OCR 密钥一律走凭据引用不使用内联明文字段数据根目录RUST_API_DATA_ROOT放在非公开路径上传件、任务工作目录与 SQLite 数据库都在其下结构见 storage.mdDocker 交付时核对三件套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——这也是你自己部署时应当遵守的底线。✅ 部署后快速验证健康检查直接访问GET /health无需鉴权即可确认可用性鉴权生效不带X-API-Key请求任务接口应返回401携带正确 key 才放行凭据闭环通过凭据接口创建一条引用再发起一次 OCR-only 任务确认任务请求中只有credential_ref而无明文错误码自检故意使用过期 revision 更新凭据应收到409而非静默成功。总结RetainPDF 的安全模型可以浓缩为一句话回环优先的监听策略守住网络边界X-API-Key守住 API 边界凭据引用守住密钥边界。自托管部署时只要遵循强随机密钥 凭据引用 受限数据目录这三条主线就能在享受保留版面 PDF 翻译能力的同时把隐私风险降到最低。【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何安全部署 RetainPDF：凭据引用、API Key 鉴权与自托管隐私保护的完整指南
如何安全部署 RetainPDF凭据引用、API Key 鉴权与自托管隐私保护的完整指南【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdfRetainPDF 是一款开源的PDF 翻译工具能在保留版面、公式与结构的前提下完成 PDF 翻译特别适合科研论文与技术文档。当你在自己的服务器上自托管部署时安全配置就成了第一道必修课既要防止未授权访问你的后端 API又不能让模型厂商的 API Key 或 OCR 密钥散落在任务配置里。RetainPDF 翻译后的 PDF 页面原文的版面、图表与公式结构被完整保留本文带你从零理解 RetainPDF 的三层安全模型后端 API Key 鉴权 → 凭据引用credential_ref机制 → 自托管隐私边界并给出一份可照做的检查清单。 先分清两类 Key最容易踩的坑很多新手部署失败是因为混淆了这两把钥匙Key 类型作用存放位置后端 API KeyRUST_API_KEYS访问 RetainPDF Rust API 的白名单密钥除健康检查外所有接口都要求携带环境变量或auth.local.json模型 / OCR 密钥DeepSeek、MinerU、Paddle 等调用第三方翻译与 OCR 服务凭据保险库通过凭据引用间接使用后端 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_KEYSauth.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。核心规则只有三条密钥只提交一次。创建凭据时提交一次密钥接口只返回元数据和一个不透明的credential_ref凭据引用列表与查询永不回显。任何 GET 响应都不返回密钥或可反推的掩码值用引用代替明文。创建翻译任务时传translation.credential_refOCR 任务传ocr.credential_ref后端在启动 worker 前一刻才解析密钥并注入到 provider 专用环境变量。保险库的物理防护同样到位数据目录权限0700、文件权限0600POSIX多进程通过文件锁串行化写入实现见 credential_vault.py任务的日志与持久化状态也会用已解析的密钥做脱敏清洗避免密钥出现在日志文件里。版本冲突保护每条凭据带revision更新时携带expected_credential_revision做乐观锁校验并发修改会返回409 CREDENTIAL_REVISION_CONFLICT被任务引用中的凭据默认禁止删除需显式forcetrue才可强制移除。️ 自托管隐私保护7 项部署检查清单只监听回环或更换强密钥后再暴露端口auth.local.json权限设为600不提交到版本库模型/OCR 密钥一律走凭据引用不使用内联明文字段数据根目录RUST_API_DATA_ROOT放在非公开路径上传件、任务工作目录与 SQLite 数据库都在其下结构见 storage.mdDocker 交付时核对三件套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——这也是你自己部署时应当遵守的底线。✅ 部署后快速验证健康检查直接访问GET /health无需鉴权即可确认可用性鉴权生效不带X-API-Key请求任务接口应返回401携带正确 key 才放行凭据闭环通过凭据接口创建一条引用再发起一次 OCR-only 任务确认任务请求中只有credential_ref而无明文错误码自检故意使用过期 revision 更新凭据应收到409而非静默成功。总结RetainPDF 的安全模型可以浓缩为一句话回环优先的监听策略守住网络边界X-API-Key守住 API 边界凭据引用守住密钥边界。自托管部署时只要遵循强随机密钥 凭据引用 受限数据目录这三条主线就能在享受保留版面 PDF 翻译能力的同时把隐私风险降到最低。【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考