LinuxServer.io 容器：airsonic-advanced

LinuxServer.io 团队简介

LinuxServer.io 团队专注于提供高质量容器解决方案，其容器具有以下特点：

• 应用定期及时更新
• 简单的用户权限映射（PGID、PUID）
• 基于 s6 overlay 的自定义基础镜像
• 每周系统更新，通过统一基础层减少存储空间占用、 downtime 和带宽消耗
• 常规安全更新

关于 Airsonic-Advanced

Airsonic-Advanced 是一款免费的 Web 媒体流服务，支持通过网络访问音乐库。您可以用它与朋友共享音乐，或在工作时远程收听自己的收藏，还能同时向多个设备（如厨房和客厅的播放器）推送音频流。

支持的架构

该镜像通过 Docker manifest 实现多平台支持，拉取 lscr.io/linuxserver/airsonic-advanced:latest 即可自动匹配对应架构。也可通过标签指定架构：

应用设置

升级注意事项

• 不建议从 Airsonic 直接升级到 Airsonic-Advanced，升级前请备份数据。升级后可能触发音乐库重新扫描（大库耗时较长）。
• 从 v10 升级到 v11 的详细说明见 官方文档。

基础配置

• Web 管理界面访问地址：<您的IP>:4040
• 默认账号密码：admin/admin

高级配置

• 可通过 JAVA_OPTS 环境变量传递 Java 参数，例如 -e JAVA_OPTS="-Xmx256m -Xms256m"（设置内存限制）。
• 若使用反向代理，需添加 -e JAVA_OPTS=-Dserver.use-forward-headers=true 以确保 URL 生成正确。
• 如需使用 Java 本地播放器，需确保 PGID 与音频设备（如 /dev/snd）的所属组一致。

运行模式说明

• 只读文件系统：支持以只读容器文件系统运行，详见 文档。
• 非 Root 用户：支持以非 root 用户运行，详见 文档。

部署方法

以下提供两种部署方式，根据需求选择（未标注“可选”的参数为必填项）。

方法一：使用 docker-compose（推荐）

创建 docker-compose.yml 文件，内容如下：

---
services:
  airsonic-advanced:
    image: lscr.io/linuxserver/airsonic-advanced:latest
    container_name: airsonic-advanced
    environment:
      - PUID=1000         # 用户ID（见下方说明）
      - PGID=1000         # 组ID（见下方说明）
      - TZ=Etc/UTC        # 时区，参考列表：***      - CONTEXT_PATH=     # 可选，反向代理时设置 URL 前缀
      - JAVA_OPTS=        # 可选，Java 额外参数
    volumes:
      - /path/to/config:/config       # 配置文件目录（替换为实际路径）
      - /path/to/music:/music         # 音乐库目录（替换为实际路径）
      - /path/to/playlists:/playlists # 播放列表目录（替换为实际路径）
      - /path/to/podcasts:/podcasts   # 播客目录（替换为实际路径）
      - /path/to/media:/media         # 可选，其他媒体文件目录
    ports:
      - 4040:4040         # Web 界面端口
    devices:
      - /dev/snd:/dev/snd # 可选，本地音频设备（用于 Java 播放器）
    restart: unless-stopped

启动容器：

docker-compose up -d

方法二：使用 docker run

直接执行命令部署：

docker run -d \
  --name=airsonic-advanced \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e CONTEXT_PATH= `#可选` \
  -e JAVA_OPTS= `#可选` \
  -p 4040:4040 \
  -v /path/to/config:/config \
  -v /path/to/music:/music \
  -v /path/to/playlists:/playlists \
  -v /path/to/podcasts:/podcasts \
  -v /path/to/media:/media `#可选` \
  --device /dev/snd:/dev/snd `#可选` \
  --restart unless-stopped \
  lscr.io/linuxserver/airsonic-advanced:latest

参数说明

环境变量与权限配置

通过文件设置环境变量

支持从文件读取环境变量，格式为 -e FILE__<变量名>=<文件路径>。例如：

-e FILE__MYVAR=/run/secrets/mysecretvariable  # 从文件 /run/secrets/mysecretvariable 读取 MYVAR 的值

Umask 权限设置

可通过 -e UMASK=022 调整容器内文件权限掩码（默认值 022）。注意 umask 是权限减法，而非直接设置权限，详情参考 说明。

用户/组 ID（PUID/PGID）

容器通过 PUID 和 PGID 映射宿主机用户权限，避免文件读写权限问题。获取当前用户的 UID/GID 命令：

id your_user  # 替换 your_user 为实际用户名，输出类似 uid=1000(xxx) gid=1000(xxx)

Docker Mods

可通过 Docker Mods 扩展容器功能。该镜像支持的 Mods 及通用 Mods 可通过以下链接查看：

• airsonic-advanced 专用 Mods
• 通用 Mods

支持与维护

常用操作命令

• 进入容器命令行：

  docker exec -it airsonic-advanced /bin/bash
  

• 实时查看日志：

  docker logs -f airsonic-advanced
  

• 查看容器版本：

  docker inspect -f '{{ index .Config.Labels "build_version" }}' airsonic-advanced
  

• 查看镜像版本：

  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/airsonic-advanced:latest
  

容器更新

使用 docker-compose 更新

# 拉取最新镜像（全部或单个）
docker-compose pull  # 全部镜像
# 或 docker-compose pull airsonic-advanced  # 单个镜像

# 重启容器（全部或单个）
docker-compose up -d  # 全部容器
# 或 docker-compose up -d airsonic-advanced  # 单个容器

# 清理旧镜像
docker image prune

使用 docker run 更新

# 拉取最新镜像
docker pull lscr.io/linuxserver/airsonic-advanced:latest

# 停止并删除旧容器
docker stop airsonic-advanced && docker rm airsonic-advanced

# 用原参数重新创建容器（配置通过 /config 目录保留）
# （重新执行部署时的 docker run 命令）

# 清理旧镜像
docker image prune

[!TIP]
推荐使用 Diun 接收镜像更新通知，不建议使用自动更新工具。

本地构建

如需自定义镜像，可按以下步骤本地构建：

# 克隆仓库
git clone [***] docker-airsonic-advanced

# 构建镜像（默认 x86-64）
docker build --no-cache --pull -t lscr.io/linuxserver/airsonic-advanced:latest .

# 构建 ARM 架构（需先注册 qemu-static）
docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset
# 然后指定架构 Dockerfile，例如 arm64:
docker build -f Dockerfile.aarch64 --no-cache --pull -t lscr.io/linuxserver/airsonic-advanced:latest .

版本历史

• 21.12.24：基于 Alpine 3.21 重构，同步上游至 [***]
• 24.05.24：基于 Alpine 3.20 重构
• 20.03.24：基于 Alpine 3.19 重构
• 30.05.23：基于 Alpine 3.18 重构
• 11.02.23：基于 Alpine 3.17 重构
• 23.10.22：基于 Alpine 3.16 重构，迁移至 s6v3
• 25.07.22：新增 vorbis-tools
• 02.01.22：初始发布

社区支持

• 博客：容器使用教程、指南及观点
• ***：实时社区交流与支持
• 论坛：问题反馈与讨论
• GitHub：源码仓库
• 赞助：支持团队开发与维护