Readest-Lite Docker容器部署教程-NodeByte

还在为想沉静看书找阅读器而发愁？好不容易找到一款Readest结果却被部署后端累垮？
Readest-Lite正好帮你解决这些问题！我们做了些什么呢详见Readest-Lite 迭代日志与核心特点

注意： 只需要 Docker，无需安装 Node.js 或数据库。

系统：Linux / macOS / Windows (WSL2)
Docker：20.10+ 及 Compose V2
内存：最低 512MB，推荐 1GB+
端口：默认 8225（可改）

安装 Docker

# 一键安装 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo systemctl enable --now docker

# 验证
docker --version

安装后需重新登录终端或执行 newgrp docker 使权限生效。macOS 推荐 Docker Desktop。

快速开始

一条命令拉起，30 秒后访问 http://localhost:8225。

docker run -d \
  --name readest-lite \
  -p 8225:8225 \
  -v readest-data:/data \
  -e [email protected] \
  -e ADMIN_PASSWORD=changeme \
  -e ADMIN_USERNAME=Admin \
  -e PUBLIC_BASE_URL=https://read.yourdomain.com \
  --restart unless-stopped \
  ghcr.io/cshdotcom/readest-lite:latest

请务必修改默认密码，生产环境使用 16 位以上随机字符串。

CLI 方式环境变量说明

通过 docker run -e 传递，常用 env：

ADMIN_EMAIL（必填）：管理员邮箱，首次启动自动创建账号
ADMIN_PASSWORD（必填）：管理员密码，建议 16+ 位随机字符串
ADMIN_USERNAME（可选，v8.1 新增）：管理员显示名，用户列表里展示用。未设置时回退到邮箱
PUBLIC_BASE_URL（可选，反向代理场景必填）：对外访问 URL，用于生成上传/下载文件的签名 URL。例如 https://read.yourdomain.com。未设置时默认 http://localhost:8225，浏览器外不可达
PORT（可选，默认 8225）：容器内监听端口，一般不需修改
DEEPL_ENABLED=true（可选）：启用 DeepL 翻译，需配合 DEEPL_FREE_API_KEYS 或 DEEPL_PRO_API_KEYS

指定特定版本：ghcr.io/cshdotcom/readest-lite:v8.14.1（每个版本都有对应 git tag，详见 GitHub Releases）。

Docker Compose 部署（推荐）

配置清晰、升级方便、重启自动恢复，适合长期运行。

docker-compose.yml

version: "3.8"
services:
  readest-lite:
    image: ghcr.io/cshdotcom/readest-lite:latest
    container_name: readest-lite
    restart: unless-stopped
    ports:
      - "${PORT:-8225}:8225"
    volumes:
      - ./data:/data
    environment:
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-}
      - DEEPL_ENABLED=${DEEPL_ENABLED:-false}

.env

[email protected]
ADMIN_PASSWORD=your-secure-password
PORT=8225
# 可选：反向代理场景必填
PUBLIC_BASE_URL=https://read.yourdomain.com
# 可选：翻译功能（默认关闭）
DEEPL_ENABLED=false
DEEPL_FREE_API_KEYS=
DEEPL_PRO_API_KEYS=

如果喜欢的话就给我点个Star吧！

常用命令

docker compose up -d       # 启动
docker compose ps           # 状态
docker compose logs -f      # 日志
docker compose down          # 停止

restart: unless-stopped 确保容器在 Docker 重启或意外退出后自动恢复。

环境变量

容器启动时读取，修改后需重启生效。

变量	必填	默认	说明
ADMIN_EMAIL	必填	—	管理员邮箱，首次启动自动创建账号
ADMIN_PASSWORD	必填	—	管理员密码，建议 16+ 位随机字符串
ADMIN_USERNAME	可选	—	v8.1 新增：管理员显示名，用户列表里展示用。未设置时回退到邮箱
PUBLIC_BASE_URL	可选	http://localhost:8225	对外访问 URL，反向代理/分享场景必填。例如 https://read.yourdomain.com
PORT	可选	8225	容器内监听端口，一般不需修改
DEEPL_ENABLED	可选	false	设为 true 启用 DeepL 翻译，需配合 DEEPL_FREE_API_KEYS 或 DEEPL_PRO_API_KEYS
JWT_SECRET	可选	派生	JWT 密钥，不设置时由 ADMIN_EMAIL + ADMIN_PASSWORD 派生

将 .env 加入 .gitignore，避免密码泄露到版本控制。

数据持久化

所有数据存储在容器 /data 目录，通过卷挂载确保容器重建不丢失。

目录结构

data/ ├── db/ SQLite 数据库 │ └── readest.db 用户、书籍、进度、批注 ├── books/ 书籍文件 │ ├── uploads/ 上传的电子书 │ └── covers/ 自动生成的封面 └── config.json 运行时配置（自动生成）

备份

# 停止容器后打包
tar czf readest-backup-$(date +%Y%m%d).tar.gz data/

# 保留最近 30 天
find . -name "readest-backup-*.tar.gz" -mtime +30 -delete

备份前建议先停止容器，避免 SQLite 在写入中被打包出损坏的文件。

升级更新

定期升级获取最新功能与修复，数据不受影响。

# 拉取最新镜像
docker compose pull

# 重建容器（数据在 ./data 不受影响）
docker compose up -d

