企业官网建设流程全解析

10分钟自部署 RetainPDF：Docker Compose 一键启动私有 PDF 翻译服务的完整实操

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

RetainPDF 是一个面向科研与技术文档的开源PDF 翻译服务，在保留版面、公式与结构的前提下翻译 PDF，图片型/扫描版文档同样支持。本文手把手教你用Docker Compose在 10 分钟内一键部署私有 RetainPDF 服务：不装依赖、不配显卡、只需 3 条命令，新手也能跑通从启动到出译文的完整流程。

📦 部署前准备：硬件与环境要求

RetainPDF 主要吃 CPU、内存和网络，不依赖独立显卡，一台普通云服务器甚至家里的台式机就能跑。

💡 Mac M 系列、树莓派或 ARM 服务器请选择linux/arm64镜像变体。轻量自用 4 核 + 8GB 即可起步，团队共享建议 8 核 + 16GB。

先自检环境，两条命令都有版本号输出即可：

docker --version docker compose version

🚀 一键启动：3 条命令拉起 PDF 翻译服务

进入仓库自带的一键部署目录 ops/deployment/docker/delivery/，整套服务由 docker-compose.yml 编排，只有两个容器：

• app：Rust API + 翻译流水线，负责 OCR、翻译与排版渲染，默认拉取retainpdf-app镜像，数据持久化在app_data卷（对应容器内/data）；
• web：NGINX 静态前端，web会等app通过健康检查后才启动，避免"页面能打开但接口全 502"。

git clone https://gitcode.com/gh_mirrors/re/retain-pdf.git cd retain-pdf/ops/deployment/docker/delivery docker compose up -d

⚠️ 首次启动会从 Docker Hub 拉取镜像并等待app就绪，耐心等待 1～3 分钟。启动后默认访问地址：http://127.0.0.1:40001

🔑 启动前必改：3 个关键配置文件

交付包内置了示例配置，正式使用前只需改 3 个文件，其余参数开箱即用。

1. 后端密钥：docker/auth.local.json

auth.local.json 是 API 鉴权白名单，把占位值换成你自己的随机长字符串：

"api_keys": ["这里换成你的随机密钥"]

2. 前端代理：docker/web.env

web.env 中的RETAINPDF_PROXY_API_KEY必须与上面的 key 一致——它由 NGINX 在服务端注入，不会暴露在浏览器里。该文件还预留了FRONT_MODEL（默认模型）、FRONT_BASE_URL（模型服务地址）、FRONT_OCR_PROVIDER（默认paddle）等可选字段，留空也没关系：最终用户可在页面右上角的"API 配置"弹窗中自行填写。

3. 运行参数：docker/app.env

app.env 控制并发与上传限制，默认值适合个人使用：

📄 各变量的完整说明见 Docker 部署说明；镜像构建细节分别在 Dockerfile.app 与 Dockerfile.web。

✅ 验证服务是否启动成功

看容器状态，web容器显示healthy即代表全链路就绪（compose 里app的健康检查调用/ready，包含数据库与全部受监管运行时）：

docker compose ps docker compose logs -f app

访问页面：浏览器打开 http://127.0.0.1:40001，上传一篇英文 PDF，选择 OCR provider 与翻译模型，几分钟后即可下载保留排版的译文 PDF、Markdown 或 ZIP 打包。

🔒 端口40001（前端）、41000（完整 API）、42000（扁平提交接口）默认只绑定127.0.0.1，本机以外的机器无法直连，天然更安全。

🖥 部署后体验：一个书架管理所有文档

服务跑起来后，登录页面进入「图书馆」，上传的每篇 PDF 都会变成书架上的一本书，翻译状态一目了然：

译文 PDF 与原文可同页并排对照阅读，公式、图表、引用位置一一对应，核对非常方便：

除 PDF 外，还能同屏查看Markdown 译文，公式与图片完整保留：

内置文档 AI 问答：围绕当前文档直接提问，回答附带页码与原文引用，适合快速抓论文核心结论：

🌐 进阶：用域名 + NGINX 反向代理对外提供

团队共享时，宿主机 NGINX 只需反向代理到127.0.0.1:40001，不要把域名直接指向 41000/42000。仓库提供了完整示例 retainpdf.example.conf，部署要点：

• client_max_body_size 256m，放行大 PDF 上传；
• /api/v1/ai/ask与任务实时事件接口是 SSE 长连接，禁止缓冲；
• 公网暴露务必加 Basic Auth、OAuth2 Proxy 或 Cloudflare Access 任一层访问门禁；
• 若不需要宿主机直调 API，可删掉 compose 中 app 的41000/42000端口映射，web 容器通过 Docker 内部网络访问app:41000。

🔄 日常运维：更新、备份与排错

升级到新版本（compose 默认latest标签）：

docker compose pull docker compose up -d

数据备份：所有上传文件、任务产物、检查点、数据库都在app_data卷（/data）中，整卷备份才能保证断点续传产物完整，只拷 SQLite 文件是不够的。

指定镜像版本启动，适合生产环境锁定版本：

APP_IMAGE=wxyhgk/retainpdf-app:<version> \ WEB_IMAGE=wxyhgk/retainpdf-web:<version> \ docker compose up -d

常见问题速查：

📎 相关文件索引

10 分钟，两条命令加三处配置，一台没有显卡的普通服务器就能拥有私有、可审计、可无限次使用的 PDF 翻译服务——论文再多，版面照旧，公式无损。

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