Karaoke Eternal 配置参数详解

Karaoke Eternal v2.0.2 的全部服务端参数只有一页纸的体量：9 个 CLI 选项/环境变量、3 个通用环境变量、1 个媒体解析器配置文件。本文先给全量清单，再对每个关键参数做"改值 → 重启 → 生效验证"的实测，所有命令与回显均来自真实操作。部署流程见《Karaoke Eternal Docker Compose 部署实战》。

一、参数体系总览

Karaoke Eternal Server 的配置入口有三类，优先级从高到低：

1. CLI 命令行参数（如 --port 8888）：karaoke-eternal-server 进程的启动参数；
2. 环境变量（如 KES_PORT）：与 CLI 一一对应，Docker 形态下用 environment 段设置；
3. 媒体解析器配置文件 _kes.v2.json：放在媒体文件夹里，控制文件名解析规则，作用域为该文件夹（含子文件夹）。

有一个容易踩的优先级陷阱值得先说：CLI 参数优先级高于环境变量。本章 3.2 节的实测会展示它的后果——Docker 形态下设置 KES_PORT 不生效，因为入口进程写死了 -p 8080。

💡 技术拓展：环境变量（Environment Variable）是操作系统层面传递配置的机制，进程启动时读取；CLI 参数是命令行里跟在程序名后的选项。两者共存时"就近原则"生效——直接写在启动命令里的参数（CLI）比环境变量更"近"，因此优先。

二、全量参数清单

2.1 服务端 CLI / 环境变量

以下清单取证自官方文档（https://www.karaoke-eternal.com/docs/karaoke-eternal-server/ ，查询日期 2026-10-28），日志级别取值约定：0=off（关闭）、1=error、2=warn、3=info、4=verbose、5=debug：

除上表外，官方发布物还遵循三个通用环境变量（LinuxServer 系约定）：PUID（进程运行用户 ID）、PGID（进程运行组 ID）、TZ（时区，影响日志时间戳）。

2.2 Docker 形态与 npm 形态的差异

两条环境差异直接影响参数用法，均来自官方文档与实测：

• 日志文件：Docker 形态默认不写日志文件（实测进程启动参数固定为 --serverLogLevel 0 --scannerLogLevel 0，即文件日志关闭），统一用 docker logs 看输出，KES_*_LOG_LEVEL 实际不参与；npm 形态的日志文件位置为 Windows %USERPROFILE%\AppData\Roaming\Karaoke Eternal Server\logs、macOS ~/Library/Application Support/Karaoke Eternal Server/logs、Linux ~/.config/Karaoke Eternal Server/logs；
• 监听端口：npm 形态 KES_PORT/--port 生效（官方示例 karaoke-eternal-server --port 8888）；Docker 形态入口写死 -p 8080，改端口应调整端口映射而非 KES_PORT（见 3.2 实测）。

数据库文件位置：Docker 形态在映射到 /config 的目录中（database.sqlite3）；npm 形态在上述平台目录中。

三、关键参数改值实测

本章引导语：参数文档最怕"抄表格"。以下每个参数都在运行中的 v2.0.2 实例上真实改过值、重启过服务、验证过效果，回显逐行照抄。

3.1 KES_SERVER_CONSOLE_LEVEL：控制日志颗粒度

实验平台初始未显式设置该变量（取默认 4）。先设为 5（debug） 并叠加 KES_URL_PATH=/kes 一起验证：

    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - KES_SERVER_CONSOLE_LEVEL=5
      - KES_SCANNER_CONSOLE_LEVEL=5
      - KES_URL_PATH=/kes

docker compose up -d 重建后，先访问一次页面再抓日志尾部：

# docker logs --tail 4 karaoke-eternal-b2 | grep -v Warning
00:19:36.516 (server)    ›   <-- GET /kes/
00:19:36.517 (server)    ›   --> GET /kes/ 200 1ms 452b
00:19:36.525 (server)    ›   <-- GET /kes/
00:19:36.526 (server)    ›   --> GET /kes/ 200 1ms 452b

<--（收到请求）与 -->（响应完成，含状态码、耗时、字节数）是 verbose/debug 级别才有的逐请求行。把级别降到 1（error） 再访问同一页面：

# docker logs --tail 3 karaoke-eternal-b2 | grep -v Warning
（无任何输出）

无输出 = 1 级别下 GET 请求不打日志，只有错误才会出现。结论：日常运行建议 3（info）；排查接口问题时临时提到 5；长期 1/0 会让你在出事时无据可查。

3.2 KES_URL_PATH：反代场景的基础路径

当服务藏在反向代理的子路径后（如 https://example.com/kes/），需要设置 KES_URL_PATH=/kes。实测设置后：

# curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8142/
404
# curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8142/kes/
200
# curl -s http://127.0.0.1:8142/kes/ | grep -o '<title>[^<]*'
<title>Karaoke Eternal

根路径返回 404、/kes/ 返回 200 且页面标题正常——全部资源与 API 都搬进了 /kes 前缀下（日志同步证实：GET /kes/ 200）。注意三个连带影响：页面内的静态资源路径会自动带上前缀；REST API 变为 /kes/api/...；socket.io 连接地址变为 /kes/socket.io/。反代把 /kes 原样转发到服务即可，无需重写。

