用 ConvertX 搭建私人文件转换入口：Docker 部署、账号限制与结果核对

偶尔收到一个不方便打开的文件，为它装一整套桌面软件不一定划算；把文件传到陌生转换网站，又会增加资料外传的顾虑。ConvertX 可以放在自己管理的服务器上，通过网页选择格式并下载结果，适合可信用户处理一般的文档、图片、音视频和其他受支持文件。

自建并不会让转换过程自动变得可靠。字体缺失、版式变化、音轨丢失、加密文档或损坏文件都可能影响结果。转换成功提示只说明任务得到了输出，文件是否还能满足原用途，需要用相应软件检查。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。

不做任意访客都能上传的公共站

转换文件需要调用多个工具，也可能消耗较多 CPU、内存和磁盘。先限制为自己或可信成员使用，关闭匿名访问和自由注册。不要把公网上传入口当作方便的免费工具直接开放，等资源被占满才去补访问控制。

ConvertX 官方上传与转换界面示例

图中是项目提供的界面示例，用来辨认上传、选择输出和查看任务的区域。可用格式与底层工具有关，具体文件仍需试转换；界面上列出一种输出格式，不等于原文件中的全部信息都能保留。

含有敏感资料时，除了转换工具，还要看服务器管理员、备份、日志和临时文件能接触到什么。文件上传到自己的 VPS，也已经离开本机；真正不能离开设备的数据继续用本地工具处理。

账号和数据目录先准备好

官方镜像使用 /app/data 持久目录，并提供 PUID 和 PGID 处理权限。示例值为 1000，实际部署按宿主用户调整。JWT_SECRET 用于签名登录令牌，生成后持续保存，不每次重建都换一个值。

mkdir -p ~/services/convertx/data
cd ~/services/convertx
umask 077
printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env

保存 compose.yaml：

services:
  convertx:
    image: ghcr.io/c4illin/convertx:latest
    env_file:
      - .env
    environment:
      PUID: "1000"
      PGID: "1000"
      ACCOUNT_REGISTRATION: "false"
      ALLOW_UNAUTHENTICATED: "false"
      AUTO_DELETE_EVERY_N_HOURS: "24"
    ports:
      - "127.0.0.1:3006:3000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

这份配置不启用非 HTTPS 的公网访问。默认最新发行标签用于首次验证，正式使用前记录实际版本或摘要，不采用跟随开发提交的 main 标签承载长期任务。

docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 convertx

如果数据库打不开，检查 data 目录的属主及访问权限。不要删除已有数据反复创建，也别通过开放所有人写权限解决问题。配置中的 UID/GID 要和挂载目录实际可读写的身份对应。

首个账号在私人入口建立

ssh -L 13006:127.0.0.1:3006 user@your-server

本机通过 http://localhost:13006 打开界面，建立首个账号。官方说明特别提示不能把未初始化的服务开放，因为首个账号可能被其他人注册。先完成账号设置和登录测试，再安排正式域名。

正式访问采用 HTTPS，反向代理接到宿主机 3006，核对请求大小和超时。不能登录时，先检查是否使用了 localhost 或 HTTPS，以及浏览器是否能够保存会话；不为了临时绕过问题，在公网长期开启 HTTP_ALLOWED。

退出登录后尝试直接访问上传页面，确认没有匿名上传；另开一个窗口检查自由注册是否关闭。多人使用应有各自账号，新增成员的方式按当前版本管理功能操作，不共享自己的登录凭据。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。

样本要覆盖自己真正会转换的内容

第一次准备小文件：一张带透明区域的图片、一份含中文和表格的文档、一个带声音的短视频。原件先保留，分别转换成预期格式，然后在本机用实际使用的软件打开结果。上传敏感文件之前，先用无敏感内容的样本把流程走通。

文档转换核对标题、分页、表格边界和字体，不只看第一页。图片核对尺寸、透明度和颜色；音视频核对时长、轨道、画面与声音是否对应。压缩和转换可能改变元数据，如果用途依赖拍摄时间或其他属性，也把它列入检查。

文件转换的上传、任务处理与下载核对流程

原件与输出分开保存，下载后再核对使用效果。ConvertX 的任务完成状态不能替代这种检查，尤其文件会交付给别人或继续进入编辑流程时。

遇到失败，保留具体格式、文件大小和任务报错。先用一个更简单的小文件测试，区分格式支持、文件损坏与资源不足。不要在只有一个失败样本时断言整个格式不可用，也不要把一个简单文档的成功推算到复杂排版。

临时文件清理不是立即销毁保证

AUTO_DELETE_EVERY_N_HOURS 控制定期检查和清理达到相应年龄的文件。设为 24，不代表每个文件上传满 24 小时便在同一秒删除；检查周期和实际任务时机需要分开理解。

建立测试任务，观察任务列表与 data 占用，再按自己的保留需求选择周期。已经下载到浏览器、手机或其他备份里的副本，不会因为服务器清理而自动消失。业务资料需要更明确的删除约定时，把这些副本也纳入范围。

先确定要备份什么。账号和应用设置需要恢复，临时转换文件未必值得长期保存。整目录备份可能把临时上传也带走，因此备份的访问权限、保留周期和清理规则不能只看应用里的自动删除设置。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。

上传超时与转换超时要分开排查

反向代理拒绝大文件时，任务可能尚未进入应用；应用处理很久才失败，则是另一条路径。看浏览器报错时间和代理、容器日志，避免一口气把所有限制都改得很大。调高限制前确认磁盘和实际用途。

批量处理先少量开始，观察并发任务、容器资源及临时目录。视频与大型文档的需求差别很大，没有必要把一份图片转换的占用数字写成整套服务的配置保证。与数据库或正式网站同机运行时，注意转换任务是否影响其他服务。

真正经常处理的格式可保留几份不含隐私的回归样本。升级转换器后再跑一次，核对结果与原来的要求是否一致；版本变化可能改变输出，不要只检查登录页面能否打开就结束升级。

保存可以恢复账号的副本

在没有进行中的任务时暂停应用，备份持久数据、Compose 和密钥；文件可能包含上传资料，保护方式应和业务数据一致。

mkdir -p backups
docker compose stop convertx
tar -czf "backups/convertx-$(date +%F-%H%M%S).tar.gz" data .env compose.yaml
docker compose start convertx

转移备份后在独立目录恢复，使用备份对应的镜像。验证账号、登录限制和一份小文件转换，检查临时文件规则还在。不要让测试实例和正式实例共享 data，也不要将含密钥的配置发给普通用户作为使用说明。