Kodi 安装实战（Debian 13 Headless 部署与远程控制）

Kodi 21.2 headless 服务器 0→1 实录：Debian 13 官方仓库在线安装与 449 包离线 dpkg 整包安装双路线（含 Pre-Depends 卡链排障）、Xvfb 虚拟显示 + systemd 双服务托管、首启默认远程关闭的启用流程、Web/JSON-RPC 认证三连验证（401/401/200）、版本选型取证（PPA 停滞 20.2 反落后 Debian 21.2）与卸载清理。

KodiKodi流媒体自托管媒体服务器2026/10/29

Kodi 安装实战（Debian 13 Headless 部署与远程控制）

目标：在一台没有显示器、没有 GPU 的 Linux 服务器上，从零安装 Kodi 21.2 并把它跑成一个可远程管理的媒体中心：apt 在线安装与离线 deb 包安装两条路线、Xvfb 虚拟显示 + systemd 托管、Web/JSON-RPC 远程接口启用与认证验证、媒体库 0→1 初始化入库，全部步骤带真实回显。已在 Debian 13 (trixie) 服务器（Kodi 2:21.2+dfsg-4）实测通过，实测日期 2026-10-28；选型背景见本专栏 《Kodi 介绍与选型指南》，参数逐项详解见本专栏《Kodi 21.2 配置参数详解》。

一、环境信息

  • 操作系统：Debian GNU/Linux 13 (trixie)，x86_64；
  • Kodi 版本：21.2 "Omega"，包版本 2:21.2+dfsg-4（Debian 官方 main 仓库）；
  • 部署形态：headless（无显示器/无 GPU 服务器），Xvfb 虚拟帧缓冲 :99（1280x720x24）供 Kodi 图形界面渲染，systemd 双服务托管；
  • 运行用户：kodi（专用系统用户，主目录 /home/kodi，数据目录 ~/.kodi/）；
  • 远程接口：HTTP Web/JSON-RPC 8080（账号 admin / q1w2e3r4），EventServer UDP 9777（kodi-send 事件推送）；
  • 媒体与备份目录：/srv/media/movies/（媒体）、/srv/backup/（备份）；
  • 安装路线：A=Debian 官方仓库在线安装（主推）、B=离线 deb 包整包安装（断网/内网）。

二、前置条件

  • 一台 x86_64 服务器，Debian 13 已联网（方案 B 不需要），root 权限；
  • ⚠️ 硬件前置说明：Kodi 是带图形界面的媒体中心应用，没有"纯后台守护进程"形态。无显示器服务器必须补一块虚拟显卡——本文用 xvfb（X virtual framebuffer，内存里的虚拟 X 服务）满足它，这也是把 Kodi 跑在服务器上的标准做法；真正的观影终端请用带 GPU/电视输出的设备，服务器形态适合做"媒体库管理 + JSON-RPC 自动化控制端"；
  • 基础依赖一条命令补齐（curl 用于验证，xvfb 提供虚拟显示）：
apt-get update && apt-get install -y curl xvfb

实测回显（输出节选，实测首尾）：

Hit:1 http://deb.debian.org/debian trixie InRelease
Hit:3 http://deb.debian.org/debian-security trixie-security InRelease
Reading package lists...
...
Setting up curl (8.14.1-2+deb13u7) ...
Processing triggers for libc-bin (2.41-12+deb13u4) ...

三、版本选型说明

Kodi 官方发行渠道多，各渠道当前版本差异明显（2026-10-28 取证），选错渠道会装到旧版：

渠道当前版本结论
Debian 13 官方 main 仓库21.2（2:21.2+dfsg-4）✅ 本文主推，稳定且最新
Ubuntu 官方仓库偏旧（随发行版冻结）适合版本够用即可的桌面机
team-xbmc PPA（Launchpad 实查）最新仅到 20.2（2023-06 构建，focal/jammy 系）⚠️ 已停滞，反而落后于 Debian 13 仓库，不建议
Flatpak（tv.kodi.Kodi）跟随上游桌面机可选，服务器依赖较重
官网 Windows/macOS/Android 安装包21.2 / 22.0-Piers 预览桌面与移动端场景
下一代 22.0 "Piers"RC 阶段（2026-10-10 rc1）只做尝鲜，生产不装

