Kodi 21.2 配置参数详解

目标：逐段讲清 Kodi 21.2 在 headless 服务器形态下的全部配置载体与关键参数——guisettings.xml、advancedsettings.xml、sources.xml、profiles.xml 与 JSON-RPC Settings 域，并对 webserver 端口、调试日志、启动扫描等关键项做改值 + 生效验证的闭环实测。全部命令与回显均为 2026-10-28 在一台 Debian 13 (trixie) 服务器（Kodi 21.2，包版本 2:21.2+dfsg-4，Xvfb 虚拟显示 headless 运行，Web/JSON-RPC 8080 端口）实测逐行照抄；部署过程见本专栏《Kodi 安装实战（Debian 13 Headless 部署与远程控制）》，日常命令运维见本专栏《Kodi 常用命令与运维实战（核心篇）》。

一、环境信息

操作系统：Debian GNU/Linux 13 (trixie)，x86_64；
Kodi 版本：21.2 "Omega"（2:21.2+dfsg-4，来自 Debian 官方 main 仓库），JSON-RPC 协议版本 13.5；
运行形态：headless——无显示器/GPU 的服务器，Xvfb 虚拟帧缓冲（:99，1280x720x24）+ systemd 双服务（xvfb.service、kodi.service）托管，运行用户 kodi；
远程接口：HTTP Web/JSON-RPC 127.0.0.1:8080（账号 admin / q1w2e3r4），EventServer UDP 9777；
数据目录：/home/kodi/.kodi/（SQLite 媒体库、guisettings、插件数据），媒体目录 /srv/media/movies/，备份目录 /srv/backup/；
本章 curl 调用统一走服务器本机回环地址 http://127.0.0.1:8080/jsonrpc，Basic 认证与 JSON-RPC 连通性验证见安装篇第四章。

二、前置条件

Kodi 已安装并处于 active 运行状态（systemctl is-active kodi 返回 active），Web 远程控制已启用；
具备 root 权限（改 guisettings.xml 等文件需要 kodi 用户属主权限，用 root 操作后需回改属主）；
curl 与 sqlite3 已安装（apt install curl sqlite3），用于远程验证与数据库检查；
JSON-RPC 调用模板（下文所有 $RPC 均指它）：

# JSON-RPC 调用模板：$RPC 后跟 JSON 报文即可
RPC='curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" -d'
$RPC '{"jsonrpc":"2.0","method":"JSONRPC.Ping","id":1}' http://127.0.0.1:8080/jsonrpc

实测回显：

{"id":1,"jsonrpc":"2.0","result":"pong"}

pong 说明认证与 RPC 通道正常，可以开始后续所有验证。

⚠️ 注意：JSON-RPC 报文中 id 字段可任意，但必须携带；缺 Basic 认证或密码错误将得到 HTTP 401（实测：无认证与错误密码均返回 401，见安装篇）。

三、参数查看与修改方式

Kodi 的参数分散在四种载体上，各有生效条件，先给一张总览表：

载体	位置	存放内容	生效方式
guisettings.xml	`~/.kodi/userdata/guisettings.xml`	GUI 全部设置（界面/服务/播放/系统等六大节）	文件方式需重启；JSON-RPC 方式多数即时
advancedsettings.xml	`~/.kodi/userdata/advancedsettings.xml`（默认不存在）	高级/底层参数（缓存/网络/库行为）	仅启动时加载，必重启
sources.xml	`~/.kodi/userdata/sources.xml`	媒体源（视频/音乐/图片目录）	启动时读取，改后重启
profiles.xml	`~/.kodi/userdata/profiles.xml`	用户配置档案（Master user 等）	启动时读取
SQLite 数据库	`~/.kodi/userdata/Database/MyVideos*.db` 等	媒体库、内容类型标记、路径	停服后改，避免锁冲突

修改方式有三种：图形界面（headless 不可用）、直接改 XML 文件（需重启）、JSON-RPC Settings.GetSettingValue / Settings.SetSettingValue（服务运行中可用，多数即时生效）。headless 服务器上第三种是首选。

方式一：JSON-RPC 读设置。 以 services.webserver 为例：

