# 常见问题（FAQ）

## Docker 启动后无法访问

1. 确认端口映射正确（默认 `6680:3000`）
2. 检查防火墙是否放行 6680 端口
3. 如果使用 NAS，确认 Docker 服务已正确启动
4. 查看日志排查错误：`docker compose logs -f`

## SQLite "out of memory" 错误

通常是**目录权限问题**，而非内存不足。Docker 环境下 `docker-entrypoint.sh` 会自动修复权限。手动运行时请确保 `data/` 目录对当前用户可写。

## 如何添加漫画/小说？

三种方式：

1. **文件目录** — 将文件放入 `comics/` 目录，系统自动扫描入库
2. **Web 上传** — 通过 Web UI 上传按钮直接上传文件
3. **额外目录** — 在 **设置 → 额外漫画目录** 中添加更多路径（Docker 需先挂载对应目录）

## 缩略图不显示

缩略图依次使用 `cwebp`、`ffmpeg`，均不可用时自动降级为 Go 原生 JPEG。Docker 镜像已内置首选的 `cwebp`。如仍不显示，请在 **系统诊断** 查看实际编码器状态，并在 **设置** 中手动触发缩略图批量生成。

## PDF 无法渲染

PDF 渲染依次使用 `pdftoppm`、`mutool`、ImageMagick `convert`。Docker 镜像已内置 `poppler-utils` 和 `mupdf-tools`；非 Docker 部署优先安装 `poppler-utils`。

## 如何配置 AI？

进入 **设置 → AI 面板**，选择供应商、填入 API Key、选择模型，点击「测试连接」验证后保存即可。AI 功能完全可选，不配置不影响任何核心功能。

## 如何使用 OPDS？

使用支持 OPDS 的阅读器（如 KOReader、Moon+ Reader），添加 OPDS 目录地址：

```
http://你的IP:6680/api/opds
```

Mihon 可通过第三方 OPDS 插件使用同一地址。客户端要求用户名和密码时，请填写 NowenReader 用户名，并把该用户创建的完整 API Key 作为密码；不要填写账户登录密码。在不可信局域网或公网使用时，请通过 HTTPS 访问。

OPDS 目录只包含已启用漫画书库中的受支持文件，且用户必须拥有对应书库的下载权限。小说书库、仅可查看的书库和已停用书库不会出现在目录中。根目录中的“Series”入口按现有合集组织漫画，普通漫画条目也会声明所属合集；客户端是否自动把它们合并展示取决于客户端实现。

当前同时支持 OPDS 1.2 文件获取和 OPDS-PSE 1.2 逐页阅读。CBZ/ZIP、CBR/RAR、CB7/7Z、PDF 以及已识别为图片漫画的 EPUB、MOBI、AZW3 可以按页返回 JPEG；文本小说仍只提供原始文件下载。逐页请求不会自动写入阅读进度，因为 OPDS 客户端可能预加载后续页面。

## 上传文件会保存到哪里？

取决于是否选择了目标书库：

- **选择了书库**：文件写入该书库的 `rootPath` 目录
- **未选择书库**（默认目录）：漫画文件写入 `comicsDir`，小说文件写入 `novelsDir`

上传后文件不会立即出现在列表中，需要等待系统自动扫描或手动点击"扫描目录"触发入库。

## 为什么上传时看不到某个书库？

只有满足以下条件的书库才会出现在上传选择列表中：

1. 书库已启用（`enabled = true`）
2. 书库的 `rootPath` 已配置且非空
3. 书库类型与当前页面匹配（漫画页只显示 comic/mixed 书库，小说页只显示 novel/mixed 书库）

请在**管理后台 → 书库管理**中检查对应书库的配置。

## 不选择目标书库上传会怎样？

文件会写入默认目录（漫画 → `comicsDir`，小说 → `novelsDir`），与旧版行为完全一致。这对于还没有创建书库的老用户来说是默认且安全的行为。

## 上传后为什么列表没有立刻出现？

上传接口只负责将文件保存到磁盘，**不会直接写入数据库**。文件入库依赖系统的同步/扫描流程（通常在上传成功后自动触发 `POST /api/sync`）。如果仍未出现，请手动点击首页的"扫描目录"按钮。

## 多漫画目录怎么配置？

