为什么自托管 PDF 工具箱，而不是再用一个免费网页转换器

纯浏览器 PDF 转换器优化的是上传、点击、下载。页面常靠广告养活，表单之外通常也没有稳定的开发者接口。这种形态适合人手一次性作业；一旦需要自动化、留存策略，或文件必须留在自有网络，形态就不对了。

浏览器转换器在优化什么

公开转换器卖的是方便：开标签页、丢文件、拿结果、走人。UI 就是产品。脚本要么抓 HTML，要么打会在无声中变更的未文档化接口；临时文件由运营方留存。合并两份个人 PDF 时，这笔交易可以接受。

一旦要从 CI、Agent 或气隙网络跑同一份活，缺口会一起冒出来：认证、OpenAPI、幂等重试，以及一份不会和上周点过的表单悄悄分叉的操作目录。

自己跑这份目录能得到什么

托管站与自托管实例共用同一套操作。压缩 与 合并 无论是从门户还是从 POST /api/v1/… 发起，都是同一批 op。自托管是在这份共享目录外围加控制：

• REST + OpenAPI（/v1/openapi.json）：每个目录工具都是稳定端点，不只是一张表单。
• MCP（/mcp）：Agent 发现并调用同一批操作，不必自造爬虫。
• CLI（pdfx）：本地 pdf-core，或用 --cloud 指向你 base URL 上的 API Key。
• 没有桌面客户端：离线方案是 Docker Compose；插件与 Windows 安装包被有意排除在范围外。
• 广告不进你的栈：公网站的 AdSense 不属于自托管部署，上传不离开你运行的机器。

Compose 会一起拉起 Rust pdfx-server 与 Next.js 门户，让人和脚本共用一份目录。原生开发（task pdfx:dev 加门户）走同一条 op 路径。细节见 自托管。

任一部署上的 OCR 仍从 /api/v1/misc/ocr-pdf 返回 Markdown（text/markdown），不是重新叠了文本层的可搜索 PDF。换服务器改变的是字节落在哪里，不会变出一份不同的 op 契约。

我们故意不抄的部分

在线“编辑 PDF”画布、可视化对比、空白“创建 PDF”与消费级签名 UI 需要另一套产品工作。我们保留基于表单的工具矩阵与 API。自托管不会解锁第二棵 UI 树，它只是把同一棵树挪到防火墙之后。

跳过这些消费级表面是刻意的。画布编辑器会成为第二套代码库，相对 OpenAPI 永远滞后。私有场景真正要紧的约束是“字节留在这里”，不是“有个 .exe”。为什么没有桌面分叉，见 为什么不做桌面应用。

何时托管就够，何时不够

要零配置、匿名一次性时用公网站。目录工具与匿名 /api/v1/ 调用不需要账号；托管响应会带限流头，有上限是为了让免费面不被当成别人的批处理农场（匿名限流）。

需要留存规则、私有网络或私有自动化时自托管。此时你负责可用性、镜像升级、临时文件磁盘、TLS 与密钥轮换（本机固定门闸用 SECURITY_CUSTOMGLOBALAPIKEY）。操作不变，变的是字节落在哪里。

试一下

从 自托管 与 开发者 起步。Agent 面向的 API 面见 为 AI Agent 而建，不只为浏览器，更长的成本收益拆分见 自托管实际买到什么。