# 读取单个设置项当前值
$RPC '{"jsonrpc":"2.0","method":"Settings.GetSettingValue","params":{"setting":"services.webserver"},"id":1}' http://127.0.0.1:8080/jsonrpc

实测回显：

{"id":1,"jsonrpc":"2.0","result":{"value":true}}

方式二：JSON-RPC 改设置。 开启详细调试日志并读回验证：

# 开启 debug.extralogging 并读回
$RPC '{"jsonrpc":"2.0","method":"Settings.SetSettingValue","params":{"setting":"debug.extralogging","value":true},"id":1}' http://127.0.0.1:8080/jsonrpc
$RPC '{"jsonrpc":"2.0","method":"Settings.GetSettingValue","params":{"setting":"debug.extralogging"},"id":1}' http://127.0.0.1:8080/jsonrpc

实测回显（两次调用）：

{"id":1,"jsonrpc":"2.0","result":true}
{"id":1,"jsonrpc":"2.0","result":{"value":true}}

第一次 result:true 表示写成功，第二次读回 value:true 确认生效（该参数影响日志详细度，验证见第六章）。

方式三：直接改文件。 关闭服务后编辑 XML，再启动：

# 改 guisettings.xml 的标准流程：停服 → 编辑 → 起服（服务期间直接改会被进程内存态覆盖）
systemctl stop kodi
vi /home/kodi/.kodi/userdata/guisettings.xml
systemctl start kodi

💡 技术拓展：XML 里每个 <setting> 节点可能带 default="true" 属性，表示"当前值等于出厂默认"。被改过的项该属性消失，例如默认端口显示 <setting id="services.webserverport" default="true">8080</setting>，改成 8090 后变为 <setting id="services.webserverport">8090</setting>。排查"这个值是默认还是被改过"时看这个属性即可。

四、参数总览

4.1 数据目录与文件布局

~/.kodi/ 是全部配置与数据的家，headless 部署后的实际布局（实测 ls /home/kodi/.kodi/）：

addons
media
system
temp
userdata

路径	内容	运维关注点
`~/.kodi/userdata/guisettings.xml`	GUI 全量设置（XML 单文件）	远程控制、界面、播放开关都在这里
`~/.kodi/userdata/advancedsettings.xml`	高级参数（默认不存在，需自建）	缓存、网络超时、库行为
`~/.kodi/userdata/sources.xml`	媒体源定义	headless 添加媒体目录的主通道
`~/.kodi/userdata/profiles.xml`	配置档案（默认单 Master user）	多档案切换
`~/.kodi/userdata/Database/`	MyVideos131.db（视频库）、MyMusic83.db（音乐库）、Textures13.db（缩略图）等	备份与内容标记
`~/.kodi/temp/kodi.log`	运行日志（重启后旧日志变 kodi.old.log）	排障第一现场
`~/.kodi/addons`、`~/.kodi/media`、`~/.kodi/system`	插件、媒体资源、运行时系统资源	一般不动

实测数据库清单（ls /home/kodi/.kodi/userdata/Database/）：

Addons33.db  CDDB  Epg16.db  MyMusic83.db  MyVideos131.db  TV46.db  Textures13.db  ViewModes6.db

版本号随 Kodi 大版本变化（21.x 对应 MyVideos131/MyMusic83），跨版本恢复备份时库文件不可直接混用，只迁 userdata 与数据库要配套。

4.2 guisettings.xml 六大设置节

JSON-RPC Settings.GetSections 可列出全部设置节（实测节选）：

{"sections":[{"id":"games","label":"Games"},{"id":"interface","label":"Interface"},
{"id":"media","label":"Media"},{"id":"player","label":"Player"},
{"id":"pvr","label":"PVR & Live TV"},{"id":"services","label":"Services"}...]}

对应 guisettings.xml 里的分类，本章 5.x 逐段详解 headless 场景最关键的 services 节与其余节的核心项。

五、核心参数分类详解

5.1 services 节（远程控制，headless 命脉）

headless 实例全部远程能力由本节决定，实测当前值（grep guisettings.xml）：

