开源库存管理系统 InvenTree 使用指南

InvenTree 库存管理系统提供低级别库存控制和零件跟踪，系统的核心是Pvthon/Django数据库后端，提供管理功能(基于Web)和RESTAPI，能与外部接口和应用程序进行交互，InvenTree支持插件，用户可以根据自己的需求进行扩展。

服务端：采用 Python 语言，搭配 Django 框架、DRF（Django REST Framework）构建 API，通过 Django Q 实现任务队列管理，通过 Django-Allauth 处理用户认证。

数据存储：支持 PostgreSQL、MySQL、SQLite 等关系型数据库，通过 Redis 实现缓存加速。

前端交互：基于 React 开发，集成 Lingui 实现国际化，使用 React Router 管理路由，搭配 TanStack Query 和 Zustand 处理状态，UI 组件库选用 Mantine。

DevOps 工具链：通过 Docker 实现容器化部署，利用 Crowdin 完成翻译，通过 Codecov 进行代码覆盖率分析，使用 SonarCloud 进行代码质量检测，通过 Packager.io 管理软件包。

容器化部署：推荐使用 Docker 快速启动，官方提供一键安装脚本：

wget -qO install.sh https://get.inventree.org && bash install.sh

云平台部署：支持 DigitalOcean 等云服务商的裸机部署，详细步骤可参考官方文档。

移动端支持：配套开发有移动端应用，用户可在 Android 应用商店和苹果 App Store 下载，方便随时查看库存数据。

InvenTree 的 API 交互设计

InvenTree 的 REST API 基于 Django REST Framework 开发，有自描述特性，在本地部署实例后，可通过 http://127.0.0.1:8000/api-doc/ 访问文档，支持调试模式下直接通过浏览器探索接口。

认证机制

1、基础认证：使用用户名和密码进行验证，适合简单场景。

2、令牌认证：用户可生成持久化令牌，在请求头中以 Token <令牌值> 格式传递，提升 API 访问效率。

# Python 请求示例
import requests
token = '你的令牌值'
headers = {'Authorization': f'Token {token}'}
response = requests.get('http://localhost:8080/api/part/', headers=headers)

3、OAuth2/OIDC 认证：作为实验性功能，需手动启用，支持通过公共客户端和 PKCE 流程实现第三方认证。

权限体系

用户角色决定 API 访问权限，可通过 /api/user/roles/ 接口获取当前用户权限列表。超级用户拥有所有模块的读写权限，只读用户仅能查看部分数据，若执行超出权限的操作，系统将返回 403 错误。

接口使用

命令行工具：通过 coreapi-cli 工具加载 schema 文件，实现无代码接口的交互：

pip install coreapi-cli
coreapi get http://127.0.0.1:8000/api-doc/

编程式调用：支持通过 Python 模块直接操作，简化数据查询和修改流程。

Python 开发工具包

官方提供的 Python 模块为第三方开发提供了便捷接口，可通过 pip3 install inventree 安装。

认证方式

用户名/密码认证：

from inventree.api import InvenTreeAPI
api = InvenTreeAPI('http://127.0.0.1:8000', username='admin', password='your_password')

令牌认证：

api = InvenTreeAPI('http://127.0.0.1:8000', token='your_token')

环境变量配置：可通过设置 INVENTREE_API_HOST、INVENTREE_API_TOKEN 等环境变量实现无感知认证。

数据操作

单条数据查询：已知对象主键时，直接初始化对象：

from inventree.part import PartCategory
category = PartCategory(api, 10)  # 获取 ID 为 10 的零件类别

多条数据查询：使用 list 方法结合过滤条件：

from inventree.part import Part
parts = Part.list(api, category=10, assembly=True)  # 查询类别 10 下的组装件

层级数据过滤：对于树形结构数据，可通过 parent 参数筛选子节点或根节点：

child_categories = PartCategory.list(api, parent=10)  # 查询父节点为 10 的子类别
parent_categories = PartCategory.list(api, parent='')  # 查询顶级类别

元数据

字段信息获取：通过 fieldNames 和 fieldInfo 方法查看模型字段元数据：

for field in Part.fieldNames(api):
    print(field, '->', Part.fieldInfo(field, api))

关联数据操作：提供简单的方法获取关联数据。 part.getStockItems() 获取零件对应的库存项，支持上传文件附件等操作。

插件开发

创建脚手架：使用 inventree-plugin-creator 工具快速生成插件模板：

pip install inventree-plugin-creator
create-inventree-plugin

代码结构：插件需继承 InvenTreePlugin 基类（旧版本为 IntegrationPluginBase），通过定义元数据（如 NAME、SLUG、VERSION）声明基本信息。

功能扩展

通过混入（Mixin）机制实现不同功能模块的扩展，支持的混入类型包括：

静态资源管理

插件所需的 CSS、JavaScript 等静态文件需放置在插件包的 static 目录下，安装后可通过 http://实例地址/static/plugins/插件名/文件名 访问，系统会自动收集并部署这些文件。