# 清理旧镜像
docker image prune -f

启动时自动检测数据库版本并执行迁移，无需手动操作。

多用户管理

管理员可以在用户中心创建和管理普通用户。

创建用户

管理员登录后进入「用户中心」
在「用户管理」面板点击「新建用户」
填写邮箱、密码、显示名称
设置存储配额（MB）和翻译配额（KB），0 = 无限
点击创建，用户即可用邮箱密码登录

普通用户登录后看不到用户管理面板，只能查看自己的账号信息。管理员可以编辑任何用户的密码、名称和配额，也可以删除非管理员用户。

常见问题

启动后无法访问？

docker ps 确认容器状态为 Up
curl http://localhost:8225 在服务器本地测试
检查防火墙：sudo ufw allow 8225
docker logs readest-lite 查看错误日志

如何修改密码？

修改 .env 中的 ADMIN_PASSWORD，然后 docker compose down && docker compose up -d。

如何换端口？

修改 docker-compose.yml 端口映射："9000:8225"（左边是对外端口）。

书籍存在哪里？

data/books/uploads/ 存书籍原文，data/books/covers/ 存封面图，容器重建不丢失。

支持多用户吗？

支持！管理员登录后在「用户中心」可以看到「用户管理」面板，可以创建普通用户、设置用户名密码、分配存储和翻译配额。普通用户登录后只能看到自己的账号信息，没有管理权限。

切换账号后，原来账号的书会泄露吗？

v8.3 起不会。登出时系统会彻底清空当前账号的：

书库列表（library.json 覆盖为空）
同步游标（lastSyncedAtBooks/Configs/Notes 重置为 0）
第三方服务凭据（WebDAV/KOSync/Readwise/Hardcover/AI 全部重置）
App Lock PIN（清空）
上传/下载队列（清空）

登录新账号后，系统走全量 pull（since=0），只拉取新账号的云端书。本地 Books/ 目录下的书籍文件保留（不删），但不会出现在新账号的书库列表里——除非新账号的云端也有同 hash 的书。

未登录时导入的书：如果你没登录就导入了书，登录账号后这些书会自动同步到当前登录的账号（不会被清空）。

如何使用远程下载？

在书库页面点击「导入」→「Download from URL」，输入书籍直链地址（如 https://example.com/book.epub）。v8.1 修复了书架不显示问题：下载完成后服务器同时写入 Book 表，新书会出现在书库中，多端 sync 同步可见。

翻译和词典需要登录吗？

v8.0 起所有翻译/词典代理强制要求登录，包括：

/api/translate/google（Google 翻译）
/api/proxy/wiki（Wikipedia / Wiktionary 词典查询）
/api/proxy/resource（通用资源代理）
/api/deepl/translate（DeepL，本就强制登录）

未登录调用返回 401。客户端无需加速器：只要服务器能访问 Google，前端通过代理就能用。

浏览器直接访问 /api/translate/google 显示”认证失败”是 bug 吗？

不是 bug，是预期行为。翻译/词典代理是 POST 接口，需要 Authorization: Bearer <token> 头。浏览器地址栏直接 GET 访问不会带这个头，所以返回 401 “Authentication required”。

v8.2 给三个代理路由加了 GET health check，返回带 hint 字段的 JSON，告诉你如何用 curl 测试：

# 测试 Google 翻译代理（替换 YOUR_TOKEN 和 your-host）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  -d '{"text":["hello"],"targetLang":"zh"}' \
  https://your-host/api/translate/google

# 测试 Wikipedia 代理
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-host/api/proxy/wiki?url=https://en.wikipedia.org/api/rest_v1/page/summary/Hello"

在应用内正常使用（选中文字 → 翻译/词典按钮）会自动带 token，不需要手动操作。

v8.2 代理开关怎么用？

登录后进入「设置 → Integrations → Network」，有「Server Proxy」开关：

开启（默认）：翻译/词典走服务器代理，客户端无需加速器
关闭：客户端直连 Google/Wikipedia 等目标 URL，需要客户端本地网络能访问这些站点（例如客户端在国外网络或自备加速器）

注意：Edge TTS 不受此开关影响（始终保持 wss 直连 + https 代理降级行为）。DeepL 也不受影响（API key 在服务器，必须走代理）。

100TB 配额是硬限制吗？

不是。100TB 是前端展示用的软上限，实际不强制执行——上传代码不查配额，真正的限制只有宿主机磁盘空间。管理员在用户管理面板设置的 storageQuotaMB 字段当前为展示型（v8.3 计划补上 enforce 逻辑）。

翻译和词典需要加速器吗？

不需要（代理开启时）。Google 翻译、Wikipedia、Wiktionary 都通过服务器代理访问。只要服务器能访问 Google（如国外 VPS），客户端无需加速器即可使用。如果关了代理开关，客户端需要自己能访问这些站点。

如何启用 DeepL 翻译？

在 .env 中设置 DEEPL_ENABLED=true 和 DEEPL_FREE_API_KEYS 或 DEEPL_PRO_API_KEYS，重启容器即可。

如何迁移数据？

直接复制整个 data/ 目录到新服务器，用相同参数启动容器即可。SQLite 文件可跨平台使用。

文章版权归作者所有，未经允许请勿转载。

THE END

Readest-Lite部署教程——只要一个容器！！