<setting id="services.webserver">true</setting>
<setting id="services.webserverport">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>
<setting id="services.esenabled">true</setting>
<setting id="services.esport" default="true">9777</setting>
<setting id="services.devicename">Kodi</setting>

逐项说明：

services.webserver：HTTP/JSON-RPC 总开关，默认 false。headless 必改 true，否则 8080 不监听；
services.webserverport：HTTP 端口，默认 8080。改值有"运行中摘除监听、重启后才挂新口"的坑（实录见第六章 6.1）；
services.webserverauthentication：是否启用 Basic 认证，默认 true；
services.webserverusername / services.webserverpassword：认证账号密码，本文用 admin / q1w2e3r4；
services.webserverssl：内建 HTTPS 开关，默认 false。Kodi 无证书管理能力，生产建议前置 Nginx 做 TLS 终结而不是开此项；
services.esenabled / services.esport：EventServer（UDP 事件推送）开关与端口，默认开、9777。kodi-send 事件客户端走这里；
services.devicename：零conf/UPnP 广播名，默认 Kodi，多实例内网环境建议改成主机名避免撞名。

⚠️ 注意：services.webserverpassword 在 XML 中是明文。该文件属主必须是运行用户 kodi（600 权限更佳），且 8080 端口不应暴露公网。

5.2 debug 节（日志排障）

<setting id="debug.showloginfo" default="true">false</setting>
<setting id="debug.extralogging">false</setting>

debug.showloginfo：屏幕角落实时显示日志行，headless 无意义，保持 false；
debug.extralogging：详细日志（DEBUG 级行），排障时经 JSON-RPC 秒开秒关，配合 tail -f kodi.log 使用（改值回显见第三章方式二）。

日志文件规则（实测）：运行日志在 ~/.kodi/temp/kodi.log，每次重启 Kodi 将旧日志改名为 kodi.old.log。除 guisettings 外，advancedsettings.xml 里的 <loglevel> 可强制全局日志级（见 5.4）。

5.3 sources.xml（媒体源）

headless 无法在 GUI 里"添加来源"，sources.xml 是主通道。实测本环境文件内容：

<sources>
    <programs>
        <default pathversion="1"></default>
    </programs>
    <video>
        <default pathversion="1"></default>
        <source>
            <name>Demo Movies</name>
            <path pathversion="1">/srv/media/movies/</path>
            <allowsharing>true</allowsharing>
        </source>
    </video>
    <music>
        <default pathversion="1"></default>
        <source>
            <name>Demo Music</name>
            <path pathversion="1">/srv/media/music/</path>
            <allowsharing>true</allowsharing>
        </source>
    </music>
    <pictures>
        <default pathversion="1"></default>
    </pictures>
    <files>
        <default pathversion="1"></default>
    </files>
</sources>

<name>：源显示名（进库后 Files.GetSources 的 label）；<path>：目录绝对路径，结尾斜杠建议保留；
五个分类节点（programs/video/music/pictures/files）都要保留空默认子项，只往需要的节点里加 <source>。

⚠️ 注意（实测踩坑）：Kodi 会把源路径归一化为全小写后写入数据库。本环境曾同时存在 /srv/media/Movies（大写）与历史目录 /srv/media/movies（小写），sources.xml 写大写路径后，扫描器实际走进的是数据库里的小写目录，媒体对不上号。结论：目录直接用小写命名，与库内归一化一致。

5.4 advancedsettings.xml（高级参数）

该文件默认不存在，自建即生效（仅启动时加载一次）。本环境实测文件与 Kodi 启动时的完整回读日志：

<advancedsettings version="1.0">
    <loglevel hide="false">1</loglevel>
    <videolibrary>
        <updateonstartup>true</updateonstartup>
        <cleanonupdate>true</cleanonupdate>
    </videolibrary>
    <network>
        <curlclienttimeout>30</curlclienttimeout>
    </network>
    <cache>
        <buffermode>1</buffermode>
        <memorysize>20971520</memorysize>
    </cache>
    <samba>
        <clienttimeout>30</clienttimeout>
    </samba>
</advancedsettings>

