Inventaire 5.1.1 介绍与选型指南

目标：面向「想自托管一套开源藏书/物品库存管理系统」的读者，介绍 Inventaire 5.1.1 的定位、架构、功能与同类横向对比，并给出选型建议。本篇为认知篇，全部信息溯源自官方渠道（官网 inventaire.io、Codeberg 主仓库、GitHub 镜像仓库、官方 Wiki、官方 Docker Hub），数据查询日期为 2026-10-23；本篇不做本地安装实测，安装与部署实操见本专栏后续部署篇。

一、环境信息

本篇为认知篇，不涉及本地实验环境，仅列出信息溯源所用的官方渠道清单，供读者复核：

💡 说明：Inventaire 的服务端主仓库已迁移至 Codeberg（codeberg.org/inventaire/inventaire），GitHub 仓库（inventaire/inventaire）作为镜像存在，其 Releases 页停留在 v3.0.1-beta（2025-03-02），不再是最新版本发布渠道。判断最新稳定版应以 Codeberg 仓库 tag、官方 Docker Hub 镜像 tag 与旗舰实例 /api/config 返回值为准——三者本次实查一致，均为 5.1.1（镜像发布于 2026-05-27）。本专栏所有文档统一采用 5.1.1 作为版本号。

二、软件概述

本节回答「Inventaire 是什么、由谁维护、处在什么成熟阶段」。Inventaire 是一个自由开源的协作式资源测绘/库存管理 Web 应用（官方自述：libre collaborative resources mapper powered by open-knowledge），当前聚焦于藏书场景：以 ISBN 与 Wikidata 开放知识图谱为底座，把个人或小组的书架搬上互联网，实现编目、共享、借阅与交换。项目由法国非营利组织 Inventaire 协会（The Inventaire Association）维护，旗舰实例即 https://inventaire.io。

关键身份信息（实查自仓库 LICENSE、package.json 与 CHANGELOG）：

版本演进上的三个关键节点（实查自 CHANGELOG.md）：

• 3.0.x（2025 年初）：引入联邦实例机制（federated instances），自托管实例可复用旗舰站的实体数据而不必全量同步 Wikidata；同时确立语义化版本与 .ts 配置体系雏形。
• 4.0.0（2025-06-02）：配置文件从 .cjs 迁移为 .ts，mapTilesAccessToken 被 mapTiles 对象取代；API 开始向「action 参数进路径」的 REST 风格收敛。
• 5.0.0 / 5.1.x（2026 年）：API 大扫除（POST /api/entities 直接建实体、items 拆分单建/批量端点等，均为破坏性变更）；5.1.0 加入请求限流（rate limiting）、ISBN URI 去规范化、以 Cirrus 搜索替代 SPARQL 查询，并新增库存导入器。

三、核心架构

本节从「进程组成—数据存储—联邦拓扑」三层拆解 Inventaire 的架构，帮助读者理解它对宿主机资源的真实诉求，以及后面部署篇中各组件的角色。

3.1 进程与组件组成

一次完整的 Inventaire 生产部署由下列部分构成（版本要求实查自仓库 README 与官方 docker-compose.yml）：

💡 技术拓展：Inventaire 的存储组合是「文档库 + 搜索引擎 + 内嵌 KV」三件套，这在开源 Web 应用中是一种务实选择。同类组合对比：

组合	代表产品	特点
文档库 + 搜索引擎 + 内嵌 KV（本文）	Inventaire	CouchDB 原生多主复制天然适配联邦；ES 可重建、可宕机降级
关系库 + 搜索引擎	InvenTree / Snipe-IT	强事务、报表能力强，联邦能力弱
单一内嵌库（SQLite/LevelDB）	Grocy / Homebox	部署最简，搜索与多主复制能力有限
关系库 + 对象存储	calibre-web 类	面向文件库而非知识实体

Inventaire 因「与 Wikidata 融合 + 联邦复制」这两个核心诉求选择了 CouchDB——其 Multi-Master 复制协议正是联邦实例间同步实体与条目的基础。

