ConvertX 安装:Ubuntu 22.04 源码直装与 systemd 服务化

实测基线:ConvertX v0.19.0 + Ubuntu 22.04.5 LTS + Bun 1.4.2,2026-10-28 真机逐条执行。产品定位与选型背景见《ConvertX 认知选型:自托管万能文件转换器的定位、引擎与替代方案》。

ConvertX 官方以预构建打包运行时为主要交付形态,但对希望掌控运行路径的运维场景,源码直装是更干净的路线:项目本身就是一个标准的 Bun 应用,直装后用 systemd 托管,升级与排障都在明面上。本文记录 v0.19.0 在 Ubuntu 22.04 上从零到可用的完整过程,包括两处必踩的依赖排障。

一、前置条件

项	要求	说明
操作系统	Ubuntu 22.04 LTS(实测 22.04.5)	其他 Debian 系版本同理,包名偶有差异
硬件	2 核 / 2GB 内存 / 5GB+ 磁盘	转换后端全家桶约 1.5GB 磁盘;服务进程常驻内存实测约 55MB
网络	可访问 github.com 与 npm registry	Bun 拉取依赖;内网环境配置代理后等价
端口	8149(本文约定)	任意未占用端口,由 `PORT` 环境变量指定

先确认系统版本与端口空闲:

cat /etc/os-release | head -2
ss -ltn | grep 8149 || echo "8149 free"

实测回显:

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
8149 free

二、安装系统依赖与转换后端

ConvertX 的转换能力来自命令行后端,按需安装即可。以下清单覆盖图像(ImageMagick/GraphicsMagick/Vips)、音视频(FFmpeg)、文档(Pandoc/XeLaTeX/LibreOffice/Poppler)、电子书(Calibre)、矢量(Inkscape/Potrace)等主航道,与官方构建脚本中的依赖清单对齐(按 Ubuntu 22.04 的包名适配):

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
  curl git unzip ca-certificates sqlite3 \
  imagemagick graphicsmagick libvips-tools libheif-examples \
  ffmpeg pandoc poppler-utils potrace ghostscript djvulibre-bin \
  libreoffice calibre inkscape mupdf-tools \
  libemail-address-perl libemail-outlook-message-perl \
  texlive-xetex lmodern texlive-fonts-recommended

实测回显(节选,安装耗时约数分钟,取决于带宽):

Setting up sqlite3 (3.37.2-2ubuntu0.8) ...

装完抽查关键可执行文件:

which convert ffmpeg pandoc ebook-convert soffice xelatex

/usr/bin/convert
/usr/bin/ffmpeg
/usr/bin/pandoc
/usr/bin/ebook-convert
/usr/bin/soffice
/usr/bin/xelatex

注意:Ubuntu 22.04 仓库的 ImageMagick 是 6.9 系列,命令为 convert;ConvertX v0.19.0 调用的是 ImageMagick 7 的 magick 命令,这一差异会在首次图片转换时暴露,排障见第六节。

三、安装 Bun 运行时

ConvertX v0.19.0 的构建脚本锁定 Bun 1.4.2,直装建议保持同一版本:

curl -fsSL -o /tmp/bun-linux-x64-baseline.zip \
  https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64-baseline.zip
unzip -j -o /tmp/bun-linux-x64-baseline.zip -d /usr/local/bin
chmod +x /usr/local/bin/bun
bun --version

1.4.2

四、获取源码并构建

git clone --depth 1 --branch v0.19.0 https://github.com/C4illin/ConvertX /opt/convertx
cd /opt/convertx
git log --oneline -1

710bc7c chore: prepare for release

安装依赖(全量安装,构建阶段需要 devDependencies 里的 Tailwind CLI 与 TypeScript 编译器):

bun install --frozen-lockfile

242 packages installed [1.52s]

构建产物:先由 Tailwind 生成站点样式 public/generated.css,再由 tsc 编译出运行入口 dist/src/index.js:

bun run build

$ bun x @tailwindcss/cli -i ./src/main.css -o ./public/generated.css && bun run build:js
≈ tailwindcss v4.3.3

Done in 55ms
$ tsc

构建完成后确认两份产物存在:

ls -la public/generated.css dist/src/index.js

-rw-r--r-- 1 root root 20982 Oct 28 04:29 public/generated.css
-rw-r--r-- 1 root root   9549 Oct 28 04:29 dist/src/index.js

五、专用用户与 systemd 服务化

5.1 创建专用用户与数据目录

groupadd -g 1000 convertx
useradd -u 1000 -g convertx -d /opt/convertx -s /usr/sbin/nologin convertx
mkdir -p /opt/convertx/data
chown -R convertx:convertx /opt/convertx
id convertx

uid=1000(convertx) gid=1000(convertx) groups=1000(convertx)

