ConvertX：用 Docker 自托管的上千格式文件转换服务
ConvertX 是一款自托管 Web 应用程序，可转换 1,000 多种文档、图像、音频和视频格式的文件。
秒懂
- 它是什么？
- ConvertX 是一个基于 TypeScript、Bun 和 Elysia 的自托管文件转换器，宣称支持超过一千种格式。它把 FFmpeg、LibreOffice、ImageMagick 等二十个转换引擎打包成一个带密码保护的 Web 服务，部署方式只有一条 docker run。
- 适合谁用？
- ConvertX 适合需要在自己服务器上处理多种文件格式的开发者、小型团队或注重隐私的个人用户。它用一个 Docker 容器集成了二十个转换引擎，省去了逐个安装配置的麻烦，但代价是镜像体积大、格式支持依赖上游工具、且 AGPL-3.0 协议对商用分发有要求。
- 能商用吗？
- 可以，但条件严格。AGPL-3.0 是网络 copyleft 许可证：如果别人通过网络使用你修改过的版本（例如作为托管服务），你必须以同一许可证向他们提供源代码。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题，谁需要它
文件格式转换是个老问题。文档、图片、音视频、电子书、3D 模型，每种类型都有各自的工具链。FFmpeg 处理视频，LibreOffice 处理 Office 文档，Calibre 处理电子书。想覆盖全部场景，你得装一堆命令行工具，还得自己写脚本把它们串起来。ConvertX 把这些工具打包成一个 Web 服务，提供一个统一的界面和 API。它面向的是愿意自己维护服务器的人，比如家庭用户、小型工作室或企业内部工具。这类人不想把文件传到第三方转换网站，又不想为每种格式单独写转换脚本。ConvertX 的定位就是替代那个过程，用 Docker 镜像把依赖关系一次性解决。
转换引擎的集成方式
ConvertX 不自己实现转换逻辑，它调用外部引擎。README 里列了二十个转换器，包括 Inkscape、libjxl、resvg、Vips、libheif、XeLaTeX、Calibre、LibreOffice、Pandoc、ImageMagick、GraphicsMagick、Assimp、FFmpeg、Potrace、VTracer、Markitdown 等。每个引擎负责一类格式。FFmpeg 覆盖视频和音频，约 472 种输入和 199 种输出。ImageMagick 和 GraphicsMagick 处理图片，分别支持 245 和 167 种输入格式。Assimp 负责 3D 资产，支持 77 种输入。这些数字加起来超过一千，但 README 也注明 FFmpeg 的格式列表里有很多重复项。所以「超过一千种格式」是个宣传口径，实际数量取决于引擎的版本和编译选项。这种集成方式的好处是转换质量直接继承上游工具，坏处是镜像体积会很大，因为要把所有引擎都装进去。
核心机制：Web 界面与多账户
ConvertX 是一个 Web 应用，用户通过浏览器上传文件、选择目标格式、下载结果。它支持多文件批量处理，这是 README 里明确列出的功能。它还提供密码保护和多账户系统。默认情况下，ACCOUNT_REGISTRATION 是 false，意味着不允许用户自行注册。但你第一次启动后访问 localhost:3000，可以创建第一个账户。README 特别警告：不要让它保持未配置状态并开放访问，因为任何人都可以注册第一个账号。这暗示了一个安全模型：系统默认信任第一个注册者，后续账户注册需要手动开启。历史记录功能默认开启，可以用 HIDE_HISTORY 隐藏。文件会自动清理，AUTO_DELETE_EVERY_N_HOURS 默认 24 小时删除旧文件。整个服务用 JWT 做认证，JWT_SECRET 环境变量控制签名密钥，如果不设置会随机生成，但重启后密钥会变，导致已有登录失效。
部署步骤与关键环境变量
部署方式非常直接。README 给出了 docker-compose.yml 示例，核心服务定义只有几行：镜像 ghcr.io/c4illin/convertx，映射端口 3000，挂载 ./data 到 /app/data。也可以直接用 docker run -p 3000:3000 -v ./data:/app/data ghcr.io/c4illin/convertx。启动后访问 http://localhost:3000 创建账户。环境变量全部可选，但 JWT_SECRET 建议设置。HTTP_ALLOWED 默认 false，如果你通过非 HTTPS 的 IP 地址访问，必须设置 HTTP_ALLOWED=true，否则无法登录。ALLOW_UNAUTHENTICATED 默认 false，允许匿名使用，但 README 说只应在本地设置。WEBROOT 可以设置子路径，比如设为 /convert 后服务会挂在 example.com/convert/ 下。FFMPEG_ARGS 和 FFMPEG_OUTPUT_ARGS 允许给 FFmpeg 传额外参数，比如 -hwaccel vaapi 开启硬件加速。这些变量都写在 README 的表格里，没有更多文档说明，实际行为需要自己试。
一个真实的失败模式：登录与数据库权限
README 用警告块明确指出了两个常见问题。第一个是登录失败：如果你不是通过 localhost 或 HTTPS 访问，服务默认拒绝登录，必须设置 HTTP_ALLOWED=true。这看起来像是一个安全设计，但文档没有解释具体机制，只说是为了阻止非安全连接。第二个问题是数据库文件打不开，README 给出的解决方案是运行 chown -R $USER:$USER path 来修正数据目录的属主。这说明服务使用 SQLite 之类的文件型数据库，Docker 挂载卷的权限不匹配会导致启动失败。这两个问题都是部署时最容易踩的坑，而且文档没有自动检测或友好的错误提示，用户只能靠报错信息去查。对于不熟悉 Docker 权限管理的用户，这会是一个挫败点。
维护成本与升级路径
ConvertX 的版本更新比较活跃，最近三个版本分别是 v0.18.0（2026-06-21）、v0.17.0（2026-01-13）和 v0.16.1（2025-12-14）。这意味着它还在快速迭代，但同时也意味着你需要关注发布说明，因为 API 或环境变量可能变化。镜像通过 GitHub Actions 自动构建，发布在 ghcr.io 和 Docker Hub 上，拉取更新只需 docker pull ghcr.io/c4illin/convertx。数据目录 ./data 保存数据库和文件，升级时只要挂载同一个卷，数据应该会保留。但没有任何迁移文档，所以升级前最好备份数据。许可证是 AGPL-3.0，这意味着如果你修改代码并部署为网络服务，你需要向用户提供源代码。对于内部使用影响不大，但如果想基于它做商业产品，这个协议会有约束。具体法律问题请咨询律师，这里只是指出协议类型。
替代方案与差异
最常见的替代方案是直接使用在线转换网站，比如 CloudConvert 或 Zamzar。它们的优势是零部署，不需要维护服务器，但需要上传文件到第三方，对隐私敏感的用户不可接受。另一个替代方案是自己安装单个工具，比如只装 FFmpeg 或 Pandoc，写一个简单的脚本。这样镜像体积小，但只能覆盖一种格式类型，而且需要自己处理 Web 界面和用户认证。ConvertX 的差异在于它把多个工具集成到一个容器里，提供了一个现成的多用户 Web 界面。如果你只需要转换视频，ConvertX 有点重；如果你需要文档、图片、音视频全支持，它比逐个配置工具省事。还有一个思路是使用 LibreOffice 自带的命令行转换，但那只覆盖文档。ConvertX 的价值在于覆盖面广，代价是资源占用和复杂度。
编辑结论
ConvertX 适合需要在自己服务器上处理多种文件格式的开发者、小型团队或注重隐私的个人用户。它用一个 Docker 容器集成了二十个转换引擎，省去了逐个安装配置的麻烦，但代价是镜像体积大、格式支持依赖上游工具、且 AGPL-3.0 协议对商用分发有要求。不适合只想偶尔转一个文件的人，那直接用在线服务更快。部署前先确认两件事：第一，通过 HTTPS 或 localhost 访问，否则需要设置 HTTP_ALLOWED=true 才能登录；第二，如果使用非默认数据目录，确保目录属主正确，否则会报 unable to open database file。另外，首次启动后立即创建账户，因为默认情况下任何人都可以注册第一个账号。最终判断：ConvertX 是一个把复杂依赖关系打包好的实用工具，但它的价值完全取决于你能否接受 Docker 镜像的体量以及 AGPL 的约束。
社区笔记