Stump 0.1.12 介绍与选型指南

Stump 0.1.12 数字书媒体服务器的定位、Rust+GraphQL 架构、功能边界与量化选型对比（vs Kavita/Komga/Audiobookshelf/Calibre-Web），信息全部联网溯源。

StumpStump电子书漫画Rust自托管2026/11/02

Stump 0.1.12 介绍与选型指南

目标：讲清 Stump 是什么、技术架构与功能边界，并用社区活跃度、版本节奏、格式与协议兼容等量化维度完成同类选型对比。本文信息全部来自官方文档、官方 GitHub 仓库与站内已发布竞品篇的联网溯源（查询日期 2026-11-02），不含本地实测。部署见本专栏 《Stump 0.1.12 Docker Compose 部署指南》，参数详解见 《Stump 0.1.12 配置参数详解》，CLI 用法见 《Stump 0.1.12 常用 CLI 命令与工具详解》。

一、环境信息

  • 被介绍组件：Stump，官方仓库 stumpapp/stump（GitHub），许可证 MIT
  • 当前最新稳定版：v0.1.12（GitHub Releases 发布于 2026-11-01T15:09:24Z，来源 releases.atom，查询日期 2026-11-02）
  • 项目创建时间：2021-12-30（来源 GitHub 仓库页，查询日期 2026-11-02）
  • 信息溯源渠道：官方文档站（stumpapp.github.io：Overview / Installation / API / Server Config）、GitHub 仓库页与 releases.atom、shields.io 星数徽章
  • 对比对象：Kavita 0.9.1.4、Komga、Audiobookshelf 2.37.2、Calibre-Web 0.6.27、Codex（官方 Overview 页「Similar Projects」列出的同类项目）

二、软件概述

Stump 是一个开源、可自托管的数字书媒体服务器（media server），面向电子书（EPUB）、漫画/图像小说（CBZ/CBR）、PDF 等数字书形态。官方的使用路径概括为三步：在电脑或 NAS 上安装运行 Stump → 配置书库（libraries）→ 用 Web 界面或任意兼容客户端阅读（来源：官方文档 Overview，查询日期 2026-11-01）。

官方明确划定了能力边界：Stump 不是抓取/下载媒体内容的工具，它只负责托管和访问你自己的藏书，定位类似「部署在家里服务器上的私人 Netflix（漫画/电子书版）」（来源：官方文档 Overview，查询日期 2026-11-01）。

作者的动机（来源：官方文档 Overview「Motivations」，查询日期 2026-11-01）：

  • 作者最初是 Komga 用户，开发 Stump 的初衷是「自己动手做一个类似 Komga 的东西」，并选择 Rust 以积累语言经验；
  • 立项目标：小体积低资源占用、在弱硬件（如树莓派）上也高效不卡顿、界面直观美观、格式覆盖广（PDF、EPUB、CBZ/CBR）。

资源要求（来源：官方文档 Overview「Compatibility」，查询日期 2026-11-01）：主流浏览器与操作系统均可用；1GB 内存与磁盘空间即足够；在树莓派等低功耗 ARM 单板机上运行良好。

三、核心架构

