Audioserve 配置参数详解
Audioserve 0.30.1 全参数详解：命令行/YAML/环境变量三通道与 --print-config 全默认值实查，认证密钥、监听 TLS、集合缓存与目录级选项、章节呈现、转码三档与 16kbps 自定义实测、播放位置备份恢复、图标缓存与排障实录。
Audioserve 配置参数详解
目标：把 Audioserve 的整套配置体系一次讲透——命令行参数、YAML 配置文件、环境变量三条通道，认证/监听/集合缓存/章节/转码/播放位置备份/图标缓存各组参数的默认值与实测行为。本文所有参数表以 v0.30.1（2026-10-28 实查）的
--help、--print-config、--help-dir-options、--help-tags真实回显为准，关键参数附实测验证；部署编排见《Audioserve Docker Compose 部署实战》。
一、环境信息
| 项目 | 取值 |
|---|---|
| 实测日期 | 2026-10-28 |
| 版本 | audioserve 0.30.1 #561370e (22.05.2026 01:40:12)，镜像 izderadicka/audioserve:latest |
| 取证方式 | audioserve --help（122 行）、--help-dir-options、--help-tags、--print-config 逐行实查；自定义转码配置、TLS、环境变量注入均实测 |
| 配置文件 | YAML 格式，-g/--config 指定（环境变量 AUDIOSERVE_CONFIG） |
二、三条配置通道与优先级
- 命令行参数（本文主体）：
audioserve [OPTIONS] [BASE_DIRS]...，每个参数都有同名环境变量（如-s/--shared-secret↔AUDIOSERVE_SHARED_SECRET），环境变量在命令行参数缺席时生效； - YAML 配置文件：
-g /path/to/config.yaml，承载命令行覆盖不了的细粒度结构（转码三档参数、线程池）；--print-config能把"当前生效配置"（含默认值与已传参数合并结果）打印成 YAML，官方定位就是"生成配置文件的起步模板"； - 环境变量：适合容器/服务注入敏感项（共享密钥），不在进程参数中暴露。
一个实用工作流：先用最短命令行启动，加 --print-config 看合并后的完整配置，把想固化的部分抄进 YAML，之后命令行只留 -g 与可能变化的参数。
--print-config 实测回显（./audioserve -s mypass --tags --print-config /tmp/collection，这本身也是生成配置模板的命令）：
listen: 0.0.0.0:3000
thread_pool:
num_threads: 8
queue_size: 100
keep_alive: null
base_dirs:
- /tmp/collection
base_dirs_options: {}
url_path_prefix: null
shared_secret: mypass
limit_rate: null
transcoding:
max_parallel_processes: 12
max_runtime_hours: 24
low:
opus-in-ogg:
bitrate: 32
compression_level: 5
cutoff: SuperWideBand
mono: true
medium:
opus-in-ogg:
bitrate: 48
compression_level: 8
cutoff: SuperWideBand
mono: false
high:
opus-in-ogg:
bitrate: 64
compression_level: 10
cutoff: FullBand
mono: false
alt_configs: null
token_validity_hours: 8760
secret_file: /home/audioserve/.audioserve/audioserve.secret
client_dir: client/dist
cors: null
ssl: null
allow_symlinks: false
search_cache: false
disable_folder_download: false
chapters:
from_duration: 0
duration: 30
no_dir_collaps: false
ignore_chapters_meta: false
positions:
ws_timeout:
secs: 600
nanos: 0
backup_file: null
restore: None
backup_schedule: null
behind_proxy: false
collections_cache_dir: /home/audioserve/.audioserve/col_db
tags:
- artist
- composer
- genre
- album
- performer
- title
- date
force_cache_update_on_init: false
natural_files_ordering: true
static_resource_cache_age: null
folder_file_cache_age: 86400
collapse_cd_folders: null
icons:
cache_dir: /home/audioserve/.audioserve/icons-cache
cache_max_size: 100
cache_max_files: 1024
cache_disabled: false
size: 128
cache_save_often: false
fast_scaling: false
time_to_folder_end: 10
read_playlist: false
collections_options:
dont_watch_for_changes: false
changes_debounce_interval: 10
compress_responses: false
（max_parallel_processes: 12 是默认规则 2 × CPU 核数 在 6 核实测机上的结果；token_validity_hours: 8760 即 365 天。）
三、认证与密钥
| 参数（环境变量） | 默认 | 说明与实测 |
|---|---|---|
-s / --shared-secret（AUDIOSERVE_SHARED_SECRET） | 无 | 共享密钥，客户端认证的唯一样式。不传它也不传密钥文件时服务启动会报密钥相关错误；生产建议 ≥14 字符 |
--shared-secret-file | 无 | 从文件读密钥，官方注释"slightly safer"，适合 compose secret 挂载 |
--no-authentication（AUDIOSERVE_NO_AUTHENTICATION） | 关 | 完全免认证，官方帮助原文 "mainly for testing purposes"——公网严禁 |
--token-validity-days（AUDIOSERVE_TOKEN_VALIDITY_DAYS） | 365（最小 10） | 认证 token 有效期；print-config 中表现为 token_validity_hours: 8760 |
--secret-file（AUDIOSERVE_SECRET_FILE） | $HOME/.audioserve/audioserve.secret | 服务端自身的哈希盐文件，不存在则自动生成（mode 600，32 字节，实测）；删掉它等于强制所有旧 token 失效 |
--limit-rate（AUDIOSERVE_LIMIT_RATE） | 不限 | 每秒 HTTP 请求数上限，超限返回 429，防 DDoS 亦防自己 |
--cors / --cors-regex（AUDIOSERVE_CORS*） | 关闭 | 跨域放行；正则只放行匹配来源。第三方 Web 客户端跨域调用 API 时需要 |
实测要点：认证失败返回 401 JSON {"error":"Unauthorized","details":"Authentication failed"}；换发 token（POST /authenticate，简单模式传明文密钥、加盐模式传 盐|sha256(密钥+盐)）后，用 Authorization: Bearer 头或 audioserve_token cookie 访问。
四、监听、TLS 与反代
| 参数（环境变量） | 默认 | 说明与实测 |
|---|---|---|
-l / --listen（AUDIOSERVE_LISTEN） | 0.0.0.0:3000 | address:port；Docker 形态保持默认并在 compose 里映射宿主端口即可 |
--ssl-key / --ssl-cert（AUDIOSERVE_SSL_KEY/CERT） | 无 | PEM 证书启用 HTTPS（rustls 实现，编译特性 tls 默认在列）。实测自签证书对：启动日志出现 listening ... with TLS，curl -k https://127.0.0.1:3003/ 返回 200；对同一端口走纯 HTTP 则连接失败（协议不匹配即断开，无降级） |
--url-path-prefix（AUDIOSERVE_URL_PATH_PREFIX） | none | 反代路径前缀部署，要求以 / 开头、不以 / 结尾 |
--behind-proxy（AUDIOSERVE_BEHIND_PROXY） | false | 声明处于反代之后，用于日志记录真实客户端 IP |
--compress-responses（AUDIOSERVE_COMPRESS_RESPONSES） | false | 响应体 gzip 压缩（API JSON 收益明显，音频流无意义） |
官方安全建议：公网部署优先"反代终止 TLS"或内置证书二选一；浏览器直连场景下 HTTP/2 会随 TLS 自动启用（反代场景取决于代理的 h2 支持与转发头）。
五、集合目录（BASE_DIRS）与缓存
全局参数：
| 参数（环境变量） | 默认 | 说明 |
|---|---|---|
[BASE_DIRS]...（AUDIOSERVE_BASE_DIRS） | 必填 | 一个或多个集合根目录，多目录即多集合（客户端可切换）。位置参数，放在命令最后 |
--force-cache-update（AUDIOSERVE_FORCE_CACHE_UPDATE） | false | 启动时强制全量重建集合缓存 |
--dont-watch-for-changes（AUDIOSERVE_DONT_WATCH_FOR_CHANGES） | false | 关闭 inotify 目录变更监听（关闭后新文件需重启才可见） |
--changes-debounce-interval（AUDIOSERVE_CHANGES_DEBOUNCE_INTERVAL） | 10 秒 | inotify 原始事件防抖间隔；实测投递新书后约 13 秒内可被搜索命中 |
--allow-symlinks（AUDIOSERVE_ALLOW_SYMLINKS） | false | 跟随符号链接（按需开，防目录环） |
--no-natural-files-ordering（AUDIOSERVE_NO_NATURAL_FILES_ORDERING） | false | 关闭自然排序（默认按文件名首个数字排序，即 001 < 002 < 010） |
--read-playlist（AUDIOSERVE_READ_PLAYLIST） | false | 用目录内 .m3u/.m3u8 播放列表决定文件与顺序 |
集合缓存落点：--data-dir（默认 $HOME/.audioserve）下的 col_db/（sled 键值库，print-config 中 collections_cache_dir）。缓存仅加速浏览/搜索并承载标签与播放位置，重建无风险（音频本体只读引用）。
目录级选项（--help-dir-options 全文回显，追加在目录路径后，: 分隔、, 连接、= 赋值）：
/my/audio:no-cache
/other/audio:ignore-chapters-meta=false,allow-symlinks,no-dir-collaps=true,tags=title+album+artist
Available options:
nc or no-cache <=true|false> directory will not use cache (browsing and search will be
slower for large collection, playback position sharing and metadata tags
will not work)
force-cache-update <=true|false> always do full cache update on start
ignore-chapters-meta <=true|false> ignore chapters metadata in audio files. Instead present as
one big audio file
allow-symlinks <=true|false> follow symbolic links
no-dir-collaps <=true|false> do not collaps directories with single chapterized audio file
chapters-duration =x duration (mins) of chapter for cutting of large audio files
chapters-from-duration =x min.duration (mins) of large audio file to be cut to chapters
tags =tag1+tag2... metadata tags to collect (supported tags names separated by +)
default-tags <=true|false> collect default tags. Use --help-tags argument to get more
information about supported metadata tags
read-playlist <=true|false> will use .m3u playlist in folder to read audio file
(only files in playlist are available and in its order)
collapse-cd-folder-regex =regex regex used to identify and collapse CD folders
(folders like CD1, CD2 will be merged to parent folder)
dont-watch or no-watch <=true|false> will not watch for changes in this collection
changes-debounce or
changes-debounce-interval,
debounce-interval =n number of seconds to debounce raw events from inotify. Basically limits updates while
still collection directories changes.
元数据标签（--help-tags 要点回显）：--tags 采集预选标签 album, artist, composer, date, genre, performer, title；--tags-custom 逗号分隔自选，可用集合含 album_artist, comment, copyright, creation_time, disc, encoder, encoded_by, filename, language, publisher, service_name, service_provider, track, variant_bitrate, series, series_sequence, show, episode_id, season_number 等。文件夹级 tags 要求"整目录音频标签一致"，逐文件不同的标签落在文件级。官方警告：改动 tags 参数必须全量重扫缓存（编译特性 tags）。
六、章节与目录呈现
| 参数（环境变量） | 默认 | 说明 |
|---|---|---|
--chapters-from-duration（AUDIOSERVE_CHAPTERS_FROM_DURATION） | 0（禁用） | 超过 x 分钟的单文件按时长虚拟切章（不物理切分） |
--chapters-duration（AUDIOSERVE_CHAPTERS_DURATION） | 30 分钟 | 每个虚拟章节时长 |
--ignore-chapters-meta（AUDIOSERVE_IGNORE_CHAPTERS_META） | false | 忽略 m4b 等内嵌章节元数据（整书按单文件呈现） |
--no-dir-collaps（AUDIOSERVE_NO_DIR_COLLAPS） | false | 禁止"单章节化音频文件所在目录"的自动折叠 |
--collapse-cd-folders / --cd-folder-regex（AUDIOSERVE_COLLAPSE_CD_FOLDERS*） | 关闭 | 把 CD1/CD2 类子目录合并进书目录；正则可自定义 |
--time-to-folder-end（AUDIOSERVE_TIME_TO_FOLDER_END） | 10 秒 | 距最后一章结尾多少秒内即标记全书 finished |
实测确认的三种章节来源均独立生效：m4b 内嵌章节（files[].section 返回章节表，Web 端呈现虚拟章节文件）、同名 .mp3.chapters CSV 侧车文件、--chapters-from-duration 时长切分。
七、转码
| 参数（环境变量） | 默认 | 说明 |
|---|---|---|
-x / --transcoding-max-parallel-processes（AUDIOSERVE_TRANSCODING_MAX_PARALLEL_PROCESSES） | 2 × 核数（最小 4） | 并发 ffmpeg 子进程上限 |
--transcoding-max-runtime（AUDIOSERVE_TRANSCODING_MAX_RUNTIME） | 24 小时 | 单个转码进程最长运行时间，超时击杀 |
-g 配置文件 transcoding 节 | 见下 | 三档（low/medium/high）参数 + 备用配置 alt_configs |
默认三档（print-config 实查，客户端请求 ?trans=l/m/h 选用）：
| 档位 | 编码器/容器 | 码率 | compression_level | cutoff | 声道 |
|---|---|---|---|---|---|
| low | Opus in Ogg | 32 kbps | 5 | SuperWideBand | 单声道 |
| medium | Opus in Ogg | 48 kbps | 8 | SuperWideBand | 立体声 |
| high | Opus in Ogg | 64 kbps | 10 | FullBand | 立体声 |
自定义转码实测：以"再省一半流量"为目标，把 low 档压到 16 kbps——YAML（/tmp/transcoding-custom.yaml）：
transcoding:
low:
opus-in-ogg:
bitrate: 16
compression_level: 3
cutoff: WideBand
mono: true
以 --config /tmp/transcoding-custom.yaml 启动后实测：
/transcodings/接口回显（low 档码率即变为 16，Web 客户端自动跟随）：
{"max_transcodings":12,"low":{"bitrate":16,"name":"opus-in-ogg"},"medium":{"bitrate":48,"name":"opus-in-ogg"},"high":{"bitrate":64,"name":"opus-in-ogg"}}
- 同一 60 秒 64k mp3 源文件转码产物：默认 low 253,962 字节 → 自定义 16k 后 124,350 字节，体积减半，人声可辨度仍可接受（超低码率的典型代价是底噪质感变硬，自行权衡）。
依赖提示：转码通过 fork 系统
ffmpeg命令行实现，服务器必须装有 ffmpeg（Docker 镜像已内置 8.0.1；静态二进制部署需自行安装，缺失时的真实报错见排障实录）。音频元数据（时长/码率）解析由二进制链接的 libavformat 完成，不需要额外依赖。
八、播放位置（positions）
| 参数（环境变量） | 默认 | 说明 |
|---|---|---|
--positions-backup-file（AUDIOSERVE_POSITIONS_BACKUP_FILE） | None | 播放位置 JSON 备份文件路径；兼作恢复源 |
--positions-backup-schedule（AUDIOSERVE_POSITIONS_BACKUP_SCHEDULE） | None | 定时备份 cron 表达式（分 时 日 月 周，如 0 3 * * *）；编译特性 cron |
--positions-restore（AUDIOSERVE_POSITIONS_RESTORE） | None | 恢复模式，值为备份文件版本（legacy 为 v0.16 前，v1 为现行）——恢复完成进程立即退出，须移除本参数后再正常重启（compose 形态下忘移除会因 restart 策略形成循环） |
--positions-ws-timeout（AUDIOSERVE_POSITIONS_WS_TIMEOUT） | 600 秒 | 进度同步 WebSocket 空闲超时 |
备份另有手动通道：向进程发 SIGUSR2 立即落盘（实测 kill -USR2 1 后 positions-backup.json 出现，内容按 集合路径→目录→设备组 三层嵌套）。SIGUSR1 为全量重扫信号，实测回显：
[INFO audioserve] Received signal SIGUSR1 for full rescan of caches
[INFO collection::cache] Full scan for collection "/audiobooks" finished
九、图标缓存与杂项
| 参数（环境变量） | 默认 | 说明 |
|---|---|---|
--icons-cache-dir（AUDIOSERVE_ICONS_CACHE_DIR） | $DATA/icons-cache | 封面缩略图缓存目录 |
--icons-cache-size（AUDIOSERVE_ICONS_CACHE_SIZE） | 100 (MB) | 缓存容量上限，满后 LRU 淘汰 |
--icons-cache-max-files（AUDIOSERVE_ICONS_CACHE_MAX_FILES） | 1024 | 缓存文件数上限 |
--icons-cache-disable（AUDIOSERVE_ICONS_CACHE_DISABLE） | false | 关闭图标缓存（每次实时缩放封面） |
--icons-size（AUDIOSERVE_ICONS_SIZE） | 128 px | 缩略图边长 |
--icons-fast-scaling（AUDIOSERVE_ICONS_FAST_SCALING） | false | 快速缩放（线性三角法）替代默认更优但更慢的 Lanczos3 |
--icons-cache-save-often（AUDIOSERVE_ICONS_CACHE_SAVE_OFTEN） | false | 每次增量即落盘（通常无必要） |
--static-resource-cache-age（AUDIOSERVE_STATIC_RESOURCE_CACHE_AGE） | no-store | 静态资源 Cache-Control（秒数或 no-store） |
--folder-file-cache-age（AUDIOSERVE_FOLDER_FILE_CACHE_AGE） | 86400 | 目录封面/简介文件的 Cache-Control 秒数 |
--disable-folder-download（AUDIOSERVE_DISABLE_FOLDER_DOWNLOAD） | false | 关闭整目录打包下载 API（需编译特性 folder-download） |
--thread-pool-large / --thread-pool-keep-alive-secs | 8 线程 / 永久 | 工作线程池扩容与空闲回收（print-config：num_threads: 8, queue_size: 100） |
--data-dir（AUDIOSERVE_DATA_DIR） | $HOME/.audioserve | 全部服务数据（col_db、图标缓存、密钥）根目录 |
--client-dir（AUDIOSERVE_CLIENT_DIR） | client/dist（相对路径） | Web 客户端文件目录。相对工作目录解析——Docker 镜像工作目录为 /audioserve 所以开箱即用；静态二进制形态若不在固定目录启动，必须显式绝对路径（真实踩坑见排障实录） |
十、排障实录
1. --search-cache 已弃用
--help 回显原文：Deprecated: does nothing. For caching config use :<options> on individual collections dirs params。老教程里用 --search-cache 开启搜索缓存的写法在 0.30.x 已完全无效，缓存默认开启；要让某个集合不走缓存，改用目录级选项 <路径>:no-cache（或 nc）。
2. 静态二进制形态报 Error: Error creating/reading secret: Permission denied (os error 13)
数据目录对运行用户不可写（盐文件 audioserve.secret 无法创建）。按 --data-dir 指向授权：chown -R audioserve:audioserve /var/lib/audioserve。Docker 形态的等价问题是宿主挂载目录属主不是 uid 1000（见《Audioserve Docker Compose 部署实战》排障实录）。
3. Web 界面白屏/404：静态二进制默认 client_dir: client/dist 是相对路径
静态构建包不含 Web 客户端，print-config 显示默认值 client/dist 相对当前工作目录解析；若二进制被 systemd 从 /opt/audioserve 之外启动（或工作目录不含 client/dist），Web 界面即 404。解法：单独部署 audioserve-web 客户端文件并用 --client-dir /绝对路径/client 显式指定（实测修复，systemd 单元示例见《Audioserve 常用命令与运维实战（核心篇）》）。
4. 转码请求返回 500，日志 Cannot spawn child process: Os { code: 2, kind: NotFound }
服务器没有安装 ffmpeg——原生流（/0/audio/<path> 不带 trans 参数）完全正常，唯独 ?trans= 请求 500。NotFound 即找不到 ffmpeg 可执行文件；安装/修正 PATH 后恢复。诊断口诀：原生 200、转码 500，先查 ffmpeg。
5. 参数写错的防呆提示
参数体系较大，拼错时 clap 会拒绝启动并给出修正提示（实测 --port 3000 误写的回显）：
error: unexpected argument '--port' found
tip: to pass '--port' as a value, use '-- --port'
Usage: audioserve --no-authentication [BASE_DIRS]...
监听参数的正名是 -l/--listen 0.0.0.0:3000。拿不准时 --print-config 比逐条试错高效。
十一、参考链接
- 官方 README（参数行为描述与安全基线）：https://github.com/izderadicka/audioserve#readme
- API 文档（/transcodings、/collections 等）：https://github.com/izderadicka/audioserve/blob/master/docs/api.md
- Releases：https://github.com/izderadicka/audioserve/releases
- 本专栏姊妹篇：《Audioserve 介绍与选型指南》（https://www.quzuo.net/document/MeqWm6L3TUWt ）、《Audioserve Docker Compose 部署实战》（https://www.quzuo.net/document/iQEgf4WeubHd ）、《Audioserve 常用命令与运维实战（核心篇）》