企业官网建设流程全解析

ReadMeABook是一款专为有声书设计的自动化请求与下载引擎：提交一本书，它自动完成搜索索引器、下载、整理文件、触发 Plex / Audiobookshelf 扫描的全流程。本文带你用 Docker 或 Unraid 一步到位完成ReadMeABook 部署，并重点拆解新手最容易翻车的卷映射问题——这也是下载不到、找不到文件的首要元凶。

两种 ReadMeABook 部署方案怎么选 🧭

💡 新手推荐统一镜像：零外部依赖、密钥自动生成、更新只需重建一个容器。

方案一：Docker 单容器镜像（推荐）

统一镜像ghcr.io/kikootwo/readmeabook:latest把 PostgreSQL、Redis、Next.js 应用打包进一个容器，由 supervisord 按postgres → redis → app的顺序启动（见 docker/unified/supervisord.conf）。

关键机制：首次启动会自动生成 JWT_SECRET、CONFIG_ENCRYPTION_KEY、POSTGRES_PASSWORD 等全部密钥，并持久化到config/.secrets，重启时复用——不需要你手动配置任何密码。

官方镜像文件 docker-compose.yml 已预置 6 个持久化卷，核心配置如下（摘取自官方文件）：

services: readmeabook: image: ghcr.io/kikootwo/readmeabook:latest container_name: readmeabook restart: unless-stopped ports: - "3030:3030" volumes: - ./config:/app/config # 配置 + 密钥（务必持久化） - ./cache:/app/cache # 封面缩略图缓存 - ./downloads:/downloads # 下载目录（与下载器对齐） - ./media:/media # 有声书媒体库 - ./pgdata:/var/lib/postgresql/data - ./redis:/var/lib/redis environment: PUID: 1000 # 宿主机用户 ID，先运行 id 查看 PGID: 1000 # 宿主机组 ID # PUBLIC_URL: "https://readmeabook.example.com" # 使用 OAuth 时必填 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3030/api/health"] interval: 30s timeout: 10s retries: 3 start_period: 60s

启动并进入初始化向导：

docker compose up -d # 浏览器打开 http://<服务器IP>:3030/setup

向导（Setup Wizard）会引导你接入 Prowlarr、下载客户端（qBittorrent / SABnzbd）、Plex / Audiobookshelf，并自带连接测试。

方案二：多容器 Compose

如果团队已有独立的 Postgres / Redis，可用三容器架构（app 3000 端口 + PostgreSQL 16 + Redis 7，详见 documentation/deployment/docker.md）。注意：

• Postgres、Redis只在内网监听，不暴露到宿主机；
• 需要手动生成NEXTAUTH_SECRET（openssl rand -base64 32写入 compose）；
• 应用启动时自动执行prisma migrate deploy，无需手动迁移。

Unraid 安装步骤：官方模板 3 步搞定 🐳

项目仓库自带 Unraid 官方模板 unraid.xml：

1. Unraid →Apps（Community Applications）→ 右上角Add Template；
2. 粘贴官方模板 URL：https://raw.githubusercontent.com/kikootwo/ReadMeABook/main/unraid.xml；
3. 安装后在模板表单中确认：
   • Web UI Host Port：3030
   • Config Location：/mnt/user/appdata/readmeabook/config
   • Postgres Storage Location：/mnt/user/appdata/readmeabook/pgdata
   • Download Location：务必与你的下载器指向同一目录，例如/mnt/user/data/downloads
   • Media Library：/mnt/user/data/media/audiobooks
   • 高级选项中的PUID / PGID：保持 Unraid 默认99/100即可

⚠️ 使用 Plex / OIDC 登录时，记得在模板的PUBLIC_URL填入你的公网 HTTPS 地址，否则 OAuth 回调会失败。

卷映射黄金法则：下载器和 RMAB 必须"看见同一条路径" 📏

这是 ReadMeABook 部署中最容易翻车的一步，官方称之为黄金法则（documentation/deployment/volume-mapping.md）：

下载客户端和 ReadMeABook在容器内看到文件的路径必须完全相同。 映射行的左侧（宿主路径）可以各不相同，右侧（容器内路径）必须一模一样。

