Ampache Docker Compose 部署实战

本文在真实服务器上用官方镜像完成一次完整的 Ampache 8.3.0 部署：外接 MariaDB 的 Compose 编排、向导安装、建 Catalog 导入测试曲库、网页与 Subsonic 播放验证，并把路上踩到的坑（数据库已存在、目录权限、端口冲突、转码 429）一并沉淀。

前置阅读：不了解 Ampache 定位与能力，先看《Ampache 介绍与选型指南》；配置项含义与调优见《Ampache 配置参数详解》。

官方镜像体系速览

Ampache 官方镜像（ampache/ampache）有两类形态，选型前必须分清：

变体	内置数据库	适用场景
`ampache/ampache:8.3.0` / `:latest`	有（内置 MariaDB）	单容器全家桶，起步最快
`ampache/ampache:nosql8.3.0` / `:nosql`	无	自备 MySQL/MariaDB，数据库独立备份与版本控制
`ampache/ampache:client*`	有	需要把 Ample/tinysub Web 客户端装进界面
`ampache/ampache:develop` / `:preview`	有/无	体验开发分支（不建议跑正式曲库）

本文采用 nosql8.3.0 + 外接 mariadb:11.8 的双容器编排。理由：数据库升级节奏与应用解耦、备份策略独立、排障时可以分别进入两个实例观察。官方镜像内置数据库的形态只是把 db 服务去掉并换用自动化安装变量，编排思路完全一致。

官方镜像多架构构建覆盖 linux/amd64、linux/arm/v7、linux/arm64，镜像内已预装 ffmpeg 与全套 PHP 8.5 扩展，无需额外装转码工具。

前置条件

一台 Linux 服务器，已安装 Docker 与 Docker Compose 插件（本文实测版本环境为 Docker 28.x）。
一个可用的 MariaDB/MySQL 实例（若用内置数据库变体则不需要）。
端口规划：本例宿主机使用 8137（未占用端口，ss -ltn 确认），容器内统一 80。
网络规划：为整个栈建立独立自定义网络。本文使用 10.89.63.0/24，创建前先确认目标网段未被占用：

docker network ls
# 检查候选网段是否已被既有网络占用
for n in $(docker network ls --format '{{.Name}}'); do
  docker network inspect "$n" --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}'
done

实测输出（节选）：

ampache-8.3.0-net 10.89.63.0/24

创建专用网络：

docker network create --subnet 10.89.63.0/24 ampache-8.3.0-net

目录规划与 Compose 文件

约定一个部署根目录，例如 /opt/ampache，内部结构：

/opt/ampache/
├── docker-compose.yml
└── data/
    ├── config/    # Ampache 配置（ampache.cfg.php 落在这里）
    ├── log/       # Ampache 日志
    ├── media/     # 音乐文件（只读挂载亦可）
    ├── mysql/     # MariaDB 数据目录
    └── backup/    # 数据库备份输出目录

创建目录并放权（Ampache 以 www-data 身份运行，配置与日志目录需要可写）：

mkdir -p /opt/ampache/data/{config,log,media,mysql,backup}
chmod 775 /opt/ampache/data/config /opt/ampache/data/log /opt/ampache/data/backup

docker-compose.yml 全文（实测可直接使用）：

name: ampache-8.3.0-stack

services:
  web:
    image: ampache/ampache:nosql8.3.0
    container_name: ampache-8.3.0-web
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8137:80"
    volumes:
      - ./data/config:/var/www/config
      - ./data/log:/var/log/ampache
      - ./data/media:/media
      - ./data/backup:/var/www/backup
    networks:
      - ampache-net

  db:
    image: mariadb:11.8
    container_name: ampache-8.3.0-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: ampache
      MARIADB_USER: ampache
      MARIADB_PASSWORD: q1w2e3r4
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - ampache-net

networks:
  ampache-net:
    external: true
    name: ampache-8.3.0-net

要点说明：