依据官方文档 Overview / API / Server Config / Installation 页（查询日期 2026-11-01）归纳：

  • 服务端：Rust 实现，单二进制同时承载 HTTP 服务与 CLI——不带子命令运行时即启动服务器，带 account/system 子命令时即为管理工具（来源：官方文档 CLI 页与 --help 描述）；
  • API 层：核心 API 是 GraphQL，RESTful 端点仅保留给需要它的集成与功能（如缩略图获取、OPDS、认证）；API 认证支持会话（server-side session）、Basic（仅 OPDS 端点）、JWT（短时效 access token + 长时效 refresh token）与用户级 API Keys（来源：官方文档 API 页，查询日期 2026-11-01）；
  • 存储层：默认 SQLite 单文件库（stump.db），也支持 PostgreSQL（通过 STUMP_DB_URL 等连接参数）；书库媒体文件直接读取本地目录，不入库；
  • 任务系统：内置作业调度器（job scheduler），书库扫描、缩略图生成等重活以异步作业执行，并发度由 parallelism_multiplier × 逻辑 CPU 数推导（来源：官方文档 Server Config「Performance」，查询日期 2026-11-01）；
  • 阅读与渲染：EPUB 阅读基于 Readium 网页技术方案；PDF 渲染依赖 PDFium（Docker 镜像内置二进制，非 Docker 部署需自行下载并配置 pdfium_path），渲染 DPI/格式/预渲染范围均可配（来源：官方文档 Server Config「PDF Rendering」，查询日期 2026-11-01）；
  • 客户端矩阵：Web App（React 实现的 SPA，随服务端一起分发）、Desktop App（Tauri 桌面端）、Mobile App（移动端），外加 OPDS 协议对接第三方阅读器；
  • 集成生态：Kobo 同步、KoReader 同步（默认关闭，需显式启用）、OIDC 第三方登录、GraphQL Playground（默认关闭）。

💡 技术拓展：数字书自托管服务在「对外协议」上常见三类形态，选型时值得一次看全——

形态特点适用
OPDS（Atom 目录协议）行业标准，Kobo/Calibre/Nova 等海量阅读器原生支持对接各类硬件阅读器与第三方 App
REST API端点直观，易被脚本与第三方集成自动化、轻量集成
GraphQL单端点按需取字段，功能面最全官方客户端与深度集成

Stump 实际采用「GraphQL 为核心 + REST 辅助 + OPDS v1.2 目录」三层并存；Kavita/Komga 以 REST 为主；Calibre-Web 以 OPDS 为主。

四、功能特性

来源：官方文档 Overview / Server Config / API / Installation 各页（查询日期 2026-11-01），以及 GitHub 仓库 topics（books、comics、media-server、opds、react、rust、self-hosted、tauri）：

  • 格式支持：EPUB、CBZ/CBR、PDF 等数字书格式（官方原文「Wide format support (e.g., PDF, EPUB, CBZ/CBR)」）；
  • 书库管理：多书库（library）/系列（series）/媒体（media）三级组织，目录扫描为异步作业；支持网页上传（enable_upload，默认关闭）；
  • 阅读进度与续读：跨设备进度跟踪，OPDS 页面访问是否计入进度可配（enable_opds_progression）；
  • 多用户与权限：用户/权限体系（API Keys 即受 ACCESS_API_KEYS 权限门控）、年龄限制（age restriction）、OIDC 外部身份源登录；
  • 设备集成：Kobo 同步、KoReader 同步两条硬件/软件阅读生态通道；
  • 部署形态：macOS/Linux/Windows 独立可执行文件（zip/tar.gz，二进制 + client 目录相邻放置即可运行，官方文档含 systemd unit 示例）、Docker 官方镜像 aaronleopold/stump、源码构建三种；
  • 配置体系：Stump.toml 单文件 + 环境变量双通道（Docker 场景推荐环境变量覆盖），默认值齐备、未配置即用默认。

五、快速开始（最小可用示例）

以下最小示例取自官方 Docker 文档（来源：官方文档 Installation/Docker 页，查询日期 2026-11-01），仅示意形态；完整部署与实测闭环见本专栏 《Stump 0.1.12 Docker Compose 部署指南》。

services:
  stump:
    image: aaronleopold/stump:latest
    container_name: stump
    volumes:
      - /srv/stump/config:/config
      - /srv/books:/data
    ports:
      - "10801:10801"
    environment:
      - PUID=1000
      - PGID=1000
    restart: unless-stopped

启动后浏览器访问 http://<服务器>:10801，首次进入按引导创建服务器属主（owner）账号，随后创建书库指向媒体目录、等待扫描作业完成即可开始阅读。

不想用 Docker 的裸机路径（来源：官方文档 Installation/Binaries 页，查询日期 2026-11-01）：从 GitHub Releases 下载对应架构的包（Linux 为 stump-<version>-linux-x64.tar.gz 或 linux-arm64），解出 stump_server 二进制与 client 目录并保持相邻，赋可执行权限后直接运行 ./stump 即启动服务器；官方文档提供了 systemd unit 示例用于常驻托管。

