KVideo 4.9.20 配置参数详解

目标：系统讲清 KVideo 4.9.20 的全部配置入口——环境变量（部署时注入）、运行时行为开关与界面内配置的边界，重点澄清官方文档未明说的两个语义陷阱（ACCESS_PASSWORD 的兜底语义、NEXT_PUBLIC_* 变量的构建期内联），核心参数语义均经 Ubuntu 22.04 实测验证。

一、环境信息

本文实测与源码核对环境：

• 操作系统：Ubuntu 22.04（x86_64）
• KVideo 版本：4.9.20（官方镜像 kuekhaoyang/kvideo:4.9.20，服务自检接口 /api/app-update 返回 currentVersion: 4.9.20，2026-10-25 实查为最新稳定版）
• 部署形态：Docker Compose 单实例，宿主端口 8131 → 应用端口 3000
• 演示管理账号：admin / q1w2e3r4
• 参数语义来源：仓库源码 lib/server/auth.ts（认证）、lib/server/redis.ts（同步）、lib/config/（部署与站点配置）、lib/auth/permissions.ts（权限），核心项均以实测回显验证
• 源码核对日期：2026-10-25

二、前置条件

1. 已按《KVideo Docker Compose 部署指南》完成基础部署并能访问 http://<服务器IP>:<端口>；
2. 理解 KVideo 的三层配置模型（见下一节），知道你要改的配置属于哪一层；
3. 修改环境变量后必须重建而非重启：docker compose up -d（compose 检测到 environment 变化会自动重建容器）；只执行 docker compose restart 不会应用新的环境变量。

三、参数查看与修改方式

KVideo 的配置分散在三个层级，修改方式与生效路径完全不同，先看清层级再动手：

服务端公开配置的自查命令（确认环境变量是否按预期生效）：

curl -s http://127.0.0.1:8131/api/auth

实测回显：

{"hasAuth":true,"hasPremiumAuth":false,"loginMode":"legacy_password","persistSession":true,"subscriptionSources":"","iptvSources":"","mergeSources":"","danmakuApiUrl":""}

字段解读：hasAuth（是否启用密码门禁）、hasPremiumAuth（是否配置了高级区密码）、loginMode（登录模式，环境变量引导账号时为 legacy_password，开启托管多账号后为 managed）、persistSession（会话持久化开关）、subscriptionSources/iptvSources/mergeSources/danmakuApiUrl（全局下发的源与弹幕配置）。

四、参数总览

环境变量按功能域分为六组，总览如下（详细语义见第五节）：

优先阅读顺序建议：认证组（决定谁能进站、进站是什么身份）→ 内容源组（决定站里有什么可看）→ 同步组（决定换设备丢不丢配置）→ 其余。

五、核心参数分类详解

5.1 认证与账号组

ADMIN_PASSWORD（推荐必设）：管理员账号密码。登录用户名固定为 admin，设置后引导出 super_admin 角色（全部 10 项权限）。同时它也是界面「仅输入密码」登录框的比对值——两种登录方式等价。

实测：管理员登录。

curl -s -X POST http://127.0.0.1:8131/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | head -c 220

实测回显（输出节选）：

