Koillection 1.8.5 介绍与选型指南

自托管收藏/物品管理 Web 应用 Koillection 的全景介绍：版本与社区数据取证、核心能力拆解、技术架构、同类组件横向对比与选型建议，全部数据于 2026-10-28 联网核实。

KoillectionKoillectionPHP 编程NAS 自托管2026/10/28

Koillection 1.8.5 介绍与选型指南

目标：为「自托管收藏/物品管理」场景讲清 Koillection 是什么、能做什么、技术底子如何、与同类开源组件的差异，并给出可落地的选型建议。本文全部版本号、星数、依赖信息均于 2026-10-28 联网核实（来源标注见文内与文末），部署实测、配置与命令的实机验证分别见本专栏后续三篇。

一、版本与社区数据取证

项目值取证方式
组件仓库github.com/koillection/koillection（旧地址 benjaminjonard/koillection 会自动重定向）官方 README 徽章与仓库页
最新稳定版1.8.5（2026-10-27 发布，安全修复版：搜索自动补全 XSS 转义、上传扩展名白名单、依赖 CVE 升级等）GitHub Releases atom feed
发布节奏1.8.1（2026-06-01）→ 1.8.2（2026-06-15）→ 1.8.3（2026-06-25）→ 1.8.4（2026-08-23）→ 1.8.5（2026-10-27），约 6~8 周一版GitHub Releases atom feed
许可证MIT仓库页 SPDX 标识 + composer.json
GitHub Stars1338（2026-10-28）仓库页 HTML 内嵌 stargazerCount，与 shields.io 徽章同源
后端运行要求PHP ≥ 8.5（1.8.5 composer.json 约束）仓库 composer.json
后端框架Symfony 8.x 组件（framework-bundle 8.0.13，各组件 8.0/8.1 混布，命令行实测报告 Symfony 8.0.13）+ API Platform 4.3.17 + Doctrine ORM 3.7.5仓库 composer.json（锁定版本）
前端构建Vite 8.3.3 + Stimulus 3.2.2 + ECharts 6.1.0，yarn 4.15.0 管理，要求 Node ≥ 26仓库 assets/package.json
官方运行时FrankenPHP（PHP 8.5）内嵌 Caddy，附 curl-impersonate 供网页刮削仓库构建文件 Dockerfile 与 docker/entrypoint.sh
数据库PostgreSQL ≥ 10、MySQL ≥ 8.0、MariaDB ≥ 10 三选一官方 README 徽章
接口REST API（API Platform 自动生成，JWT 鉴权，lexik/jwt-authentication-bundle 3.2.0）仓库 composer.json
官方文档https://koillection.github.io/koillection/（官网）+ 仓库 Wiki（安装/配置）官网页头与仓库导航

💡 技术拓展：PHP 应用的三种经典运行时形态。 传统 Apache + mod_php 把解释器编进 Web 服务器进程，配置简单但进程模型重；nginx + PHP-FPM 是过去十年的事实标准——FPM 管理一组常驻 worker，nginx 通过 FastCGI（或 Unix socket）把请求转给它，本文实测部署采用的就是这一形态；FrankenPHP 则把 PHP 解释器直接嵌入 Caddy（Go 编写的现代 Web 服务器），支持 worker 模式常驻内存、自动 HTTPS 与早期提示，是 Koillection 官方构建采用的运行时。三种形态跑的是同一份代码，性能差异在小流量自托管场景基本无感，选型主要看运维习惯。

二、Koillection 是什么

Koillection 的官方一句话定义是「a self-hosted service allowing users to manage any kind of collections」——一个自托管的服务，用来管理任意类型的收藏（仓库页描述，2026-10-28）；官网首页标题则是「A self-hosted website to manage all your collections」（官网首页，2026-10-28）。它面向的是实物收藏：书、DVD、邮票、游戏卡带、模型、香水、黑胶……只要你能归类，它就能管。

它的设计哲学很克制：不内置任何元数据源。Koillection 不会自动从豆瓣、TMDB 或 Discogs 拉数据，而是提供一个自定义 HTML 刮削器机制——你可以为自己的收藏品类编写抓取规则，也可以完全手工录入。这换来了零外部依赖和彻底的数据自主权。

