Loading... # 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 文件： ```yaml 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 ``` 启动服务： ```bash docker-compose up -d ``` ## 3. 使用 Docker 部署 ```bash 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. 数据目录权限 如果遇到无法打开数据库文件的错误，运行： ```bash chown -R $USER:$USER ./data ``` # 三、系统架构 ## 1. 工作原理 ```mermaid 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 ```  ## 2. 核心组件 ### A. Web 前端 基于 TypeScript 和 Bun 开发的响应式 Web 界面，提供文件上传、转换历史查看等功能。 ### B. API 服务 基于 Elysia 框架构建的高性能 API 服务，处理文件上传、转换请求、用户认证等。 ### C. 转换引擎 集成多种专业转换工具： - FFmpeg：视频和音频处理 - ImageMagick/GraphicsMagick：通用图像处理 - LibreOffice：办公文档转换 - Calibre：电子书格式转换 - Pandoc：文档标记语言转换 - Inkscape：矢量图形处理 ### D. 存储层 使用 SQLite 数据库存储用户配置和转换历史，转换后的文件存储在本地文件系统。 # 四、配置说明 ## 1. 环境变量 | 变量名 | 默认值 | 说明 | |-------|-------|------| | JWT_SECRET | randomUUID() | JWT 签名密钥，建议设置 | | ACCOUNT_REGISTRATION | false | 是否允许用户注册 | | HTTP_ALLOWED | false | 是否允许 HTTP 连接（仅限本地） | | ALLOW_UNAUTHENTICATED | false | 是否允许未认证用户使用（仅限本地） | | AUTO_DELETE_EVERY_N_HOURS | 24 | 自动删除 n 小时前的文件，0 表示禁用 | | WEBROOT | 空 | Web 根路径，如设置为 /convert 则访问 example.com/convert/ | | FFMPEG_ARGS | 空 | FFmpeg 输入参数，如 -hwaccel vaapi | | FFMPEG_OUTPUT_ARGS | 空 | FFmpeg 输出参数，如 -preset veryfast | | HIDE_HISTORY | false | 是否隐藏历史记录页面 | | LANGUAGE | en | 日期格式语言（BCP 47 语言标签） | | UNAUTHENTICATED_USER_SHARING | false | 未认证用户是否共享转换历史 | | MAX_CONVERT_PROCESS | 0 | 最大并发转换进程数，0 表示无限制 | ## 2. 反向代理配置 ### Nginx 配置示例 ```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. 硬件加速 对于视频转换，可启用硬件加速以提高性能： ```bash # Intel/AMD GPU FFMPEG_ARGS=-hwaccel vaapi # NVIDIA GPU FFMPEG_ARGS=-hwaccel cuda FFMPEG_OUTPUT_ARGS=-preset veryfast ``` # 六、Docker 镜像说明 ## 1. 镜像标签 | 标签 | 说明 | 推荐用途 | |-----|------|---------| | latest | 最新稳定版本 | 生产环境 | | main | 最新开发版本 | 测试新功能 | ## 2. 镜像来源 ```bash # 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. 开发环境搭建 ```bash # 安装 Bun 和 Git # 克隆仓库 git clone https://github.com/C4illin/ConvertX.git cd ConvertX # 安装依赖 bun install # 启动开发服务器 bun run dev ``` # 十、参考资料 1. [ConvertX GitHub 仓库](https://github.com/C4illin/ConvertX) 最后修改：2026 年 01 月 15 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