Ampache 配置参数详解

Ampache 的一切行为都由一份 ampache.cfg.php 驱动：数据库、会话安全、Catalog 扫描、转码编解码、API、日志、注册与第三方认证全在这一个文件里。本文按配置文件的真实分节顺序逐节讲解 8.3.0 的关键参数，并补齐容器部署时的环境变量体系。

环境搭建与向导安装过程见《Ampache Docker Compose 部署实战》，本文所有参数示例均基于该实测环境的 Ampache 8.3.0。

配置体系总览

文件位置：安装后配置文件位于应用根目录 config/ampache.cfg.php（容器部署对应挂载点 ./data/config:/var/www/config）。同目录还有一份 ampache.cfg.php.dist——完整的参数字典，带每个参数的注释、单位与默认值，8.3.0 的 dist 文件约 300 个参数，排错时先查它。

生成方式：安装向导第三步按你选择的 Installation Type（usecase）模板生成配置，default 模板即常规流媒体服务器；向导还接受 transcode 等模板取向。生成后即可手工编辑，改完无需重启服务进程（PHP 每次请求重新读配置），但正在播放的流不受影响。

分节结构：dist 文件用横线注释分成 19 个小节，按顺序为：

Auto Update（自动升级检查）
Path Vars（路径变量：web_path、local_web_path）
Database（数据库连接）
Session and Security（会话与安全）
Metadata（元数据行为）
File Tags（文件标签读取）
Catalog（曲库扫描）
Program Settings（程序设置：界面、排序、播放行为）
API keys（API 密钥）
Debugging（调试日志）
Encoding Settings（编码设置）
Custom actions（可选自定义动作）
LDAP login info（可选 LDAP 认证）
OpenID Connect (OIDC) login info（OIDC 认证）
Proof of work（工作量证明）
Public Registration settings（公开注册，默认关闭）
Dynamic downsampling（动态降码率）
Transcode Settings（转码设置）
Transcode Caching（转码缓存）

下面按使用频率挑重点节讲。

路径与站点定位：web_path 与 local_web_path

这是新手最容易栽的一节，也是实测中真实踩过的坑。

;web_path = ""
;local_web_path = "http://localhost/ampache"

web_path：URL 路径前缀，不是完整 URL。部署在域名根目录时保持空字符串 ""；部署在子路径（https://example.com/music）时填 /music。实测中把完整 URL 填进去后，站内链接生成变成 http://...http://... 的双重前缀，全站链接失效——因为 Ampache 内部把它按路径拼接。
local_web_path：服务器自身访问自己的完整地址，容器/反向代理场景下用于内部回源。官方容器文档的排障建议就是「把 local_web_path 设为 localhost」。

容器化部署还有一条隐含规则：某些内部回源逻辑（如 Subsonic 流代理）使用请求头里的 Host 构造回源地址，所以发布给客户端的地址必须同时是服务器自己可达的地址，否则流播放会静默失败（定位过程见《Ampache 常用命令与运维实战（核心篇）》排障实录）。

Database：数据库连接

database_hostname = "localhost"
;database_port = 3306
database_name = "ampache"
database_username = "username"

database_hostname：容器部署填服务名（Compose 场景即 db），实测环境如此。
database_port：非 3306 才需要写；MariaDB 官方镜像的端口仅暴露在内部网络。
database_name / database_username：向导创建的应用账号，与内置数据库变体的 AMPACHE_DB_USER 环境变量对应。
数据库密码紧随其后（database_password），文件含明文密码，权限应收紧到运行用户可读，且 data/config 目录不应进入公开备份渠道。

Session and Security：会话与安全

session_length = 3600        ; Web 会话时长（秒）
remember_length = 604800     ; 「记住我」时长（7 天）
stream_length = 7200         ; 流媒体会话时长（2 小时）
stream_proxy = "true"
access_control = "true"
require_session = "true"

session_length / remember_length / stream_length 三条时间线分别管网页登录、持久登录、流播放授权，单位都是秒。
access_control：启用基于 IP 的访问控制列表；关闭时任何来源都能打 API 与流（内网裸奔场景可关）。
require_session：流播放是否强制会话校验；配合 stream_proxy 决定流地址的形态。
8.3.0 的数据库升级明确移除了旧版可预测的 MD5(username) API 会话，老版本升级后所有依赖该会话形态的脚本需要重新握手。
公开注册相关（allow_public_registration、user_agreement）默认全部关闭；开放注册前建议先配齐邮箱验证与工作量证明（Proof of work 节）。

