Docker 部署指南

本指南适用于所有支持 Docker 的环境，包括 Linux、macOS、Windows、群晖、威联通等。

推荐使用 docker compose 部署。镜像已经内置前端页面、数据库默认路径和服务监听端口，普通用户只需要关心两件事：

ports：把容器服务端口暴露到宿主机，决定浏览器访问哪个端口。
volumes：把容器内数据目录挂载到宿主机，决定数据是否能持久保存。
激活服务默认使用 https://auth.leelaa.cn/api；只有切换到自建兼容服务时才需要设置 ACTIVATION_SERVICE_URL。

1. 快速部署

创建 docker-compose.yml：

yaml

services:
  leelaa-reader:
    image: leedaisen/leelaa-reader-server:latest
    container_name: leelaa-reader
    ports:
      - "8686:8686"
    volumes:
      - ./data:/data
    environment:
      TZ: Asia/Shanghai
      # 可选：首次初始化管理员密码。不填写时会自动生成，并写入 /data/password.txt。
      # DEFAULT_ADMIN_PASSWORD: 请设置强密码
    restart: unless-stopped

启动：

bash

docker compose up -d

访问：

text

http://服务器IP:8686

如果是在本机运行，也可以访问：

text

http://localhost:8686

查看首次生成的管理员密码：

bash

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

也可以查看容器日志：

bash

docker logs leelaa-reader

2. ports 说明

ports 用来配置宿主机端口到容器端口的映射：

yaml

ports:
  - "8686:8686"

格式是：

text

宿主机端口:容器端口

本镜像容器内服务端口固定使用 8686。通常只需要修改左侧宿主机端口，不需要修改容器内部端口。

例如宿主机 8686 已被占用，可以改成：

yaml

ports:
  - "18868:8686"

此时访问地址变为：

text

http://服务器IP:18868

对 Docker 部署来说，修改访问端口只需要改 ports 左侧的宿主机端口。

3. volumes 说明

volumes 用来配置数据持久化：

yaml

volumes:
  - ./data:/data

格式是：

text

宿主机目录:容器内目录

容器内的 /data 是 Leelaa Reader 的数据目录，包含：

SQLite 数据库
管理员初始密码文件 password.txt
封面缓存
运行时生成的临时文件

必须把 /data 挂载到宿主机目录。否则删除容器后，数据库和配置都会丢失。

可以使用相对路径：

yaml

volumes:
  - ./data:/data

也可以使用绝对路径：

yaml

volumes:
  - /volume1/docker/leelaa-reader/data:/data

Windows 示例：

yaml

volumes:
  - D:/docker/leelaa-reader/data:/data

如果需要让容器读取宿主机上的有声书目录，可以额外挂载书库目录：

yaml

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

然后在 Leelaa Reader 中添加本地书库时，路径填写容器内路径：

text

/books

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

4. 可选环境变量

普通部署只建议配置下面这些变量：

变量名	是否必填	说明
`TZ`	否	容器时区，国内用户建议设置为 `Asia/Shanghai`。
`DEFAULT_ADMIN_USERNAME`	否	首次初始化管理员用户名。数据库已有用户后不再生效；不填默认为 `admin`。
`DEFAULT_ADMIN_PASSWORD`	否	首次初始化管理员密码。数据库已有用户后不再生效；不填会自动生成并写入 `/data/password.txt`。

示例：

yaml

environment:
  TZ: Asia/Shanghai
  DEFAULT_ADMIN_USERNAME: admin
  DEFAULT_ADMIN_PASSWORD: 请设置强密码

如果已经完成首次初始化，之后再修改 DEFAULT_ADMIN_USERNAME 或 DEFAULT_ADMIN_PASSWORD 不会重置现有账号。

5. Docker Run

如果不使用 Compose，也可以直接运行：

bash

docker run -d \
  --name leelaa-reader \
  -p 8686:8686 \
  -v ./data:/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  leedaisen/leelaa-reader-server:latest

如果要指定首次管理员密码：

bash

docker run -d \
  --name leelaa-reader \
  -p 8686:8686 \
  -v ./data:/data \
  -e TZ=Asia/Shanghai \
  -e DEFAULT_ADMIN_PASSWORD=请设置强密码 \
  --restart unless-stopped \
  leedaisen/leelaa-reader-server:latest

6. 镜像架构

Docker 镜像支持多架构：

linux/amd64：常见 x86_64 服务器、Intel/AMD NAS、普通 PC。
linux/arm64：ARM64/aarch64 NAS、ARM 服务器、Apple Silicon 上的 Docker。

一般情况下直接使用 leedaisen/leelaa-reader-server:latest 即可，Docker 会自动拉取匹配架构。

可以先确认当前 Docker 服务端架构：

bash

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

如果日志中出现 exec format error，通常是镜像架构与设备架构不匹配。可以在 Compose 中显式指定：

yaml

services:
  leelaa-reader:
    image: leedaisen/leelaa-reader-server:latest
    platform: linux/amd64
    container_name: leelaa-reader
    ports:
      - "8686:8686"
    volumes:
      - ./data:/data
    environment:
      TZ: Asia/Shanghai
    restart: unless-stopped

ARM64/aarch64 设备使用：

yaml

platform: linux/arm64

7. 常用维护命令

查看容器状态：

bash

docker ps

查看日志：

bash

docker logs -f leelaa-reader

停止服务：

bash

docker compose down

升级镜像：

bash

docker compose pull
docker compose up -d

升级前建议先备份宿主机上的 data 目录。

8. 常见问题

部署后访问不了页面、删除容器后数据丢失、首次管理员密码找不到、本地书库路径填写错误等问题，请查看：Docker 部署常见问题。

Docker 部署指南 ​

1. 快速部署 ​

2. ports 说明 ​

3. volumes 说明 ​

4. 可选环境变量 ​

5. Docker Run ​

6. 镜像架构 ​

7. 常用维护命令 ​

8. 常见问题 ​

Docker 部署指南

1. 快速部署

2. ports 说明

3. volumes 说明

4. 可选环境变量

5. Docker Run

6. 镜像架构

7. 常用维护命令

8. 常见问题