ConvertX 文件转换工具使用指南

一、概述

1. 简介

A. 是什么

ConvertX 是一个自托管的在线文件转换工具，支持超过 1000 种不同的文件格式转换。该项目使用 TypeScript、Bun 和 Elysia 框架开发，提供完整的 Web 界面和 RESTful API。

B. 为什么使用

  • 完全自主可控，数据无需上传到第三方服务
  • 支持格式极其丰富，覆盖图片、视频、文档、3D 模型等多种类型
  • 支持批量处理，提高工作效率
  • 可部署在本地或私有云环境中

C. 适用场景

  • 企业内部文件格式统一转换
  • 个人隐私敏感文件处理
  • 需要离线环境下的格式转换
  • 批量文件处理需求

2. 支持的转换格式

A. 图片格式（约 700+ 种）

  • 常用格式：JPG、PNG、GIF、WebP、SVG、HEIF
  • 专业格式：JPEG XL、TIFF、BMP、ICO
  • 矢量格式：SVG（通过 Inkscape、resvg）
  • 转换工具：ImageMagick、GraphicsMagick、Vips、libjxl、libheif、Potrace、VTracer

B. 视频格式（约 671 种）

  • 输入格式：约 472 种（通过 FFmpeg）
  • 输出格式：约 199 种
  • 支持硬件加速（如 VAAPI）

C. 文档格式（约 200+ 种）

  • 办公文档：通过 LibreOffice 支持 41 种输入、22 种输出
  • 电子书：通过 Calibre 支持 26 种输入、19 种输出
  • 标记文档：通过 Pandoc 支持 43 种输入、65 种输出
  • Markdown：通过 Markitdown 支持 6 种输入格式

D. 其他格式

  • 3D 资产：通过 Assimp 支持 77 种输入、23 种输出
  • 邮件格式：Outlook msg 文件转换
  • 联系人：VCF 转 CSV
  • 数据文件：通过 Dasel 转换
  • LaTeX 文档：通过 XeLaTeX、dvisvgm 转换

二、部署方式

1. 系统要求

  • Docker 或 Docker Compose
  • 至少 1GB 可用磁盘空间
  • 推荐 2GB 以上内存

2. 使用 Docker Compose 部署

创建 docker-compose.yml 文件：

services:
  convertx:
    image: ghcr.io/c4illin/convertx
    container_name: convertx
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - JWT_SECRET=aLongAndSecretStringUsedToSignTheJSONWebToken1234
      # - HTTP_ALLOWED=true
    volumes:
      - ./data:/app/data

启动服务：

docker-compose up -d

3. 使用 Docker 部署

docker run -d \
  -p 3000:3000 \
  -v ./data:/app/data \
  -e JWT_SECRET=your-secret-key \
  --name convertx \
  --restart unless-stopped \
  ghcr.io/c4illin/convertx

4. 访问服务

部署完成后，在浏览器中访问 http://localhost:3000

首次访问时需要注册账户，这将是管理员账户。建议不要将未配置的服务公开暴露。

5. 数据目录权限

如果遇到无法打开数据库文件的错误，运行：

chown -R $USER:$USER ./data

三、系统架构

1. 工作原理

graph TB
    User[用户] -->|上传文件| Web[Web 界面]
    Web -->|转发请求| API[Elysia API]
    API -->|验证身份| JWT[JWT 认证]
    JWT -->|通过| Converter[转换引擎]
    Converter -->|调用| FFmpeg[FFmpeg 视频]
    Converter -->|调用| ImageMagick[ImageMagick 图片]
    Converter -->|调用| LibreOffice[LibreOffice 文档]
    Converter -->|调用| Calibre[Calibre 电子书]
    Converter -->|调用| Other[其他转换器]
    Converter -->|返回| Storage[(存储)]
    Storage -->|下载| Web
    Web -->|下载文件| User

mermaid

2. 核心组件

A. Web 前端

基于 TypeScript 和 Bun 开发的响应式 Web 界面，提供文件上传、转换历史查看等功能。

B. API 服务

基于 Elysia 框架构建的高性能 API 服务，处理文件上传、转换请求、用户认证等。

C. 转换引擎

集成多种专业转换工具：

  • FFmpeg：视频和音频处理
  • ImageMagick/GraphicsMagick：通用图像处理
  • LibreOffice：办公文档转换
  • Calibre：电子书格式转换
  • Pandoc：文档标记语言转换
  • Inkscape：矢量图形处理

D. 存储层

使用 SQLite 数据库存储用户配置和转换历史，转换后的文件存储在本地文件系统。

四、配置说明

1. 环境变量

