配置指南
V1 可以通过环境变量、外部配置文件、项目根目录 config.js 和管理后台进行配置。
加载优先级
项目当前定义的优先级由高到低为：
- WebDAV 恢复或同步的数据。
- 环境变量。
CONFIG_PATH指定的配置文件，或项目根目录config.js。src/defaultConfig.ts内置默认值。
如果某个值由环境变量固定，管理后台修改后可能在服务重启时再次被环境变量覆盖。生产环境建议把关键网络和密码配置保留在 Docker 环境变量中。
网络与路径
| 环境变量 | 配置项 | 默认值 | 说明 |
|---|---|---|---|
PORT | port | 9527 | 服务端口 |
BIND_IP | bindIP | 0.0.0.0 | 监听地址 |
SERVER_NAME | serverName | yinyun | 服务名称 |
ADMIN_PATH | admin.path | 空 | 管理后台路径，空表示 / |
PLAYER_PATH | player.path | /music | Web 播放器路径 |
SUBSONIC_PATH | subsonic.path | /rest | Subsonic API 路径 |
PROXY_HEADER | proxy.header | x-real-ip | 反向代理真实 IP 请求头 |
CONFIG_PATH | - | 空 | 外部 config.js 绝对路径 |
DATA_PATH | - | ./data | 服务数据目录 |
LOG_PATH | - | ./logs | 日志目录 |
账户与访问控制
| 环境变量 | 配置项 | 默认值 | 说明 |
|---|---|---|---|
FRONTEND_PASSWORD | frontend.password | 123456 | 管理后台密码 |
USER_ENABLE_ROOT | user.enableRoot | true | 允许使用根地址连接 LX 同步 |
USER_ENABLE_PATH | user.enablePath | false | 允许使用 /用户名 地址连接 |
ENABLE_WEBPLAYER_AUTH | player.enableAuth | false | 启用播放器入口密码 |
WEBPLAYER_PASSWORD | player.password | 123456 | 播放器入口密码 |
LX_USER_<用户名> | users | - | 启动时预置同步账户 |
根路径与用户名路径只决定同步连接如何定位用户，不会关闭用户数据隔离。根路径依赖密码识别账户，因此用户密码必须唯一；用户名路径会同时校验路径和凭据。
缓存与歌单
| 环境变量 | 配置项 | 默认值 | 说明 |
|---|---|---|---|
MAX_SNAPSHOT_NUM | maxSnapshotNum | 10 | 最大历史快照数 |
ENABLE_LOGIN_USER_CACHE_RESTRICTION | user.enableLoginCacheRestriction | false | 限制非管理员修改核心缓存设置 |
ENABLE_CACHE_SIZE_LIMIT | user.enableCacheSizeLimit | false | 启用缓存容量限制 |
CACHE_SIZE_LIMIT | user.cacheSizeLimit | 2000 | 每用户缓存上限，单位 MB |
LIST_ADD_MUSIC_LOCATION_TYPE | list.addMusicLocationType | top | 新歌曲添加到列表顶部或底部 |
缓存限制只用于可再生成的缓存内容。下载曲库 /music 不应被 LRU 自动清理。
WebDAV
| 环境变量 | 配置项 | 默认值 |
|---|---|---|
WEBDAV_ENABLE | webdav.enable | false |
WEBDAV_URL | webdav.url | 空 |
WEBDAV_USERNAME | webdav.username | 空 |
WEBDAV_PASSWORD | webdav.password | 空 |
WEBDAV_SYNC_PATH | webdav.syncPath | /lx-sync |
WEBDAV_BACKUP_PATH | webdav.backupPath | /lx-sync-backups |
SYNC_INTERVAL | sync.interval | 60 分钟 |
BACKUP_INTERVAL | sync.backupInterval | 24 小时 |
WebDAV 密码建议使用服务商提供的应用专用密码。恢复操作会覆盖本地相关数据，执行前先确认远端备份版本。
代理与隐私
| 环境变量 | 配置项 | 默认值 | 说明 |
|---|---|---|---|
PROXY_ALL_ENABLED | proxy.all.enabled | false | 服务端外发请求使用代理 |
PROXY_ALL_ADDRESS | proxy.all.address | 空 | HTTP 或 SOCKS5 代理地址 |
DISABLE_TELEMETRY | disableTelemetry | false | 禁用匿名统计及相关远程通知 |
Docker 容器中的 127.0.0.1 不等于 NAS 主机。代理位于主机时使用容器可访问的主机地址。
Subsonic
| 环境变量 | 配置项 | 默认值 |
|---|---|---|
SUBSONIC_ENABLE | subsonic.enable | true |
SUBSONIC_PATH | subsonic.path | /rest |
以下高级项当前通过 config.js 或后台配置：
| 配置项 | 默认值 | 说明 |
|---|---|---|
subsonic.enableDebug | true | 记录 Subsonic 调试日志 |
subsonic.onlineSearch | true | 开启在线搜索 |
subsonic.onlineSearchMode | fallback | fallback、merge 或 local_only |
subsonic.onlineSearchSources | wy,tx,kw,kg,mg | 在线搜索平台顺序 |
subsonic.lyricTranslation | true | 返回翻译歌词 |
业务高级项
| 环境变量或配置项 | 默认值 | 说明 |
|---|---|---|
SINGER_SOURCE_PRIORITY / singer.sourcePriority | tx,wy | 歌手详情来源优先级 |
artist.maxFetchPages | 20 | 歌手歌曲最大抓取页数 |
cache.namingPattern | simple | 下载文件命名规则 |
system.allowUnsafeVM | false | 允许不安全原生 VM 音源模式 |
system.allowUnsafeVM 只应在确认脚本可信且沙箱模式不兼容时启用。
Docker 环境变量示例
yaml
environment:
NODE_ENV: production
FRONTEND_PASSWORD: "replace-admin-password"
USER_ENABLE_ROOT: "true"
USER_ENABLE_PATH: "false"
ENABLE_WEBPLAYER_AUTH: "false"
SUBSONIC_ENABLE: "true"
PROXY_ALL_ENABLED: "false"修改环境变量后需要重建容器：
bash
docker compose up -d --force-recreate