gonic 配置参数详解

目标：把 gonic v0.23.0 的全部配置项讲透——三通道配置体系（命令行参数 / 环境变量 / 配置文件）的优先级实测、29 个参数的逐项详解（含默认值、类型、环境变量对照）、关键参数改值+重启的回显验证。本文基于 2026-10-28 在 Ubuntu 24.04 服务器上对 sentriz/gonic:v0.23.0 的逐行实测。部署全流程见本专栏《gonic Docker Compose 部署实战》，产品背景见《gonic 介绍与选型指南》，运维操作见《gonic 常用命令与运维实战（核心篇）》。

一、配置体系总览

本章先建立全局认知：gonic 没有庞大的配置文件生态，全部配置收敛为 29 个参数项，通过三条通道注入，优先级有明确的先后关系。

1.1 三条配置通道与优先级实测

gonic 支持命令行参数（-scan-interval 30）、环境变量（GONIC_SCAN_INTERVAL=20）、配置文件（-config-path 指向的文本文件）三通道混用。优先级结论先行：命令行参数 > 环境变量 > 配置文件 > 内置默认值。以下是实测证据——三通道同时给 scan-interval 赋不同值：

# 配置文件 /tmp/gonic.conf 内容：scan-interval 15；同时注入环境变量 20、命令行 30
$ cat /tmp/gonic.conf
scan-interval 15
http-log false
exclude-pattern (?i)test
$ gonic -config-path /tmp/gonic.conf -scan-interval 30 ... # 环境 GONIC_SCAN_INTERVAL=20
2026/10/28 21:34:49     scan-interval                  30    # 命令行胜出
$ # 去掉命令行，只留 环境20 vs 文件15：
2026/10/28 21:33:41     scan-interval                  20    # 环境变量胜出
$ # 去掉环境变量，只留文件：
2026/10/28 21:34:30     scan-interval                  15    # 文件生效

三轮实验分别由命令行（30）、环境变量（20）、配置文件（15）生效，优先级链一目了然。日常用 Docker Compose 部署时固定在环境变量通道即可；配置文件通道适合 systemd 直管二进制的场景。

1.2 环境变量命名规则

换算规则：参数名转大写 → 短横线 - 换成下划线 _ → 加 GONIC_ 前缀。对照示例：

命令行参数	环境变量
`-music-path`	`GONIC_MUSIC_PATH`
`-scan-at-start-enabled`	`GONIC_SCAN_AT_START_ENABLED`
`-scan-interval`	`GONIC_SCAN_INTERVAL`
`-jukebox-enabled`	`GONIC_JUKEBOX_ENABLED`
`-tls-cert`	`GONIC_TLS_CERT`

多值型参数（music-path、multi-value-*）在环境变量里用逗号分隔多个值。

1.3 查看全部参数：gonic --help 原文

在运行实例内执行 gonic --help 可得权威参数清单（v0.23.0 实测全文照抄）：