逐项说明：

<loglevel hide="false">1</loglevel>：全局日志级，0=NORMAL、1=DEBUG。hide="false" 让 GUI 里仍可改；设为 DEBUG 后日志出现 debug <general>: 级行（实测见下）；
<videolibrary><updateonstartup>true：每次启动自动扫描视频库（实测日志出现 UpdateLibraries: Starting video library startup scan）；
<videolibrary><cleanonupdate>true：每次扫描后清理库中已失效条目（实测日志出现 CleanDatabase: Cleaning videodatabase done. Operation took 1 ms）；
<network><curlclienttimeout>30</curlclienttimeout>：Kodi 作为 HTTP 客户端（刮削/网络流）的连接超时秒数，默认 30，弱网环境可加大；
<cache><buffermode>1</buffermode><memorysize>20971520</memorysize>：播放缓冲模式（0=按需、1=全部媒体强制缓冲、2=仅网络流？——按官方 Wiki 语义：1 表示除本地真文件外全部缓冲）与缓冲内存字节数（20MB）。 ⚠️ Kodi 21 起 cache 段部分能力已被 GUI 播放设置取代，日志中会打印 New Cache GUI Settings (replacement of cache in advancedsettings.xml) 提示，旧参数向后兼容但优先级以 GUI 为先；
<samba><clienttimeout>30</clienttimeout>：SMB 源读写超时秒数。

启动加载验证（重启后 grep advancedsettings /home/kodi/.kodi/temp/kodi.log 实测回显）：

