# 业务配置

管理员在「我的 → 管理 → 服务配置」编辑实例业务配置，通过「配置分类」切换各分类。普通用户无法读取或修改服务凭据。

每个用户的影音权限在「我的 → 用户管理」中设置，包括管理员自己的权限；全站关闭时仍可管理。总开关与个人开关同时开启才可使用影音。生命周期、共享数据库与播放直链边界见[影音模块开关与纯阅读模式](media-features.md)。

| 分类 | 可修改内容 |
| --- | --- |
| 功能模块 | 全站启用影音、新用户默认启用影音，均默认开启；全站关闭进入纯阅读模式，保留影音数据 |
| AI 功能 | 启用 AI、AI 扫描与 AI 总结；OpenAI 兼容接口地址、API Key、模型（填写地址和密钥后可获取模型列表）、扫描与总结 Prompt、扫描批次大小、总结最大输入字符数 |
| 媒体播放 | OpenList 自动（直连优先）、浏览器直连、服务器代理；默认自动 |
| TMDB | 启用、读取令牌、API Key、元数据语言，令牌优先于 API Key |
| MusicBrainz | 启用、应用标识与联系地址，例如 `Reader/0.1 (mailto:admin@example.com)` |
| HTTP 朗读 | 启用、合成接口、Bearer 令牌、音色列表接口、超时、缓存上限，支持检测连接、获取音色、试听和清理缓存 |
| 扫描设置 | 阅读书库自动检查间隔（秒，默认 60，0 关闭）、同时扫描的媒体库数、远端文件处理并发数；影音库自动扫描新文件（每小时检查）、扫描后刮削封面与简介、读取内嵌字幕与歌词、扫描隐藏文件夹 |
| 刮削高级设置 | 请求超时、失败重试次数；MusicBrainz 的服务商限流仍强制执行 |
| 登录与服务访问 | 对外地址、允许的浏览器来源、访问令牌与登录续期有效期 |
| WebDAV 备份 | HTTPS 目录、账号、密码、上传上限、连接测试及已验证离线备份上传 |
| 书库 | 允许成员上传书籍（默认开启）。开启时成员只能在书库页新增支持格式的书籍文件，不解包压缩包、不覆盖已有文件；关闭后成员看不到上传按钮。改名、移动、删除和新建目录始终仅限管理员 |

注册策略在同一面板的「注册与邀请」管理；OpenList、媒体库目录及权限在「我的 → 媒体库」管理。影音扫描的四个开关同样显示在媒体库管理页，两处修改的是同一份配置。个人音色、语速和阅读样式不属于实例配置。

## 保存与生效

- 配置存入 `reader.db`，随完整 DATA_DIR 备份与恢复。备份含凭据，需限制访问权限。
- 凭据不回显。未编辑时保留，填写时替换，点击清除后保存会删除；关闭功能可以保留凭据。
- 保存后新请求使用新配置；已开始的朗读请求、扫描文件处理及批量刮削使用原配置。媒体库同时运行数量的调整在队列调度时应用。
- 阅读自动扫描合并为一个定时器；保存后重新计时，不重复触发两套相同扫描。启动时仍进行一次书库检查。
- 登录有效期调整只影响随后签发的令牌，不修改已经签发的令牌。OPDS 的对外地址立即更新。
- 连接测试与试听使用当前表单，成功不代表已经保存。重新加载会丢弃未保存编辑。
- 同一分类使用版本号防止覆盖其他管理员的修改；遇到冲突需重新加载后编辑。

## 旧配置迁移

升级首次初始化每个分类时，导入原有 `AI_BASE_URL`/`AI_API_KEY`/`AI_MODEL`、`MEDIA_TMDB_*`、`MEDIA_MUSICBRAINZ_USER_AGENT`、`TTS_*`、`PUBLIC_URL`、`CORS_ORIGINS`、登录有效期及 `WEBDAV_*` 环境变量。原 `SCAN_INTERVAL` 与 `WATCH_INTERVAL` 取启用值中的较小间隔，两者都关闭则关闭自动检查。已有注册策略优先于 `ALLOW_REGISTRATION`。

完成初始化后，环境变量不再覆盖已保存配置，清空凭据也不会让旧变量重新生效。部署端可移除这些业务环境变量。监听端口、DATA_DIR、BOOKS_DIR、WEB_DIR、签名密钥、日志级别和外部程序路径仍是部署参数。

## OpenList 播放

自动模式先验证 Reader 播放票据，再以 307 临时跳转交给浏览器读取 OpenList 的下载地址。管理 Token 和目录密码不下发；临时下载地址会出现在浏览器网络请求中，过期由上游控制，已签发地址不能由 Reader 立即撤销。同一播放会话的解析结果最多复用 30 秒，每次跳转仍校验访问权限。若 OpenList 自身启用了 Web 代理，流量仍可能经过 OpenList。

浏览器报告普通直连失败时，自动模式先尝试一次匿名 CORS 直连，以兼容 ORB 拦截；上游不允许 CORS 或仍失败时，再尝试一次 Reader 代理。直连 20 秒仍未读到媒体元数据时也会尝试代理。用户暂停、仅恢复页面不自动播放、浏览器拒绝自动播放时不会触发回退；用户手动继续播放后重新启用恢复。错误提示提供“通过服务器重试”，可主动切换当前会话而不修改全局配置。HTTPS 实例访问 HTTP 下载源时，自动模式直接使用代理。固定直连不自动回退；仅服务器可达或需要代理访问的资源可选择服务器代理。不进行转码，容器或编码不受浏览器支持时，代理也不能解决。

播放器立即打开并显示连接/缓冲状态。服务端日志 `media playback source ready/failed` 记录会话、传输方式、准备耗时和错误码，不记录签名地址或凭据；网络面板的 `Server-Timing` 可查看解析/上游准备时间。

## WebDAV 备份操作

这里配置备份目的地，不提供在线数据库快照。先按[离线备份指南](backup.zh-CN.md)停服制作完整、已验证的备份，再启动服务，从 WebDAV 页输入服务器可访问的备份目录及 `.zip` 文件名上传。容器中只能访问已挂载的目录。

上传先验证本地清单，临时上传后校验远端内容，再发布最终文件；不会覆盖同名备份。连接测试使用 `PROPFIND` 检查目录访问，不保证上传配额或写权限。

命令行仍可用 `node dist/maintenance/webdav-cli.js <备份目录> <名称.zip>`，读取 DATA_DIR 对应实例已保存的 WebDAV 配置，不再从环境变量读取目的地凭据。