3.2 数据模型

Inventaire 的数据围绕四类核心对象组织（实查自官方 Wiki Glossary 与服务端 routes 目录）：

• Entity（实体）：知识层面的抽象对象，分 work（作品）、edition（版本）、human（作者）、publisher（出版社）、collection（丛书）、serie（系列）等类型。实例可拥有本地实体（前缀 inv:），也可引用 Wikidata 实体（前缀 wd:，如 wd:Q392 即鲍勃·迪伦，实测返回其 100+ 种语言的标签）。
• Item（条目）：用户手中的具体物理件，通过 entity 关联到某个 edition 实体，携带交易状态（inventorying / lending / borrowing / selling / giving / loaning）、明细、评论与图片。
• User / Group（用户与小组）：用户可建小组共享书架，组内可发起借阅/赠送/出售等事务（transactions）。
• Shelve / List（书架与列表）：个人或小组的内容组织单元，可导出 RSS。

条目与实体的关系是「一条 Wikidata/本地实体描述『这本书是什么』，N 个 item 描述『谁拥有这本实体书』」——这是它与普通「物品盘点软件」最大的模型差异。

3.3 联邦拓扑

自 3.0 起，Inventaire 采用主实例 + 联邦实例拓扑：旗舰站 inventaire.io 作为 entities host（实体宿主，承担 Wikidata 同步、实体去重、 popularity 计算等任务，对应配置 NODE_APP_INSTANCE=primary 与 alt 双实例）；自托管实例以 federated 模式（NODE_APP_INSTANCE=federated，端口 3016）运行，通过 federation.remoteEntitiesOrigin 指向实体宿主按需拉取实体，本地只需维护用户、条目与本地实体。这一设计显著降低了自托管的资源门槛——无需全量导入 Wikidata。

四、功能特性

本节列出 5.1.1 的主要功能域，作为选型时的能力清单（依据官方 README、CHANGELOG 与旗舰站实查）：

• 编目与知识图谱：ISBN 扫码/手动录入即自动匹配 Wikidata 与 Open Library 数据，作品-作者-出版社关系自动成图；/api/entities 系列接口可按 URI 直接读取实体（见五、快速开始实测）。
• 多语言：界面 30+ 语言，翻译经 Weblate 平台众包持续同步。
• 共享与社交：小组书架、好友关系、私信事务（借/还/送/卖全流程）、活动流、RSS 订阅、定期活动摘要邮件。
• 搜索：Elasticsearch 驱动的全文搜索（作品/版本/作者/用户/小组/列表多类型），以及基于地图的用户位置发现（OpenStreetMap/Mapbox 瓦片可配）。
• 联邦与 ActivityPub：3.0 起实例间可互引实体；服务端内置 ActivityPub 端点（/api/activitypub），实体可被联邦宇宙关注。
• 开放 API：完整 REST API + 内置 OAuth2 授权服务器（/api/oauth），第三方应用可代表用户读写库存。
• 运维配套：CouchDB 备份/恢复脚本（npm run couchdb:backup-databases）、实体导出 dump 脚本、Elasticsearch 重建索引脚本、请求限流（5.1.0 起）。

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

本节在不做任何本地安装的前提下，通过官方旗舰实例的公开 API 体验 Inventaire 的核心能力（实查日期 2026-10-23）。以下命令在任何可联网的 Linux 终端原样可执行。

5.1 确认实例版本与配置

GET /api/config 返回实例对外公开的配置（版本、实例名、组织信息、地图瓦片等）：

curl -s https://inventaire.io/api/config

实测回显（节选，完整 JSON 见官方站）：