❌ 反例的后果：两个容器各自为政，RMAB 永远在/downloads找文件，而文件躺在/data/torrents，请求状态卡在"等待下载完成"。

如果下载器把成品放在子目录（qBittorrent 常见/downloads/complete），RMAB 后台的Download Directory也要填/downloads/complete，两边对到同一格。

验证卷映射是否正确的 3 步

1. 下载客户端设置页：qBittorrent 看Options → Downloads → Default Save Path；SABnzbd 看Config → Folders → Completed Download Folder；
2. RMAB 设置页：Download Directory 必须落在上述同一目录内；
3. 发起一次真实下载，在 RMAB 日志中找organizePath——出现合法路径即说明映射打通。

不会算？打开 Web UI 里的Path Helper（/path-helper页面）：选择下载客户端 → 填保存路径与映射 → 自动生成正确的卷映射，源码见 src/app/path-helper/page.tsx。

💡 进阶场景（下载器在另一台机器上、或无法对齐挂载点）才需要开启Remote Path Mapping，官方文档标注 99% 的用户用不到，可跳过。

部署避坑清单：权限、密钥与备份

坑 1：权限错误Operation not permitted

绑定挂载目录在 LXC、NFS / CIFS 或非 root 用户运行 Docker 时最容易触发。解法：

id # 输出示例：uid=1000(youruser) gid=1000(yourgroup)

把得到的 UID/GID 填入 compose 的PUID/PGID，然后：

docker compose down && docker compose up -d

ReadMeABook 会启用"混合映射"策略：downloads、media、config归属你的用户，PostgreSQL 数据目录保持 UID 103 + 组权限。完整原理见 documentation/deployment/unified.md。

WSL2 用户在/mnt/c/下挂载绑定卷同样会报权限错，改用命名卷或把项目放到 Linux 文件系统即可。

坑 2：.secrets丢失 → 本地管理员无法登录

本地管理员密码会用CONFIG_ENCRYPTION_KEY加密存储；密钥若丢失（比如config卷没持久化），重启后自动换新密钥，密码就"解密失败"了。备份 config 卷时必须包含.secrets文件。

更新与备份：一键命令

# 更新（多容器：代码在本地；统一镜像则 git pull 后 docker compose up -d --build 重建） git pull docker compose up -d --build # 数据库迁移自动执行

# 备份数据库（统一镜像） docker exec readmeabook su - postgres -c "pg_dump -h 127.0.0.1 -U readmeabook readmeabook" > backup.sql # 备份数据库（多容器） docker compose exec postgres pg_dump -U readmeabook readmeabook > backup.sql # 恢复 cat backup.sql | docker exec -i readmeabook su - postgres -c "psql -h 127.0.0.1 -U readmeabook readmeabook"

容器起不来时三连查：

docker compose logs -f app docker compose exec app npx prisma migrate status docker exec readmeabook redis-cli ping # 应返回 PONG

部署成功后的样子 🎉

首页会展示热门有声书网格，卡片上的绿色圆点与 "ONLY on audible" 角标一目了然：

管理面板中System Health 显示 HEALTHY、能看到请求统计与下载队列，说明各服务全部在线；BookDate 页面则是 Tinder 式推荐卡片，右滑即可一键请求新书。

小结

• Docker 用户：首选单容器统一镜像，改好PUID/PGID，6 个卷全部持久化，10 分钟走完 Setup Wizard；
• Unraid 用户：导入官方模板，重点核对 Download Location 与下载器一致；
• 卷映射：容器内路径一致是黄金法则，拿不准就用/path-helper工具生成；
• 备份：pgdata+config（含.secrets）双卷备份，更新永不慌。

相关资料

• 单容器部署文档：documentation/deployment/unified.md
• 多容器部署文档：documentation/deployment/docker.md
• 卷映射指南：documentation/deployment/volume-mapping.md
• 官方 compose 文件：docker-compose.yml
• Unraid 模板：unraid.xml
• 路径助手源码：src/app/path-helper/page.tsx