Usage of gonic:
  -cache-path string
    	path to cache
  -config-path string
    	path to config (optional)
  -cover-cache-size int
    	size of the cover art cache in MB (0 = no limit) (optional)
  -cover-eject-interval int
    	interval (in minutes) to eject cover art cache (0 = never) (optional)
  -db-path string
    	path to database (optional) (default "gonic.db")
  -exclude-pattern string
    	regex pattern to exclude files from scan (optional)
  -expvar
    	enable the /debug/vars endpoint (optional)
  -genre-split string
    	(deprecated, see multi-value settings)
  -genre-tree string
    	path to a tab-separated genre tree file for hierarchical genre browsing (optional)
  -http-log
    	http request logging (optional) (default true)
  -jukebox-enabled
    	whether the subsonic jukebox api should be enabled (optional)
  -jukebox-mpv-extra-args string
    	extra command line arguments to pass to the jukebox mpv daemon (optional)
  -listen-addr string
    	listen address (optional) (default "0.0.0.0:4747")
  -log-db
    	enable database query logging (optional)
  -multi-value-album-artist value
    	setting for multi-valued album artist scanning (optional)
  -multi-value-artist value
    	setting for multi-valued track artist scanning (optional)
  -multi-value-genre value
    	setting for multi-valued genre scanning (optional)
  -multi-value-isrc value
    	setting for multi-valued isrc scanning (optional)
  -music-path value
    	path to music
  -playlists-path string
    	path to your list of new or existing m3u playlists that gonic can manage
  -podcast-path string
    	path to podcasts
  -podcast-purge-age uint
    	age (in days) to purge podcast episodes if not accessed (optional)
  -pprof
    	enable the /debug/pprof endpoint (optional)
  -proxy-prefix string
    	url path prefix to use if behind proxy. eg '/gonic' (optional)
  -scan-at-start-enabled
    	whether to perform an initial scan at startup (optional)
  -scan-embedded-cover-enabled
    	whether to scan for embedded covers in audio files (optional) (default true)
  -scan-interval uint
    	interval (in minutes) to automatically scan music (optional)
  -scan-watcher-enabled
    	whether to watch file system for new music and rescan (optional)
  -tls-cert string
    	path to TLS certificate (optional)
  -tls-key string
    	path to TLS private key (optional)
  -transcode-cache-size int
    	size of the transcode cache in MB (0 = no limit) (optional)
  -transcode-eject-interval int
    	interval (in minutes) to eject transcode cache (0 = never) (optional)
  -version
    	show gonic version

下面按用途分七组逐项详解，每项给出默认值（实测启动回显）与配置建议。启动时 gonic 会把全部生效值打印在 provided config 段，那是核对配置的权威现场。

二、路径与存储类参数

本章讲清六个路径参数——它们是部署时最先要确定的一组。

参数	环境变量	默认值	说明
`-music-path`	`GONIC_MUSIC_PATH`	无（必填）	音乐库根目录，可多次指定实现多音乐库；支持 `别名->路径` 语法起别名，环境变量方式用逗号分隔
`-playlists-path`	`GONIC_PLAYLISTS_PATH`	无	m3u 播放列表目录，gonic 可管理（新建/更新）其中的列表，需可写
`-podcast-path`	`GONIC_PODCAST_PATH`	无	播客剧集下载存放目录，需可写
`-cache-path`	`GONIC_CACHE_PATH`	无	封面缩放产物与转码产物的缓存目录，需可写
`-db-path`	`GONIC_DB_PATH`	`gonic.db`	SQLite 数据库文件路径，gonic 的全部状态都在此文件
`-config-path`	`GONIC_CONFIG_PATH`	空	配置文件路径（可选），格式为每行 `参数名值`

要点实测：

路径不存在会直接拒绝启动。实测把播客目录指向不存在的 /tmp/pc，启动即失败：2026/10/28 21:33:25 checking podcast directory: path does not exist, please provide one。挂载失效（如磁盘未挂载）时的报错就是这个形态，看到它先查挂载点；
music-path 是唯一必填项，其余路径缺省时功能对应关闭（如不配 podcast-path 则播客功能不可用）；
db-path 建议显式指定到独立数据目录（如 /data/gonic.db），备份时目标明确——备份实测见《gonic 常用命令与运维实战（核心篇）》。

三、扫描类参数

本章详解控制「曲库扫描」这一核心链路的五个参数。

参数	环境变量	默认值	说明
`-scan-at-start-enabled`	`GONIC_SCAN_AT_START_ENABLED`	`false`	启动后立即执行一次全量扫描
`-scan-interval`	`GONIC_SCAN_INTERVAL`	`0`（分钟，0=关闭）	定时自动扫描间隔
`-scan-watcher-enabled`	`GONIC_SCAN_WATCHER_ENABLED`	`false`	监视音乐目录文件系统变动，有变更自动增量扫描
`-scan-embedded-cover-enabled`	`GONIC_SCAN_EMBEDDED_COVER_ENABLED`	`true`	扫描时读取音频内嵌封面
`-exclude-pattern`	`GONIC_EXCLUDE_PATTERN`	空	扫描排除正则，命中的文件不入库

