Part-DB 2.20.2 介绍与选型指南

目标：本文面向需要在自有服务器上搭建电子元器件（以及通用物料）库存管理系统的工程师与电子爱好者，介绍 Part-DB 2.20.2 的定位、架构、功能与同类产品横向对比，帮助读者判断它是否适合自己的场景。文中版本号、星数、发布节奏等数据均于 2026-10-24 通过官方渠道实查取证，功能能力基于 Part-DB v2.20.2 实例实测。

一、环境信息

本文为 A1 认知篇，数据以官方源联网溯源为主（标注来源与查询日期），部署验证部分来自本团队在 Ubuntu 22.04 x86_64 服务器上实测 Part-DB v2.20.2 的结果。

💡 说明：Part-DB 存在两个 GitHub 组织仓库——Part-DB/Part-DB（v1.0 之前的旧版，PHP 5 时代技术栈，已停止功能开发）与 Part-DB/Part-DB-server（v1.0 起基于 Symfony 的完全重写版）。本文与官方推荐一致，只讨论后者（新版），旧版仅作为迁移来源出现。

二、软件概述

Part-DB 是一个开源（AGPL-3.0）的自托管电子元器件库存管理系统，由德国开发者 Jan Böhmer（jbtronics）主导开发。它以 Web 服务形态安装在自己的服务器上，用户通过浏览器访问，无需在客户端安装任何软件。其核心使命是回答电子研发/制作场景中最频繁出现的几个问题：我有哪些料？放在哪个柜子哪个格子里？库存还剩多少？价格是多少？这个 BOM（物料清单）够不够打 10 块板子？

与通用资产管理工具（如 Snipe-IT）不同，Part-DB 的数据模型围绕元器件的物理属性设计：类别、封装（Footprint）、制造商、存储位置（库位树）、供货渠道（Orderdetail）、价格多币种、脚位/参数（Parameters）、数据手册附件等一应俱全；与家庭库存工具（如 Koillection）相比，它内建了库存操作（入库/出库/移库）、最低库存预警、BOM 领料等「进销存」能力，而不是简单的「收藏清单」。

Part-DB 对个人创客、开源硬件团队、高校实验室、创客空间（Maker Space）以及需要管理样机物料的小型企业都适用。它支持多用户与细粒度权限，可以做到「所有人可查库存、仅管理员可改基础数据」的协作模式。

三、核心架构

Part-DB 采用经典的「PHP 框架 + 关系型数据库 + 文件存储」三层结构，自上而下分为四层：

1. Web 展示层：服务端渲染的 Twig 模板 + Bootstrap 5 主题（Bootswatch 多主题可选），配合 Stimulus/Turbo 实现局部刷新；响应式设计，PC/平板/手机共用一套界面。
2. 应用层（Symfony 7）：路由、权限（基于 Voter 的细粒度权限位）、事件日志、标签生成、条码扫描等业务逻辑全部在 PHP 服务端完成。
3. 数据层（Doctrine ORM）：所有实体（Part、Category、Footprint、Manufacturer、Storelocation、PartLot、Orderdetail 等）通过 Doctrine 映射到 MySQL/MariaDB/PostgreSQL/SQLite 四种可选后端。
4. 文件存储：附件（数据手册、图片）与上传文件存放在服务器文件系统（uploads 目录），缩略图由服务端自动生成。

架构上值得注意的三个设计点：

• 数据库可插拔：SQLite 用于单人小库（零依赖），MySQL/MariaDB 用于多用户并发场景（官方明确建议较大实例用 MySQL），PostgreSQL 亦可。数据库平台之间提供 partdb:migrations:convert-db-platform 转换命令。
• 权限是「权限位」而非角色：Part-DB 把权限拆成 20 多个域（元件、基础数据、系统、API、标签等），每个域内若干操作位，可按用户或用户组逐一配置，粒度远细于常见的 admin/editor/reader 三段式。
• API 与 AI 优先：v2.x 内建基于 API Platform 的 REST API（本文实测于 v2.20.2）、OAuth2 授权服务器与 MCP Server（供 AI 助手查询库存），并可与 KiCad EDA 双向集成——这是同类产品中独一份的「EDA 数据源」定位。

四、功能特性

以下特性清单来自官方 README（查询日期 2026-10-24）并结合 v2.20.2 实例核验：

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

本节给出从零到可用站点的最短路径（以官方推荐的容器化方式为例，完整部署细节见部署篇；传统裸机安装需 PHP 8.2 + Composer + Node.js/yarn 构建前端资产，流程较长，见参考链接中的官方安装文档）。

1. 准备一台 64 位 Linux 服务器（32 位 PHP 受 2038 年问题影响，官方明确建议 64 位），已安装 Docker 与 Docker Compose 插件。
2. 新建目录并写入官方 docker-compose.yaml（SQLite 版，零外部依赖）：

services:
  partdb:
    image: jbtronics/part-db1:v2.20.2
    ports:
      - '8080:80'
    volumes:
      - ./uploads:/var/www/html/uploads
      - ./public_media:/var/www/html/public/media
      - ./db:/var/www/html/var/db
    environment:
      - DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db
      - APP_ENV=docker
      - APP_SECRET=CHANGE_ME