{"version":"5.1.1","softwareName":"inventaire","serverGitHeadRev":"226317918","env":"production","instanceName":"inventaire","orgName":"Example Organization","orgUrl":"https://inventaire.example.org","mapTiles":{"tileUrl":"https://api.mapbox.com/styles/v1/mapbox/streets-v8/tiles/{z}/{x}/{y}?access_token={accessToken}","attribution":"Map data &copy; <a href=\"http://openstreetmap.org\">OpenStreetMap</a> contributors, <a href=\"http://creativecommons.org/licenses/by-sa/2.0/\">CC-BY-SA</a>, Imagery © <a href=\"http://mapbox.com\">Mapbox</a>"},"publicHost":"inventaire.io","publicOrigin":"https://inventaire.io","contactAddress":"hello@inventaire.io"}

version 字段即本文认定的最新稳定版 5.1.1，与 Codeberg tag、Docker Hub tag 三方互证。

5.2 全文搜索一个作品

GET /api/search 按 types（可多选）与 search 关键词检索知识图谱：

curl -s 'https://inventaire.io/api/search?types=works&search=borges&limit=2'

实测回显（节选）：

{
    "results": [
        {
            "id": "Q2483432",
            "type": "works",
            "uri": "wd:Q2483432",
            "label": "Ficciones",
            "description": "short story collection by Jorge Luis Borges",
            "_score": 92065.05,
            "_popularity": 80
        },
        {
            "id": "Q60153676",
            "type": "works",
            "uri": "wd:Q60153676",
            "label": "Borges",
            "description": "book published in 2006",
            "_score": 78223.85,
            "_popularity": 3
        }
    ],
    "total": 441,
    "continue": 2
}

返回结果直接携带 Wikidata URI（wd:Q2483432 即《Ficciones》），说明搜索命中了开放知识图谱而非本地私有数据——这正是 Inventaire 的核心卖点。

5.3 读取一个实体的多语言数据

GET /api/entities?action=by-uris&uris=wd:Q392 按 URI 批量取实体（此处取鲍勃·迪伦）：

curl -s 'https://inventaire.io/api/entities?action=by-uris&uris=wd:Q392'

实测回显（节选）：

{"entities":{"wd:Q392":{"uri":"wd:Q392","wdId":"Q392","type":"human","labels":{"ab":"Дилан, Боб","am":"ቦብ ዲለን","ar":"بوب ديلان","ja":"ボブ・ディラン","ko":"밥 딜런","mn":"Боб Дилан", "...":"共 100+ 语言标签"}}}}

⚠️ 注意：/api/search 的类型参数是复数 types，误写为 type 会得到 400 missing_parameter 与 error_name: missing_types 错误（实测如此），并附 warnings: ["unexpected parameter: \"type\""] 提示。完整的 API 能力清单与逐域实测见本专栏 《Inventaire 5.1.1 API 详解》。

5.4 自托管路径入口

体验后如需自托管，推荐使用官方 docker-inventaire 套件一键编排，完整部署步骤、镜像选型与常见坑均已实测沉淀在本专栏 《Inventaire 5.1.1 Docker Compose 部署指南》；源码部署路径（原生安装 Node.js + CouchDB + Elasticsearch 后从 Codeberg 克隆仓库构建）的配置细节可见本专栏 《Inventaire 5.1.1 配置参数详解》。

六、适用场景与限制

6.1 适用场景

• 个人/家庭藏书管理：ISBN 扫码建库，借出给朋友时全流程跟踪，显著优于表格软件。
• 小型社群共享书房：办公室书角、社区图书角、读书会——小组模式 + 事务流程（借/还/送/卖）开箱即用。
• 开放知识贡献：发现 Wikidata 缺失的书籍/作者时可直接在站内补录并同步回 Wikidata。
• 需要开放 API 的库存集成：内置 OAuth2 + REST API，可对接第三方应用（如 scanner App、自动化脚本）。

6.2 已知限制

