BentoPDF Docker 自托管部署：合并/拆分/转换留在浏览器-TKMiss Notes

BentoPDF 的 Docker 自托管只需要一行命令：拉取官方镜像 bentopdf/bentopdf:latest，把容器的 8080 端口映射到宿主机任意未占用端口，浏览器打开 http://localhost:映射端口 就能用 [1]。如果要给团队内网长期跑，建议直接写一份 docker-compose.yml，用官方提供的镜像 + restart: unless-stopped 配置，后台常驻更省心 [1]。

一、先用一行 `docker run` 把 BentoPDF 跑起来

BentoPDF 官方提供的部署入口很简单——镜像本身只是一个静态站点（前端用 WebAssembly 在浏览器里完成 PDF 解析与转换），拉镜像、起容器、浏览器访问即可 [5]。官方在 Docker Hub 上同时维护两个标签：bentopdf/bentopdf:latest 是完整版，包含首页介绍和品牌内容；bentopdf/bentopdf-simple:latest 是简洁版，只保留工具入口，隐藏首页与营销区 [1]。个人本机试用完整版就够了，内网给同事用建议直接用简洁版，避免无关链接从工具页跳出去。

拉镜像 + 运行的标准命令按官方文档写是这样 [1]：

docker run -p 3000:8080 bentopdf/bentopdf:latest

简洁版换镜像名即可：

docker run -p 3001:8080 bentopdf/bentopdf-simple:latest

容器内服务监听 8080，宿主机的端口可以随意选，只要没被占用。运行起来后访问 http://localhost:3000（简洁版访问 :3001）就能看到界面。官方说明里写到，所有解析、合并、拆分、转换都在浏览器里完成，服务器只负责把静态资源发过来 [5]。

二、要常驻运行：用 docker-compose 起

docker run 适合临时试用，但容器重启、机器重启后就没了。要长期跑，官方推荐的写法是用 Docker Compose [1]。按官方给出的模板结构（image 字段、容器名、restart 策略、security_opt 加 no-new-privileges:true）写一份 docker-compose.yml 就能后台常驻：

version: "3.8"
services:
  bentopdf:
    image: bentopdf/bentopdf:latest   # 或 bentopdf/bentopdf-simple:latest
    container_name: bentopdf
    restart: unless-stopped
    ports:
      - "3000:8080"
    security_opt:
      - no-new-privileges:true

然后 docker-compose up -d，容器就在后台跑着了 [1]。社区里常见的做法是把镜像换成 bentopdf/bentopdf-simple:latest，再根据内网访问需要决定是否把宿主机端口改成 80/443 之外的其他端口（比如 3001、8081，避免和 NAS 自带的 Web 管理界面撞车）。重点就是把 restart 和 no-new-privileges 两项保留下来——前者保证机器重启后服务自启，后者是容器安全的基础项，官方模板里都明确给出了 [1]。

三、镜像拉不下来 / 端口冲突 / 反代空白：常见部署报错排查

部署路上真正卡人的往往不是 BentoPDF 本身，而是周边环境。社区里反馈比较多的几类问题，按出现顺序排一下。

镜像拉不下来。 从 Docker Hub 拉 bentopdf/bentopdf:latest 超时或失败的情况在国内网络环境下并不少见。官方镜像在 GitHub Container Registry 上有同步发布，可以直接换源拉 ghcr.io/alam00000/bentopdf:latest 作为兜底 [3]；或者给 Docker daemon 配置国内镜像加速器后再重试。这两种处理方式在 BentoPDF 的部署帖子里都出现过 [3]，属于环境层面的常规应对。

端口冲突。 容器内服务固定监听 8080，宿主机端口选 3000/3001/8081 都行，但如果你机器上已经有别的服务占了这些端口，docker run 会直接报 bind: address already in use。改一下宿主机端口映射（比如 -p 3001:8080）就够了，这是 Docker 部署最常见的小坑 [1]。

反代之后页面空白或 404。 在 Nginx / Caddy 后面反代 BentoPDF 时偶尔会出现首页能打开、点工具链接却 404 的情况。BentoPDF 本质上是个 SPA（单页应用），路由靠前端处理，反代配置里缺少 fallback 是常见原因。官方说明里把它归在”静态网站托管”那一类，按 SPA 的通用做法补 try_files $uri /index.html;（Nginx）或 handle_path / 兜底（Caddy）即可，具体写法以你反代工具的官方文档为准 [1]。这一类问题不是 BentoPDF 独有，凡是纯前端路由的项目都会遇到。

NAS 上的 docker-compose 报错。 极空间、绿联、群晖这类 NAS 自带的 Docker 应用对 compose 文件的路径、文件名、YAML 缩进都有各自的要求，社区里搜到最多的报错往往是”找不到 compose 文件”或者”YAML 解析失败”。这类问题各 NAS 表现不一致，最稳妥的办法是参考对应 NAS 官方文档里”Docker Compose”那一节的路径约定，把 docker-compose.yml 放到 NAS 指定的目录（比如 /docker/bentopdf/），再从 NAS 的 Docker 应用里指定该路径启动。具体的目录和命名规则以你所使用 NAS 的官方说明为准。

四、什么时候选简洁模式（bentopdf-simple）

完整版和简洁版用同一套 PDF 处理工具，差别只在页面外壳：完整版有首页介绍、品牌区和营销入口，简洁版直接进工具列表，把这些外壳内容都拿掉了 [1]。如果只是自己本机用，无所谓首页长什么样，完整版就行；如果是部署在公司内网、团队共用，或者放到对外提供服务的小机器上，建议用简洁版，避免工具页里有外链跳出去，也省去不必要的视觉干扰。

另一个常被问到的点是协议。BentoPDF 源码采用 AGPL-3.0 授权 [2]，如果你的产品是闭源的、要把它打包进自己的商业产品里分发，需要单独评估 AGPL 义务，必要时购买官方提供的商业授权 [2]。个人使用、团队内网自托管不在这个限制里，正常用即可。

五、怎么验证 PDF 文件真的没离开浏览器

部署好之后，想确认”文件没上传”这件事并不只是看官方文档怎么写——自己也可以验。常见做法是打开浏览器 DevTools 的 Network 面板，再去做一次合并或拆分：正常情况下你应该看不到任何包含 PDF 内容的 POST/Upload 请求，只有加载页面、字体、WebAssembly 模块这类静态资源的 GET 请求。如果看到了把 PDF 二进制流往外发的请求，那就要停下来排查了。

进一步验证可以断网再操作一次：把网线拔掉或者禁用 Wi-Fi，再做一次合并、拆分或转换。如果功能照样能用，就说明处理确实完全发生在本地 [5]。官方还提到 BentoPDF 支持 PWA 安装，安装后浏览器会缓存静态资源，本身就具备离线使用能力 [1]，这一点和”本地处理”的设计是一致的——既然计算在浏览器里，断网自然是预期内的情况。

“文件不上传”是 BentoPDF 默认架构下的设计，但具体某个工具、某个版本的行为仍以官方文档和实际测试为准；正式拿敏感文件跑批之前，建议先用不含敏感信息的样本文件完整走一遍流程，确认行为符合预期 [2]。