ghcr.io/advplyr/audiobookshelf:2.19.3

文档 · 用户指南 · 支持

关于

Audiobookshelf 是一个自托管的有声书和播客服务器。

功能

• 完全开源，包括安卓和 iOS 应用（测试版）
• 实时流式传输所有音频格式
• 搜索并添加播客以下载剧集，支持自动下载
• 多用户支持，带自定义权限
• 为每个用户保存进度并跨设备同步
• 自动检测库更新，无需重新扫描
• 上传有声书和播客，支持拖放文件夹批量上传
• 备份元数据及自动每日备份
• 渐进式 Web 应用（PWA）
• Web 应用和安卓应用支持 Chromecast
• 从多个来源获取元数据和封面图
• 章节编辑器和章节查找（使用 Audnexus API）
• 将音频文件合并为单个 m4b 文件
• 将元数据和封面图嵌入音频文件
• 基本电子书支持和阅读器（Epub、pdf、cbr、cbz）
• 将电子书发送到设备（如 Kindle）
• 播客和有声书的开放 RSS 订阅源

您是否在寻找某个功能？欢迎提出建议

加入我们的 *** 社区

演示

查看 Web 客户端演示：[***] @Vito0912 提供 hosting！）

用户名/密码：demo/demo（用户账户）

demo``demo

安卓应用（测试版）

在 Google Play 商店试用

iOS 应用（测试版）

测试版目前已满员。Apple 对测试版测试人员有 10k 的硬性限制。更新将在 *** 中发布。

使用 Test Flight：[***]

构建自己的工具和客户端

查看 API 文档

组织您的有声书

目录结构和文件夹名称对 Audiobookshelf 非常重要！

参见文档了解支持的目录结构、文件夹命名规范和音频文件元数据用法。

安装

参见安装文档

反向代理设置

[!IMPORTANT] Audiobookshelf 需要 websocket 连接。

[!NOTE] 支持使用子文件夹，无需额外更改，但路径必须为 /audiobookshelf（不可更改）。参见讨论

/audiobookshelf

NGINX Proxy Manager

启用 websockets 支持。

NGINX 反向代理

在 nginx 服务器的站点配置文件中添加以下内容，替换 <> 括号中的相关部分并插入证书路径。

server {
listen 443 ssl;
server_name . . ;

access_log /var/log/nginx/audiobookshelf.access.log;
error_log /var/log/nginx/audiobookshelf.error.log;

ssl_certificate /path/to/certificate;
ssl_certificate_key /path/to/key;

location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

proxy_http_version 1.1;

proxy_pass http:// ;
proxy_redirect http:// https://;

# 防止 413 请求实体过大错误
# 通过增加客户端请求体的最大允许大小
# 例如，设置为 10 GiB
client_max_body_size 10240M;
}
}

Apache 反向代理

在 Apache 服务器的站点配置文件中添加以下内容，替换 <> 括号中的相关部分并插入证书路径。

为此，您必须使用 a2enmod 启用至少以下模块：

a2enmod

• ssl ssl
• proxy proxy
• proxy_http proxy_http
• proxy_*** proxy_balancer
• proxy_wstunnel proxy_wstunnel
• rewrite rewrite

ServerName . .

ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined

ProxyPreserveHost On
ProxyPass / http://localhost: /
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/?(.*) "ws://localhost: /$1" [P,L]

# 除非有特殊需求，否则这部分应由 Let's Encrypt 的 certbot 等工具自动生成
SSLCertificateFile /path/to/cert/file
SSLCertificateKeyFile /path/to/key/file

如果使用 Apache >= 2.4.47，您可以使用以下配置，无需使用任何 RewriteEngine、RewriteCond 或 RewriteRule 指令。例如：

RewriteEngine``RewriteCond``RewriteRule

ProxyPreserveHost on
ProxyPass http://localhost: /audiobookshelf upgrade=websocket
ProxyPassReverse http://localhost: /audiobookshelf

某些 SSL 证书（如 Let's Encrypt 签名的证书）需要 ACME 验证。要允许 Let's Encrypt 写入并确认 ACME 挑战，请编辑您的 VirtualHost 定义，以防止代理查询 /.well-known 的流量，而是直接提供该路径：

/.well-known

# ...

# 在 DocumentRoot 中创建 /.well-known/acme-challenges 目录结构
# 并给予 HTTP 用户递归写入权限
DocumentRoot /path/to/local/directory

ProxyPreserveHost On
ProxyPass /.well-known !
ProxyPass / http://localhost: /

# ...

SWAG 反向代理

参见 LinuxServer.io 配置示例

群晖 NAS 反向代理设置（DSM 7+/Quickconnect）

• 打开控制面板，导航至登录门户

高级。 Login Portal Advanced

• 常规选项卡，点击反向代理

创建。

• 来源配置

. .synology.me

• 示例主机名：audiobookshelf.mydomain.synology.me audiobookshelf.mydomain.synology.me

• 目标配置

• 自定义标头选项卡，前往创建

Websocket。 Create Websocket

• 配置标头（保持默认）：

$http_upgrade``$connection_upgrade

• 高级设置选项卡，保持默认。

Traefik 反向代理

与 CORS 相关的中间件会导致应用在登录时报告“未知错误”。为避免此问题，不要将以下任何标头应用于该站点的路由器：

• accessControlAllowMethods
• accessControlAllowOriginList
• accessControlMaxAge

