Kavita 0.9.1.4 配置参数详解

目标：逐项讲清 Kavita 0.9.1.4 的两层参数体系——启动参数文件 /kavita/config/appsettings.json 全参数与运行时设置库全参数，并实测环境变量覆盖与端口修改是否生效。全部内容在本环境实测通过（2026-10-31）。部署过程见 《Kavita 0.9.1.4 Docker Compose 部署指南》。

一、环境信息

• 软件版本：Kavita v0.9.1.4（服务已按部署篇拉起并完成首次向导）
• 服务地址：http://127.0.0.1:8145（服务进程内部监听 5000）
• 数据目录：/kavita/config（含 appsettings.json、kavita.db、covers/、logs/ 等）
• 测试账号：admin / q1w2e3r4（管理员）
• 补充实测环境：裸机二进制形态实例（发行包 kavita-linux-x64.tar.gz 解压直跑，见部署篇附节），用于环境变量覆盖机制验证
• 参考文件：/kavita/config/appsettings.json 实测全文见 4.1；运行时设置清单实测于 4.2

二、前置条件

1. Kavita 服务已启动（GET /api/health 返回 Ok）。
2. 需要管理员 JWT 才能读写设置 API（登录获取方式见部署篇 5.1 或 API 篇）。
3. 修改 appsettings.json 前先备份；修改后需重启 Kavita 服务进程。

三、参数查看与修改方式

3.1 两层参数体系

Kavita 的参数分两层，职责不同：

💡 技术拓展：这种"启动文件 + 设置库"双层结构在单文件数据库型自托管服务里很常见（如 Jellyfin 的 system.xml + 数据库、Navidrome 的 toml + 数据库）。判断一个参数在哪层，最直接的办法是看它出现在 appsettings.json 还是 GET /api/Settings。

3.2 appsettings.json 的查看与修改

数据目录下直接查看：

cat /kavita/config/appsettings.json

修改后重启 Kavita 服务进程生效（重启命令见部署篇运维命令）。注意实测结论：运行期端口不在这一层生效（见 5.2 与 FAQ）。

3.3 运行时设置：管理界面与 Settings API

管理员登录后可通过 GET /api/Settings 一次读出全部运行时设置（实测回显，节选标量字段）：

allowStatCollection = True
baseUrl = '/'
bookmarksDirectory = '/kavita/config/bookmarks'
cacheDirectory = '/kavita/config/cache'
cacheSize = 75
coverImageSize = 1
enableFolderWatching = False
enableOpds = True
encodeMediaAs = 0
firstInstallDate = '2026-10-31T04:06:51'
firstInstallVersion = '0.9.1.4'
hostName = ''
installId = 'cd0b8465'
installVersion = '0.9.1.4'
ipAddresses = ''
loggingLevel = 'Debug'
onDeckProgressDays = 30
onDeckUpdateDays = 7
pdfRenderResolution = 1
port = 5000
statsApiHits = 0
taskBackup = 'daily'
taskCblSync = '0 4 * * *'
taskCleanup = 'daily'
taskScan = 'daily'
totalBackups = 30
totalLogs = 30

写回走 POST /api/Settings（需管理员 JWT），或直接在管理界面「系统设置」中修改。

3.4 环境变量覆盖机制实测

结论先行：0.9.1.4 不支持用环境变量覆盖业务参数。实测在裸机二进制形态实例上向服务进程注入 Port=5011 后启动：

cd /opt/kavita/Kavita && Port=5011 ./Kavita

实测日志回显（服务仍尝试绑定默认端口 5000，而非 5011）：

[Kavita] [2026-10-31 04:46:09.023 +00:00  1] [Information] Kavita.Server.Program Starting with base url as /
System.IO.IOException: Failed to bind to address http://[::]:5000: address already in use.

（address already in use 是因为该环境另有实例占用 5000，恰好证明进程读取的是既有配置而非注入的 Port=5011。）调整参数请改 appsettings.json 或运行时设置，不要依赖环境变量。

四、参数总览

4.1 appsettings.json 全参数（实测文件）

首次启动后实测文件内容（TokenKey 为首次启动自动生成的 512 位随机密钥，此处以 ${TOKEN_KEY} 占位）：

{
  "TokenKey": "${TOKEN_KEY}",
  "Port": 5000,
  "IpAddresses": "",
  "BaseUrl": "/",
  "Cache": 75,
  "AllowIFraming": false,
  "OpenIdConnectSettings": {
    "Authority": "",
    "ClientId": "kavita",
    "Secret": "",
    "CustomScopes": [],
    "Enabled": false
  }
}

💡 说明：发行包自带的初始 appsettings.json 只有 5 个键（TokenKey 占位值/Port/IpAddresses/BaseUrl/Cache）。首次启动后 Kavita 自动补写了 AllowIFraming 与 OpenIdConnectSettings 两段，并把占位 TokenKey 替换为随机生成的长密钥——这是首次启动行为，不是人工修改。

4.2 运行时设置总表（GET /api/Settings 实测）

4.3 数据目录速查

/kavita/config/
├── appsettings.json         # 启动参数（本篇 4.1）
├── kavita.db (-shm/-wal)    # 主库：账户/书库/系列/进度/运行时设置
├── cache.db (-shm/-wal)     # 缓存库
├── backups/                 # 每日备份任务产物（保留 totalBackups 份）
├── bookmarks/               # 下载与书签
├── cache/ cache-long/       # 阅读缓存与长期缓存
├── covers/                  # 封面
├── logs/                    # 运行日志 kavita<日期>.log（保留 totalLogs 份）
├── themes/ fonts/ templates/ favicons/ images/ temp/

五、核心参数分类详解