官网（https://koillection.github.io/koillection/）列出的管理对象有五类：

  • Collections（收藏集）：可无限嵌套的树形结构，每个收藏集可定义自己的字段模板；
  • Items（物品条目）：归属某个收藏集，携带照片、价格、数量等字段；
  • Signs（标记/签条）：轻量的记录单位；
  • Tags（标签）：跨收藏集的横向归类；
  • Wishlists（愿望单）：想买/想收的清单，支持购物追踪。

围绕这五类对象，官网首页给出三组卖点（2026-10-28 核实）：Share——把收藏分享给别人并保留完整的可见性控制；Invite——邀请其他人在你的实例上独立管理他们自己的收藏；以及 PWA——渐进式 Web 应用，手机/平板上可像原生 App 一样使用。首页同时标注了夜间模式与 REST API 两个特性入口。

💡 技术拓展：自托管应用的多用户隔离模型。 单用户单实例（如多数个人壁纸站）、共享空间（所有人看同一份数据，靠权限位区分读写）、独立空间（每个账号一套数据，默认互不可见）是三种常见模型。Koillection 采用第三种：每个被邀请用户拥有独立数据空间，分享是显式动作且粒度可控，因此天然适合「家庭共用一台服务器、各自记各自的收藏」。

三、核心能力逐项拆解

3.1 数据模型：收藏集自定义字段

这是 Koillection 区别于「表格工具」的关键。每个收藏集可以定义自己的字段模板：文本、数字、日期、价格、下拉、多选等，条目按模板录入；统计面板用 ECharts 渲染（仓库 assets/package.json 锁定 echarts 6.1.0，2026-10-28 核实），价格曲线、数量分布一目了然。

3.2 图片与缩略图

条目图片存放在应用 public/uploads/<用户ID>/ 目录下（仓库 src/Service/ImageHandler.php 第 50 行，路径按用户 ID 分目录，2026-10-28 核实），GD 库生成缩略图；源码自带重建缩略图、清理未引用图片、重建操作日志、刷新缓存计数的维护命令（见《Koillection 1.8.5 常用 CLI 命令与工具详解》）。工具页面还内置了图片打包导出（仓库 src/Controller/ToolsController.php 提供 exportImages 动作，2026-10-28 核实）。

3.3 自定义刮削器

README 明确说明：Koillection「doesn't come with pre-built metadata download」，即不预置任何元数据抓取源，但支持自写 HTML scraper，或自由手工录入（仓库 README，2026-10-28）。官方构建还内置了 curl-impersonate——一个模拟真实浏览器 TLS/HTTP2 指纹的 curl 变体（仓库构建文件，2026-10-28 核实），说明作者认真对待「目标站点反爬」这个现实问题。

💡 技术拓展：网页刮削的两种主流姿势。 一种是调官方/第三方元数据 API（省事但受制于人，且冷门品类无 API 可调）；另一种是解析目标站点的 HTML（自由度高，但要应对反爬）。curl-impersonate 属于后者的工程化方案：普通 curl 的 TLS 握手指纹与浏览器差异明显，容易被站点拦截，而它完整复刻了 Chrome 的握手特征。Koillection 把它预置进运行时，自写刮削器的成功率因此更高。

3.4 多用户与隐私

每个被邀请的用户拥有独立的数据空间，互不可见（除非主动分享）；所有数据存在你自己的服务器上。官网首页的 Private 栏目原话：「Everything is stored on your own server, you have full control over your data and anything you upload.」（2026-10-28 核实）。

3.5 REST API 与 JWT

后端基于 API Platform 4.3，自动暴露 REST 接口，用 lexik JWT 包做鉴权（composer.json 锁定 lexik/jwt-authentication-bundle 3.2.0，2026-10-28 核实）。JWT 密钥对可用一条命令生成（php bin/console lexik:jwt:generate-keypair，实测见《Koillection 1.8.5 常用 CLI 命令与工具详解》）。想写脚本批量导入、对接 Home Assistant 或自建前端，都有官方通道；实测 /api/docs 返回完整的 OpenAPI 描述（部署验证见安装部署指南）。

💡 技术拓展：JWT 与 Session 是 Web 登录态的两大流派。 Session 把状态存在服务端（数据库或内存），浏览器只拿一个会话 ID Cookie，优点是服务端可随时吊销；JWT 把用户身份签名后放进令牌本身，服务端无状态、天然适合前后端分离与多端复用。Koillection 两条腿走路：Web 界面用 Session，REST API 用 JWT，两条通道互不干扰。

3.6 国际化