选型结论：Debian 系服务器直接用发行版仓库；"PPA 一定更新"的直觉在 Kodi 上不成立，是其版本生态里最容易踩的坑。

四、方案 A：在线仓库安装（Debian 官方 apt，主推）

本章从零开始：装包 → 建用户 → systemd 托管 → 首启初始化 → 启用远程控制 → 逐项验证。

4.1 安装软件包

apt-get install -y kodi kodi-eventclients-kodi-send

说明：kodi 元包会连带拉入 kodi-bin（主程序）、kodi-data（皮肤/资源）等；kodi-eventclients-kodi-send 是 EventServer 事件推送客户端（运维篇要用），一并装上。

实测回显（输出节选，实测首尾）：

Reading package lists...
Building dependency tree... Done
The following additional packages will be installed:
  kodi-bin kodi-data kodi-repository-kodi ... (共 300+ 个依赖包)
...
Setting up kodi (2:21.2+dfsg-4) ...
Processing triggers for libc-bin (2.41-12+deb13u4) ...

安装完成即可双验证：

dpkg -l kodi kodi-bin kodi-data kodi-eventclients-kodi-send | grep ^ii
apt-cache policy kodi | head -4

实测回显：

ii  kodi                                 2:21.2+dfsg-4    amd64  Open Source Home Theatre (executable binaries)
ii  kodi-bin                             2:21.2+dfsg-4    amd64  Open Source Home Theatre (architecture-dependent files)
ii  kodi-data                            2:21.2+dfsg-4    all    Open Source Home Theatre (arch-independent data package)
ii  kodi-eventclients-kodi-send          2:21.2+dfsg-4    amd64  Open Source Home Theatre (Event Client Kodi-SEND package)
kodi:
  Installed: 2:21.2+dfsg-4
  Candidate: 2:21.2+dfsg-4
  Version table:
 *** 2:21.2+dfsg-4 500
        500 http://deb.debian.org/debian trixie/main amd64 Packages

kodi --version

实测回显：

Kodi from Debian Media Center 21.2 Debian package version: 2:21.2+dfsg-4
Copyright (C) 2005-2025 Team Kodi from Debian - http://kodi.tv

4.2 创建专用运行用户

Kodi 不建议用 root 跑（数据目录、权限都会乱）：

useradd -m -s /bin/bash kodi
getent passwd kodi

实测回显：

kodi:x:1000:1000::/home/kodi:/bin/bash

4.3 systemd 托管（Xvfb + Kodi 双服务）

headless 运行 = Xvfb 先起、Kodi 后起。写两个 unit：

# /etc/systemd/system/xvfb.service —— 虚拟显示服务
cat > /etc/systemd/system/xvfb.service <<'EOF'
[Unit]
Description=Xvfb Virtual Framebuffer X Server (for Kodi headless)
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x720x24 -nolisten tcp -ac
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF

# /etc/systemd/system/kodi.service —— Kodi 本体（依赖 Xvfb，DISPLAY=:99）
cat > /etc/systemd/system/kodi.service <<'EOF'
[Unit]
Description=Kodi Media Center (headless via Xvfb)
After=network.target xvfb.service
Wants=xvfb.service

[Service]
Type=simple
User=kodi
Group=kodi
Environment=DISPLAY=:99
ExecStart=/usr/bin/kodi
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload

要点逐条说明：kodi.service 的 User=kodi 限定运行用户；Environment=DISPLAY=:99 指向 Xvfb 虚拟显示；Wants=xvfb.service 保证虚拟显示先拉起；两个服务都 Restart=always，进程崩溃自动拉回。启动并设开机自启（逐单元单独执行）：

systemctl enable xvfb
systemctl enable kodi
systemctl start xvfb
systemctl start kodi

状态验证：

systemctl is-active xvfb
systemctl is-active kodi
ps -o pid,user,cmd -C kodi.bin

实测回显：

active
active
    PID    USER     CMD
   1522    kodi     /usr/lib/x86_64-linux-gnu/kodi/kodi.bin

💡 技术拓展：Kodi 的图形后端不止 Xvfb 一种。常见对比——