• 域聚焦：数据模型围绕「ISBN 实体 + 人持有物品」设计，管理非书类通用资产（如设备工单、库位/批次）不如 InvenTree/Snipe-IT 专业。
• Elasticsearch 7.x：官方固定 7.17.28，未跟进 ES 8.x；自托管需接受该老版本（安全补丁依赖 7.17 维护线）。
• 生产依赖 Nginx：生产配置关闭了服务端静态文件能力（serveStaticFiles: false），前端资源必须由 Nginx 服务，裸跑服务端无法直接使用 Web 界面。
• 邮件能力需要 SMTP：注册验证、通知、活动摘要依赖外部 SMTP（默认关闭 mailer 时仅影响通知类功能）。
• 资源基线：官方 Docker 套件要求 4 GB 内存、10 GB 磁盘（实查自 docker-inventaire README），低于该配置需自行调低 Elasticsearch 堆内存。
• 社区规模：462 stars 的中小型社区，Issue 响应与文档更新节奏依赖少数核心维护者，企业级支持需自购服务或自行兜底。

七、同类选型对比

7.1 横向对比表

下列同类开源项目均可自托管，定位从「社交化阅读」到「工业库存」各有侧重。星数为 shields.io 实查值（查询日期 2026-10-23）：

💡 表格解读：如果你的核心诉求是「藏书 + 朋友间共享/借阅 + 开放知识图谱」，Inventaire 是唯一同时内置三者且带联邦能力的选项；如果你更看重社区规模与阅读社交，选 BookWyrm；如果管理对象是电子书文件，Calibre-Web 最成熟；如果要管通用家庭物资/工业备件，Grocy、Homebox、InvenTree 更专业；如果是正规图书馆业务（MARC、编目规则、流通规则），Koha 才是对口工具。

7.2 社区活跃度与版本节奏量化

• 版本节奏：实查 CHANGELOG，2025-01-28（3.0.0-alpha）至 2026-05-27（5.1.1）共发布 9 个版本（3.0.x×3、4.0.x×2、5.0.0、5.1.x×2 等），平均 3~6 个月一个功能版本，维护处于活跃期。
• API 稳定性承诺：5.0.0 对 API 做了集中破坏性清理（CHANGELOG 明示 BREAKING CHANGES 清单），预示后续大版本 API 将进入稳定期。
• 兼容矩阵（实查自仓库 package.json 与 README）：Node.js >= 18（建议 20 LTS）、CouchDB >= 3.1、Elasticsearch >= 7.10（套件固定 7.17.28）、GraphicsMagick；操作系统官方文档覆盖 Debian/Ubuntu 系。
• 多语言与生态：Weblate 众包翻译 30+ 语言；前端、i18n、Docker、部署脚本均为独立官方仓库，生态分工清晰。

7.3 选型建议（「如果…则…」）

• 如果你要自托管藏书管理并与朋友共享借阅，且希望数据接入 Wikidata → 选 Inventaire。
• 如果你要纯私有库存、不联网补数据，且重视部署简单（单二进制/单容器）→ 选 Homebox 或 Grocy。
• 如果你是硬件/制造团队管理零件与 BOM → 选 InvenTree。
• 如果你是读书社区运营者，需要书评与共读氛围 → 选 BookWyrm。
• 如果你已有 Calibre 电子书库只想给它一个好看的 Web 界面 → 选 Calibre-Web。
• 如果你是正规图书馆（需要 MARC 编目、读者卡、罚则）→ 选 Koha。

八、参考链接

• 官网与旗舰实例：https://inventaire.io
• 服务端主仓库（Codeberg，最新版本发布处）：https://codeberg.org/inventaire/inventaire
• GitHub 镜像仓库：https://github.com/inventaire/inventaire
• 前端仓库：https://codeberg.org/inventaire/inventaire-client
• Docker 套件（官方 Compose）：https://github.com/inventaire/docker-inventaire
• 官方 Docker 镜像：https://hub.docker.com/r/inventaire/inventaire
• 部署脚本仓库（systemd/Nginx 参考）：https://codeberg.org/inventaire/inventaire-deploy
• 项目 Wiki：https://wiki.inventaire.io
• 安装文档（仓库 docs/installation）：https://codeberg.org/inventaire/inventaire/raw/branch/main/docs/installation/README.md
• 示例账号约定：本文档系列演示实例的注册账号为 admin，密码 q1w2e3r4