5.2 生成 JWT 签名密钥

openssl rand -hex 32

19fa2a8fbbb6ae2c6c829aba6e98a4e1c2859c828965c927543876cc153d7756

上面的值是本次实测实例的示例密钥,你的环境必须现场重新生成,且轮换后所有登录会话失效。

5.3 编写 systemd 单元

/etc/systemd/system/convertx.service:

[Unit]
Description=ConvertX - Self-hosted online file converter
After=network.target

[Service]
Type=simple
User=convertx
Group=convertx
WorkingDirectory=/opt/convertx
Environment=PORT=8149
Environment=JWT_SECRET=19fa2a8fbbb6ae2c6c829aba6e98a4e1c2859c828965c927543876cc153d7756
Environment=HTTP_ALLOWED=true
ExecStart=/usr/local/bin/bun run dist/src/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

HTTP_ALLOWED=true 仅建议在内网明文访问场景开启;若已配置反向代理提供 HTTPS,应删除该行(默认 false 时登录 Cookie 携带 Secure 标志,明文 HTTP 无法维持会话)。参数详解见《ConvertX 配置:环境变量全参数详解与逐项生效验证》。

5.4 启动与自启

systemctl daemon-reload
systemctl enable --now convertx

Created symlink /etc/systemd/system/multi-user.target.wants/convertx.service → /etc/systemd/system/convertx.service.

systemctl is-active convertx
ss -ltnp | grep 8149

active
LISTEN 0      512                *:8149             *:*

服务状态详情:

systemctl status convertx --no-pager -l | head -10

