Atsumeru 介绍与选型指南

目标：搞清楚 Atsumeru 是什么——Kotlin/JVM 写的自托管漫画/图像小说/轻小说数字内容服务器，它的架构、功能、版本线与生态位，并用量化维度与同族的 Kavita、Komga、Ubooquity 对比出选型结论。本篇为认知篇，全部信息来自官方站点与仓库的联网溯源（查询日期 2026-11-01），不含本地实测；部署与 API 的逐条实测回显见本专栏后续的 Compose 部署、配置详解与 API 实践三篇。

一、环境信息

本篇为联网溯源认知篇，无本地实验环境，信息源如下（查询日期均为 2026-11-01）：

• 官方网站：https://atsumeru.xyz/（安装指南：Running from a Jar file / Running in Docker）
• GitHub 仓库：https://github.com/Atsumeru-xyz/Atsumeru（官方组织现名 Atsumeru-xyz；历史路径 AtsumeruDev/Atsumeru 仍可重定向，README 徽章仍指向旧名）
• 发布记录：仓库 releases.atom（1.0.0 → 2.2 全部版本时间线）
• 构建文件：仓库 build.gradle（tag 1.1，经 jsDelivr CDN 镜像获取）
• Docker Hub：atsumerudev/atsumeru 镜像仓库 tags API
• 星数徽章：img.shields.io/github/stars/...（规避 GitHub API 限流的取证方式）
• 对比对象：Kavita（Kareadita/Kavita）、Komga（gotson/komga）官方仓库 README/LICENSE/releases，Ubooquity 用户论坛（ubooquity.userecho.com）

二、软件概述

Atsumeru（日文「集める」，意为"收集/收藏"）是一款免费的自托管漫画/图像小说/轻小说媒体服务器，官方 README 自我定位为 "Free self-hosted mangas/comics/light novels media server"。它把散落在磁盘上的漫画压缩包、PDF、轻小说等数字内容收编成一个带元数据、封面、分类与阅读进度的在线书库，通过配套的原生客户端（Windows/Linux/Mac 桌面端 Atsumeru Manager + Android 端 Atsumeru）或 REST API 访问。

与"浏览器里读书"路线（Kavita/Komga 主打 Web 阅读器）不同，Atsumeru 从诞生起就是客户端优先架构：服务器只做存储、导入、元数据与权限，阅读体验交给原生应用，1.x 时代服务器端甚至没有 Web 管理界面，配置管理全部经桌面端 Manager 完成。

版本线（实查 releases.atom，查询日期 2026-11-01）：

⚠️ 注意（选型关键事实）：官方 Docker 镜像 atsumerudev/atsumeru 的 latest tag 停留在 1.1（最后推送 2025-01-15，Docker Hub tags API 实查），GitHub 上的 1.2/1.3/2.x 目前只提供 Atsumeru-x.y.z.jar 构件。也就是说"镜像部署 = 1.1 时代形态（无 WebUI、无 Swagger）"，"jar 部署才能到 2.2（有 WebUI）"。本专栏的部署/配置/API 三篇均基于可复现的官方 Docker 镜像 1.1 实测，并把这一版本落差如实写进文档。

三、核心架构

Atsumeru 服务器是单个 Spring Boot 可执行 jar（AtsumeruServerInstall 或 Atsumeru-x.y.z.jar），技术栈从 build.gradle（tag 1.1）实查：

数据流：把内容目录注册为 Import Folder → FileWatcher/scan 触发导入器解析压缩包结构（Series→Volumes→Chapters 三层）→ 自动读取包内 ComicInfo.xml（漫画元数据事实标准）或 book_info.json（轻小说）填充元数据 → 生成封面缓存到 cache/ → 客户端经 REST API（HTTP Basic 认证）拉取列表/页面/下载。

💡 技术拓展：数字内容服务器常见的存储模型不止 SQLite 一种。

模型	代表	特点
单文件 SQLite	Atsumeru、Komga（H2 同类嵌入式）	零外部依赖、备份=拷文件；写并发弱，适合单机
外接 PostgreSQL	Kavita（可选）/ 大型媒体服务	多进程并发、可扩展；需独立数据库服务
纯文件系统+边车元数据	Kavita 的 ComicInfo/Rarities、Calibre	元数据随文件走，迁移无锁定；查询靠扫描

Atsumeru 选择嵌入式 SQLite 双库，与它"个人 NAS 单机、低运维"的定位一致；代价是书库元数据与库文件绑定，跨软件迁移需靠 ComicInfo.xml 边车文件带走。

四、功能特性

官方 README 列举的核心特性（查询日期 2026-11-01）：

• 导入与阅读：导入 manga/comics/light novels，Windows/Linux/Mac/Android 原生客户端阅读，支持整册下载；
• 三级分类体系：Autocategories（按内容类型自动生成）、Custom categories（自定义分类）、Metacategories（作者/流派/审查等级/上色等元分类聚合）；
• 元数据编辑：图形化编辑元数据，可从支持的目录站（catalog）解析抓取；
• 边车元数据自动导入：ComicInfo.xml 与 book_info.json 两种格式开箱即读；
• 多用户与访问控制：每用户独立阅读历史，支持按分类白名单、流派/标签黑名单限制可见内容；
• REST API：官方明示 "Easy and convenient REST API"，1.2 起提供 OpenAPI/Swagger-UI。