界面翻译托管在 Crowdin（crowdin.com/project/koillection，README 徽章，2026-10-28 核实），支持包括中文在内的多语言；JavaScript 侧的翻译通过 php bin/console app:translations:dump 命令重新导出（仓库 cheatsheet.md，2026-10-28 核实），改完翻译不必等发版。

四、技术架构与部署形态

Koillection 是一个典型的单体 PHP 全栈应用，没有微服务、没有消息队列、没有独立缓存服务：

  • 后端：PHP ≥ 8.5 + Symfony 8.x（HTTP 内核、表单、安全、Messenger 等）+ Doctrine ORM；API 层由 API Platform 4.3 自动生成；
  • 运行时：官方构建采用 FrankenPHP——把 PHP 解释器嵌入 Caddy 的现代 PHP 运行时，支持 worker 模式常驻内存；裸机部署同样可以用传统的 nginx + PHP-FPM 承载（本专栏实测即为此形态，见《Koillection 1.8.5 安装部署指南》）；
  • 前端：源码形态是 Vite + Stimulus 的现代工程，部署前需要用 Node ≥ 26 + yarn 4 构建出静态资源（assets/package.json，2026-10-28 核实）；
  • 数据库：PostgreSQL / MySQL / MariaDB 三选一，由 DB_DRIVER 环境变量切换（本专栏实测选 PostgreSQL 17）；
  • 文件存储：本地磁盘（public/uploads），没有对象存储依赖。

这个架构决定了它的资源画像：一台 1 核 1GB 的小主机就能流畅跑起来，备份 = 数据库转储 + uploads 目录，运维心智负担接近零。

五、横向选型对比

在「自托管物品/收藏管理」这个赛道上，Koillection 的差异化在于数据模型自由度 + 多用户隔离：

组件定位数据模型多用户适合谁
Koillection通用收藏管理收藏集自定义字段，无限嵌套用户邀请 + 独立空间 + 精细分享任何实物收藏爱好者、家庭多成员各自管理
Inventree库存/零件管理强结构化：零件、库存位、BOM团队协作电子工程师、仓库管理，数据模型偏工业
Part-DB电子元件库围绕元器件型号建模有电子爱好者，垂直场景
Inventaire书籍/媒体 + 社区交换绑定 Wikidata/ISBN 书目数据社区化藏书管理 + 想要社区互通的用户
Homebox家庭物品收纳定位房间/箱盒位置模型家庭共享「东西放在哪个箱子里」的收纳管理
Discogs/Goodreads云 SaaS固定品类平台账号不介意数据出户、只要单一品类的用户

一句话总结：要「定义自己的收藏长什么样」选 Koillection，要「管库存流水」选 Inventree，要「管元器件」选 Part-DB，要「管书并接入开放数据」选 Inventaire。

六、选型建议

适合上 Koillection 的信号：

  1. 你收藏的品类「杂」或「冷门」，现成的元数据工具覆盖不了；
  2. 家庭/小团队多人使用，希望数据互相隔离又能选择性分享；
  3. 你在意数据自主：导出、备份、API 全在自己手里；
  4. 服务器资源紧张（1C1G 起步即可）。

需要犹豫的信号：

  1. 你希望开箱即得的自动元数据抓取——Koillection 刻意不内置，需要自写刮削器或手工录入；
  2. 你的场景是工业级库存流转（出入库单、BOM、盘点）——Inventree 更对口；
  3. 不想碰 Node/Composer 构建链——源码部署需要完整的前后端构建（流程与耗时实测见《Koillection 1.8.5 安装部署指南》）。

七、下一步

参考来源（查询日期均为 2026-10-28）

  1. 官方网站：https://koillection.github.io/koillection/
  2. 官方仓库：https://github.com/koillection/koillection（README、构建文件 Dockerfile、cheatsheet.md、1.8.5 源码）
  3. composer.json / assets/package.json（1.8.5 锁定版本）：https://github.com/koillection/koillection/tree/1.8.5
  4. GitHub Releases（1.8.5，2026-10-27，安全修复版）：https://github.com/koillection/koillection/releases
  5. 官方 Wiki 安装页：https://github.com/koillection/koillection/wiki/Installation
  6. 官方 Wiki 配置页：https://github.com/koillection/koillection/wiki/Configuration
  7. Star 数取证：https://img.shields.io/github/stars/koillection/koillection（shields.io，与仓库页 stargazerCount=1338 一致）