ConvertX 配置:环境变量全参数详解与逐项生效验证
ConvertX v0.19.0 全部 16 个环境变量参数表与 systemd 注入方式,11 项参数真机逐项生效验证(PORT/JWT_SECRET/HTTP_ALLOWED/WEBROOT/BRANDING/AUTO_DELETE 等),含 drop-in 语法排障与三档安全基线建议。
ConvertX 配置:环境变量全参数详解与逐项生效验证
实测基线:ConvertX v0.19.0 + Ubuntu 22.04.5 LTS + systemd 托管,2026-10-28 真机逐项验证。安装路径见 《ConvertX 安装:Ubuntu 22.04 源码直装与 systemd 服务化》,选型背景见 《ConvertX 认知选型:自托管万能文件转换器的定位、引擎与替代方案》。
ConvertX 的全部行为开关都收敛在环境变量里,没有配置文件。直装形态下,这些变量由 systemd 单元的 Environment= 行注入;官方打包运行时形态另有 PUID/PGID/UMASK 三个进程身份变量(由启动入口脚本消费,直装不适用)。本文对 v0.19.0 的 16 个参数逐一说明默认值与行为,并对其中 11 个做了"修改 → 重启 → 观测"的真机生效验证。
一、配置机制与生效方式
源码 src/helpers/env.ts 集中读取环境变量,服务启动时一次性加载,src/index.tsx 以 app.listen(process.env.PORT || 3000) 监听端口——任何配置变更都需要重启服务进程才生效:
systemctl restart convertx
systemd 注入有两种写法。直接编辑单元文件:
/etc/systemd/system/convertx.service
Environment=PORT=8149
Environment=JWT_SECRET=<openssl rand -hex 32 生成的值>
或者用 drop-in(不动主文件,便于版本化管理):
mkdir -p /etc/systemd/system/convertx.service.d
printf '[Service]\nEnvironment=HTTP_ALLOWED=true\nEnvironment=LANGUAGE=zh\n' \
> /etc/systemd/system/convertx.service.d/override.conf
systemctl daemon-reload && systemctl restart convertx
核对注入结果:
systemctl show convertx -p Environment
Environment=PORT=8149 JWT_SECRET=19fa2a8fbbb6ae2c6c829aba6e98a4e1c2859c828965c927543876cc153d7756 HTTP_ALLOWED=true
排障提示:drop-in 的
Environment=每行只能写一个KEY=VALUE。实测中若把多行值塞进一行printf模板,第二行会丢失Environment=前缀而被 systemd 静默忽略——变量没生效时先cat override.conf逐行检查。
二、参数总表(v0.19.0)
| 变量 | 默认值 | 作用 | 验证方式 |
|---|---|---|---|
| PORT | 3000 | 服务监听端口 | 真机实测 |
| JWT_SECRET | 未设置时用 randomUUID() 随机值 | JWT 登录态签名密钥 | 真机实测 |
| HTTP_ALLOWED | false | 允许明文 HTTP 访问(影响 Cookie Secure 标志) | 真机实测 |
| ACCOUNT_REGISTRATION | false | 允许注册新账号 | 真机实测 |
| ALLOW_UNAUTHENTICATED | false | 允许未登录访客使用 | 真机实测 |
| AUTO_DELETE_EVERY_N_HOURS | 24 | 按 N 小时清理过期任务文件与记录,0=禁用 | 真机实测 |
| WEBROOT | 空(根路径) | 子路径发布前缀,如 /convert | 真机实测 |
| BRANDING | ConvertX | 站点显示名(≤26 字符) | 真机实测 |
| HIDE_HISTORY | false | 隐藏历史页 | 真机实测 |
| LANGUAGE | en | 日期/时间格式化的 BCP 47 语言标签 | 真机实测 |
| FFMPEG_OUTPUT_ARGS | 空 | FFmpeg 输出侧附加参数 | 真机实测(负向) |
| FFMPEG_ARGS | 空 | FFmpeg 输入侧附加参数(如硬件加速) | 源码级确认 |
| MAX_CONVERT_PROCESS | 0(不限) | 转换并发分块大小 | 源码级确认 |
| UNAUTHENTICATED_USER_SHARING | false | 未登录访客共享同一身份(用户 0) | 源码级确认 |
| TZ | 未设置 | 历史页时间显示时区 | 源码级确认 |
| PUID / PGID / UMASK | 0(root)/ PUID / 002 | 进程运行身份与权限掩码 | 打包运行时专属 |
布尔型变量的解析规则统一为"字符串小写后等于 true 才为真"(env.ts),写成 TRUE、True 也能命中,但写成 1、yes 无效。
三、逐项生效验证实录
以下每项均为"修改环境变量 → systemctl daemon-reload && systemctl restart convertx → 请求观测"的真实过程,验证脚本使用 drop-in 方式改写配置。
3.1 PORT:监听端口
设置 PORT=8148 重启后:
ss -ltn | grep -E ':(8148|8149)'
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8148/healthcheck
LISTEN 0 512 *:8148 *:*
200
恢复 PORT=8149 后监听回到 8149。结论:端口完全由环境变量决定,无其他来源。
3.2 JWT_SECRET:轮换即全端下线
流程:轮换前用旧密钥登录拿到的 Cookie 存入 jar → 轮换密钥并重启 → 携带旧 Cookie 访问首页:
old-token(after restore) GET /: 302 -> http://127.0.0.1:8149/login
旧 JWT 验签失败,应用清除 Cookie 并跳转登录页。含义:轮换 JWT_SECRET 等价于强制全端登出,用户需要重新登录,数据不受影响。未设置时每次启动用 randomUUID() 生成随机密钥——这意味着每次重启都会踢掉全部会话,生产环境必须显式设置。
3.3 HTTP_ALLOWED:明文 HTTP 与 Cookie Secure
设置 HTTP_ALLOWED=false 后,从非本机地址(实测以同网段另一地址 10.89.73.2 模拟外部客户端,生产对应服务器 IP)登录,观察 Cookie 标志与后续请求:
cookie jar: auth ... secure flag: TRUE
GET / via 10.89.73.2: 302 -> http://10.89.73.2:8149/login
Cookie 被打上 Secure 标志,明文 HTTP 请求不再回传,服务端视为未登录。两个实务细节:
- 本机回环(127.0.0.1/localhost)访问不受影响——现代 HTTP 客户端把回环地址视为安全上下文,实测 127.0.0.1 下即使
HTTP_ALLOWED=false登录会话依然可用,这也是官方 README 提示"确认你是通过 localhost 或 https 访问,否则设置 HTTP_ALLOWED=true"的技术根源; - 已发出去的 Secure Cookie 会一直保留该标志,即便随后改回
HTTP_ALLOWED=true,旧会话在明文地址上依旧失效,需要重新登录。
3.4 ACCOUNT_REGISTRATION:注册开关
curl -s -o /dev/null -w '%{http_code}\n' -H 'Accept: text/html' http://127.0.0.1:8149/register
true 时:200
恢复 false 后:302 -> http://127.0.0.1:8149/login
首个账号始终可以通过"首次运行"流程创建(与该开关无关),开关只影响后续注册。官方安全提示:任何情况下都不应将开启注册的服务暴露到不可信网络。
3.5 ALLOW_UNAUTHENTICATED:免登录访客模式
设置 true 后,不带任何 Cookie 请求首页:
no-cookie GET /: 200
应用为访客自动签发临时身份并直接进入转换界面。配合 UNAUTHENTICATED_USER_SHARING=false(默认),每个访客获得独立随机身份;设为 true 时全部访客共享固定身份"用户 0"——历史与文件互通,内网全信任场景才考虑。
3.6 WEBROOT:子路径发布
设置 WEBROOT=/convert 后:
GET /convert/healthcheck: 200
GET /healthcheck: 404
全部路由(含健康检查、静态资源)迁移到子路径,反向代理按 /convert/ 前缀转发即可。注意根路径访问返回 404 属预期,日志中会留下 404: GET / 的提示。
3.7 BRANDING:站点显示名
设置 BRANDING=FileForge 后,登录页 HTML 中出现 1 处 "FileForge"(原标题 ConvertX 位置)。该名称同时出现在页面标题与导航栏,长度上限 26 字符。
3.8 HIDE_HISTORY:隐藏历史页
设置 HIDE_HISTORY=true 后,已登录用户访问历史页:
GET /history: 302 -> http://127.0.0.1:8149/
历史入口被重定向回首页,导航中不再展示。
3.9 AUTO_DELETE_EVERY_N_HOURS:过期自动清理
验证思路:服务启动时会立即执行一轮清理(源码 index.tsx 中 if (AUTO_DELETE_EVERY_N_HOURS > 0) clearJobs()),把历史任务的时间戳回拨到阈值之外,重启服务即可观测。设置 AUTO_DELETE_EVERY_N_HOURS=1,将 job 3/5/6 的 date_created 改写为 2026-10-27(超过 1 小时),重启:
ls /opt/convertx/data/output/1/
1
15
16
17
2
4
目录 3、5、6 及对应记录被删除,其余保留。三个要点:
- 清理对象同时包括输出目录、上传目录与 jobs 表记录;
- 值为 0 完全禁用(启动时不再触发清理循环);
- 清理循环的再次执行间隔等于 N 小时,运行期内不会重复扫描。
3.10 FFMPEG_OUTPUT_ARGS:输出侧参数注入(负向验证)
正常值(如 -preset veryfast -threads 2)的效果难以从外部观测,采用负向验证——注入一个非法参数:
Environment=FFMPEG_OUTPUT_ARGS=-bogusopt
再触发一次 mp4 → gif,转换失败,服务日志直接暴露了参数拼接位置:
Oct 28 04:47:43 convertx bun[13973]: Unrecognized option 'bogusopt'.
Oct 28 04:47:43 convertx bun[13973]: Failed to convert ./data/uploads/1/20/c3.mp4 from mp4 to gif using ffmpeg. error: Error: Command failed: ffmpeg -i ./data/uploads/1/20/c3.mp4 -bogusopt ./data/output/1/20/c3.gif
可以看到 FFMPEG_OUTPUT_ARGS 被原样拼在输出文件之前(输入文件之后);FFMPEG_ARGS 则位于输入侧。多个参数以空格分隔,由源码 split(/\s+/) 切分。恢复后同文件转换成功:
Oct 28 04:46:58 convertx bun[13717]: Converted ./data/uploads/1/17/c2.mp4 from mp4 to gif successfully using ffmpeg. Done
典型用途:GPU 硬件加速(FFMPEG_ARGS=-hwaccel vaapi)与输出压缩档位控制。
3.11 LANGUAGE:时间本地化格式
LANGUAGE 作用于历史页时间渲染(源码使用 toLocaleTimeString(LANGUAGE, ...))。同一时间戳,LANGUAGE=zh 与 LANGUAGE=en 的实测渲染:
LANGUAGE=zh: 04:47:43
LANGUAGE=en: 4:47:43 AM
值应为 BCP 47 语言标签;无效值回落到运行时默认行为。
四、源码级确认的参数
以下三项的行为来自 v0.19.0 源码阅读,未做外部观测(外部表现与文件数量、访客时区相关,不适合单点验证):
- MAX_CONVERT_PROCESS(默认 0):转换任务把文件列表按该值分块串行推进,块内并发。0 表示单块全并发;设为 1 即逐文件串行,适合给弱机器降压;
- TZ:传递给
toLocaleTimeString的时区选项,影响历史页时间显示,不影响存储(时间戳一律 ISO UTC 入库); - UNAUTHENTICATED_USER_SHARING:见 3.5 节说明。
五、打包运行时专属:PUID / PGID / UMASK
官方打包运行时的启动入口支持以非 root 身份运行转换进程(先以 root 修正数据目录属主,再降权执行):PUID/PGID 指定目标 UID/GID(默认 0=root),UMASK 默认 002。直装形态下这三者不生效——进程身份由 systemd 的 User=/Group= 决定,权限掩码如需控制可在单元中加 UMask=002。v0.19.0 的更新说明亦建议打包形态用户显式设置 PUID=1000 以避免文件属主问题。
六、安全基线建议
结合逐项验证结果,给出三档推荐组合:
| 场景 | 推荐配置 |
|---|---|
| 内网明文(家庭内网/NAS) | HTTP_ALLOWED=true + 显式 JWT_SECRET + 注册关闭 + ALLOW_UNAUTHENTICATED=false |
| 反向代理 HTTPS | 删除 HTTP_ALLOWED(默认 false)+ 显式 JWT_SECRET + 可按需开 WEBROOT 子路径 |
| 公网可达 | 必须前置 HTTPS;ACCOUNT_REGISTRATION=false、ALLOW_UNAUTHENTICATED=false 双关闭;JWT_SECRET 定期轮换(代价是全员重登) |
无论哪档,都建议保持 AUTO_DELETE_EVERY_N_HOURS 默认值(或按合规要求调小),避免转换产物在服务器上无限堆积;涉及敏感文件的环境可设为 0 关闭自动清理、改由运维定时巡检,但需要自行评估磁盘与数据残留风险。
七、验证矩阵小结
| 参数 | 验证结论 | 关键观测 |
|---|---|---|
| PORT | 生效 | 监听随环境变量切换 8149↔8148 |
| JWT_SECRET | 生效 | 轮换后旧会话 302 下线 |
| HTTP_ALLOWED | 生效 | false 时 Cookie 带 Secure,明文 IP 访问 302 |
| ACCOUNT_REGISTRATION | 生效 | true→注册页 200,false→302 |
| ALLOW_UNAUTHENTICATED | 生效 | true→无 Cookie 访问首页 200 |
| WEBROOT | 生效 | /convert 前缀全路由迁移 |
| BRANDING | 生效 | 页面显示名替换 |
| HIDE_HISTORY | 生效 | /history 302 回首页 |
| AUTO_DELETE_EVERY_N_HOURS | 生效 | 过期任务目录与记录被清 |
| FFMPEG_OUTPUT_ARGS | 生效 | 非法参数致 ffmpeg 失败并回显拼接位置 |
| LANGUAGE | 生效 | zh 24 小时制 / en 12 小时制 |
全部 11 项外部可观测参数验证通过,3 项源码级确认,3 项打包运行时专属(N/A)。日常巡检中若怀疑配置未生效,按"drop-in 逐行检查 → systemctl show convertx -p Environment → systemctl restart"三步走即可定位。
变更后的例行巡检、数据备份与恢复实操,见《ConvertX 命令运维:服务管理、格式转换与备份恢复》。