name: ampache-8.3.0-stack 显式指定项目名，避免 Compose 用目录名派生。
networks 引用外部预建网络并显式命名，多栈共存时互不干扰。
./data/media 挂到容器内 /media，这就是后面建 Catalog 时填的路径；音乐只读场景可以加 :ro。
./data/backup 对应容器内 /var/www/backup，官方镜像自带的 backup-db.sh 会把数据库备份写到这个目录（见《Ampache 常用命令与运维实战（核心篇）》）。

拉取镜像并启动

docker pull ampache/ampache:nosql8.3.0
docker pull mariadb:11.8
cd /opt/ampache
docker compose up -d

实测启动后状态：

$ docker compose ps
NAME                  STATUS         PORTS
ampache-8.3.0-web     Up 15 seconds  0.0.0.0:8137->80/tcp
ampache-8.3.0-db      Up 16 seconds  3306/tcp

验证 Web 服务已就绪（安装向导会 302 跳转）：

curl -sI http://localhost:8137/ | head -4

实测输出：

HTTP/1.1 302 Found
Location: /install.php
Content-Type: text/html; charset=UTF-8

看到 Location: /install.php 即说明应用已运行、等待初始化。

走一遍安装向导

浏览器打开 http://<服务器IP>:8137/，自动进入安装向导。整个过程分四步：语言与依赖检查 → 数据库初始化 → 生成配置文件 → 创建管理员。

第 1 步：依赖检查

选择语言后向导执行环境自检（PHP 版本、PDO MySQL、intl、cURL、GD 等扩展），官方镜像全部预置，全绿通过后点击 Continue。

第 2 步：数据库初始化

向导表单关键字段与填写值：

字段	填写值	说明
Database Name	`ampache`	数据库名
Database Host	`db`	Compose 服务名即主机名
Database Port	`3306`	MariaDB 默认端口
Administrator User（连接）	`root`	供向导建库建用户的管理账号
Administrator Password	`q1w2e3r4`	对应 `MARIADB_ROOT_PASSWORD`
Create Database User	勾选	由向导创建应用专用账号
Ampache Database Username	`ampache`	对应 `MARIADB_USER`
Ampache Database Password	`q1w2e3r4`	对应 `MARIADB_PASSWORD`

实测中这里出现第一个坑：提交后报「database already exists」。原因是 mariadb 官方镜像启动时已经按 MARIADB_DATABASE 环境变量建好了 ampache 库，而向导默认还要再建一次。处理方式：勾选 Overwrite Existing Database（覆盖已有数据库）重新提交即可，向导会跳过建库、复用现有库并完成建表。

提交成功后可用数据库客户端验证：

docker exec ampache-8.3.0-db mariadb -uroot -pq1w2e3r4 -e "show databases"

实测输出：

+--------------------+
| Database           |
+--------------------+
| ampache            |
| information_schema |
| mysql              |
| performance_schema |
| sys                |
+--------------------+

第 3 步：生成配置文件

向导会把数据库连接信息写进 config/ampache.cfg.php。此页的关键字段：

Web Path：部署在域名根路径时留空。这是实测中遇到的第二个坑——如果把完整 URL http://localhost:8137 填进去，生成配置里 web_path 会被当作路径前缀拼接进站内链接，页面出现 http://localhost:8137http://localhost:8137/... 的双重前缀，所有链接失效。正确值：根部署留空；子路径部署（如 https://example.com/music）填 /music 这类路径，而不是 URL。
Installation Type（usecase）：Default 即可，向导会据此套用一份合理的基础配置模板。
API Backends：勾选 subsonic，让初始配置包含 Subsonic 兼容接口的上下文。

成功后服务器上应出现配置文件：

ls -la /opt/ampache/data/config/

实测输出：

total 68
drwxrwxr-x 7 www-data www-data  4096 Oct 28 17:02 .
-rw-r--r-- 1 www-data www-data 61918 Oct 28 17:08 ampache.cfg.php
...

第 4 步：创建管理员

填写管理员账号（本文统一使用 admin / q1w2e3r4）提交，向导完成初始化后即可进入登录页。用刚才的账号登录，首页正常渲染即部署完成：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8137/login.php

