Docker 部署常见问题

本文用于排查 Docker / Docker Compose 部署中的常见问题。

访问不了页面

先确认容器是否正在运行：

docker ps

如果看不到 leelaa-reader 容器，说明服务没有正常启动。可以查看日志：

docker logs leelaa-reader

如果容器正在运行，再确认端口映射是否正确。例如配置为：

ports:
  - "18868:8686"

访问地址就应该是：

http://服务器IP:18868

ports 左侧是宿主机端口，决定用户访问哪个端口；右侧是容器内端口，通常保持 8686。

如果服务器开启了防火墙、安全组或 NAS 反向代理，还需要放行对应的宿主机端口。

删除容器后数据丢失

通常是没有挂载 /data，或挂载到了临时目录。

请确认 docker-compose.yml 中存在：

volumes:
  - ./data:/data

容器内的 /data 是核心数据目录，包含：

• SQLite 数据库 leelaa.db
• 初始管理员密码文件 password.txt
• 封面缓存
• 运行时文件

删除容器前，请确认宿主机上的 data 目录没有被删除。升级前也建议先备份该目录。

首次管理员密码在哪里

如果没有设置 DEFAULT_ADMIN_PASSWORD，系统会在首次启动且数据库为空时自动生成随机密码，并写入 /data/password.txt。

查看命令：

docker exec leelaa-reader cat /data/password.txt

也可以查看日志：

docker logs leelaa-reader

如果容器名称不是 leelaa-reader，请替换为实际容器名。

修改 DEFAULT_ADMIN_PASSWORD 后为什么没生效

DEFAULT_ADMIN_PASSWORD 只在数据库为空、首次创建管理员时生效。

如果数据库中已经存在用户，修改环境变量不会重置密码。请登录系统后在用户设置中修改密码。

本地书库路径应该怎么填

Docker 部署时，Leelaa Reader 只能看到容器内路径，不能直接看到宿主机路径。

例如 Compose 中配置：

volumes:
  - ./data:/data
  - /volume1/audiobooks:/books:ro

在 Leelaa Reader 里添加本地书库时，路径应该填写：

/books

不要填写宿主机上的 /volume1/audiobooks。

:ro 表示只读挂载，推荐用于书库目录，避免容器误改原始文件。

exec format error 是什么原因

exec format error 通常表示镜像架构和设备架构不匹配。

先确认 Docker 服务端架构：

docker version --format '{{.Server.Arch}}'

如果是 x86_64 / amd64 设备，可在 Compose 中指定：

platform: linux/amd64

如果是 ARM64 / aarch64 设备，指定：

platform: linux/arm64

一般情况下不需要手动指定，只有遇到架构识别异常或旧版 Docker 拉错镜像时才需要加。