5.1 TokenKey（JWT 签名密钥）

• 首次启动自动生成（实测为 512 位随机值 base64 编码），是全站 JWT 的签名密钥，安全敏感。
• 更换 TokenKey 会使所有已签发 JWT 立即失效，所有用户需重新登录；迁移/克隆环境时保留原值可保登录态。
• 文档中以 ${TOKEN_KEY} 占位，禁止将真实值提交到代码库或文档。导出/注入方式：编辑 appsettings.json 后重启服务。

5.2 Port（监听端口）——实测双层行为

实测 0.9.1.4 中 Port 的生效逻辑与直觉不同：

1. 首次安装：appsettings.json 的 Port（默认 5000）作为初值进入设置库，服务绑定该端口。
2. 运行期：端口以设置库为准。实测把 appsettings.json 改为 "Port": 5001 并重启服务，日志仍显示：

[Kavita] [2026-10-31 04:49:29.056 +00:00  1] [Information] Kavita.Server.Program Starting with base url as /
[Kavita] [2026-10-31 04:49:29.107 +00:00  1] [Information] Microsoft.Hosting.Lifetime Now listening on: http://[::]:5000

同时 GET /api/Settings 返回 port = 5000——设置库未随文件变化。

结论：改端口请走管理界面「系统设置」或 Settings API（写设置库，重启服务后生效），直接改文件无效。

5.3 BaseUrl（子路径前缀）

默认 /。反向代理按子路径发布（如 https://example.com/kavita/）时设置为 /kavita，同时在反代上做对应路径转发。修改属于启动层参数，改完需重启服务。默认值与运行时设置 baseUrl 一致（实测均为 /）。

5.4 IpAddresses（监听地址）

默认空串，实测服务绑定 http://[::]:5000（IPv6 双栈全地址）。需要收紧监听面时在设置库（ipAddresses）中填入具体地址；该参数同时出现在启动文件与设置库，运行期以设置库为准（与 Port 同机制）。

5.5 Cache（缓存阈值）

启动层默认 75，与运行时设置 cacheSize=75 对应，用于缓存清理判定；清理动作由每日 taskCleanup 任务执行。缓存目录由 cacheDirectory 指定（默认 /kavita/config/cache）。

5.6 AllowIFraming（iframe 嵌入）

首次启动自动补写的安全项，实测默认 false（不允许被第三方页面 iframe 嵌入，降低点击劫持面）。仅在明确需要被嵌入门户时开启。

5.7 OpenIdConnectSettings（OIDC 单点登录）

启用后登录页出现 SSO 入口，本地账户体系仍保留（管理员账户兜底）。

5.8 运行时高频项

• loggingLevel：默认 Debug（实测），生产建议改 Information，日志量显著下降（日志文件在 logs/，保留 totalLogs=30 份）。
• enableOpds：默认开启；不对外提供 OPDS 时关闭。
• enableFolderWatching：默认 False。追更场景可开启，文件落盘即触发扫描；无此需求保持关闭可降低 inotify 压力。
• taskScan/taskCleanup/taskBackup：默认 daily；taskCblSync 为 cron 表达式 0 4 * * *（每日 04:00）。
• totalBackups=30：每日备份保留 30 份，磁盘紧张可下调（备份在 backups/）。

六、生产配置模板

适用场景：家庭/小团队自托管，8GB 内存、NVMe 或 SATA SSD、书库规模数万文件以内。直接替换 ${TOKEN_KEY} 后落盘 /kavita/config/appsettings.json：

{
  "TokenKey": "${TOKEN_KEY}",
  "Port": 5000,
  "IpAddresses": "",
  "BaseUrl": "/",
  "Cache": 75,
  "AllowIFraming": false,
  "OpenIdConnectSettings": {
    "Authority": "",
    "ClientId": "kavita",
    "Secret": "",
    "CustomScopes": [],
    "Enabled": false
  }
}

配套运行时设置建议（管理界面或 Settings API 修改）：

⚠️ 注意：TokenKey、OpenIdConnectSettings.Secret 属系统级密钥，落盘/入库前用 ${VAR} 占位并通过受控方式注入；本模板其余参数均为非敏感默认值。

七、常见问题

Q1：改了 appsettings.json 的 Port 为什么不生效？ 运行期端口以设置库为准，文件值仅首次初始化生效（完整实测过程见 5.2）。改端口走管理界面或 Settings API。

Q2：环境变量能覆盖参数吗？ 不能。实测向进程注入 Port=5011 后服务仍按既有配置绑定 5000（回显见 3.4）。

Q3：首次启动后 appsettings.json 怎么"多"了几个字段？ Kavita 首启自动补写 AllowIFraming、OpenIdConnectSettings 并生成随机 TokenKey（见 4.1 说明），属正常行为。

Q4：TokenKey 可以随便换吗？ 可以换，但会让全部已签发 JWT 失效、用户需重新登录；非密钥泄露场景不建议更换。

Q5：日志在哪、怎么降噪？ /kavita/config/logs/kavita<日期>.log；把运行时设置 loggingLevel 从 Debug 改为 Information。

八、参考链接

1. Kavita GitHub 仓库与源码（配置加载逻辑）：https://github.com/Kareadita/Kavita （2026-10-31 查询）
2. Kavita 官方 Wiki：https://wiki.kavitareader.com/ （2026-10-31 查询）
3. 站内部署篇（环境变量表与运维命令）：《Kavita 0.9.1.4 Docker Compose 部署指南》
4. 站内 API 篇（Settings API 调用细节）：《Kavita 0.9.1.4 REST API 使用详解》
5. 站内选型篇：《Kavita 0.9.1.4 介绍与选型指南》