方案原理适用场景
Xvfb纯内存虚拟 X 服务，无真实输出无显示器服务器，本文采用
X11 + 真实显卡物理显示输出HTPC 影厅主机
GBM/wayland 直出绕过 X 直接驱动 GPULibreELEC 等盒子系统

本文因服务器无 GPU 无显示器，采用 Xvfb；它牺牲了硬件加速但换来"任何服务器都能跑"的形态。

4.4 首启初始化与默认远程状态

Kodi 首次启动会在用户主目录生成数据目录骨架（~/.kodi/），并生成默认关闭远程控制的 guisettings.xml。全新实例首启后的实测状态：

ls /home/kodi/.kodi/
grep -o '<setting id="services.webserver[^>]*>[^<]*</setting>' /home/kodi/.kodi/userdata/guisettings.xml

实测回显：

addons
media
system
temp
userdata
<setting id="services.webserver" default="true">false</setting>
<setting id="services.webserverport" default="true">8080</setting>
<setting id="services.webserverauthentication" default="true">true</setting>
<setting id="services.webserverusername" default="true">kodi</setting>
<setting id="services.webserverssl" default="true">false</setting>

四个关键默认值：webserver=false（远程控制关）、port=8080、authentication=true、默认用户名 kodi 且无密码。headless 部署必须手工启用 webserver，否则 8080 完全不监听。

4.5 启用 Web/JSON-RPC 远程控制

停服 → 改 guisettings.xml → 起服（运行中直接改会被进程内存态覆盖）：

systemctl stop kodi
sed -i \
  -e 's|<setting id="services.webserver" default="true">false</setting>|<setting id="services.webserver">true</setting>|' \
  -e 's|<setting id="services.webserverusername" default="true">kodi</setting>|<setting id="services.webserverusername">admin</setting>|' \
  /home/kodi/.kodi/userdata/guisettings.xml
# 密码项默认不存在，手工插入（admin 账号 + 演示口令）
sed -i 's|<setting id="services.webserverusername">admin</setting>|<setting id="services.webserverusername">admin</setting>\n    <setting id="services.webserverpassword">q1w2e3r4</setting>|' /home/kodi/.kodi/userdata/guisettings.xml
chown kodi:kodi /home/kodi/.kodi/userdata/guisettings.xml
systemctl start kodi

改后核对与连通验证：

grep -o '<setting id="services.webserver[a-z]*"[^>]*>[^<]*</setting>' /home/kodi/.kodi/userdata/guisettings.xml
ss -ltnp | grep 8080

实测回显：

<setting id="services.webserver">true</setting>
<setting id="services.webserverport" default="true">8080</setting>
<setting id="services.webserverauthentication" default="true">true</setting>
<setting id="services.webserverusername">admin</setting>
<setting id="services.webserverpassword">q1w2e3r4</setting>
<setting id="services.webserverssl" default="true">false</setting>
LISTEN 0      4096         0.0.0.0:8080       0.0.0.0:*    users:(("kodi.bin",pid=2663,fd=24))
LISTEN 0      4096            [::]:8080          [::]:*    users:(("kodi.bin",pid=2663,fd=29))

webserver=true、用户 admin、密码已落盘，kodi.bin 已监听 8080。

4.6 远程接口认证与连通验证

三连验证：无认证应 401、错误密码应 401、正确认证应通：

curl -s -o /dev/null -w 'no-auth => %{http_code}\n' http://127.0.0.1:8080/jsonrpc
curl -s -o /dev/null -w 'wrong-pass => %{http_code}\n' -u admin:wrongpass http://127.0.0.1:8080/jsonrpc
curl -s -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"Application.GetProperties","params":{"properties":["version","name"]},"id":1}' \
  http://127.0.0.1:8080/jsonrpc

实测回显：

no-auth => 401
wrong-pass => 401
{"id":1,"jsonrpc":"2.0","result":{"name":"Kodi","version":{"major":21,"minor":2,"revision":"20250330-nogitfound","tag":"stable"}}}

版本三元组 21.2 / stable 拿到，安装与远程控制全部就绪。浏览器访问 http://<服务器IP>:8080/ 可打开 Web 界面（Chorus2），登录账号即 admin / q1w2e3r4。

五、方案 B：离线 deb 包整包安装（断网/内网服务器）