2026-10-28 16:14:32.983 T:2194     info <general>: No settings file to load (special://xbmc/system/advancedsettings.xml)
2026-10-28 16:14:32.983 T:2194     info <general>: Loaded settings file from special://profile/advancedsettings.xml
2026-10-28 16:14:32.983 T:2194     info <general>: Contents of special://profile/advancedsettings.xml are...
                                                   <advancedsettings version="1.0">
                                                     <loglevel hide="false">1</loglevel>
                                                     <videolibrary>
                                                       <updateonstartup>true</updateonstartup>
                                                       <cleanonupdate>true</cleanonupdate>
                                                     </videolibrary>
                                                     <network>
                                                       <curlclienttimeout>30</curlclienttimeout>
                                                     </network>
                                                     <cache>
                                                       <buffermode>1</buffermode>
                                                       <memorysize>20971520</memorysize>
                                                     </cache>
                                                     <samba>

日志逐行回读文件内容，是确认"文件被读到、读到了什么"的最直接证据。配套的库行为验证（同一次启动日志）：

2026-10-28 16:14:39.234 T:2194     info <general>: UpdateLibraries: Starting video library startup scan
2026-10-28 16:14:39.288 T:2244    debug <general>: VideoInfoScanner: Skipping dir '/srv/media/movies/' due to no change (fasthash)
2026-10-28 16:14:39.290 T:2244     info <general>: CleanDatabase: Cleaning videodatabase done. Operation took 1 ms
2026-10-28 16:14:39.290 T:2244     info <general>: VideoInfoScanner: Finished scan. Scanning for video info took 3 ms

三条链路全部对上：updateonstartup → startup scan；loglevel 1 → 出现 debug 级行；cleanonupdate → CleanDatabase 执行。另注意 Skipping dir ... (fasthash)：库对未变化目录做快速哈希跳过，属正常行为不是扫描失败。

5.5 profiles.xml（配置档案）

实测内容（节选）：

<profiles>
    <lastloaded>0</lastloaded>
    <useloginscreen>false</useloginscreen>
    <autologin>-1</autologin>
    <nextIdProfile>1</nextIdProfile>
    <profile>
        <id>0</id>
        <name>Master user</name>
        <directory pathversion="1">special://masterprofile/</directory>
        <hasdatabases>true</hasdatabases>
        ...

Kodi 的多档案是"同一台机器上的多套界面/库视图"，不是多用户权限体系；headless 单用途部署保持默认 Master user 即可；
useloginscreen/autologin 控制开机档案选择，headless 保持默认。

5.6 数据库与内容类型标记（headless 专属）

GUI 里"设置内容类型（此目录包含：电影）"这一步，headless 无界面可点，需要直接写库。本环境实测过程：

# 1. 停服（SQLite 防锁）
systemctl stop kodi
# 2. 找到视频库文件并查看 path 表（strContent 为 NULL 即未设内容类型）
sqlite3 /home/kodi/.kodi/userdata/Database/MyVideos131.db \
  "SELECT idPath,strPath,IFNULL(strContent,'NULL'),IFNULL(strScraper,'NULL') FROM path WHERE strPath LIKE '/srv%';"

实测回显：

1|/srv/media/movies/|NULL|NULL

# 3. 打上"电影"内容类型 + 本地 NFO 刮削器
sqlite3 /home/kodi/.kodi/userdata/Database/MyVideos131.db \
  "UPDATE path SET strContent='movies', strScraper='metadata.local' WHERE strPath='/srv/media/movies/';"
# 4. 起服后触发扫描，影片入库
systemctl start kodi

入库验证（JSON-RPC，实测）：

{"id":1,"jsonrpc":"2.0","result":{"limits":{"end":4,"start":0,"total":4},"movies":[{"title":"Big Buck Bunny","year":2008},...]}}

💡 技术拓展：Kodi 刮削器（Scraper）决定元数据从哪来，常用对比——

刮削器元数据来源适用场景
metadata.local 仅本地 NFO 文件内网/离线，元数据完全自持
metadata.themoviedb.org.python TMDB 在线能出外网的标准家庭环境
metadata.universal 等多源聚合特殊命名/混合库

本文因服务器隔离场景采用 metadata.local，配合与视频同名的 .nfo 文件（如 Big Buck Bunny 2008.nfo 内嵌 <movie><title>…</title><year>…</year></movie>）实现零外网入库；未写 NFO 且内容类型为 movies 时扫描器会警告 No information found for item ... it won't be added to the library.（实测日志原文）。

刮削器	元数据来源	适用场景
metadata.local	仅本地 NFO 文件	内网/离线，元数据完全自持
metadata.themoviedb.org.python	TMDB 在线	能出外网的标准家庭环境
metadata.universal 等	多源聚合	特殊命名/混合库

六、关键项改值与生效验证实录

6.1 实录一：webserver 端口 8080→8090 的坑与回切

目标：验证 services.webserverport 改值行为。先经 JSON-RPC 改为 8090：

$RPC '{"jsonrpc":"2.0","method":"Settings.SetSettingValue","params":{"setting":"services.webserverport","value":8090},"id":1}' http://127.0.0.1:8080/jsonrpc

实测回显：

{"id":1,"jsonrpc":"2.0","result":true}

紧随其后的端口探测（实测）：

8080 => 000
8090 => 000

两个端口全断：写值成功（result:true）但运行中的 Web 服务被摘除，新端口并未即时监听——该参数需要重启 Kodi 才重新挂载。重启后验证：

systemctl restart kodi
grep -o '<setting id="services.webserverport"[^>]*>[0-9]*</setting>' /home/kodi/.kodi/userdata/guisettings.xml
curl -s -o /dev/null -w '8090 => %{http_code}\n' -u admin:q1w2e3r4 http://127.0.0.1:8090/jsonrpc

实测回显：

<setting id="services.webserverport">8090</setting>
8090 => 200

注意两点：落盘值变成 8090 且 default="true" 属性消失；8090 => 200 说明新端口生效。回切同理（服务此时在 8090 上，RPC 目标地址也要跟着换）：

curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"Settings.SetSettingValue","params":{"setting":"services.webserverport","value":8080},"id":1}' \
  http://127.0.0.1:8090/jsonrpc
systemctl restart kodi
curl -s -o /dev/null -w 'revert 8080 => %{http_code}\n' -u admin:q1w2e3r4 http://127.0.0.1:8080/jsonrpc

实测回显：

revert 8080 => 200

结论：services.webserverport 是"落盘即时、挂载要重启"的参数；运行中改端口会造成 Web 管理面短暂失联，若新端口错了只能改文件重启救回。