{"valid":true,"session":{"accountId":"legacy-admin","profileId":"81ee72e5f0e797a4","username":"admin","name":"超级管理员","role":"super_admin","mode":"legacy"},"hasAuth":true,...

实测：仅密码登录（不带用户名，密码为 ADMIN_PASSWORD 值），获得同样身份。

curl -s -X POST http://127.0.0.1:8131/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"password":"q1w2e3r4"}' | head -c 220

实测回显（输出节选）：

{"valid":true,"session":{"accountId":"legacy-admin",...,"role":"super_admin","mode":"legacy"},...

ACCESS_PASSWORD（语义陷阱，重点）：源码中它是 ADMIN_PASSWORD 的兜底别名（getEffectiveAdminPassword() 返回 ADMIN_PASSWORD || ACCESS_PASSWORD），不是访客密码：

• ADMIN_PASSWORD 已设置时，ACCESS_PASSWORD 无论设什么值都不参与登录——实测用它的值做仅密码登录直接被拒：

curl -s -X POST http://127.0.0.1:8131/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"password":"q1w2e3r4view"}'

实测回显（该部署 ADMIN_PASSWORD=q1w2e3r4，ACCESS_PASSWORD=q1w2e3r4view）：

{"valid":false}

• 只有 ADMIN_PASSWORD 为空时，ACCESS_PASSWORD 才成为门禁密码。
• 错误密码与空请求体的服务端响应也有区别（实测）：

curl -s -X POST http://127.0.0.1:8131/api/auth -H 'Content-Type: application/json' -d '{"username":"admin","password":"wrongpass"}'
curl -s -X POST http://127.0.0.1:8131/api/auth -H 'Content-Type: application/json' -d '{}'

实测回显：

{"valid":false}
{"valid":false,"message":"Password required"}

ACCOUNTS：多账号引导串，逗号分隔多个账号，每个账号格式为 密码:昵称:角色（角色为 viewer/admin/super_admin 之一；不带角色段时按普通用户处理）。适合「家人能管理、访客只能看」的家庭站。角色与权限的对应关系由源码 lib/auth/permissions.ts 定义：super_admin 持有全部 10 项权限（源管理、账号管理、弹幕 API、数据管理、播放器设置、弹幕外观、视图设置、IPTV 访问、IPTV 源管理、IPTV 内置源）；admin 持有播放器/弹幕外观/视图/IPTV 4 域共 6 项；viewer 仅有 view_settings 一项。

💡 技术拓展：Web 应用的访问控制常见三种模型——

模型	原理	适用
单密码门禁	全站一个密码，不区分身份	个人自用
角色权限模型（RBAC）	用户→角色→权限位三级映射	家庭/小团队多账号
ACL 精细授权	逐用户逐资源授权	大型多租户

KVideo 采用第二种：三个固定角色 + 10 个权限位，引导账号写进环境变量、日常增删在管理界面完成。KVideo 实际选择的是「环境变量引导种子账号 + RBAC 权限位」的组合。

MANAGED_AUTH_ENABLED=true：强制启用托管账号体系（loginMode: managed），账号数据存于服务端（可同步层），支持界面建号、改权限，适合账号较多的场景；默认 false 走 legacy_password 模式。

AUTH_SECRET：会话 Cookie（kvideo_session）的签名密钥。留空时服务端自行生成。它的核心价值是多实例部署时保持签名一致、避免随机密钥；但不要指望它能保住重启前的登录态——实测固定 AUTH_SECRET 后执行停止再启动，重启前取得的会话 Cookie 依然失效：

curl -s -b cookies.txt http://127.0.0.1:8131/api/auth/session

实测回显（重启后用重启前的 Cookie）：

{"authenticated":false,"session":null,"hasAuth":true,"hasPremiumAuth":false,"loginMode":"legacy_password","persistSession":true,...

即服务重启后所有用户需重新登录（家庭站影响小；若做成对外服务，升级窗口应避开使用高峰）。实测会话 Cookie 形态（登录响应头，输出节选）：

set-cookie: kvideo_session=v1.eyJhY2NvdW50SWQiOiJsZWdhY3ktYWRtaW4iLCJ...; Path=/; Max-Age=2592000; HttpOnly; SameSite=lax

会话有效期 30 天（2592000 秒），HttpOnly + SameSite=lax，前端 JS 不可读取。

PERSIST_SESSION：默认 true，会话在浏览器关闭后保留；设为 false 变成会话级 Cookie，关浏览器即登出（实测该部署返回 "persistSession":true）。

PREMIUM_PASSWORD：高级内容区密码。不配置时 /api/auth 返回 "hasPremiumAuth":false（实测确认），站内高级分类入口隐藏；配置后进入高级区需单独验密。

5.2 站点标识组

NEXT_PUBLIC_* 前缀变量（语义陷阱，重点）：NEXT_PUBLIC_SITE_NAME、NEXT_PUBLIC_SITE_TITLE、NEXT_PUBLIC_SITE_DESCRIPTION 属于 Next.js 的 NEXT_PUBLIC_ 体系，在构建期内联进客户端代码。官方 Docker 镜像是通用构建产物，运行时注入这些变量对已构建的客户端界面不生效——实测该部署注入 NEXT_PUBLIC_SITE_NAME=KVideo Demo 后，页面标题仍是构建默认值：

curl -s http://127.0.0.1:8131/ | grep -oE '<title>[^<]*</title>'

实测回显：

<title>KVideo - 视频聚合平台</title>

要让 NEXT_PUBLIC_* 生效只有两条路：源码构建时注入（自建镜像），或接受默认站点名。部署时不要浪费时间在运行时调这几个变量上。

SITE_ICON_URL / SITE_ICON_FILE：自定义站点图标。URL 方式直接指向外部图片；FILE 方式指向容器内路径（配合 compose 挂载，见部署篇「配置文件挂载」一节）。

5.3 内容源下发组

这一组是「管理员统一配源、全家直接用」的关键——站长在环境变量里下发源，用户打开即用，不需要每人在自己浏览器里加源：

• SUBSCRIPTION_SOURCES：订阅源 JSON 地址（可逗号分隔多个）。订阅源是 KVideo 批量管理源列表的机制：把源清单托管成一个 JSON 文件 URL，客户端定期拉取自动更新。当前部署未配置，接口返回 "subscriptionSources":""（实测）。
• IPTV_SOURCES：全局 IPTV 源，支持 M3U 播放列表地址与 JSON 频道列表，客户端「直播」页直接展示。
• MERGE_SOURCES：同名源结果合并策略配置。
• AD_KEYWORDS / AD_KEYWORDS_FILE：屏蔽关键词（如某类目词），命中类目的内容从搜索结果中过滤；关键词多时用文件形式（配合挂载）更好维护。

⚠️ 注意：KVideo 不内置任何源，上述变量的值必须来自部署者自有授权渠道。订阅源 JSON 的字段体系遵循仓库 lib/utils/source-import-utils.ts 的导入格式（id/name/baseUrl/searchPath/detailPath 等），与界面「导入设置」的 JSON 粘贴格式一致。

5.4 数据同步组（Upstash Redis）

UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN：两者同时配置后启用服务端配置同步——用户的源配置、播放偏好按账号存入 Upstash Redis（键形如 user:config:<profileId>），实现跨浏览器/跨设备/PWA 同步。

未配置时行为（实测）：

curl -s -b cookies.txt http://127.0.0.1:8131/api/user/config

实测回显：

{"error":"Server-side sync is not configured on this deployment"}

（HTTP 503，应用其余功能完全正常。）

⚠️ 注意两个常见误解：①这里要求的是 Upstash 的 REST API 凭据（形如 https://example.upstash.io），不是自建 Redis 的 redis:// 连接串——源码使用 @upstash/redis 客户端走 HTTP 协议，自建 Redis 无法直接填入；②同步粒度是「账号级配置」，播放进度的实时续播主要仍在浏览器本地完成。

5.5 功能开关组

• VIDEOTOGETHER_ENABLED（默认 true）：「一起看」功能开关，关闭后播放页不加载 VideoTogether 集成脚本；VIDEOTOGETHER_SCRIPT_URL/VIDEOTOGETHER_SETTING_URL 可替换为自托管脚本地址。
• DANMAKU_API_URL：弹幕服务 API 地址，配置后播放页支持弹幕加载与发送；不配则弹幕入口隐藏。弹幕 API 权限位（danmaku_api）仅 super_admin 持有。

5.6 运行环境组

• NODE_ENV：保持 production（官方镜像已内置）。
• PORT/HOSTNAME：镜像内固定 PORT=3000、HOSTNAME=0.0.0.0（监听全部网卡），无需修改；对外端口调整靠 compose 的端口映射，不动这两个变量。

六、生产配置模板

以下两套按规模给出可直接落地的 environment 模板（compose 片段），按内存/磁盘/场景标注适用面：

模板 A：单人/情侣家庭站（1GB 内存即可，磁盘 1GB 级，无跨设备需求）

    environment:
      - NODE_ENV=production
      - ADMIN_PASSWORD=q1w2e3r4
      - AUTH_SECRET=change-me-to-a-long-random-string
      - PERSIST_SESSION=true

最简形态：单密码门禁 + 固定会话密钥，配置全存浏览器本地。

模板 B：家庭多用户站（2GB 内存，磁盘 2GB 级，全家共用 + 跨设备同步）

    environment:
      - NODE_ENV=production
      - ADMIN_PASSWORD=q1w2e3r4
      - ACCOUNTS=q1w2e3r4:女主人:admin,letmein:客厅电视:viewer
      - MANAGED_AUTH_ENABLED=true
      - AUTH_SECRET=change-me-to-a-long-random-string
      - SUBSCRIPTION_SOURCES=https://nas.lan/kvideo-sources.json
      - IPTV_SOURCES=https://nas.lan/iptv.m3u
      - AD_KEYWORDS=伦理
      - UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
      - UPSTASH_REDIS_REST_TOKEN=${UPSTASH_TOKEN}

模板 B 说明：ACCOUNTS 引导两个成员账号（admin 角色可管源、viewer 只能看）；源经内网地址统一下发；Upstash Token 用环境变量注入（${UPSTASH_TOKEN} 从宿主 shell export，避免明文进 compose 文件——这是系统级第三方凭据，按密钥规范占位）。

内存与资源基线（实测）：KVideo 是 Node.js 单进程应用，实测空载内存占用仅约 50 MiB（docker stats 显示 mem=49.93MiB，CPU 空闲 0.01%），无数据库子进程；1 核 1GB 的 NAS 虚拟机即可稳定承载家庭规模并发。资源敏感部署建议加 compose 资源上限（deploy.resources.limits.memory: 512m 起步）防搜索高峰内存膨胀——聚合搜索有多源超时与结果数上限保护，正常不会失控。

七、常见问题

Q1：改了 NEXT_PUBLIC_SITE_NAME 站点名没变？ 构建期内联，运行时注入无效（见 5.2 实测）。要么源码自建镜像，要么用 SITE_ICON_URL 等服务端读取的变量配合界面配置，要么接受默认名。

Q2：ACCESS_PASSWORD 设了但用它登录不上？ 它只是 ADMIN_PASSWORD 的兜底，ADMIN_PASSWORD 非空时它不参与登录（见 5.1 实测）。要给访客单独入口请用 ACCOUNTS 引导 viewer 账号。

Q3：改了环境变量不生效？ docker compose restart 不应用 environment 变更，必须 docker compose up -d 重建；重建后用 curl -s http://127.0.0.1:8131/api/auth 核对公开配置字段。

Q4：重启后所有人要重新登录？ AUTH_SECRET 没固定——服务端每次启动随机生成密钥，旧会话签名全部失效。固定一个长随机串到 AUTH_SECRET。

Q5：配置了同步但接口 503？ 503 响应体是 Server-side sync is not configured on this deployment（实测），说明 URL 与 TOKEN 没有同时配齐，或填的是 redis:// 自建地址而非 Upstash REST 地址（见 5.4）。

Q6：搜索能搜到但播放黑屏？ 配置层面先查三点：源接口是否要求自定义请求头（源配置的 headers 字段）；播放代理模式（界面播放器设置中「智能重试/仅直连/总是代理」三种，直连被 CORS 拦的源选代理模式）；浏览器控制台是否有混合内容告警（https 站点引用 http 源会被浏览器拦截）。

八、参考链接

• 官方 GitHub 仓库：https://github.com/KuekHaoYang/KVideo
• 权限模型源码：lib/auth/permissions.ts（仓库 main 分支，2026-10-25 核对）
• 本专栏相关篇目：
  • 《KVideo 介绍与选型指南》
  • 《KVideo Docker Compose 部署指南》
  • 《KVideo 日常运维手册》