convertx/convertx-cn repository overview

⁠ConvertX-CN

ConvertX-CN 是一个以 Docker 为主要交付方式的文件转换服务，提供 Web UI、批量上传、转换历史、格式推断、多语言界面，以及可选的 Rust API Server。

Docker Hub⁠ · Releases⁠ · License⁠

当前应用版本对齐上游 v0.19.0；采用选择性同步并保留中文分支功能。逐项同步记录⁠列出已合入、已有等效实现与跳过的更新。

⁠主要特色

• 支持多类文件转换：影音、图片、文档、电子书、PDF、OCR、向量图、3D 模型与结构化数据。
• 内置多种转换引擎，包括 FFmpeg、ImageMagick、GraphicsMagick、libvips、LibreOffice、Pandoc、Calibre、Inkscape、pdftops、PDFMathTranslate、MinerU、OCRmyPDF 等。
• 提供 Web UI，支持用户登录、上传、转换、下载和历史记录。
• 提供 Lite / Standard / Full 映像选择，便于在镜像体积与功能完整度之间取舍。
• 提供可选 API Server，用于 REST API、JWT 鉴权与任务式转换流程；该部分仍可能重构。

⁠适合谁使用

• 需要私有部署文件转换服务的个人或团队。
• 需要用 Docker 快速集成多种转换工具的部署者。
• 需要通过 API 接入 ConvertX-CN 转换能力的开发者。
• 想维护转换引擎、格式矩阵或文档体系的贡献者。

⁠Quick Start

mkdir -p convertx-cn/data
cd convertx-cn
cp .env.example .env
# 可选：在 .env 设置 JWT_SECRET；未设置时会安全生成并持久化到 data/.secrets/
docker compose up -d

启动后打开：

http://localhost:3000

最小 compose.yaml 示例：

services:
  convertx:
    image: convertx/convertx-cn:latest
    container_name: convertx-cn
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env

Docker Run 示例：

docker run -d \
  --name convertx-cn \
  --restart unless-stopped \
  -p 3000:3000 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v ./data:/app/data \
  --env-file .env \
  convertx/convertx-cn:latest

PUID / PGID 可选，用于让容器内进程使用指定宿主机 UID/GID 访问挂载的 ./data；通常设置为 id -u 和 id -g 的输出。需要调整新文件权限时可同时设置 UMASK。

⁠在线演示(正在維護)

演示地址：https://convertx-cn.bioailab.qzz.io⁠

⁠文档入口

⁠版本选择摘要

⁠API Server 状态

API Server 是可选服务，不影响 Web UI 的基本使用。当前实现位于 api-server/，使用 Rust + Axum，提供 REST API 与 GraphQL 入口；由于后续可能重构，对外集成前请阅读 API Server⁠ 与 API Reference⁠。

⁠安全提醒

• 未设置 JWT_SECRET 时，服务会在数据目录原子生成并持久化随机密钥；请备份 data/.secrets/。也可用 JWT_SECRET 或 JWT_SECRET_FILE 明确管理密钥。
• 公开部署时请使用 HTTPS，并正确配置反向代理相关环境变量。
• 仅向可信用户开放文件转换；公开部署请关闭匿名转换和自助注册。Calibre recipe 文件可能执行代码，现已明确拒绝。
• 不建议在公网开启未认证访问。
• 上传和转换敏感文件前，请确认数据目录、备份策略和访问控制符合你的安全要求。

⁠授权与致谢

ConvertX-CN 使用 AGPL-3.0 授权。项目集成并依赖多个开源转换工具，详见各工具原始项目与本仓库文档。