实测输出：

建 Catalog 并导入测试曲库

部署完成后曲库是空的，需要两步：建 Catalog（登记媒体目录）→ 执行扫描。

先用 ffmpeg 在媒体目录生成几个带完整标签的测试文件（服务器上需有 ffmpeg；本文在应用实例内执行，效果相同）：

cd /opt/ampache/data/media
ffmpeg -f lavfi -i "sine=frequency=440:duration=45" \
  -metadata title="Morning Signal" -metadata artist="Echo Valley" \
  -metadata album="Analog Dreams" -metadata genre="Electronic" \
  -metadata track=1 -metadata date=2024 \
  -codec:a libmp3lame -b:a 320k "01 - Morning Signal.mp3"
ffmpeg -f lavfi -i "sine=frequency=262:duration=40" \
  -metadata title="Deep Field" -metadata artist="Echo Valley" \
  -metadata album="Analog Dreams" -metadata date=2024 \
  -codec:a flac "05 - Deep Field.flac"

然后进入 Web 界面：管理 → Catalog → 添加 Catalog，类型选 local，名称填 music，路径填容器内的媒体目录 /media，保存。

扫描既可以走 Web 界面按钮，也可以走命令行（本例用后者，输出更清晰）：

docker exec ampache-8.3.0-web php /var/www/bin/cli run:updateCatalog music -a -t

实测输出（节选）：

Web/interface action … starting
update_catalog: music
------------------
Time: 00:01

验证入库结果：

docker exec ampache-8.3.0-db mariadb -uroot -pq1w2e3r4 ampache \
  -e "select count(*) songs from song; select name,year from album;"

实测输出：

songs
6
name            year
Analog Dreams   2024
Field Notes     2023

网页端打开「音乐」即可浏览专辑并播放；Subsonic 客户端连接 http://<服务器IP>:8137 也能直接看到这两张专辑。扫描命令的完整参数与坑（verify 不刷新已替换文件的元数据等）见运维篇。

升级与回滚

升级：改 docker-compose.yml 中的镜像标签（如 nosql8.3.0 → nosql9.x），docker compose pull && docker compose up -d。Ampache 首次启动会自动执行数据库结构升级（如 8.3.0 对应数据库版本 830003），升级前务必先备份数据库（backup-db.sh）。
回滚：换回旧镜像标签重启；若数据库已被新版升级，需要用升级前的 SQL 备份恢复后再降版本。
大版本提醒：官方发布页预告 Ampache 9 将调整目录结构，跨大版本升级前先读变更说明并演练备份恢复。

排障实录

部署过程实测踩到的四个坑，按发生顺序整理：

坑 1：向导报 database already exists。 官方 MariaDB 镜像已按环境变量预建了 ampache 库，向导默认再建一次就会冲突。解法：勾选覆盖已有数据库（或让 MariaDB 环境变量不建库、全部交给向导）。

坑 2：页面链接变成双重前缀。 向导的 Web Path 填了完整 URL，web_path 被当成路径前缀拼进链接，页面出现 http://...http://...。解法：根部署留空，子路径部署只填路径部分。相关语义详见《Ampache 配置参数详解》。

坑 3：8137 端口启动失败。 docker compose up 报端口绑定错误，ss -ltn 查看发现 8129 已被并行服务占用。解法：从 8128–8152 区间换一个未被占用的端口（本例 8137），ss -ltn | grep 8137 确认为空后再启动。

坑 4：配置/日志目录不可写导致向导卡住。 配置文件要写进 config/，日志要写进 log/，这两个目录如果被挂载成 root-only，向导在「生成配置文件」一步会失败。解法：宿主机目录 chmod 775（或 chown 33:33，对应容器内 www-data）。

另外两个「不报错但功能不对」的现象也值得一并记住：FLAC 播放 429 说明转码未按格式授权（transcode_flac 默认关闭，需显式开启）；Subsonic 播放返回空内容则要看日志里的 Stream proxy 回源地址——两者都在运维篇排障实录里有完整定位过程。