Catalog 与元数据行为

Catalog 节控制扫描器的默认动作：新增/变更/校验/清理的组合开关，以及按目录结构推断专辑的规则。几个实用点：

扫描不是只增不减：默认动作包含清理（clean），从目录移除的文件会同步下架；外置存储（NFS/SMB）掉线时为防误清，可用环境变量 DISABLE_INOTIFYWAIT_CLEAN=1 关闭目录监控的自动清理。
File Tags 节决定从音频文件读哪些标签字段（标题/艺术家/专辑/流派/年份等），混合大小写、多值流派等行为在此调整。
元数据的年份/专辑名变化不会自动刷新旧记录——实测中修改文件标签后需要用单文件重扫命令才会更新（命令与现象见运维篇）。

API keys 与接口

8.x 的 Ampache API 与 Subsonic/OpenSubsonic API 默认随应用一起提供，配置文件里不再有「后端开关」；API keys 节用于管理集成密钥类配置。与 API 相关的重要事实：

Ampache API 当前版本 8.1.0（握手响应可见），XML/JSON 双格式。
Subsonic 兼容层报 type="ampache" serverVersion="8.3.0" openSubsonic="1"，协议版本 1.16.1。
Subsonic 的 token/salt 认证使用的不是登录密码，而是用户档案里的专用 Subsonic 密码——用登录密码算 token 会得到 BADAUTH，这是实测确认过的行为，详见运维篇。

Debugging：调试日志

log_filename = "%name.%Y%m%d.log"   ; 默认按模块+日期分文件
debug = "true"

官方容器文档给出的开启步骤（实测有效）：

sed -i 's/log_filename = "%name.%Y%m%d.log"/log_filename = "ampache.log"/g' config/ampache.cfg.php
sed -i 's/;debug = "true"/debug = "true"/g' config/ampache.cfg.php
chmod 754 /var/log/ampache

log_filename 收敛成单文件后，docker logs 与宿主机 data/log/ 都能直接看完整日志；log_level 控制详细程度。排障结束记得把 debug 关回去，调试日志量不小。

Transcode Settings：转码体系（重点）

转码是 Ampache 配置里语义最细的一节，三层结构：

第一层：按输入格式授权。

; TYPE is the extension. 'allowed' certifies that transcoding works properly for
; this input format. 'required' further forbids the direct streaming of a format.
; transcode_TYPE = {allowed|required|false}
; DEFAULT: "false"
;transcode_flac = "allowed"
;transcode_mpc = "allowed"
;transcode_m4a = "allowed"

语义：allowed＝该格式允许转码；required＝禁止原格式直出、必须转码；false（默认）＝不转码。默认全部为 false——这就是 FLAC 播放返回 429 的直接原因：转码未授权时请求转码流被拒。想让客户端默认拿到 MP3 而不是原文件，把 FLAC 等设为 required。

第二层：转码命令。

;transcode_cmd = "ffmpeg"
transcode_input = "-i %FILE%"

transcode_cmd 是可执行文件（官方镜像已内置 ffmpeg），transcode_input 是输入参数模板，%FILE% 占位源文件；个别格式可用 transcode_cmd_TYPE 覆盖。

第三层：输出编码参数。

encode_args_mp3 = "-vn -b:a %BITRATE% -c:a libmp3lame -f mp3 pipe:1"
encode_args_ogg = "-vn -b:a %BITRATE% -c:a libvorbis -f ogg pipe:1"
encode_args_opus = "-vn -b:a %BITRATE% -c:a libopus -compression_level 10 -f ogg pipe:1"
encode_args_m4a = "-vn -b:a %BITRATE% -c:a aac -movflags +frag_keyframe+empty_moov+default_base_moof -f mp4 pipe:1"
encode_args_wav = "-vn -b:a %BITRATE% -c:a pcm_s16le -f wav pipe:1"

%BITRATE% 由播放请求动态传入（如请求 128k 时回源参数 bitrate=128000）。实测发现一个值得注意的现象：Subsonic 请求 maxBitRate=128 时回源确实带了 bitrate=128000，但落盘文件探测为 320 kbps——码率参数在部分路径上并未如预期传导到最终输出。对码率敏感的部署，建议用 encode_args 定制后以真实播放输出验证，不要想当然。

动态降采样（Dynamic downsampling）节里的 min_bit_rate = 48000（默认 8000 注释值需注意单位是 bps）控制低码率客户端的下限。