💡 技术拓展：反向代理（Reverse Proxy）是部署在服务前面的流量入口，常见如 Nginx/Caddy。"子路径部署"（https://域名/kes/）与"子域名部署"（kes.example.com）是两种典型形态，后者无需 KES_URL_PATH，前者必须设置，否则页面能打开但 JS/CSS 全部 404。

3.3 KES_PORT：一个不生效的反例（Docker 形态）

按官方文档设置 KES_PORT=8090 并把映射改为 8142:8090，重建后访问全部超时：

# curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8142/kes/
000

进入运行实例查看进程命令行与监听端口，真相是：

# ps aux | head -2
PID   USER     TIME  COMMAND
    1 node      0:00 {MainThread} node /opt/.npm-global/bin/karaoke-eternal-server -p 8080 --data /config --serverLogLevel 0 --scannerLogLevel 0
# netstat -tln | grep LISTEN | grep -v 127.0.0.11
tcp        0      0 :::8080                 :::*                    LISTEN

进程固定以 -p 8080 启动（CLI 优先级高于环境变量，第一章的陷阱在此应验），实际监听 8080，而映射却指向 8090——端口错位导致 000。修复：把映射改回 8142:8080 并删除 KES_PORT，服务立即恢复 200。

结论：Docker 形态下调整对外端口只动映射左侧；KES_PORT 仅供 npm 形态使用。

3.4 KES_SCAN：启动时自动扫描

KES_SCAN 的值是媒体文件夹的 pathId 列表或 all。给实验平台加入 KES_SCAN=1（指向 3.1 节添加的 pathId=1 的文件夹——实测环境中当时为 /mnt/karaoke）后重启：

00:02:35.701 (main[1])   › Starting media scanner process
16:02:35.880 (queue)                › path queued for scan: /mnt/karaoke
16:02:35.881 (queue)                › Starting media scan
16:02:35.882 (FileScanner)          › Searching: /mnt/karaoke
16:02:35.897 (FileScanner)          ›   => found 3 files with valid extensions [".m4a",".mp3",".mp4",".zip"]
16:02:35.901 (FileScanner)          ›   => no .cdg sidecar found
16:02:35.918 (FileScanner)          ›   => ok
16:02:35.922 (FileScanner)          › Scanned 2 valid media files

启动即触发扫描，效果与 GET /api/prefs/paths/scan 等价。两点提醒：其一，v2.0.2 默认已对媒体文件夹启用文件监视（watch），媒体目录有变化会自动增量扫描，日常并不需要常备 KES_SCAN；其二，如果重启时数据目录权限不对，KES_SCAN 会把问题放大成崩溃循环（扫描收尾要写库，attempt to write a readonly database 直接把进程打崩）——先修权限再谈扫描，完整案例见《Karaoke Eternal 常用命令与运维实战（核心篇）》。

3.5 _kes.v2.json：媒体解析器配置文件

官方默认按"Artist - Title"拆文件名。在媒体文件夹放一个 _kes.v2.json（JSON/JSON5 均可）即可整体改写解析行为，且对子文件夹生效。实测配置：

{
  "artist": "Demo 歌手",
  "title": "${name}"
}

artist 是显式常量，title 用 ${name} 模板取"去扩展名的文件名"。触发重扫（GET /api/prefs/paths/scan 返回 OK，扫描日志出现 Using default parser config 之后的模板应用）后核对数据库：

[{"songId":3,"title":"Test Trio - Sine Wave Serenade","titleNorm":"Test Trio - Sine Wave Serenade","artist":"Demo 歌手"},
 {"songId":4,"title":"星光乐队 - 夜航星","titleNorm":"星光乐队 - 夜航星","artist":"Demo 歌手"}]

三个生效证据：artist 全部变成模板值；title 变成完整文件名；songId 从 1/2 重建为 3/4——元数据变化被视为新曲目（旧曲目及其收藏记录随之失效）。删除 _kes.v2.json 再重扫，曲库恢复原名（songId 再次重建为 5/6）。改解析器配置属于"伤筋动骨"操作：曲库 ID 会变，历史收藏需要重新标星，建议一次性定稿。

除字段模板外，解析器还支持三个基础开关（官方文档同页）：articles（冠词归一化列表，默认 ['A','An','The']）、artistOnLeft（文件名左侧是否为歌手，"Title - Artist"曲库设 false）、delimiter（分隔符，默认 -）。高级模板可用 JSON-e 语法引用媒体内嵌标签（如 ${meta.artist}）与正则清洗（内置 replace 方法）。

3.6 PUID/PGID/TZ：进程身份与时区

这三个变量决定进程身份与日志时区。实测反例已在部署篇详述：数据目录属主与 PUID/PGID 不匹配时，数据库以只读方式打开、服务崩溃循环（日志铁证：Opening database file (read-only) + attempt to write a readonly database），chown -R 1000:1000 <数据目录> 一条命令修复。TZ 影响可从日志时间戳直接观察：本机时区为 Asia/Shanghai 时，控制台日志呈现 00:12:46 本地时间与 16:02:35 UTC 双轨（主进程打本地时间、扫描进程打 UTC），排查跨时段问题时以 UTC 行为准换算。

四、参数速查：改什么、去哪改、怎么验证

配置不是孤立的——改完参数后的日常操作（手动扫描、队列管理、备份恢复、升级）都在《Karaoke Eternal 常用命令与运维实战（核心篇）》中给出完整命令与回显。