Atsumeru 1.1 配置参数详解

目标：把 Atsumeru 1.1 服务的全部可调配置讲透——/app/config 下两个属性文件（atsumeru.properties 运行设置、folders.properties 导入目录注册表）、users.db 里的用户权限模型、JVM 堆与端口参数，每项给出查看/修改方式、默认值与实测回显。环境为本专栏部署篇的 Compose 栈（2026-11-01 实测）；部署过程见 《Atsumeru Docker Compose 部署指南》，组件背景见 《Atsumeru 介绍与选型指南》。

一、环境信息

• 软件版本：Atsumeru v1.1（/api/server/info 实测返回 "version":"1.1","version_name":"Bohrium"）
• 运行形态：Docker Compose 栈 atsumeru-11-stack，服务端口 31337、宿主映射 8138，JVM -Xms256m -Xmx512m
• 配置目录：容器 /app/config（宿主 bind 于 tmp/atsumeru/config），含 atsumeru.properties、folders.properties
• 数据目录：容器 /app/database（library.db 书库 + users.db 用户库，SQLite）
• 演示账号：Admin / q1w2e3r4（管理员）、root / q1w2e3r4（普通用户，本篇 5.3 实测创建）
• 取证方式：配置值一律经 /api/v1/settings/get、/api/v1/importer/list、/api/v1/users/* 实测回显 + 宿主侧 cat 属性文件 + 源码（jsDelivr 镜像 Atsumeru-xyz/Atsumeru@1.1）交叉核对

二、前置条件

1. 服务已按部署篇拉起且健康（docker compose -p atsumeru-11-stack ps 显示 (healthy)）；
2. 具备管理员凭据（Admin / q1w2e3r4），API 认证为 HTTP Basic（1.1 无 token 端点，见部署篇 4.3 排障实录）；
3. 本篇所有 curl 均针对 http://localhost:8138，远程管理时替换为宿主地址。

三、参数查看与修改方式

Atsumeru 1.1 的配置有三条通路，优先级与生效方式不同：

运行设置的 API 读写实测（先读默认值）：

curl -s -u 'Admin:q1w2e3r4' http://localhost:8138/api/v1/settings/get

{"allow_loading_list_with_volumes":true,"allow_loading_list_with_chapters":true,"disable_request_logging_into_console":false,"disable_file_watcher":false,"disable_watch_for_modified_files":false,"disable_chapters":true}

修改经 POST /api/v1/settings/update 提交全量 JSON（非增量，缺字段会被置 false），实测：

curl -s -X POST -u 'Admin:q1w2e3r4' -H 'Content-Type: application/json' \
  -d '{"allow_loading_list_with_volumes":true,"allow_loading_list_with_chapters":false,"disable_request_logging_into_console":true,"disable_file_watcher":false,"disable_watch_for_modified_files":false,"disable_chapters":true}' \
  http://localhost:8138/api/v1/settings/update

{"code":200,"message":"Settings updated successfully"}

curl -s -u 'Admin:q1w2e3r4' http://localhost:8138/api/v1/settings/get

{"allow_loading_list_with_volumes":true,"allow_loading_list_with_chapters":false,"disable_request_logging_into_console":true,"disable_file_watcher":false,"disable_watch_for_modified_files":false,"disable_chapters":true}

两处改动（allow_loading_list_with_chapters true→false、disable_request_logging_into_console false→true）读回一致。

⚠️ 注意：源码 SettingsApiController 显示，当导入/元数据更新/封面缓存任务任一在跑时，settings/get|update 会返回 406 Unable to edit server settings；批量导入期间改配置需等 importer/status 的 import_active 归 false。

四、atsumeru.properties 六键详解

修改生效后宿主侧文件同步落盘（实测 cat）：

#Auto save properties: Sun Nov 01 11:18:52 UTC 2026
#Sun Nov 01 11:18:52 UTC 2026
allow_loading_list_with_volumes=true
allow_loading_list_with_chapters=false
disable_chapters=true
disable_file_watcher=false
disable_watch_for_modified_files=false
disable_request_logging_into_console=true

💡 技术拓展：Atsumeru 的属性持久化不止"文件即时写"一种策略。

策略	特点	代表
变更即写 properties 文件	简单可靠、崩溃不丢；文件带时间戳头	Atsumeru（本文）
仅关闭时落盘	减少 IO；崩溃丢配置	早期 Java 服务常见
配置入数据库	集中管理、可审计	Kavita 的 settings 表

Atsumeru 每次 settings/update 立即 properties.store()（源码 Settings.saveProperties），所以宿主 bind 目录里总能 cat 到最新值。

4.1 allow_loading_list_with_volumes（默认 true）

控制列表接口 GET /api/v1/books?with_volumes=true 是否真的内联返回卷清单。关掉后列表请求强制不带卷，客户端需逐册调 /books/{hash}/volumes——大书库下能显著降低列表响应体积。实测本环境保持 true 时列表请求直接返回系列条目（卷需另取，行为与源码 Settings.isAllowListLoadingWithVolumes() && withVolumesAndHistory 的与逻辑一致）。

4.2 allow_loading_list_with_chapters（默认 true）

同上，控制 with_chapters=true 是否生效。与 disable_chapters（4.6）联动：章节体系关闭时此键无实际意义。

4.3 disable_request_logging_into_console（默认 false）

true 后请求日志不再刷控制台（docker logs 变干净），但文件日志 logs/requests.log 照常记录。实测置 true 后：

head -3 /opt/data/quzuo/tmp/atsumeru/logs/requests.log

INFO:[Sun Nov 01 11:13:58 UTC 2026] [10.89.57.1@Admin] Requested /server/info
INFO:[Sun Nov 01 11:17:36 UTC 2026] [10.89.57.1@Admin] Requested /api/server/ping
INFO:[Sun Nov 01 11:17:37 UTC 2026] [10.89.57.1@Admin] Requested /api/server/info

（首行 /server/info 即部署篇 4.5 排障实录中 404 的那次请求，日志按请求路径原样记录。）

4.4 disable_file_watcher（默认 false）

true 后关闭导入文件系统监听，新文件只有手动 GET /api/v1/importer/scan 才入库。适合批量拷书期间避免边写边导；部署篇 4.7 的"注册目录即完成首轮导入"正是监听器在工作。

4.5 disable_watch_for_modified_files（默认 false）

监听开启时是否忽略"被修改的既有文件"。NAS 上用外部工具改压缩包（如补页）后若不重导，就是此键为 true 所致；默认 false 会触发重导入。

4.6 disable_chapters（默认 true）

1.1 起章节功能默认关闭（changelog 明示 "chapters are disabled by default"），书库按 系列→卷 两级组织。实测默认值回显即 true（见第三章）。改动此键会触发服务器延迟自动重启（源码 restartServerDelayed：等待导入/元数据任务空闲后 AtsumeruApplication.restart()），本篇未实测翻转以避免打断栈状态，生产上翻转前先排空导入任务。

五、folders.properties 与用户权限模型

5.1 导入目录注册表字段语义

folders.properties 是单行 JSON 数组（实测 cat 见部署篇第七章），每个目录对象字段（源码 ImportFolder 模型 + API 实测）：

注册/移除/重扫 API 用法见部署篇 4.6–4.7；单目录重扫 GET /api/v1/importer/rescan/{hash}（源码实测端点，全量参数 fully、封面刷新参数 update_covers）。

5.2 用户库权限字段

users.db 的 USERS 表结构（宿主侧 strings 实测取证）：

CREATE TABLE `USERS` (`id` INTEGER PRIMARY KEY AUTOINCREMENT , `USERNAME` VARCHAR , `PASSWORD` VARCHAR , `ROLES` VARCHAR , `AUTHORITIES` VARCHAR , `ALLOWED_CATEGORIES` VARCHAR , `DISALLOWED_GENRES` VARCHAR , `DISALLOWED_TAGS` VARCHAR )

口令为 BCrypt 存储（实测 users/list 返回 $2a$10$... 哈希，非明文）。权限三层的可选值经 API 实查：

curl -s -u 'Admin:q1w2e3r4' http://localhost:8138/api/v1/users/constants

{"roles":["ADMIN","USER"],"authorities":["IMPORTER","UPLOADER","METADATA_UPDATER","DOWNLOAD_FILES"],"categories":[{"id":"atsumeru-category966faeabbc679ba4457e2d75e031d487","name":"Unsorted","content_type":"UNKNOWN","order":0}],"genres":[...33 项，Action/Adult/Adventure/Comedy/Doujinshi/Drama...],"tags":[]}

💡 技术拓展：内容服务器的访问控制模型不止本文这一种。

模型	机制	代表
角色（RBAC）	ADMIN/USER 粗粒度	Atsumeru roles、Kavita roles
细粒度权限位	按动作授权（导入/上传/改元数据/下载）	Atsumeru authorities
内容白名单	仅允许指定分类可见	Atsumeru ALLOWED_CATEGORIES
内容黑名单	屏蔽指定流派/标签	Atsumeru DISALLOWED_GENRES/DISALLOWED_TAGS

Atsumeru 四层并用：角色定 API 面（如 ADMIN 才能进 /api/v1/settings），权限位定动作，白名单+黑名单定内容可见性——家庭共享按"分类白名单 + Adult 流派黑名单"给孩子开号即可。

5.3 建受限用户实测

curl -s -X PUT -u 'Admin:q1w2e3r4' -H 'Content-Type: application/json' \
  -d '{"user_name":"root","password":"q1w2e3r4","roles":["USER"],"authorities":["ROLE_USER"]}' \
  http://localhost:8138/api/v1/users/create

{"code":201,"message":"2"}

返回体 message 为新用户 id（2）。用户表实测：

curl -s -u 'Admin:q1w2e3r4' http://localhost:8138/api/v1/users/list

[{"id":1,"user_name":"Admin","password":"$2a$10$ne7i/OgxDu6S0HnSUmVlBuZX/XE.l5L93adFeGMOLIPMFEPV.mc26","roles":["ADMIN"],"authorities":["ROLE_ADMIN"]},{"id":2,"user_name":"root","password":"$2a$10$acVoMoHHYm6ft0h6FnHrRenRVgKlTIbtNZinu2BOTMYGVwuDi04.u","roles":["USER"],"authorities":["ROLE_USER"]}]

越权验证（root 访问管理员端点应被拒）：

curl -s -u 'root:q1w2e3r4' -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8138/api/v1/settings/get

HTTP 403

口令策略实测：创建时密码少于 6 位会被拒（源码校验 Password must be at least 6 characters long!），用户名/角色为空同样 400 报错。

六、JVM 与端口参数

七、生产配置模板

适用场景：16GB 内存 NAS、amd64、单管理员 + 若干家庭子用户、书库 ≤ 数万册（本实测环境的放大版）：

# /app/config/atsumeru.properties
allow_loading_list_with_volumes=true
allow_loading_list_with_chapters=false
disable_request_logging_into_console=true
disable_file_watcher=false
disable_watch_for_modified_files=false
disable_chapters=true

• 列表默认带卷、不带章节：兼顾阅读器翻页体验与响应体积；
• 控制台请求日志关闭（排障看 logs/requests.log 文件即可）；
• 保持监听导入（NAS 拷书即入库）；章节体系维持默认关闭。

Compose 侧固定 JAVA_OPT_XMX=-Xms256m -Xmx512m 与 1.1 版本号 tag；子用户按 5.3 模板创建并配 ALLOWED_CATEGORIES 白名单 + DISALLOWED_GENRES 含 Adult。

八、常见问题

Q1：settings/update 返回 406？ 导入/元数据/封面任务在跑（importer/status 看 import_active），等空闲再改（见第三章注意）。

Q2：手改 properties 文件不生效？ 属性只在启动时加载、API 写时落盘；手改后 docker compose -p atsumeru-11-stack restart。

Q3：改了 disable_chapters 服务自己重启了？ 源码内置行为（4.6），非故障。

Q4：新用户看不到任何书？ 其 ALLOWED_CATEGORIES 为空且书库分类未授权，或分类被 DISALLOWED_GENRES 命中；用 users/update 调整（全量 JSON，同 4.5 改密格式带 id）。

Q5：GET /api/v1/books/categories 列表比库里实际少？ 实测行为：列表按"该分类下有内容"过滤（源码 countForCategory > 0），空分类不展示；新建未挂内容的分类调 create 后需再查列表可见性。

九、参考链接

• 源码（配置与安全模型取证）：https://github.com/Atsumeru-xyz/Atsumeru （tag 1.1，经 jsDelivr 镜像，查询日期 2026-11-01）
• 官方 jar 指南（内存与恢复）：https://atsumeru.xyz/installation/jar.html （查询日期 2026-11-01）
• 同站相关：《Atsumeru 介绍与选型指南》、《Atsumeru Docker Compose 部署指南》、《Kavita 0.9.1.4 配置参数详解》