支持的档案与图像格式（README + changelog + build.gradle 实查）：CBZ/ZIP 压缩包（ARM 设备仅支持 ZIP 路线）、PDF、DJVU（1.3 changelog 明示导入页数处理）、EPUB 类轻小说（book_info.json 元数据）；内页图像除 JPEG/PNG 外，经 TwelveMonkeys 解码 WebP，1.3 增 JPEG2000/JBIG2（PDF 内嵌），2.1 增 JPEG-XL。

五、快速开始（最小可用示例，官方文档溯源）

以下两种起步方式逐字取自官方安装指南（atsumeru.xyz，查询日期 2026-11-01），未在本篇实测；完整部署实录见本专栏部署篇。

方式 A：Docker（官方 docker.html 原文片段）

docker run -d \
  --name=atsumeru \
  -p 31337:31337 \
  -v /path/to/your/library:/library \
  -v /path/to/your/config:/app/config \
  -v /path/to/your/db:/app/database \
  -v /path/to/your/cache:/app/cache \
  -v /path/to/your/logs:/app/logs \
  --restart unless-stopped \
  atsumerudev/atsumeru:latest

官方指南同时说明：启动后执行 docker logs atsumeru 可找到首次启动自动创建的 Admin 用户随机密码。

方式 B：jar 直跑（官方 jar.html 原文）

java -jar Atsumeru-x.y.z.jar

要求 Java 17+；首次启动会在 jar 同侧创建 cache/settings/database，并在控制台一次性打印 Admin 随机密码。官方建议登录后改密；若要重置管理员，可停服后删除 database/users.db 再启动（会清空所有用户，谨慎操作）。

六、适用场景与限制

适合：

• 个人/NAS 漫画、图像小说、轻小说收藏的"收编"：目录扔给服务器，元数据靠 ComicInfo.xml 边车自动填充；
• 家庭多用户分发：家长建库，给孩子开受限用户（按分类/流派黑名单过滤成人内容），每人独立阅读进度；
• 想要原生桌面/安卓阅读器体验、把服务器当纯后端用的用户。

限制（实查依据）：

1. Docker 通道版本落后：官方镜像停在 1.1，WebUI（2.0+）与 Swagger（1.2+）在镜像部署形态下不可用，管理依赖桌面端 Manager 或 API；
2. 1.x 无 Web 管理界面：浏览器打开 31337 只有 API，无登录页（本专栏实测篇将展示这一形态）；
3. ARM 支持打折：官方 docker.html 明示 ARM 镜像 "only reading ZIP archives is supported"，树莓派上 PDF/DJVU 不可用；
4. 社区规模小：195 星（shields.io，2026-11-01），文档与客户端以俄语社区为主（官网提供 EN/RU/UK 三语）；
5. 无 OPDS/Calibre 集成（官方 README 与 changelog 未提及，对比 Kavita/Komga 时按此口径）。

七、同类选型量化对比

同族"漫画/电子书数字内容服务器"代表：Kavita、Komga、Ubooquity。量化数据均为 2026-11-01 实查（星数取 shields.io 徽章 SVG，版本取各仓库 releases/atom 或 tag 列表）：

解读与选型建议：

• 要开箱即用的 Web 体验与生态：选 Kavita 或 Komga——星数差两个数量级（12k/6.8k vs 195），镜像版本与 GitHub 同步，Web 阅读器、OPDS、第三方应用生态成熟。同站已有 《Kavita 0.9.1.4 介绍与选型指南》 可深入。
• 要原生桌面/安卓客户端、把服务器当纯后端：Atsumeru 是该家族里唯一官方全家桶客户端的，且 MIT 许可对二次开发友好。
• 接受"镜像=1.1 老形态"或愿意跑 jar：Atsumeru 部署成本极低（单 jar + 两个 SQLite 文件），官方明示大书库也"consume not much RAM"，256–512MB 堆即可服役，适合小内存 NAS。
• Ubooquity 仅建议存量用户维持；更新停滞（论坛口径"多年未更"），新项目不建议入场。

💡 技术拓展：JVM 媒体服务器的堆内存策略也不止一种。

策略	说明	取舍
默认堆（1/4 物理内存）	不传 -Xmx，JVM 自适应	大内存机器上浪费/不可控
显式 -Xms/-Xmx 定界	官方 jar.html 建议仅在明确报内存不足时调整	本专栏采用 -Xms256m -Xmx512m
容器感知（UseContainerSupport）	按 cgroup 限额自动算堆	镜像未默认开启，需显式加参

Atsumeru 官方立场是"默认即够用，慎用大参数"；本专栏按批次规范统一压到 256–512MB 并实测验证。

八、参考链接

• Atsumeru 官网与安装指南：https://atsumeru.xyz/installation/jar.html 、https://atsumeru.xyz/installation/docker.html （查询日期 2026-11-01）
• GitHub 仓库（含 README/releases/changelog）：https://github.com/Atsumeru-xyz/Atsumeru （查询日期 2026-11-01）
• Docker Hub 镜像与 tags：https://hub.docker.com/r/atsumerudev/atsumeru/tags （查询日期 2026-11-01）
• Kavita 仓库：https://github.com/Kareadita/Kavita （查询日期 2026-11-01）
• Komga 仓库：https://github.com/gotson/komga （查询日期 2026-11-01）
• Ubooquity 用户论坛：https://ubooquity.userecho.com/ （查询日期 2026-11-01）
• 同站相关：《Kavita 0.9.1.4 介绍与选型指南》、《Kavita 0.9.1.4 Docker Compose 部署指南》