来自 @Dondochaka 和 @BeastleeUK

示例 Caddyfile - Caddy 反向代理

subdomain.domain.com {
encode gzip zstd
reverse_proxy :
}

HAProxy

以下是通用 HAProxy 配置，使用 audiobookshelf.YOUR_DOMAIN.COM。

audiobookshelf.YOUR_DOMAIN.COM

要使用 http2，需要 ssl。

http2``ssl

global
# ...（您的全局设置在此处）

defaults
mode http
# ... (此处填写默认设置)

frontend my_frontend
# 绑定到443端口，启用SSL，并指定证书列表文件
bind :443 name :443 ssl crt-list /path/to/cert.crt_list alpn h2,http/1.1
mode http

# 为以"audiobookshelf"开头的子域名定义ACL
acl is_audiobookshelf hdr_beg(host) -i audiobookshelf

# 使用ACL：如果条件满足则将流量路由到audiobookshelf_backend，
# 否则使用default_backend
use_backend audiobookshelf_backend if is_audiobookshelf
default_backend default_backend

backend audiobookshelf_backend
mode http
# ... (此处填写audiobookshelf的后端设置)

# 定义audiobookshelf后端的服务器
server audiobookshelf_server 127.0.0.99:13378

backend default_backend
mode http
# ... (此处填写默认后端设置)

# 定义默认后端的服务器
server default_server 127.0.0.123:8081

pfSense 和 HAProxy

对于pfSense，输入为图形化界面，且健康检查已启用。

Health checking

前端、默认后端、访问控制列表和操作

访问控制列表

操作

条件ACL名称需要与上面的名称“audiobookshelf”匹配。

condition acl names
audiobookshelf

Use Backend

后端

名称需要与上面的参数“audiobookshelf”匹配。

Name
Parameters
audiobookshelf

名称：audiobookshelf

服务器列表：

健康检查：

默认启用健康检查。Audiobookshelf不支持OPTIONS的HTTP检查方法。如果健康检查失败，数据将不会转发。需要执行以下操作之一：

Http check method
OPTIONS

• 禁用：将健康检查方法改为none。
  Health check method
none
• 使健康检查生效：将HTTP检查方法改为HEAD或GET。
  Health check method
HEAD
GET

从源码运行

贡献

本应用使用NodeJs构建。

本地化

感谢Weblate免费提供本地化基础设施。如果您希望Audiobookshelf支持您的语言，请帮助我们进行本地化。有关帮助翻译的更多信息，请参见此处。

开发容器设置

开始开发此项目的最简单方法是使用开发容器。VSCode中开发容器的介绍可在此处找到。

所需软件：

• Docker Desktop
• VSCode

注意，可以使用Docker以外的其他容器软件和VSCode以外的其他IDE。但这种设置更为复杂，此处不做介绍。

注意：这需要带有winget的PowerShell命令提示符。您应该可以复制粘贴代码块进行安装。如果使用 elevated PowerShell 命令提示符，安装过程中不会弹出UAC。

winget install -e --id Docker.DockerDesktop; `
winget install -e --id Microsoft.VisualStudioCode

brew install --cask docker visual-studio-code

sudo snap install docker; \
sudo snap install code --classic

安装这些软件包后，现在可以安装VSCode的Remote Development扩展。安装此扩展后，打开命令面板（ctrl+shift+p或cmd+shift+p）并选择命令>Dev Containers: Rebuild and Reopen in Container。这将构建并启动开发环境容器。

ctrl+shift+p
cmd+shift+p
>Dev Containers: Rebuild and Reopen in Container

现在您已准备好开始开发！

手动环境设置

如果不想使用开发容器，仍然可以开发此项目。首先，需要安装NodeJs（20版）和FFmpeg。

接下来，需要在项目根目录中创建dev.js文件。该文件包含特定于您开发环境的配置信息和路径。您可以在.devcontainer/dev.js中找到此文件的示例。

dev.js
.devcontainer/dev.js

现在可以构建客户端：

npm ci
cd client
npm ci
npm run generate
cd ..

开发命令

设置开发环境后（无论是使用开发容器还是自定义环境），以下命令将帮助您运行服务器和客户端。

要运行服务器，可以使用命令npm run dev。这将使用在客户端目录中运行npm run generate时或启动开发容器时构建的客户端。如果对服务器进行更改，需要重启服务器。如果对客户端进行更改，需要运行命令(cd client; npm run generate)，然后重启服务器。默认情况下，客户端运行在localhost:3333，不过端口可以在dev.js中配置。

npm run dev
npm run generate
(cd client; npm run generate)
localhost:3333
dev.js

您也可以构建支持热重载的客户端版本。为此，先启动服务器，然后运行命令(cd client; npm run dev)。这将在localhost:3000运行一个单独的客户端实例，当您对客户端进行更改时，该实例将自动更新。

(cd client; npm run dev)
localhost:3000

如果使用VSCode，此项目包含几个预定义目标以加快此过程。首先，如果构建项目（ctrl+shift+b或cmd+shift+b），它将自动生成客户端。其次，有用于运行服务器和客户端的调试命令。您可以使用调试面板（通过ctrl+shift+d或cmd+shift+d调出）查看这些目标：

ctrl+shift+b
cmd+shift+b
ctrl+shift+d
cmd+shift+d

• Debug server—运行服务器。
  Debug server
• Debug client (nuxt)—运行带热重载的客户端。