适用：目标服务器不通外网（或不想让它联网）。思路：在同架构同发行版的联网机上用 apt-get install --download-only 把 Kodi 全依赖闭包（449 个 deb，约 282MB）下载成一个目录，整体拷到目标机 dpkg -i 一次装完。

5.1 联网机：下载全依赖闭包

mkdir -p /tmp/debs
apt-get install --download-only --reinstall -y \
  -o Dir::Cache::archives=/tmp/debs -o DPkg::Post-Invoke="" \
  kodi kodi-eventclients-kodi-send
ls /tmp/debs/*.deb | wc -l
du -sh /tmp/debs

实测回显：

449
282M     /tmp/debs

两个 -o 选项缺一不可：Dir::Cache::archives 把包下到指定目录；DPkg::Post-Invoke="" 干掉 Debian 预装环境自带的 apt 缓存清理钩子（/etc/apt/apt.conf.d/ 里的 Post-Invoke 清理动作，装完即删缓存 deb，实测不空此参数则目录最终为空）。

5.2 拷贝到目标机并离线安装

把整个 /tmp/debs 拷到目标机（scp/U盘皆可）后，在目标机上一条命令装全（本实录为演示严格性，先把目标机从内网断开，再做纯离线安装）：

dpkg -i /tmp/debs/*.deb

实测回显（输出节选，实测首尾）：

(Reading database ... 7894 files and directories currently installed.)
Preparing to unpack .../libgcc-s1_14.2.0-19_amd64.deb ...
Unpacking libgcc-s1:amd64 (14.2.0-19) ...
...
Setting up kodi (2:21.2+dfsg-4) ...
Processing triggers for libc-bin (2.41-12+deb13u4) ...

dpkg -i 一次传全部包，解包与配置排序由 dpkg 在单次事务内自动完成。但注意：exit 0 不等于全部配置完成——本实录装完即遇到个别包停留未配置态（见 5.3），装后先做状态核对：

dpkg -l kodi kodi-bin kodi-data kodi-eventclients-kodi-send | grep -E '^(ii|iU|in)'
which kodi

实测回显（首次核对，出现 iU/in 属未收敛）：

iU  kodi                        2:21.2+dfsg-4 amd64  Open Source Home Theatre (executable binaries)
iU  kodi-bin                    2:21.2+dfsg-4 amd64  Open Source Home Theatre (architecture-dependent files)
ii  kodi-data                   2:21.2+dfsg-4 all    Open Source Home Theatre (arch-independent data package)
iU  kodi-eventclients-kodi-send 2:21.2+dfsg-4 amd64  Open Source Home Theatre (Event Client Kodi-SEND package)
/usr/bin/kodi

5.3 收尾排障：iU/in 未收敛实录

Kodi 本体已解包（/usr/bin/kodi 在）但状态 iU（unpacked 未配置）。dpkg --configure -a 补配置时暴露依赖链断点：

dpkg --configure -a
dpkg --configure python3-pil

实测回显（两条命令逐层揭出根因）：

dpkg: dependency problems prevent configuration of kodi-bin:
 kodi-bin depends on python3-pil; however:
  Package python3-pil:amd64 is not configured yet.
...
dpkg: dependency problems prevent configuration of python3-pil:amd64:
 python3-pil:amd64 depends on python3 (<< 3.14); however:
  Package python3 is not installed.

根因：python3 包声明 Pre-Depends（预依赖）python3-minimal (= 3.13.5-1)，而大事务里 python3-minimal 自身也未及时配置，导致 python3 在解包阶段被拒（实测 dpkg: error processing archive ... python3_3.13.5-1_amd64.deb (--install): pre-dependency problem - not installing python3）。修复按"先补预依赖链、再全量收敛"三步：

dpkg -i /tmp/debs/python3-minimal_3.13.5-1_amd64.deb
dpkg -i /tmp/debs/python3_3.13.5-1_amd64.deb
dpkg --configure -a

最终核对：

dpkg -l kodi python3 kodi-bin kodi-eventclients-kodi-send | grep -E '^(ii|iU|in)'
kodi --version

实测回显：

ii  kodi                        2:21.2+dfsg-4 amd64  Open Source Home Theatre (executable binaries)
ii  kodi-bin                    2:21.2+dfsg-4 amd64  Open Source Home Theatre (architecture-dependent files)
ii  kodi-eventclients-kodi-send 2:21.2+dfsg-4 amd64  Open Source Home Theatre (Event Client Kodi-SEND package)
ii  python3                     3.13.5-1      amd64  interactive high-level object-oriented language (default python3 version)
Kodi from Debian Media Center 21.2 Debian package version: 2:21.2+dfsg-4
Copyright (C) 2005-2025 Team Kodi from Debian - http://kodi.tv

全部 ii、版本三元组正常，离线安装收官。经验：dpkg -i 大闭包安装后必须做 dpkg -l 状态核对，发现 iU/in 就用 dpkg --configure -a 收敛，遇 Pre-Depends 报错按提示顺序手工补解包对应 deb 即可。后续 4.2–4.6 步骤原样适用。

六、方案对比与选择建议

维度方案 A：在线仓库方案 B：离线 deb 闭包
需要联网是（apt 源可达）仅联网机需要，目标机全断网
版本trixie main 当前 21.2与联网机取包时一致（可锁定）
安装方式apt-get installdpkg -i *.deb（449 包一次事务）
依赖处理apt 自动解析闭包预下载，单事务内自动排序
体积按需（约 282MB 下载）约 282MB 目录整体拷贝
systemd 托管本文 4.3 步骤同左
适用常规可联网服务器内网隔离、批量同版本部署

选择建议：能联网选 A，省心且随 apt upgrade 滚动更新；内网/安全区选 B，版本完全可控。两方案装出来的 Kodi 行为完全一致，后续配置与运维篇对两者通用。

七、配置说明（两方案共用的关键配置）

  • 远程控制三件套：services.webserver=true、services.webserverusername=admin、services.webserverpassword=q1w2e3r4（4.5 步），改动方式与生效条件详见《Kodi 21.2 配置参数详解》第三章；
  • 建议关闭零conf 广播（内网多实例防撞名）：services.devicename 改成主机名；
  • 媒体目录：统一小写命名（如 /srv/media/movies/），原因与 sources.xml 写法见配置篇 5.3；
  • 开机自启：systemctl enable xvfb kodi（逐单元执行），服务器重启后自动恢复远程控制面。

八、常见问题

Q1：systemctl start kodi 后服务反复重启？ 先看 journalctl -u kodi -n 30。最常见原因是 Xvfb 没起来（DISPLAY=:99 连不上）——确认 systemctl is-active xvfb 为 active；其次确认运行用户 kodi 对 /home/kodi 有写权限。

Q2：8080 端口不通？ 按序检查：services.webserver 是否 true（首启默认 false，见 4.4）；ss -ltnp | grep 8080 是否有 kodi.bin 监听；认证头是否带对（无认证返回 401 属正常，见 4.6）。改过 services.webserverport 的要重启才挂新口。

Q3：日志里 libva/VDPAU/音频 sink 报错是坏了吗？ 不是。headless 无 GPU 无声卡的必然回显（实测日志原文：libva error: vaGetDriverNames() failed with unknown libva error、Failed to open VDPAU backend libvdpau_nvidia.so: cannot open shared object file、CActiveAESink::OpenSink - no sink was returned），库管理与 JSON-RPC 功能不受影响。

Q4：扫描媒体库后影片数是 0？ 三个原因（全部实测踩过）：源路径大小写被归一化、path 表 strContent 未设内容类型、metadata.local 刮削器缺同名 NFO。完整定位与修复步骤见《Kodi 21.2 配置参数详解》第八章。

九、卸载与清理

systemctl disable kodi
systemctl disable xvfb
systemctl stop kodi
systemctl stop xvfb
apt-get purge -y 'kodi*' kodi-bin kodi-data
rm -rf /home/kodi/.kodi /etc/systemd/system/kodi.service /etc/systemd/system/xvfb.service
systemctl daemon-reload
userdel -r kodi

说明：purge 'kodi*' 连配置带包一起清；~/.kodi/ 是全部媒体库与设置，确认不再需要再删；两个 unit 文件与运行用户一并回收。验证：

which kodi
systemctl is-active kodi

实测回显：

which: no kodi in (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin)
inactive

十、参考链接