配置建议：三选一即可——低曲库变动频率用 scan-at-start + 手动触发；固定节奏更新用 scan-interval（如 60 分钟）；实时性要求高用 scan-watcher（依赖 inotify，网络挂载盘如 NFS/SMB 上事件不可靠，慎用）。三者可叠加。exclude-pattern 改值实测见第九章 9.4 节（6 轨 → 4 轨 → 恢复 6 轨的完整过程）。

四、缓存类参数

本章讲封面与转码两类缓存的容量控制。

参数	环境变量	默认值	说明
`-cover-cache-size`	`GONIC_COVER_CACHE_SIZE`	`0`（MB，0=不限）	封面缓存容量上限
`-cover-eject-interval`	`GONIC_COVER_EJECT_INTERVAL`	`0`（分钟，0=从不）	封面缓存定时清理间隔
`-transcode-cache-size`	`GONIC_TRANSCODE_CACHE_SIZE`	`0`（MB，0=不限）	转码产物缓存容量上限
`-transcode-eject-interval`	`GONIC_TRANSCODE_EJECT_INTERVAL`	`0`（分钟，0=从不）	转码缓存定时清理间隔

两类缓存都在 cache-path 目录下（实测机上为 cache/covers/ 与 cache/audio/）。容量上限与定时清理是两种独立的回收策略，可单用可叠加；默认全不限，曲库大且客户端常转码时缓存会持续增长，建议至少给一个容量上限（改值回显见 9.2 节）。

五、网络与安全类参数

本章讲监听地址、反向代理、TLS 与访问日志四个参数。

参数	环境变量	默认值	说明
`-listen-addr`	`GONIC_LISTEN_ADDR`	`0.0.0.0:4747`	监听地址；官方制品内改为 `:80`
`-proxy-prefix`	`GONIC_PROXY_PREFIX`	`/`	反代子路径前缀，如 `/gonic`，配合 Nginx 等反代按路径分流时使用
`-tls-cert`	`GONIC_TLS_CERT`	空	TLS 证书文件路径，与 `-tls-key` 成对配置后 gonic 直接以 HTTPS 对外服务
`-tls-key`	`GONIC_TLS_KEY`	空	TLS 私钥文件路径
`-http-log`	`GONIC_HTTP_LOG`	`true`	每个 HTTP 请求打一行访问日志

要点：listen-addr 默认值 0.0.0.0:4747 是源码/直装形态的默认；官方制品 sentriz/gonic 在实例内默认注入 GONIC_LISTEN_ADDR=:80（实测启动回显为 :80），映射端口时以 80 为准。TLS 二选一：要么 gonic 直出 HTTPS（配 cert/key），要么前置反代终止 TLS（配 proxy-prefix），不必叠加。http-log 关闭前后的日志对比实测见 9.5 节。

六、功能开关类参数

本章讲四个按需开启的进阶开关。

参数	环境变量	默认值	说明
`-jukebox-enabled`	`GONIC_JUKEBOX_ENABLED`	`false`	开启 Subsonic jukebox API，服务端经 mpv 向本机声卡外放音频
`-jukebox-mpv-extra-args`	`GONIC_JUKEBOX_MPV_EXTRA_ARGS`	空	传给 jukebox mpv 守护进程的额外命令行参数
`-expvar`	`GONIC_EXPVAR`	`false`	开放 `/debug/vars` 端点（Go expvar 运行时指标）
`-pprof`	`GONIC_PPROF`	`false`	开放 `/debug/pprof` 端点（Go 性能剖析）
`-log-db`	`GONIC_LOG_DB`	`false`	打印每条 SQL 查询及耗时，排障利器

