Spoolman v0.27.0 介绍与选型指南
介绍 3D 打印耗材库存自托管服务 Spoolman 的定位、架构、功能与生态集成，并与 OctoPrint Filament Manager、Filaman 做量化选型对比，基于官方仓库与 Wiki 溯源（查询日期 2026-10-25）。
Spoolman v0.27.0 介绍与选型指南
目标：全面介绍 3D 打印耗材库存管理自托管服务 Spoolman 的定位、架构、功能与生态，并与同类方案做量化对比，帮助读者判断「是否需要、是否适合、如何入手」。本篇为认知篇，全部信息来自对官方来源的联网溯源（GitHub 仓库、Releases、官方 Wiki、shields.io 徽章），查询日期 2026-10-25；部署与实测内容见本专栏后续篇章。
一、环境信息
- 目标软件：Spoolman，最新稳定版 v0.27.0（发布于 2026-09-25，commit
bed3f14） - 官方仓库：https://github.com/Donkie/Spoolman（注意作者为 Donkie，与早期第三方教程中出现的拼写不同）
- 官方 Wiki：https://github.com/Donkie/Spoolman/wiki（Installation / Configuration / Security 等页，2026-08-02 更新）
- 信息来源与取证方式：GitHub 仓库页与 Releases 页 HTML、官方 Wiki、shields.io 星数/版本徽章；查询日期 2026-10-25
- 社区活跃度快照（2026-10-25 实测）：stars ≈ 2.9k，open issues 152，open PR 19
二、软件概述
Spoolman 是一个自托管的 3D 打印耗材丝盘（filament spool）库存管理服务，官方一句话定位是 "Keep track of your inventory of 3D-printer filament spools"（跟踪你的 3D 打印机耗材丝盘库存）。
- 维护方：Daniel Hultgren（GitHub ID：Donkie），开源许可为 MIT（LICENSE 文件首部实测 "MIT License, Copyright (c) 2023 Daniel Hultgren"），可自由商用与二次开发。
- 解决的痛点：3D 打印玩家/工作室普遍面临「这卷料还剩多少、够不够打这个模型、料放哪了、多少钱一卷」的问题。Spoolman 把耗材按「厂商 → 耗材型号 → 实物丝盘」三级建模，打印过程中自动扣减用量，随时掌握每卷料的剩余重量/长度。
- 运行形态：一个长驻的 Web 服务（Web UI + REST API），默认监听 7912 端口；本身是单用户、无内置账户体系的轻量服务，面向内网部署。
- 生态位：它不替代打印机固件或打印主机软件，而是作为耗材数据的中心，被 OctoPrint、Klipper/Moonraker（Fluidd/Mainsail 面板）、Home Assistant 等生态调用，让「库存」数据在整条打印链路里流动。
💡 技术拓展：3D 打印耗材（filament）常见形态对比——
形态 规格 特点 适用 丝盘 Spool 1.75mm / 2.85mm 直径 FDM 打印机主流耗材，按卷称重 绝大多数桌面 FDM 打印 树脂 Resin 瓶装光敏液体 LCD/SLA 光固化打印 光固化机型 粉末 Powder 尼龙等粉末 SLS 工业打印 工业设备 Spoolman 管理的是第一种「丝盘」形态，也是保有量最大的一类；本文及本专栏均围绕丝盘耗材展开。
三、核心架构
Spoolman 是一个典型的现代 Python Web 单体应用，架构简洁、外部依赖少：
| 层 | 技术选型 | 说明 |
|---|---|---|
| 后端框架 | Python ≥ 3.10 + FastAPI | REST API 自动生成 OpenAPI 3.1.0 文档（/api/v1/openapi.json） |
| Web 服务 | uvicorn（ASGI） | 生产级异步服务器，同时托管 API 与前端静态资源 |
| 前端 | 内置 Web 客户端（新版 + 旧版双客户端） | 默认新版客户端；设 SPOOLMAN_LEGACY_CLIENT=TRUE 可回退旧版 React 客户端 |
| 持久层 | SQLAlchemy 2.0 + Alembic | ORM + 数据库版本迁移，升级时自动演进表结构 |
| 数据库 | SQLite（默认）/ PostgreSQL / MySQL（MariaDB）/ CockroachDB | 零配置开箱用 SQLite 单文件，多实例或大负载可换外部库 |
| 外部数据 | SpoolmanDB 耗材目录 | 定时同步社区维护的厂商耗材参数库到本地缓存 |
数据流主线：打印主机软件（OctoPrint / Moonraker）在打印过程中调用 Spoolman REST API 上报「本次用了多少料」→ Spoolman 按丝盘密度/直径换算重量与长度并落库 → Web UI 与各面板实时展示剩余量。部分 API 端点同时提供 WebSocket，可订阅库存变更事件。
💡 技术拓展：Spoolman 支持的四种数据库后端对比——
数据库 部署成本 并发能力 适用场景 SQLite（默认） 零依赖单文件 单写低并发 个人单机、几台打印机（官方默认，绝大多数用户够用） PostgreSQL 需独立部署 强 工作室多客户端高频写入 MySQL/MariaDB 需独立部署 强 已有 MySQL 基础设施的团队 CockroachDB 分布式部署 强且可水平扩展 多站点/高可用诉求的进阶场景 官方默认且推荐个人用户使用 SQLite；本专栏安装与部署篇均以 SQLite 为主线实测。
四、功能特性
依据官方 Wiki 与仓库 README（2026-10-25 查询），Spoolman 的核心功能点：
- 三级库存模型：厂商（Vendor）→ 耗材（Filament，记录材料/密度/直径/颜色/单价等）→ 实物丝盘（Spool，记录初始重量、皮重、已用量、存放位置）。
- 用量追踪双模式：既支持按「使用长度」扣减（打印机生态自动上报），也支持按「称重」校准（电子秤称整卷，自动去皮重反推剩余料）。
- 自动换算：根据耗材密度与直径自动在重量（g）与长度（mm）之间换算，剩余量一眼可见。
- 位置与标签：丝盘可挂存放位置（如干燥箱编号）；支持自定义扩展字段；提供 NFC/QR 标签扫描接口（
/api/v1/tag/scan），贴标签实现「一刷上料」。 - 外部耗材目录 SpoolmanDB：内置对接社区维护的 SpoolmanDB（donkie.github.io/SpoolmanDB），常见厂商耗材参数可检索后一键建档，免去手填密度/直径。
- 生态集成：OctoPrint 有专用插件；Klipper 系通过 Moonraker 原生集成，Fluidd/Mainsail 面板直接显示当前丝盘余量并在打印时自动扣减；Home Assistant 有集成可读取库存数据。
- 可观测与数据安全：可开启 Prometheus
/metrics；SQLite 模式下每晚自动备份（保留 5 份）；支持整库备份端点与丝盘/耗材/厂商 CSV 导出。 - 多币种与价格：耗材可按币种记价，UI 内可设货币与价格取整，统计打印成本。
五、快速开始（最小可用示例）
官方 Wiki（Installation 页，2026-10-25 查询）给出两种安装形态：Docker（官方推荐） 与 Standalone（裸机 zip 包 + install.sh）。最小体验的官方推荐命令：
docker run -d --name spoolman -p 7912:8000 -v spoolman_data:/home/app/.local/share/spoolman ghcr.io/donkie/spoolman:latest
启动后访问 http://<服务器IP>:7912 即可进入 Web 界面建档丝盘。
💡 说明：镜像同时发布在 GHCR（
ghcr.io/donkie/spoolman）与 Docker Hub（donkieyo/spoolman）双仓库，内容一致，拉取困难时可互换。Standalone 形态与完整的生产化部署步骤，见本专栏《Ubuntu 22.04 安装 Spoolman v0.27.0 指南》与《Spoolman v0.27.0 Docker Compose 部署指南》两篇的实测记录。
六、适用场景与限制
适用场景：
- 个人 3D 打印玩家：多卷耗材的剩余量与位置管理，避免「打到一半料不够」。
- 打印工作室/农场：多台打印机共享一套库存账，按丝盘追踪成本与消耗。
- Klipper / OctoPrint 用户：希望面板里直接看到余量、打印自动扣账的技术玩家。
- 需要自动化的进阶用户：通过 REST API / WebSocket 把库存接入自己的报表、告警或采购流程。
限制与注意事项：
- ⚠️ 无内置认证：官方 Wiki Security 页明确说明 Spoolman 不带任何登录/权限体系，严禁直接暴露公网；应部署在内网，或置于带认证的反向代理之后。
- 单用户设计：没有多用户与角色权限，团队协作靠「共用一个实例」。
- 只管丝盘耗材：不管理树脂等其他形态耗材，也不是打印任务调度系统。
- SQLite 默认库的边界：默认 SQLite 面向单实例低并发；若要多服务实例并发写或集中式数据库管理，需切换到 PostgreSQL/MySQL（见《Spoolman v0.27.0 配置参数详解》篇）。
七、同类选型对比
围绕「3D 打印耗材库存管理」这一目标，社区主要有三类方案。量化数据均为 2026-10-25 对各仓库 shields.io 徽章与 Releases 页的实测：
| 维度 | Spoolman | OctoPrint Filament Manager（OllisGit 维护分支） | Filaman |
|---|---|---|---|
| 仓库 | Donkie/Spoolman | OllisGit/OctoPrint-FilamentManager | ManuelW77/Filaman |
| GitHub Stars | ≈ 2.9k | ≈ 60 | ≈ 176 |
| 最新版本 | v0.27.0（2026-09-25） | v1.9.1 | v2.0.10 |
| 形态 | 独立 Web 服务 + REST API | OctoPrint 插件 | 独立服务 + 电子秤/硬件联动 |
| 适用生态 | OctoPrint / Klipper(Moonraker) / Home Assistant 通用 | 仅限 OctoPrint | 偏 Klipper，强调称重建档 |
| 数据库 | SQLite / PostgreSQL / MySQL / CockroachDB | 依托 OctoPrint 自身存储 | 自带存储 |
| 部署方式 | Docker / Standalone | OctoPrint 插件管理器 | Docker |
| 许可 | MIT | AGPLv3（插件沿用 OctoPrint 生态许可惯例） | 开源（仓库内许可证） |
关键差异解读：
- Spoolman 是目前社区事实标准：星数领先同类一个数量级以上，版本迭代活跃（2026 年持续发版），且是唯一被 Moonraker/Fluidd/Mainsail 原生集成的耗材库存服务。
- OctoPrint Filament Manager 只在 OctoPrint 内部有效，换 Klipper 就用不了；适合「只用 OctoPrint 且不想多跑一个服务」的轻量需求。
- Filaman 特色是配套电子秤等硬件联动、称重建档体验好，但社区规模与生态集成广度远小于 Spoolman。
选型建议（「如果…则…」）：
- 如果你使用 Klipper（Fluidd/Mainsail）或希望库存数据跨 OctoPrint/Klipper/HA 共享 → 选 Spoolman（本专栏方案）。
- 如果你只用 OctoPrint、坚决不想多维护一个服务 → 可考虑 OctoPrint Filament Manager 插件。
- 如果你希望「放秤上自动建档称重」的硬件一体体验 → 可评估 Filaman。
- 如果只是想记账式地记录几卷料 → 电子表格也能凑合，但失去自动扣减与生态联动。
八、参考链接
- 官方仓库：https://github.com/Donkie/Spoolman
- 官方 Wiki（安装/配置/安全）：https://github.com/Donkie/Spoolman/wiki
- Releases 页（v0.27.0，2026-09-25）：https://github.com/Donkie/Spoolman/releases
- 社区耗材目录 SpoolmanDB：https://donkie.github.io/SpoolmanDB/
- 容器镜像：https://github.com/Donkie/Spoolman/pkgs/container/spoolman 与 https://hub.docker.com/r/donkieyo/spoolman
- 同类方案仓库：https://github.com/OllisGit/OctoPrint-FilamentManager 、https://github.com/ManuelW77/Filaman