Jellyfin 12.4 常用 CLI 命令详解

目标：汇总 Jellyfin 12.4 在 Ubuntu 服务器上的命令行日常——systemd 服务管理、jellyfin 主程序参数逐项释义（--help 全文实测）、jellyfin-ffmpeg 媒体探测与直转、包版本核查与日志诊断；全部命令与回显均在 Ubuntu 22.04 + jellyfin 12.4+ubu2204 实测照抄。

一、环境信息

操作系统：Ubuntu 22.04
软件包（dpkg -l 实查）：

jellyfin 12.4+ubu2204
jellyfin-ffmpeg8 8.1.3-1-jammy
jellyfin-server 12.4+ubu2204
jellyfin-web 12.4+ubu2204

服务进程：/usr/bin/jellyfin，由 systemd 托管（active (running)）
配置目录：/etc/jellyfin；数据目录：/var/lib/jellyfin；日志目录：/var/log/jellyfin；缓存目录：/var/cache/jellyfin
服务环境文件：/etc/default/jellyfin
演示账号：admin / q1w2e3r4

二、前置条件

root 或 sudo 权限（服务管理与改 /etc 下文件都需要）；
主程序在 PATH 中（实查）：

which jellyfin

实测回显：

/usr/bin/jellyfin

服务已由 systemd 托管——systemctl status jellyfin 为 active (running)（见 3.1 节）；未安装时先按发行包流程安装（本专栏部署指南篇给出完整流程）。

三、服务管理命令（systemd）

3.1 状态查看

systemctl status jellyfin --no-pager

实测回显：