jukebox 需要宿主有声卡并把 /dev/snd 映射进运行实例（官方制品已内置 mpv）；开启后的回显与限制见 9.3 节。expvar/pprof 面向开发调试，生产一般不开。log-db 开启后日志会刷出全部 SQL（实测见 9.5 节），仅排障时临时开启。

七、标签解析类参数

本章讲多值标签与流派树的六个参数——它们决定「按标签浏览」的索引形态。

参数	环境变量	默认值	说明
`-multi-value-album-artist`	`GONIC_MULTI_VALUE_ALBUM_ARTIST`	`none`	专辑艺术家多值处理：`multi` / `delim <分隔符>` / `none`
`-multi-value-artist`	`GONIC_MULTI_VALUE_ARTIST`	`none`	音轨艺术家多值处理，同上
`-multi-value-genre`	`GONIC_MULTI_VALUE_GENRE`	`none`	流派多值处理，同上
`-multi-value-isrc`	`GONIC_MULTI_VALUE_ISRC`	`none`	ISRC 码多值处理，同上
`-genre-split`	`GONIC_GENRE_SPLIT`	空	已废弃，被 multi-value 系列取代
`-genre-tree`	`GONIC_GENRE_TREE`	空	制表符分隔的流派层级树文件，实现层级化流派浏览

💡 技术拓展：多值标签（multi-valued tags）指一条音轨同属多个流派或多位艺术家的元数据形态。三种模式的选择逻辑：用 MusicBrainz Picard / beets 规范刮削过的曲库选 multi（直接读多值字段）；标签里用分隔符拼接的选 delim ;（竖线 | 也行，避免 & 这类高频字符误拆）；未整理的曲库保持 none。改动后需全量重扫才生效。

八、播客与杂项参数

参数	环境变量	默认值	说明
`-podcast-purge-age`	`GONIC_PODCAST_PURGE_AGE`	`0`（天，0=不清理）	按「最后访问时间」清理超过 N 天未访问的播客剧集
`-version`	无	—	打印版本号后退出（实测输出 `v0.23.0`）

podcast-purge-age 开启后后台会多一个 podcast purge 定时任务（实测回显见 9.2 节），磁盘紧张且播客订阅多的场景建议设为 30 天量级。

九、关键参数改值重启实测

本章把上文关键参数真正改一遍，用「启动回显 + 日志行为 + API 计数」三重证据验证生效。基准编排见《gonic Docker Compose 部署实战》，以下改动均在 environment: 段追加环境变量后 docker compose up -d --force-recreate 重建生效。

9.1 扫描任务组：scan-interval + scan-watcher

追加 GONIC_SCAN_INTERVAL=10 与 GONIC_SCAN_WATCHER_ENABLED=true，重建后启动日志回显：

2026/10/28 21:17:40     scan-interval                  10
2026/10/28 21:17:40     scan-watcher-enabled           true

后台任务列表同步多出两个新 job（对比默认启动只有 scan at start）：

2026/10/28 21:17:40 starting job "scan watcher"
2026/10/28 21:17:40 starting job "scan timer"

scan timer 即 10 分钟定时扫描器，scan watcher 即文件系统监视器——参数→回显→任务三者闭环，确认生效。

9.2 缓存上限与播客清理

追加 GONIC_COVER_CACHE_SIZE=100、GONIC_TRANSCODE_CACHE_SIZE=256、GONIC_PODCAST_PURGE_AGE=30，回显：

2026/10/28 21:17:40     cover-cache-size               100
2026/10/28 21:17:40     transcode-cache-size           256
2026/10/28 21:17:40     podcast-purge-age              30
2026/10/28 21:17:40 starting job "podcast purge"

podcast purge 定时任务随 podcast-purge-age 非零而出现；缓存容量值直接在回显中生效。

9.3 jukebox 开关

追加 GONIC_JUKEBOX_ENABLED=true，回显与任务：

2026/10/28 21:17:40     jukebox-enabled                true
2026/10/28 21:17:40 starting job "jukebox"