转码缓存：Transcode Caching 节独立成节，开启后转码产物按源文件+参数缓存，重复播放同参数请求不再重复转码，CPU 紧张的服务器建议开启。

缓存与性能

memory_cache = "false"：启用后元数据热数据走内存缓存，大曲库多用户场景收益明显。
PHP 侧的 memory limit 在 8.3.0 实测的 show:debug 输出中标 [!!] 警告，说明默认内存上限偏紧，曲库很大时可调 PHP memory_limit。

LDAP / OIDC / 自定义动作

LDAP login info：服务器地址、端口、绑定 DN、用户模板等一套参数，适合复用企业目录。
OpenID Connect：issuer、client_id、client_secret 等参数，适合对接 Keycloak/Authentik。
Custom actions：把外部脚本挂到界面上执行（如按需触发下载/整理脚本），路径与可见权限在此配置。
两类外部认证都要求 PHP 对应扩展存在（官方镜像已含），配置后先在测试账号上验证再放开。

容器环境变量体系

用官方镜像时，一部分「配置」不在 cfg 文件里而在容器环境变量，分四组（源自官方 ampache-docker 文档）：

基础运行：

变量	作用
`UID` / `GID`	把容器内 www-data 的 uid/gid 改成宿主机用户，解决挂载目录权限
`LOG_FILE`	容器内日志文件路径（默认 `/var/log/ampache/ampache.log`），同时决定 `docker logs` 是否回显日志
`DISABLE_INOTIFYWAIT_CLEAN`	置 1 关闭目录监控自动清理，外置存储挂载场景强烈建议
`MYSQL_USER` / `MYSQL_PASS`	内置数据库变体的管理员账号

自动化安装（仅当 config/ampache.cfg.php 不存在时执行，可跳过 Web 向导）：

变量	必填	作用
`DB_NAME` / `DB_HOST` / `DB_PORT`	DB_NAME、DB_HOST 必填	目标数据库
`DB_USER` / `DB_PASSWORD`	否	数据库管理员账号（回退到 `MYSQL_USER`）
`AMPACHE_DB_USER` / `AMPACHE_DB_PASSWORD`	否	应用专用数据库账号
`AMPACHE_ADMIN_USER` / `AMPACHE_ADMIN_EMAIL`	必填	初始管理员
`AMPACHE_ADMIN_PASSWORD`	否	不填则生成随机密码
`FORCE_INSTALL`	否	置 1 强制重装覆盖现有库
`Random`	—	上述密码类变量可填 `Random` 由系统生成

Web 客户端（client 变体）：CLIENT_INSTALL（默认 ample.sh）、CLIENT_VERSION、CLIENT_ZIP、CLIENT_FORCE；构建/下载缓存在 /var/tmp/client/.cache。

客户端注入：AMPACHE_URL 会写进 config/ample.json 的 ampacheURL（Ample 用），tinysub 用 TINYSUB_SERVER 回退到 AMPACHE_URL。

自动化安装示例（官方文档原样）：

docker run -d --name=ampache-develop \
    -e DB_NAME=ampache-develop \
    -e MYSQL_USER=admin \
    -e MYSQL_PASS=changeme \
    -e DB_HOST=localhost \
    -e AMPACHE_ADMIN_USER=admin \
    -e AMPACHE_ADMIN_EMAIL=admin@example.com \
    -p 80:80 \
    ampache/ampache:develop

配置排障三条实录

1. web_path 填成完整 URL → 全站链接双重前缀。 向导 Web Path 与配置文件 web_path 都只接受路径语义；已踩坑的修复方式是直接把配置改回 web_path = ""（或正确子路径），无需重装。

2. FLAC 播放 429。 响应状态 429、无音频内容，日志无异常——根因是 transcode_flac 默认 false，客户端请求 format=mp3 被拒。显式开启 transcode_flac = "allowed" 并确认 transcode_cmd = "ffmpeg" 后立即恢复。

3. 开了 debug 却看不到日志。 三个检查点：log_filename 是否被 sed 改对；/var/log/ampache 对 www-data 是否可写（官方建议 chmod 754）；容器场景确认 LOG_FILE 与挂载路径一致，否则日志只进 data/log/ 不进 docker logs。

参考

官方容器文档（环境变量、变体、备份、调试日志）：github.com/ampache/ampache-docker
参数字典：应用目录内 config/ampache.cfg.php.dist（8.3.0，约 300 参数，本文键名与默认值均核对此文件）
站内相关：《Ampache Docker Compose 部署实战》、《Ampache 常用命令与运维实战（核心篇）》