● jellyfin.service - Jellyfin Media Server
     Loaded: loaded (/lib/systemd/system/jellyfin.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/jellyfin.service.d
             └─jellyfin.service.conf
     Active: active (running) since Tue 2026-10-27 00:42:39 UTC; 53min ago
   Main PID: 3839 (jellyfin)
      Tasks: 18 (limit: 21153)
     Memory: 86.5M
        CPU: 5.884s
     CGroup: /system.slice/jellyfin.service
             └─3839 /usr/bin/jellyfin --webdir=/usr/share/jellyfin/web --ffmpeg=/usr/lib/jellyfin-ffmpeg/ffmpeg

Oct 27 00:42:39 HOSTNAME systemd[1]: Started Jellyfin Media Server.

信息量最大的两行：Active 行看运行状态与已运行时长；CGroup 行是服务进程的真实启动命令行——--webdir 与 --ffmpeg 两个参数由 /etc/default/jellyfin 注入（见 4.3 节）。

3.2 启动、停止与重启

systemctl stop jellyfin       # 停止服务
systemctl start jellyfin      # 启动服务
systemctl restart jellyfin    # 重启服务（改完配置文件后用）

三个命令均无回显。重启后用 journalctl 确认（-o cat 只输出消息正文，去掉主机名与时间戳前缀）：

systemctl restart jellyfin && journalctl -u jellyfin -n 2 --no-pager -o cat

实测回显：

jellyfin.service: Consumed 6.014s CPU time.
Started Jellyfin Media Server.

3.3 开机自启

systemctl is-enabled jellyfin   # 查询自启状态
systemctl enable jellyfin       # 设为开机自启
systemctl disable jellyfin      # 取消开机自启

is-enabled 实测回显：

enabled

发行包安装时默认已 enable；重复执行 enable 无副作用（幂等，无额外输出）。

3.4 服务日志（journalctl）

journalctl -u jellyfin -n 5 --no-pager -o cat   # 最近 5 条启动相关日志

实测回显（重启场景）：

Stopped Jellyfin Media Server.
jellyfin.service: Consumed 5.470s CPU time.
Started Jellyfin Media Server.

systemd 层日志只记录「起了/停了」；业务日志（元数据扫描、转码、API 错误）看 7.2 节的应用日志文件。

四、jellyfin 主程序参数详解

4.1 版本与帮助

jellyfin --version

实测回显：

Jellyfin.Server 12.4.0.0

jellyfin --help

4.2 --help 全文实测

jellyfin --help 完整回显（12.4.0.0 实测原文）：

Jellyfin.Server 12.4.0.0
Copyright ©  2019 Jellyfin Contributors. Code released under the GNU General Public License

  -d, --datadir             Path to use for the data folder (database files,
                            etc.).

  --nowebclient             Indicates that the web server should not host the
                            web client.

  -w, --webdir              Path to the Jellyfin web UI resources.

  -C, --cachedir            Path to use for caching.

  -c, --configdir           Path to use for configuration data (user settings
                            and pictures).

  -l, --logdir              Path to use for writing log files.

  --ffmpeg                  Path to external FFmpeg executable to use in place
                            of default found in PATH.

  --service                 Run as headless service.

  --package-name            Used when packaging Jellyfin (example, synology).

  --published-server-url    Jellyfin Server URL to publish via auto discover
                            process

  --nonetchange             Indicates that the server should not detect network
                            status change.

  --restore-archive         Path to a Jellyfin backup archive to restore from

  --mode                    Mode which selects what action the jellyfin server
                            should perform when started.

  --help                    Display this help screen.

  --version                 Display version information.

12.4 的命令行面非常克制：只有目录、ffmpeg 路径与运行模式，业务配置（端口、语言、转码参数等）全部走 XML 配置文件与管理台，命令行不承载业务开关。

4.3 参数逐项释义（含 deb 包实测默认值）

参数	语义	deb 安装的默认值（实测）
`-d, --datadir`	数据目录（数据库文件等）	`/var/lib/jellyfin`
`-c, --configdir`	配置目录（用户设置与图片）	`/etc/jellyfin`
`-l, --logdir`	日志目录	`/var/log/jellyfin`
`-C, --cachedir`	缓存目录	`/var/cache/jellyfin`
`-w, --webdir`	Web UI 资源目录	`/usr/share/jellyfin/web`
`--ffmpeg`	指定 ffmpeg 可执行文件路径	`/usr/lib/jellyfin-ffmpeg/ffmpeg`
`--nowebclient`	服务端不托管 Web 客户端（纯 API 模式）	默认托管
`--service`	以无头服务模式运行（systemd 场景）	systemd 单元已带
`--package-name`	打包标识（如 synology）	空
`--published-server-url`	自动发现时广播的服务器 URL（反代场景）	空
`--nonetchange`	不监听网络状态变化事件	默认监听
`--restore-archive`	从 Jellyfin 备份归档恢复（接归档路径）	空
`--mode`	选择启动时执行的动作模式	默认正常启动

目录类默认值不是写死在代码里，而是由 systemd 单元从 /etc/default/jellyfin 注入（实测文件内容节选）：

JELLYFIN_DATA_DIR="/var/lib/jellyfin"
JELLYFIN_CONFIG_DIR="/etc/jellyfin"
JELLYFIN_LOG_DIR="/var/log/jellyfin"
JELLYFIN_CACHE_DIR="/var/cache/jellyfin"
JELLYFIN_WEB_OPT="--webdir=/usr/share/jellyfin/web"
JELLYFIN_FFMPEG_OPT="--ffmpeg=/usr/lib/jellyfin-ffmpeg/ffmpeg"

改默认目录位置就改这个环境文件（改完 systemctl restart jellyfin），不要动 /lib/systemd/system/jellyfin.service 单元文件本身。3.1 节 CGroup 行显示的进程命令行 --webdir=/usr/share/jellyfin/web --ffmpeg=/usr/lib/jellyfin-ffmpeg/ffmpeg 正是这两个 _OPT 变量拼装出来的。

4.4 自定义目录前台运行实测

命令行参数最实用的场景是「临时拉起一台独立实例」（如验证备份归档、测试新数据目录）。实测用自定义目录前台运行：

mkdir -p /tmp/jf-cfg /tmp/jf-data /tmp/jf-cache /tmp/jf-log
jellyfin -c /tmp/jf-cfg -d /tmp/jf-data -C /tmp/jf-cache -l /tmp/jf-log

实例会立刻在新目录生成初始结构（ls /tmp/jf-cfg /tmp/jf-data 实测）：

/tmp/jf-cfg/:
logging.default.json
system.xml

/tmp/jf-data/:
data
metadata
plugins
root

⚠️ 注意：系统里已有 systemd 实例运行时，这台前台实例起不来——它同样要绑 8096 端口，实测报错（FAQ 8.1 有原文与解法）。端口不归命令行参数管，要走服务器「网络」设置；所以临时实例先停用 systemd 服务，或用没装服务的验证机。

五、媒体探测与直转 CLI（jellyfin-ffmpeg）

5.1 工具位置与版本

发行包自带定制构建的 ffmpeg 套件，不在 PATH 里，固定在 /usr/lib/jellyfin-ffmpeg/：

/usr/lib/jellyfin-ffmpeg/ffmpeg -version | head -2

实测回显：

ffmpeg version 8.1.3-Jellyfin Copyright (c) 2000-2026 the FFmpeg developers
built with gcc 11 (Ubuntu 11.4.0-1ubuntu1~22.04.3)

ffprobe 在同一目录（/usr/lib/jellyfin-ffmpeg/ffprobe）。

5.2 ffprobe 探测媒体流

排查「某个文件转码失败/扫不进库」时，第一步用 ffprobe 看真实流参数。用 ffmpeg 自造一个测试片段后探测（注意这是测试素材，非真实影片）：

/usr/lib/jellyfin-ffmpeg/ffmpeg -hide_banner -loglevel error -y \
  -f lavfi -i "testsrc2=size=320x180:rate=24" -f lavfi -i "sine=frequency=440:duration=10" \
  -t 10 -c:v libx264 -preset veryfast -crf 28 -pix_fmt yuv420p -c:a aac /tmp/probe-clip.mp4

/usr/lib/jellyfin-ffmpeg/ffprobe -v error \
  -show_entries stream=codec_name,codec_type,width,height -of csv=p=0 /tmp/probe-clip.mp4

实测回显：

h264,video,320,180
aac,audio

两行输出即「视频流 h264 320x180 + 音频流 aac」。-show_entries 换成 stream=codec_name,bit_rate 等键名可按需取字段。

5.3 ffmpeg 命令行直转

不经过 Jellyfin、直接把测试片段转成标准 H.264/AAC（验证编码器可用性、预演服务端转码参数）：

/usr/lib/jellyfin-ffmpeg/ffmpeg -hide_banner -y -i /tmp/probe-clip.mp4 \
  -c:v libx264 -preset veryfast -crf 23 -c:a aac -movflags +faststart /tmp/probe-out.mp4 2>&1 | tail -3

实测回显：

[libx264 @ 0x62445a2ebfc0] Weighted P-Frames: Y:0.0% UV:0.0%
[libx264 @ 0x62445a2ebfc0] kb/s:227.00
[aac @ 0x62445a3e4e40] Qavg: 121.278

确认产物与退出码：

ls -l /tmp/probe-out.mp4
echo $?

实测回显：

-rw-r--r-- 1 root root 380337 Oct 27 01:36 /tmp/probe-out.mp4
0

5.4 CLI 探测与服务端转码的关系

服务端转码调用的就是 5.1 这套 ffmpeg（--ffmpeg 参数所指路径），参数风格与 5.3 完全同源——服务端在一次真实 HLS 转码里生成的命令行为 -codec:v:0 libx264 -preset veryfast -crf 23 -maxrate 500000 …，与 5.3 手工直转的 -c:v libx264 -preset veryfast -crf 23 一一对应。所以：CLI 直转通过 ⇔ 服务端转码引擎健康；CLI 都失败的文件（损坏流、不支持的编码），服务端同样转不动，这使 5.2/5.3 成为「上库前预检」的标准动作。

六、包版本核查与升级命令

dpkg -l | grep jellyfin

实测回显：

ii  jellyfin        12.4+ubu2204  amd64  Jellyfin Media Server
ii  jellyfin-ffmpeg8 8.1.3-1-jammy amd64  FFmpeg for Jellyfin Media Server
ii  jellyfin-server 12.4+ubu2204  amd64  Jellyfin Media Server
ii  jellyfin-web    12.4+ubu2204  amd64  Jellyfin Media Server

查看可升级版本与源：

apt-cache policy jellyfin

实测回显：

jellyfin:
  Installed: 12.4+ubu2204
  Candidate: 12.4+ubu2204
  Version table:
 *** 12.4+ubu2204 500
        500 https://repo.jellyfin.org/ubuntu jammy/main amd64 Packages

升级标准流程（Installed 与 Candidate 不一致时执行）：

apt update
apt install --only-upgrade jellyfin jellyfin-server jellyfin-web
systemctl restart jellyfin
jellyfin --version   # 回读确认新版本号

--only-upgrade 防止误装其他包；升级会保留 /etc/jellyfin 与 /var/lib/jellyfin（数据与配置不随包卸载）。回滚则 apt install jellyfin-server=<旧版本号> 指定版本重装。

七、日志与诊断命令

7.1 日志文件布局

ls /var/log/jellyfin/

实测回显：

jellyfin20261027.log
log_20261027.log

按日滚动的应用日志（jellyfin<日期>.log）；保留天数由 LogFileRetentionDays 参数控制（默认 3 天）。journalctl（3.4 节）与这两份文件互补：systemd 层看生命周期，文件层看业务。

7.2 实时跟踪与错误定位

tail -f /var/log/jellyfin/jellyfin$(date +%Y%m%d).log

定位问题先数错误再取样本：

grep -c '\[ERR\]' /var/log/jellyfin/jellyfin20261027.log

实测回显：

grep '\[ERR\]' /var/log/jellyfin/jellyfin20261027.log | cut -c1-200

实测回显：

[2026-10-27 00:41:51.714 +00:00] [ERR] Error processing request: "Invalid username or password entered". URL "POST" "/Users/AuthenticateByName".

这条实测记录是「客户端密码错误」的典型形态：URL "POST" "/Users/AuthenticateByName" 指明是登录接口，连续大量出现即说明有终端在反复试错密码——结合用户策略里的 InvalidLoginAttemptCount（登录失败上限）与 EnableContentDeletion 等收紧面处理。

7.3 转码问题专用诊断

转码卡壳时按顺序查三处：应用日志里的 TranscodeManager 行（有完整 ffmpeg 命令行与退出码）、/var/cache/jellyfin/temp/transcodes/ 下有无堆积分片、再用 5.2 节的 ffprobe 对源文件做参数预检——三步能把「服务端参数问题」与「源文件本身问题」干净分开。

八、常见问题（FAQ）

8.1 Q1：前台运行 `jellyfin` 报 `Failed to bind to address http://0.0.0.0:8096: address already in use`？

实测异常原文：

System.IO.IOException: Failed to bind to address http://0.0.0.0:8096: address already in use.
 ---> Microsoft.AspNetCore.Connections.AddressInUseException: Address already in use

原因：systemd 服务实例正在运行并占用 8096，前台再拉起同一程序必然撞端口。解法按需求二选一：只是想看服务实时行为→用 journalctl -u jellyfin -f 与 tail -f 应用日志，不要再前台起进程；确需双实例（备份验证等）→先 systemctl stop jellyfin，或者临时实例在「网络」设置里改用其他端口后再同时运行（端口不走命令行参数）。

8.2 Q2：服务能起但一播放就转码失败，说找不到 ffmpeg？

检查两处：/etc/default/jellyfin 里 JELLYFIN_FFMPEG_OPT 是否仍指向 /usr/lib/jellyfin-ffmpeg/ffmpeg（实测值）；3.1 节 status 的 CGroup 行里进程命令行是否带了 --ffmpeg=...。手工编译或第三方 ffmpeg 未带 Jellyfin 补丁集时也会出现「能跑但缺硬件加速」，按 5.1 节 ffmpeg -version 应显示 8.1.3-Jellyfin 版本串，对不上就换回发行包自带的 jellyfin-ffmpeg。

8.3 Q3：想把数据/日志迁到新磁盘？

标准动作四步：systemctl stop jellyfin → mv 旧目录到新位置 → 改 /etc/default/jellyfin 里对应的 JELLYFIN_DATA_DIR/CONFIG_DIR/LOG_DIR/CACHE_DIR → systemctl start jellyfin。重启后用 3.1 节 status 确认进程命令行与目录变化，再验证媒体库列表完整即迁移成功。

8.4 Q4：日志里出现大量 `Invalid username or password entered`？

见 7.2 节实测样本——这是登录接口在报错。先确认是不是自己忘了改密码的旧客户端（一个定时重连的电视盒能刷出很多条）；排除后按「可疑来源」处理：临时改演示账号密码、把用户策略 InvalidLoginAttemptCount 调到 5 并确认该用户 IsAdministrator=false，必要时在防火墙层限制来源 IP。

九、参考链接

官方文档站：https://jellyfin.org/docs/
官方仓库：https://github.com/jellyfin/jellyfin
发行包仓库：https://repo.jellyfin.org/ubuntu
系列阅读：《Jellyfin 12.4 介绍与选型指南》、《Jellyfin 12.4 Docker Compose 部署指南》、《Jellyfin 12.4 配置参数详解》

Jellyfin 12.4 常用 CLI 命令详解

Jellyfin 12.4 常用 CLI 命令详解

一、环境信息

二、前置条件

三、服务管理命令（systemd）

3.1 状态查看

3.2 启动、停止与重启

3.3 开机自启

3.4 服务日志（journalctl）

四、jellyfin 主程序参数详解

4.1 版本与帮助

4.2 --help 全文实测

4.3 参数逐项释义（含 deb 包实测默认值）

4.4 自定义目录前台运行实测

五、媒体探测与直转 CLI（jellyfin-ffmpeg）

5.1 工具位置与版本

5.2 ffprobe 探测媒体流

5.3 ffmpeg 命令行直转

5.4 CLI 探测与服务端转码的关系

六、包版本核查与升级命令

七、日志与诊断命令

7.1 日志文件布局

7.2 实时跟踪与错误定位

7.3 转码问题专用诊断

八、常见问题（FAQ）

8.1 Q1：前台运行 jellyfin 报 Failed to bind to address http://0.0.0.0:8096: address already in use？

8.2 Q2：服务能起但一播放就转码失败，说找不到 ffmpeg？

8.3 Q3：想把数据/日志迁到新磁盘？

8.4 Q4：日志里出现大量 Invalid username or password entered？

九、参考链接

8.1 Q1：前台运行 `jellyfin` 报 `Failed to bind to address http://0.0.0.0:8096: address already in use`？

8.4 Q4：日志里出现大量 `Invalid username or password entered`？