3. 启动并初始化数据库：

docker compose up -d
docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate

迁移完成时会在终端输出 admin 用户的初始随机密码；也可在 compose 环境变量中预先设置 INITIAL_ADMIN_PW 指定初始密码。

4. 浏览器访问 http://<服务器IP>:8080，用 admin 与上述密码登录，即可开始录入元件。

💡 本团队实测补充：若 MySQL 侧日志/二进制日志（binlog）开启且数据库账号无 SUPER 权限，迁移会报错 1419，需在 MySQL 侧设置 log_bin_trust_function_creators=1（详见部署篇排障实录）。

六、适用场景与限制

6.1 适用场景

• 个人电子工程师/创客的元件库：几十到几万种料，配合摄像头扫码和标签打印，彻底告别「这电阻在哪」。
• 创客空间/开放实验室：多人共用库存，权限位控制谁能领料谁能改数据，事件日志可追溯每次出入库。
• 小型硬件团队/高校实验室：BOM 核算 + 最低库存 + LCSC/Digikey 价格自动抓取，采购与备料有据可依；KiCad 集成让工程师在画图时直接看到库存。
• 需要 AI/自动化集成的库存：REST API + OAuth2 + MCP Server 使其成为 AI 助手可直查的「物料大脑」。

6.2 限制与注意

• 元器件域强绑定：数据模型（封装、脚位、参数、料号前缀）围绕电子料设计，管理非电子类物品（如文具、食材）会显得别扭，这类场景更适合同系列对比产品中的 Koillection。
• API 仍标注 beta：官方文档明示 REST API「尚未保证稳定，未来版本可能无通知变更」，API 集成需自行锁定版本并回归测试（本文 D5 篇实测口径为 v2.20.2）。
• 单实例架构：无官方集群/多节点方案，横向扩展不在设计目标内；好在 Web 应用本身无状态，可用负载均衡跑多份无状态副本 + 共享数据库与文件存储实现读扩展（需自行处理 uploads 共享存储）。
• HTTPS 不在容器内置：官方容器方案只提供 HTTP，公网暴露必须自建反向代理 + TLS 证书。
• 搜索规模：全文搜索在数万级元件内体验良好；更大规模需依赖数据库性能与参数化检索优化。

七、同类选型对比

自托管「物料/库存管理」领域可选产品较多，但定位差异明显。下表从部署形态、数据模型、协作与 API 等维度对主流选项做量化对比（数据来源：GitHub shields.io 徽章，查询日期 2026-10-24；InvenTree 另有站内专栏可参考）。

选型建议：

• 画电路、买芯片、打板子 → Part-DB。封装/脚位/参数/BOM 扣料/KiCad 集成是硬需求，Part-DB 是唯一同时满足且活跃维护的选择；InvenTree 亦可胜任（其库存模型更通用，PLM 属性更强，适合「硬件产品工程」视角，见站内 《InvenTree 1.6.1 介绍与选型指南》对比）。
• 硬件产品的完整库存 + 制造链路（采购订单、BOM 版本、供应商管理） → InvenTree，其项目/构建/订单体系更完整，社区规模也更大。
• 收藏品/家庭物品目录 → Koillection：纯目录型，无库存操作，轻量好看；Part-DB 用于此场景属「杀鸡用牛刀」。
• IT 设备/办公资产管理（谁领了这台笔记本） → Snipe-IT，签发/归还/折旧模型对路；电子元件颗粒度太细，不适合。
• 老 PartKeepr 用户 → 官方已停止维护，Part-DB 提供 partdb:migrations:import-partkeepr 迁移命令，是官方指定的后继选项之一。

💡 补充说明：德国 Krämer IT 开发的 InvenioKMU（PartKeepr 的商业维护分叉）也常出现在同类对比中，主要面向中小企业 IT/物料管理，发布渠道以 SourceForge 与官网为主，不在 GitHub Releases 体系内。截至 2026-10-24 查询，其官网与 SourceForge 页面未能在线访问核实当前发布状态，故未纳入上表量化对比；选型时如考虑该产品，请先自行确认其维护状态。

社区活跃度小结：Part-DB 月提交数（134/月）高于 InvenTree（107/月）与 Koillection（12/月），发布节奏上 2026 年 9-10 月连续发布 v2.19.x 与 v2.20.x（Docker Hub tag 时间线 2026-09-27 至 2026-10-21，查询日期 2026-10-24），属于高频迭代项目；InvenTree 星标数（7.8k）约为 Part-DB 的 4 倍，生态插件与商业化支持更丰富；两者均为活跃维护状态。

八、参考链接

• 官方文档（含安装/配置/API）：https://docs.part-db.de/
• 源码仓库：https://github.com/Part-DB/Part-DB-server
• 在线演示：https://demo.part-db.de/
• Docker 镜像：https://hub.docker.com/r/jbtronics/part-db1
• 官方裸机安装指南（Debian/通用）：https://docs.part-db.de/installation/installation_guide-debian.html
• 官方配置文档：https://docs.part-db.de/configuration.html
• 本系列部署篇：《Part-DB 2.20.2 Docker Compose 部署指南》
• 站内同类组件：《InvenTree 1.6.1 介绍与选型指南》