6.2 实录二：debug.extralogging 即时生效

第三章方式二已展示写值回显，其生效验证为日志出现 DEBUG 级行（配合 advancedsettings <loglevel>1，实测日志中同屏出现）：

2026-10-28 16:14:39.288 T:2244    debug <general>: VideoInfoScanner: Skipping dir '/srv/media/movies/' due to no change (fasthash)

info 与 debug 级行并存即详细日志生效。排查完成后 value:false 关回即可，无需重启。

七、生产配置模板

适用场景：4GB 内存、机械盘或 SATA SSD、局域网内网、无 GPU 的 headless 媒体/自动化服务器，Kodi 仅做库管理与 JSON-RPC 控制端。

<!-- ~/.kodi/userdata/advancedsettings.xml -->
<advancedsettings version="1.0">
    <loglevel hide="false">0</loglevel>
    <videolibrary>
        <updateonstartup>true</updateonstartup>
        <cleanonupdate>true</cleanonupdate>
    </videolibrary>
    <network>
        <curlclienttimeout>60</curlclienttimeout>
    </network>
</advancedsettings>

<!-- ~/.kodi/userdata/guisettings.xml 需改动的 services 项 -->
<setting id="services.webserver">true</setting>
<setting id="services.webserverport">8080</setting>
<setting id="services.webserverusername">admin</setting>
<setting id="services.webserverpassword">q1w2e3r4</setting>
<setting id="services.esenabled">true</setting>

模板说明：日志保持 NORMAL（0）减少磁盘写；启动扫描 + 清理开启保证库随源目录自愈；curl 超时放宽到 60 秒适配刮削弱网；远程控制仅内网使用。大内存（16GB）且常播网络流的场景可另加 <cache><memorysize>104857600</memorysize></cache>（100MB 缓冲）。

八、常见问题

Q1：改了 guisettings.xml 不生效？ 文件方式必须先 systemctl stop kodi 再改再启动；服务运行中改文件会被进程内存态在退出时覆盖回旧值。JSON-RPC 方式则要注意 6.1 实录的"部分参数落盘即时、挂载要重启"差异。

Q2：扫描返回 OK 但媒体库是空的？ 三步排查（本环境全踩过）：① 源路径大小写——库内路径会被归一化为小写，目录命名用小写；② 内容类型未设——headless 用 sqlite3 给 path.strContent 打 movies 标记（见 5.6）；③ 无元数据——metadata.local 刮削器要求每个媒体配同名 .nfo，否则日志报 No information found for item ... it won't be added to the library.。

Q3：日志里持续刷 CActiveAESink::OpenSink - no sink was returned 与 libva/VDPAU 报错？ headless 服务器无声卡无 GPU 的正常现象（实测日志原文：libva error: vaGetDriverNames() failed、Failed to open VDPAU backend libvdpau_nvidia.so）。播放/库管理不受影响；要消除可给虚拟环境加载 dummy 音频驱动，运维上建议直接忽略。

Q4：System.SetLogLevel/GetLogLevel 这类 RPC 方法报 Method not found？ 部分 Kodi RPC 方法未在 HTTP 通道的白名单里（实测 {"error":{"code":-32601,"message":"Method not found."}}）。日志级改用 advancedsettings.xml 的 <loglevel> 或 Settings.SetSettingValue 改 debug.extralogging。

九、参考链接

官方 Wiki：设置文件说明 https://kodi.wiki/view/Settings.xml
官方 Wiki：advancedsettings.xml https://kodi.wiki/view/Advancedsettings.xml
官方 Wiki：guisettings.xml 逐项 https://kodi.wiki/view/Guisettings.xml
官方 Wiki：sources.xml https://kodi.wiki/view/Sources.xml
官方 Wiki：NFO files https://kodi.wiki/view/NFO_files
JSON-RPC API（v13，对应 Kodi 21）：https://kodi.wiki/view/JSON-RPC_API/v13
本专栏相关篇目：《Kodi 介绍与选型指南》、《Kodi 安装实战（Debian 13 Headless 部署与远程控制）》、《Kodi 常用命令与运维实战（核心篇）》