本文说明如何用 Docker Compose 部署 Grimmory开启 OPDS 目录再用手机客户端访问自己的 EPUB 书库。重点是目录挂载、账号认证和连接排错。部署参数依据 Grimmory 安装文档 整理OPDS 配置依据 项目协议接入说明。客户端界面步骤来自已有操作录屏下文配置是供读者按设备调整的示例不代表已在所有 NAS 型号上测试。1. 先明确服务端与客户端的关系宿主机 books 目录 ↓ 挂载为容器内 /books Grimmory 扫描并管理书籍 ↓ /api/v1/opds使用 OPDS 专用账号认证 手机客户端浏览目录并获取 EPUB 文件服务端和客户端通过 OPDS 交换书目及文件链接。能够浏览目录不等于阅读进度和笔记会在不同客户端之间自动同步。本文先在同一个局域网中验证连接。示例服务器 IP 使用192.168.1.10实际操作时替换为自己的地址。书籍使用自己有权使用的 EPUB 文件。2. 准备持久化目录在运行 Docker 的设备上执行docker--versiondockercompose versionmkdir-pgrimmory/data grimmory/books grimmory/bookdrop grimmory/mariadbcdgrimmory后续命令均在这个目录执行。四个子目录分别保存应用数据、书籍、自动导入文件和数据库数据避免容器重建后丢失配置。Linux 或 NAS 上可用下面的命令查看准备运行服务的用户 IDid-uid-g将结果填入下一节的APP_UID和APP_GID并通过设备的权限管理界面或系统工具授予对应用户访问挂载目录所需的权限。3. 编写环境变量与 Compose 配置创建.env填入以下内容APP_UID1000 APP_GID1000 TZAsia/Shanghai MAPPED_PORT6060 DB_PASSWORDreplace_with_a_unique_app_password DB_ROOT_PASSWORDreplace_with_a_different_root_password把两个示例密码替换为不同的随机密码。应用与数据库共用DB_PASSWORD数据库 root 密码单独设置。不要将包含实际密码的.env上传到公开仓库。在同一目录创建compose.ymlservices:database:image:lscr.io/linuxserver/mariadb:11.4.5environment:PUID:${APP_UID}PGID:${APP_GID}TZ:${TZ}MYSQL_DATABASE:grimmoryMYSQL_USER:grimmoryMYSQL_PASSWORD:${DB_PASSWORD}MYSQL_ROOT_PASSWORD:${DB_ROOT_PASSWORD}volumes:-./mariadb:/confighealthcheck:test:[CMD,mariadb-admin,ping,-h,localhost]interval:5stimeout:5sretries:10restart:unless-stoppedgrimmory:image:grimmory/grimmory:latestenvironment:USER_ID:${APP_UID}GROUP_ID:${APP_GID}TZ:${TZ}SERVER_PORT:6060DATABASE_URL:jdbc:mariadb://database:3306/grimmoryDATABASE_USERNAME:grimmoryDATABASE_PASSWORD:${DB_PASSWORD}ports:-${MAPPED_PORT}:6060volumes:-./data:/app/data-./books:/books-./bookdrop:/bookdropdepends_on:database:condition:service_healthyrestart:unless-stopped镜像名和应用参数参考上述安装文档示例使用latest。需要重复部署时应把它改成项目实际发布的确定版本或镜像摘要并记录下来。这里的database是 Compose 服务名因此数据库地址写成jdbc:mariadb://database:3306/grimmory。无需把数据库端口映射到宿主机。先检查配置再启动dockercompose config--quietdockercompose pulldockercompose up-ddockercomposepsdockercompose logs--tail100grimmory database配置检查只能发现 YAML 和变量等问题。数据库健康、应用成功启动及页面可访问需要继续通过状态、日志和浏览器确认。4. 初始化并导入一本 EPUB在同一局域网的电脑浏览器打开http://192.168.1.10:6060按界面完成初始用户设置。把测试 EPUB 放入宿主机的grimmory/books目录然后在 Grimmory 中创建书库并选择/books执行扫描或导入。注意两种路径的区别宿主机上使用的是实际存储目录应用配置中使用的是容器内部路径/books。如果书籍在 NAS 的其他目录将./books:/books的左侧替换成实际绝对路径右侧和应用中的书库路径保持对应。继续之前确认两件事网页中能看到这本书并且能正常获取或打开文件。若扫描不到文件先检查挂载位置、文件权限和导入结果。5. 开启 OPDS 并创建独立账号进入 Grimmory 的Settings → OPDS开启OPDS Server Enabled。在OPDS Users中创建供客户端使用的账号例如opds_reader为它设置独立密码。OPDS 使用 HTTP Basic Auth账号与网页登录账号分开。该账号可见的书库取决于创建它的 Grimmory 用户权限认证成功但目录缺书时也要检查这一层权限。复制设置页显示的目录地址并核对手机能否访问对应主机。本文默认映射端口下的示例为http://192.168.1.10:6060/api/v1/opds如果MAPPED_PORT改成8080上述地址也应改成:8080。手机客户端里的localhost指向手机自身不能用它代替服务器 IP。6. 用 HTTP 响应区分网络与认证问题先在同一局域网的电脑终端执行curl--connect-timeout5--max-time15\-Dopds-headers.txt-oopds-feed.xml\-uopds_reader\http://192.168.1.10:6060/api/v1/opds-u只传用户名时curl 会交互询问密码输入上一节创建的 OPDS 密码即可。响应头和正文分别保存在两个文件中便于排查。验证时同时检查 HTTP 状态和正文正常情况下应取得成功响应及 OPDS 目录 XML。如果返回的是网页登录 HTML即使状态为 200也要检查是否填错地址或被反向代理重定向。现象下一步检查连接超时或拒绝连接服务器 IP、端口映射、应用状态、防火墙和网络隔离HTTP 401OPDS 用户名及密码是否误用了网页登录账号HTTP 403当前账号权限及反向代理的访问规则HTTP 404/api/v1/opds路径、服务开关和代理转发路径HTTP 200 但目录缺书是否完成导入以及创建 OPDS 账号的用户是否有书库权限电脑可用而手机不可用手机是否连到访客 Wi-Fi、是否存在客户端隔离或不同网段局域网验证阶段的 HTTP 示例仅用于可信网络。远程访问应使用自己的 VPN或配置具备有效证书的 HTTPS 入口Basic Auth 本身不加密传输内容。7. 手机客户端接入示例以下以离卷的 OPDS 配置界面为例其他支持 OPDS 的阅读器也需要目录地址、用户名和密码这三个参数。在离卷中进入书源页面选择添加 OPDS。填写完整目录地址http://192.168.1.10:6060/api/v1/opds。填写独立创建的 OPDS 用户名和密码保存配置。打开该书源检查能否显示刚才导入的测试 EPUB。获取并打开这本书确认文件读取正常。客户端菜单名称可能随版本变化按实际 OPDS 配置入口操作。如果能浏览书目却无法获取文件继续检查书目中的文件链接、文件权限以及反向代理生成的主机名、协议和端口。排错时按“容器启动 → 网页导入 → OPDS 认证 → 手机目录 → 文件读取”的顺序逐段验证可以判断问题发生在哪一环。