变量名默认值说明
JWT_SECRETrandomUUID()JWT 签名密钥，建议设置
ACCOUNT_REGISTRATIONfalse是否允许用户注册
HTTP_ALLOWEDfalse是否允许 HTTP 连接（仅限本地）
ALLOW_UNAUTHENTICATEDfalse是否允许未认证用户使用（仅限本地）
AUTO_DELETE_EVERY_N_HOURS24自动删除 n 小时前的文件，0 表示禁用
WEBROOT空Web 根路径，如设置为 /convert 则访问 example.com/convert/
FFMPEG_ARGS空FFmpeg 输入参数，如 -hwaccel vaapi
FFMPEG_OUTPUT_ARGS空FFmpeg 输出参数，如 -preset veryfast
HIDE_HISTORYfalse是否隐藏历史记录页面
LANGUAGEen日期格式语言（BCP 47 语言标签）
UNAUTHENTICATED_USER_SHARINGfalse未认证用户是否共享转换历史
MAX_CONVERT_PROCESS0最大并发转换进程数，0 表示无限制

2. 反向代理配置

Nginx 配置示例

location /convert/ {
    proxy_pass http://localhost:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 文件上传大小限制
    client_max_body_size 100M;
    
    # 超时设置
    proxy_read_timeout 300s;
    proxy_connect_timeout 300s;
}

设置环境变量 WEBROOT=/convert 以配合反向代理使用。

五、使用指南

1. 用户注册

首次访问时，需要创建第一个账户（管理员账户）：

  1. 打开 http://localhost:3000
  2. 点击注册按钮
  3. 输入用户名、密码
  4. 完成注册

默认情况下，后续用户无法自行注册，需要管理员在环境变量中设置 ACCOUNT_REGISTRATION=true。

2. 文件转换

基本转换流程

  1. 登录系统
  2. 点击上传区域或拖拽文件
  3. 选择目标格式
  4. 点击转换按钮
  5. 等待转换完成
  6. 下载转换后的文件

批量转换

支持同时上传多个文件进行批量转换，提高处理效率。

3. 转换历史

系统会记录所有转换历史，包括：

  • 原始文件名
  • 目标格式
  • 转换时间
  • 转换状态

可通过历史页面重新下载之前转换的文件。

4. 硬件加速

对于视频转换，可启用硬件加速以提高性能：

# Intel/AMD GPU
FFMPEG_ARGS=-hwaccel vaapi

# NVIDIA GPU
FFMPEG_ARGS=-hwaccel cuda
FFMPEG_OUTPUT_ARGS=-preset veryfast

六、Docker 镜像说明

1. 镜像标签

标签说明推荐用途
latest最新稳定版本生产环境
main最新开发版本测试新功能

2. 镜像来源

# GitHub Container Registry
ghcr.io/c4illin/convertx
ghcr.io/c4illin/convertx:main

# Docker Hub
c4illin/convertx
c4illin/convertx:main

推荐使用 ghcr.io/c4illin/convertx（latest 标签）。

七、常见问题

1. 登录问题

问题：无法登录

确保通过 localhost 或 HTTPS 访问服务，或设置 HTTP_ALLOWED=true。

2. 文件上传问题

问题：文件上传失败

检查 Nginx 的 client_max_body_size 设置，确保允许上传大文件。

3. 转换失败

问题：某些格式无法转换

  • 检查源文件是否损坏
  • 确认该格式在支持的转换列表中
  • 查看容器日志排查问题

4. 性能优化

问题：转换速度慢

  • 启用硬件加速（FFMPEG_ARGS）
  • 增加 MAX_CONVERT_PROCESS 限制
  • 确保磁盘 I/O 性能充足

八、安全建议

1. 部署安全

  • 不要将未配置的服务暴露到公网
  • 设置强密码作为 JWT_SECRET
  • 使用 HTTPS 部署
  • 限制账户注册功能

2. 数据安全

  • 定期备份 data 目录
  • 配置自动删除过期文件
  • 敏感文件转换后及时删除

3. 访问控制

  • 使用反向代理添加额外认证层
  • 配置防火墙规则限制访问
  • 定期审查用户账户

九、扩展与定制

1. 添加新的转换器

ConvertX 采用模块化设计，可以方便地添加新的转换器：

  1. Fork 项目仓库
  2. 在 issues 中查看转换器请求
  3. 提交 Pull Request

2. 开发环境搭建

# 安装 Bun 和 Git
# 克隆仓库
git clone https://github.com/C4illin/ConvertX.git
cd ConvertX

# 安装依赖
bun install

# 启动开发服务器
bun run dev

十、参考资料

  1. ConvertX GitHub 仓库
最后修改：2026 年 01 月 15 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