开关即时生效、jukebox 守护任务启动。注意本实测机无 /dev/snd 声卡设备，jukebox 任务虽启动但实际外放需要声卡映射；这正好说明开关生效 ≠ 链路可用，外放类功能要连同硬件映射一起验收。

9.4 exclude-pattern 排除实测

追加 GONIC_EXCLUDE_PATTERN=(?i)synth（忽略大小写排除路径含 synth 的文件，会命中演示专辑「Synth Waves」），重建后启动扫描结果：

2026/10/28 21:18:13     exclude-pattern                (?i)synth
2026/10/28 21:18:13 finished scan in 20.52ms, +0/4 tracks (0 err)

API 侧确认音轨总数从 6 降到 4：

$ curl -s "http://127.0.0.1:8137/rest/getScanStatus.view?u=admin&t=...&s=...&v=1.16.1&c=curltest&f=json"
{"subsonic-response":{...,"scanStatus":{"scanning":false,"count":4}}}

删掉该环境变量再重建，扫描恢复 +2/6 tracks、count 回到 6——排除规则是「扫描期过滤」，不删数据，撤掉规则重扫即恢复。

9.5 日志开关：http-log 与 log-db

追加 GONIC_HTTP_LOG=false 与 GONIC_LOG_DB=true，重建后回显：

2026/10/28 21:18:33     http-log                       false
2026/10/28 21:18:33     log-db                         true

随后调一次 getArtists，日志里没有任何 response 200 GET ... 访问行（grep -c 'response ' 结果为 0），取而代之的是逐条 SQL 及耗时：

2026/10/28 21:18:38 query 262.435µs "SELECT * FROM \"users\"  WHERE (name=?) ORDER BY \"users\".\"id\" ASC LIMIT 1"
2026/10/28 21:18:38 query 850.596µs "SELECT artists.*, count(album_credits.album_id) album_count, ... FROM \"artists\" JOIN album_credits ON album_credits.artist_id=artists.id ... GROUP BY artists.id ORDER BY artists.name COLLATE NOCASE"
2026/10/28 21:18:38 query 122.849µs "SELECT * FROM \"artist_stars\"  WHERE (\"artist_id\" IN (?,?)) AND (user_id=?)"

一次 getArtists 实际拆了 6 条 SQL（查用户、查艺术家聚合、查收藏、查评分、查信息），log-db 是定位慢查询与理解 gonic 内部行为的直接窗口；排完障记得关回，生产常驻会显著放大日志量。

十、配置文件方式

本章补全第三通道的用法。配置文件为纯文本，每行一条 参数名值（空格分隔，不带前导短横线），用 -config-path 或 GONIC_CONFIG_PATH 指入：

$ cat /tmp/gonic.conf
scan-interval 15
http-log false
exclude-pattern (?i)test
$ gonic -config-path /tmp/gonic.conf -listen-addr :9998 -db-path /tmp/t2.db ...
2026/10/28 21:34:30     exclude-pattern                (?i)test
2026/10/28 21:34:30     http-log                       false
2026/10/28 21:34:30     scan-interval                  15

三行全部生效（实测回显）。结合 1.1 节的优先级实测，落地建议：Docker Compose 形态统一用环境变量通道（编排文件即配置的事实来源）；二进制直装形态用配置文件通道（systemd 单元里只留 -config-path）；命令行通道留给一次性调试（如临时 -log-db）。

十一、小结

本文完整覆盖了 gonic v0.23.0 的 29 个配置项：三通道优先级（命令行 > 环境变量 > 配置文件 > 默认值）经三轮对照实测坐实；路径/扫描/缓存/网络/开关/标签/播客七组参数逐项给出默认值与配置建议；九组关键参数全部做了「改值 → 重建 → 回显/日志/API 三重验证」。部署基线见《gonic Docker Compose 部署实战》，备份恢复与升级见《gonic 常用命令与运维实战（核心篇）》。