六、适用场景与限制

适用场景：

  • 个人/NAS 数字藏书托管：低资源占用（1GB 内存即可）适合树莓派、入门 NAS 等弱硬件；
  • 多端阅读家庭：Web/桌面/移动官方客户端 + OPDS 第三方阅读器 + Kobo/KoReader 同步，一套服务端覆盖全家设备；
  • 对 API 自动化有诉求的自托管玩家：GraphQL 核心 API + API Keys/JWT，便于脚本化建库、上传与集成。

限制与风险（来源：官方文档，查询日期 2026-11-01）：

  • 版本仍在 0.x 系列（当前 0.1.12），官方明确 API「仍在持续开发、可能变化」，且文档设有 Breaking changes 专页，升级需留意迁移说明；
  • 不做内容获取：下载/刮削需依赖 Calibre、其他工具或手动整理书库目录；
  • 上传、GraphQL Playground、Kobo/KoReader 同步、OPDS 进度跟踪等能力默认关闭，需要显式开启；
  • 社区规模与同类头部项目（Kavita、Komga、Audiobookshelf）有明显差距，长尾问题响应依赖作者业余维护与 Discord 社区。

七、同类选型对比

星数来源：shields.io GitHub stars 徽章与仓库页（查询日期 2026-11-02；Komga 当日两条渠道均查询失败，标注未取到）。竞品版本与定位佐证另见站内已发布文档。

项目定位语言栈星数(2026-11-02)最新稳定版站内详解
Stump 0.1.12数字书（电子书/漫画/PDF）媒体服务器Rust + React2764（2.8k）0.1.12（2026-11-01）本专栏
Kavita漫画/电子书服务器C#/.NET12k0.9.1.4《Kavita 0.9.1.4 介绍与选型指南》
Komga漫画/电子书服务器（Stump 作者的对标起点）Kotlin未取到（查询失败）——
Audiobookshelf有声书/播客服务器（兼电子书）Node.js15k2.37.2《Audiobookshelf 2.37.2 介绍与选型指南》
Calibre-WebCalibre 书库的 Web 端Python19k0.6.27《Calibre Web 0.6.27 介绍与选型指南》
CodexRust 生态同类数字书服务器Rust———

版本节奏量化：Stump 自首版（仓库创建于 2021-12-30）至 v0.1.12 共发布 26 个 release（来源：GitHub 仓库页/releases.atom，查询日期 2026-11-02），最新一版发布于 2026-11-01，迭代持续但单版跨度较长（0.1.x 系列小步演进）。

选型建议（如果…则…）：

  • 如果藏书以漫画/图像小说 + EPUB/PDF 为主、希望单二进制低内存、且看重 GraphQL API 与 Kobo/KoReader 集成 → 选 Stump；
  • 如果需要更成熟的社区、多语言界面与更重的书库管理功能 → 选 Kavita（站内有完整部署与配置篇）；
  • 如果藏书主体是有声书/播客 → 选 Audiobookshelf，它与 Stump 互补而非互斥（官方 Overview 亦将其列为同类但定位含音频）；
  • 如果已有 Calibre 书库、只想做 Web 分发与推送 → 选 Calibre-Web；
  • 如果无法接受 0.x 版本与 API 变动风险 → 优先 Kavita/Komga 这类 1.0+ 项目。

💡 技术拓展：「数字书服务器」与相邻两类自托管组件的边界——

类型代表与 Stump 的关系
书库管理软件Calibre本地整理/转换/元数据，Stump 不做抓取整理，二者常搭配使用
通用文件服务器Jellyfin/Emby面向视频/音频流，不含书页式阅读与阅读进度
数字书媒体服务器Stump/Kavita/Komga书页式阅读、进度同步、OPDS，本表对比维度

Stump 属第三类；Calibre-Web 是「第一类的 Web 前端」，定位差异会影响选型。

八、参考链接

Stump 0.1.12 介绍与选型指南 - Quzuo