**推荐方式：使用书库管理**

在**管理后台 → 书库管理**中创建独立书库（漫画库/小说库/混合库），支持目录浏览选择、公开/私有访问控制、自动扫描开关。管理员还可以为不同用户分配不同的书库访问权限。

**兼容方式：旧版目录配置**

旧版的环境变量和"站点设置 → 额外漫画目录"仍然可用：

1. Docker 环境：先在 `docker-compose.yml` 中挂载对应宿主机目录到容器内路径

   ```yaml
   volumes:
     - /your/manga/path1:/mnt/manga
     - /your/manga/path2:/mnt/comics2
   ```

2. 在 Web UI **设置 → 额外漫画目录** 中添加容器内的挂载路径
3. 系统会自动扫描所有配置的目录

## 如何更新到最新版本？

```bash
# Docker 部署
docker compose pull
docker compose up -d

# 二进制部署
# 下载最新 Release，替换二进制文件后重启即可
```

数据库升级自动完成，无需手动操作。

## NAS 上遇到 permission denied 怎么办？

NAS 上挂载主机目录时常因 UID/GID 不匹配导致权限问题。优先在 Compose 文件的 `environment` 中配置为宿主机文件的实际 UID/GID：

```yaml
environment:
  - PUID=1001  # 替换为你 NAS 上的 UID
  - PGID=1001  # 替换为你 NAS 上的 GID
  - UMASK=0002
```

可通过 `ls -ln` 查看实际 UID/GID。启动日志会检查 `appuser` 是否真的能写入 `/data`、缓存目录和书库目录；如果显示仍不可写，说明 Docker 容器内用户和 NAS 挂载权限仍未对齐。

如果是 SMB/NFS/部分 NAS 共享目录，文件系统可能禁止容器内 `chown`。在确认目录确实要允许容器写入后，可以开启宽松回退：

```yaml
environment:
  - PERMISSION_FIX_MODE=relaxed
```

另外，书库管理里要填写**容器内路径**，不是宿主机路径。例如 compose 中写的是：

```yaml
volumes:
  - /volume1/comics:/app/comics
```

那么 Web UI 里的书库根目录应填写 `/app/comics`，不要填写 `/volume1/comics`。

## 数据库存在哪？是否需要备份？

数据库默认位于 `${DATA_DIR}/nowen-reader.db`（Docker 内为 `/data/nowen-reader.db`）。

**强烈建议定期备份此文件**，这里存储了：
- 所有用户、阅读历史
- 收藏、评分、阅读进度
- 标签、分类、合并分组
- 元数据修改

直接备份 `.db` 文件即可，无需额外导出。

## 内存占用多少？

实际日常占用通常在 100-200 MB。NAS 配置文件 (`docker-compose.nas.yml`) 默认设置 512 MB 内存上限，足够流畅运行。

## 如何调整漫画图片亮度 / 对比度 / 灰度？

在漫画阅读器中打开设置面板，找到「图片滤镜」区域。可以拖动亮度、对比度、灰度滑块实时调整，也可以一键应用预设（夜间护眼、老漫画增强、黑白增强）。设置会自动保存。

## Webtoon 模式如何放大查看细节？

在 Webtoon 模式下双击图片区域即可放大到 200%，再次双击还原。放大状态下可以单指拖拽平移查看细节，右下角显示缩放比例。

## 漫画书签保存在哪里？

漫画书签保存在浏览器 localStorage 中，按漫画 ID 分组存储。每本漫画的书签互不影响，刷新页面后仍然保留。目前不支持跨设备同步。

## 阅读状态是每个用户独立的吗？

是的。每个用户的「想读」「在读」「已读完」状态完全独立，不会互相影响。多个用户看同一本漫画，各自标记的状态不会覆盖。

## 为什么我和其他用户看到的想读/在读/已读完不一样？

这是正常行为。阅读状态是用户级的，每个用户有自己独立的状态。如果您想让所有用户看到相同的阅读状态，请注意这不是当前设计的目标——每个用户的阅读习惯应该是私人的。

## 还有问题？

- 🐛 [GitHub Issues](https://github.com/cropflre/nowen-reader/issues)
- 💡 [GitHub Discussions](https://github.com/cropflre/nowen-reader/discussions)
- 💬 QQ 交流群：**1093473044**