ConvertX Docker部署教程：快速搭建个人文件转换服务器

你还在为文件格式转换烦恼吗？寻找一个支持千种格式、完全掌控数据的解决方案？本文将带你5分钟内通过Docker快速搭建ConvertX个人文件转换服务器，无需复杂配置，即刻拥有安全高效的本地转换工具。

读完本文你将获得：

• 从零部署ConvertX服务的完整步骤
• 环境变量配置最佳实践
• 多平台客户端访问指南
• 常见问题解决方案

项目简介

ConvertX是一款开源自托管文件转换工具，支持超过1000种格式转换，涵盖文档、图片、音视频等多种类型。项目采用TypeScript开发，基于Bun和Elysia框架构建，提供直观的Web界面和强大的转换能力。

核心功能包括：

• 多文件批量处理
• 用户认证与权限管理
• 700+格式支持
• 转换历史记录
• 数据本地化存储

支持的转换器列表可查看项目源码中的src/converters/目录，包含ImageMagick、FFmpeg、Pandoc等18种专业转换工具。

准备工作

系统要求

• Docker Engine 20.10+
• Docker Compose v2+
• 至少2GB RAM（视频转换建议4GB+）
• 10GB可用磁盘空间

安装Docker环境

如果尚未安装Docker，请根据你的操作系统选择以下方式：

Ubuntu/Debian:

sudo apt update && sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

CentOS/RHEL:

sudo dnf install -y docker docker-compose-plugin
sudo systemctl enable --now docker

macOS/Windows: 推荐安装Docker Desktop，内置Docker Compose功能。

部署步骤

1. 获取项目代码

git clone https://gitcode.com/GitHub_Trending/co/ConvertX
cd ConvertX

2. 配置Docker Compose

项目提供了两种部署方式，推荐使用Docker Compose进行管理，配置文件位于compose.yaml。

默认配置已足够日常使用，关键参数说明：

参数	默认值	说明
ports	3000:3000	端口映射，左侧为宿主机端口
volumes	./data:/app/data	数据持久化目录
JWT_SECRET	随机生成	用户认证密钥，建议手动设置
HTTP_ALLOWED	false	是否允许HTTP访问（生产环境建议设为false）

如需自定义配置，可创建.env文件覆盖默认值：

JWT_SECRET=your_secure_random_string_here
TZ=Asia/Shanghai
AUTO_DELETE_EVERY_N_HOURS=48

3. 启动服务

使用Docker Compose启动服务：

docker compose up -d

首次启动会自动拉取镜像并创建容器，根据网络情况可能需要3-5分钟。可通过以下命令查看启动日志：

docker compose logs -f

当看到类似Server running on port 3000的输出时，表示服务已成功启动。

访问与使用

初始访问

在浏览器中输入http://服务器IP:3000，首次访问会要求创建管理员账户。

基本操作流程

1. 注册账户：首次访问时创建管理员账户
2. 上传文件：点击上传区域或拖拽文件至上传框
3. 选择格式：根据文件类型选择目标格式
4. 开始转换：点击"Convert"按钮
5. 下载结果：转换完成后点击文件链接下载

高级配置

环境变量详解

项目支持多种环境变量配置，完整列表可参考README.md：

变量名	用途	安全建议
JWT_SECRET	用户认证密钥	必须设置为强随机字符串
ACCOUNT_REGISTRATION	是否允许注册新用户	生产环境建议设为false
ALLOW_UNAUTHENTICATED	允许匿名使用	仅本地测试使用
AUTO_DELETE_EVERY_N_HOURS	自动清理旧文件	建议设置为24-48
FFMPEG_ARGS	额外FFmpeg参数	可添加-hwaccel auto启用硬件加速

修改环境变量后需重启容器生效：

docker compose down && docker compose up -d

反向代理配置

如需通过域名访问并启用HTTPS，可使用Nginx或Caddy作为反向代理。

Nginx示例配置：

server {
    listen 80;
    server_name convertx.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name convertx.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        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;
    }
}

使用反向代理时，需在compose.yaml中添加环境变量：

environment:
  - HTTP_ALLOWED=false
  - WEBROOT=/

维护与更新

查看容器状态

docker compose ps

备份数据

数据存储在项目目录下的data文件夹，定期备份此目录即可：

tar -czf convertx_backup_$(date +%Y%m%d).tar.gz ./data

更新服务

# 获取最新代码
git pull

# 重建并启动容器
docker compose down
docker compose pull
docker compose up -d

常见问题解决

1. 无法访问服务

• 检查容器是否运行：docker compose ps
• 检查端口映射：netstat -tulpn | grep 3000
• 检查防火墙设置：确保3000端口已开放

2. 转换失败

查看详细日志定位问题：

docker compose logs --tail=100 convertx

常见原因及解决办法：

• 文件太大：调整上传限制
• 格式不支持：查看支持的格式列表
• 资源不足：增加容器内存限制

3. 忘记密码

删除数据目录中的用户数据库后重启服务：

rm data/users.db
docker compose restart

总结

通过Docker部署ConvertX仅需3个简单步骤，即可拥有功能强大的个人文件转换服务器。项目源码结构清晰，主要代码位于src/目录，包含Web界面、转换器集成和数据管理等模块。

推荐定期查看项目CHANGELOG.md获取更新信息，或参与GitHub Discussions与社区交流使用经验。

如果觉得这个项目对你有帮助，请给项目一个Star支持开发者！

提示：本文档基于ConvertX v0.14.1版本编写，不同版本间可能存在差异，请以官方文档为准。