● convertx.service - ConvertX - Self-hosted online file converter
     Loaded: loaded (/etc/systemd/system/convertx.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 04:32:46 UTC; 6s ago
   Main PID: 10426 (bun)
      Tasks: 24 (limit: 2932)
     Memory: 54.8M
        CPU: 351ms
     CGroup: /system.slice/convertx.service
             └─10426 /usr/local/bin/bun run dist/src/index.js

Oct 28 04:32:46 convertx systemd[1]: Started ConvertX - Self-hosted online file converter.

启动日志同时会打印版本横幅(来自 journalctl):

Oct 28 04:32:46 convertx bun[10426]: ConvertX v0.19.0
Oct 28 04:32:46 convertx bun[10426]: 🦊 Elysia is running at http://localhost:8149

5.5 防火墙放行(如启用 ufw)

ufw allow 8149/tcp

六、排障实录(直装必读)

6.1 图片转换报 `Executable not found in $PATH: "magick"`

现象:Web 界面上传 PNG 转 JPG,任务失败,服务日志出现:

Oct 28 04:36:48 convertx bun[10426]: Failed to convert ./data/uploads/1/2/test.png from png to jpeg using imagemagick. error: Error: Executable not found in $PATH: "magick"

原因:ConvertX v0.19.0 的 ImageMagick 适配层调用 ImageMagick 7 的统一入口 magick,而 Ubuntu 22.04 仓库的 ImageMagick 6.9 只提供 convert 命令。

处置:为 magick 建立指向 convert 的符号链接(常规格式互转两者 CLI 兼容):

ln -sf /usr/bin/convert /usr/local/bin/magick
magick --version | head -1

Version: ImageMagick 6.9.11-60 Q16 x86_64 2021-01-25 https://imagemagick.org

修复后重新发起转换即成功。若对 IM7 特性有硬需求,则需从上游源码自建 ImageMagick 7,代价明显高于符号链接方案。

6.2 Markdown 转 PDF 报 `xelatex not found`

现象:md → pdf 任务失败,日志:

Oct 28 04:37:33 convertx bun[10426]: stderr: xelatex not found. Please select a different --pdf-engine or install xelatex -- see also /usr/share/doc/pandoc/README.Debian
Oct 28 04:37:33 convertx bun[10426]: Failed to convert ./data/uploads/1/4/doc.md from markdown to pdf using pandoc. error: Error: Command failed: pandoc --pdf-engine=xelatex ./data/uploads/1/4/doc.md -f markdown -t pdf -o ./data/output/1/4/doc.pdf

原因:ConvertX 的 Pandoc 转 PDF 硬编码使用 XeLaTeX 引擎,未安装 TeX Live XeTeX 时必然失败。

处置:

DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
  texlive-xetex lmodern texlive-fonts-recommended

安装后重试,日志确认成功:

Oct 28 04:49:16 convertx bun[14428]: Converted ./data/uploads/1/27/doc.md from markdown to pdf successfully using pandoc. Done

6.3 数据目录权限不足导致库打不开(官方提示)

官方 README 明确提示:若映射的数据目录属主与应用运行身份不一致,会出现 unable to open database file,需要 chown -R $USER:$USER 数据目录。直装场景对应:

chown -R convertx:convertx /opt/convertx/data

七、首次初始化与功能验收

7.1 健康检查与首次注册

ConvertX 内置免认证健康检查端点:

curl -s http://127.0.0.1:8149/healthcheck

{"status":"ok"}

浏览器打开 http://<服务器IP>:8149/,首次访问会被引导到 /setup 初始化页;用命令行等价操作如下(首个注册的账号即管理员,之后注册入口默认关闭):

curl -s -c /tmp/cx.jar -o /dev/null http://127.0.0.1:8149/
curl -s -b /tmp/cx.jar -c /tmp/cx.jar -o /dev/null -w '%{http_code} -> %{redirect_url}\n' \
  -X POST -d 'email=admin@example.com&password=q1w2e3r4' \
  http://127.0.0.1:8149/register

302 -> http://127.0.0.1:8149/

重复注册在注册关闭后会被拒绝(302 跳回登录页),这正是首个账号安全的体现——官方 README 特别警告:不要在未配置且公开可访问的状态下搁置首注册流程,任何人都可以抢注首个账号。

7.2 四类转换验收(命令行全流程)

登录并创建任务上下文(首页会签发 jobId Cookie):

rm -f /tmp/cx.jar
curl -s -c /tmp/cx.jar -o /dev/null -X POST \
  -d 'email=admin@example.com&password=q1w2e3r4' \
  http://127.0.0.1:8149/login
curl -s -b /tmp/cx.jar -c /tmp/cx.jar -o /dev/null http://127.0.0.1:8149/

生成测试文件并批量验收(图片/文档/视频/电子书各一):

convert -size 200x100 gradient:blue-red /tmp/test.png
printf '# Hello ConvertX\n\nThis is a **markdown** test file.\n' > /tmp/doc.md
ffmpeg -y -loglevel error -f lavfi -i testsrc=duration=2:size=320x240:rate=10 /tmp/clip.mp4
printf 'Chapter One\nSample book text for ConvertX epub conversion test.\n' > /tmp/book.txt

逐个上传并触发转换(convert_to 的格式为"目标格式,引擎名"):

curl -s -b /tmp/cx.jar -c /tmp/cx.jar -o /dev/null -w 'upload png: %{http_code}\n' \
  -F 'file=@/tmp/test.png' http://127.0.0.1:8149/upload
curl -s -b /tmp/cx.jar -c /tmp/cx.jar -o /dev/null -w 'convert png: %{http_code} -> %{redirect_url}\n' \
  -d 'convert_to=jpg,imagemagick' --data-urlencode 'file_names=["test.png"]' \
  http://127.0.0.1:8149/convert

upload png: 200
convert png: 302 -> http://127.0.0.1:8149/results/3

其余三组同理,目标参数分别为 pdf,pandoc、gif,ffmpeg、epub,calibre。完成后核验输出:

find /opt/convertx/data/output -type f

/opt/convertx/data/output/1/3/test.jpg
/opt/convertx/data/output/1/4/doc.pdf
/opt/convertx/data/output/1/5/clip.gif
/opt/convertx/data/output/1/6/book.epub

identify $(find /opt/convertx/data/output -name 'test.jpg' | head -1)

/opt/convertx/data/output/1/3/test.jpg JPEG 200x100 200x100+0+0 8-bit sRGB 1513B 0.000u 0:00.000

四类任务全部落盘,直装验收完成。日常命令与服务运维见《ConvertX 命令运维:服务管理、格式转换与备份恢复》。

八、升级方法

ConvertX 的直装升级是"换源码、重建产物、重启服务"三步:

cd /opt/convertx
systemctl stop convertx
git fetch --tags && git checkout v0.20.0   # 以目标版本为准
bun install --frozen-lockfile
bun run build
chown -R convertx:convertx /opt/convertx
systemctl start convertx

ConvertX 安装:Ubuntu 22.04 源码直装与 systemd 服务化

ConvertX 安装:Ubuntu 22.04 源码直装与 systemd 服务化

一、前置条件

二、安装系统依赖与转换后端

三、安装 Bun 运行时

四、获取源码并构建

五、专用用户与 systemd 服务化

5.1 创建专用用户与数据目录

5.2 生成 JWT 签名密钥

5.3 编写 systemd 单元

5.4 启动与自启

5.5 防火墙放行(如启用 ufw)

六、排障实录(直装必读)

6.1 图片转换报 Executable not found in $PATH: "magick"

6.2 Markdown 转 PDF 报 xelatex not found

6.3 数据目录权限不足导致库打不开(官方提示)

七、首次初始化与功能验收

7.1 健康检查与首次注册

7.2 四类转换验收(命令行全流程)

八、升级方法

6.1 图片转换报 `Executable not found in $PATH: "magick"`

6.2 Markdown 转 PDF 报 `xelatex not found`