InvenTree 开源库存管理系统技术全览:架构、部署与扩展实战指南 📅 发布时间:2026/9/16 15:46:11 👁 浏览次数: InvenTree 开源库存管理系统技术全览架构、部署与扩展实战指南【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree导读InvenTree 是一款开源的库存管理系统Inventory Management System以Python/Django 后端 REST API React 前端 可插拔插件体系为核心设计提供细粒度的低层库存控制low-level stock control与零件追踪能力。本文以项目根目录 README.md 为主线结合 tasks.py、config_template.yaml、docker-compose.yml 等仓库源码系统讲解其技术架构、部署方式、配置系统与集成扩展能力帮助你从零掌握 InvenTree 的安装、配置与二次开发。一、项目定位与核心能力README 开篇即给出 InvenTree 的精确定位开源的库存管理系统提供强大的低层库存控制和零件跟踪能力。其核心设计有三层Python/Django 数据库后端提供基于 Web 的管理界面admin interface与 REST API供外部接口和应用交互REST API官方文档中提供 API 文档用于与外部系统集成插件系统强大的插件体系支持自定义应用与扩展详见 插件文档。从 version.py 可以看到当前仓库的软件版本信息为INVENTREE_SW_VERSION 1.6.0 dev最低要求Python 3.12以上MIN_PYTHON_VERSION (3, 12)并提供了inventreeVersion()、inventreeApiVersion()、inventreeCommitHash()等一系列运行时信息查询函数。从 tasks.py 的builtin_apps()函数可以清晰地看到系统内置的业务模块def builtin_apps(): return [ build, common, company, importer, machine, order, part, report, stock, users, plugin, InvenTree, generic, machine, web, scim, ]这些模块对应着 InvenTree 的核心业务域part零件/物料、stock库存、build生产/装配、order采购/销售订单、company供应商/客户/制造商、report报表/标签、machine机器集成、scim用户供给与身份管理等。二、技术栈全景README 用折叠菜单Tech Stack展示了完整的服务器端、数据库、客户端与 DevOps 技术选型结合仓库实际文件可以逐项验证服务端ServerPythonDjangoWeb 框架核心Django REST FrameworkDRFREST API 层Django Q后台任务队列用于运行长时间任务与周期性任务worker任务即调用qcluster见 tasks.pyDjango-Allauth认证体系支持账号、SSO 等。数据库DatabasePostgreSQL、MySQL、MariaDB、SQLite均可作为数据库后端Redis作为缓存管理器。在 config_template.yaml 的database段中配置模板明确列出engine可取值包括mysql、postgresql、sqlite3。生产环境 Docker Compose 默认采用 PostgreSQL 17见 docker-compose.yml并以 Redis 7 作为缓存inventree-cache服务。客户端Client前端是独立的 React 单页应用代码位于 src/frontend从 package.json 可以看到主要依赖React 19React RouterUI 框架与路由Lingui前端国际化TanStack Query服务端状态管理Zustand客户端状态管理MantineMantine Data Table组件库与数据表格CodeMirror代码/模板编辑器支持。DevOpsDocker官方镜像inventree/inventreeCrowdin社区翻译平台crowdin.ymlCodecov / SonarCloud / Packager.io代码覆盖率、代码质量与打包分发。三、部署方式详解README 明确给出了三种部署途径Docker、Bare Metal裸机安装和单行安装脚本并强调完整安装和设置说明请参考 getting started 指南。下文结合仓库真实文件逐一展开。3.1 Docker Compose 生产部署仓库在 contrib/container/docker-compose.yml 中提供了一套生产可用的编排方案包含 5 个容器服务镜像职责inventree-dbpostgres:17PostgreSQL 数据库后端inventree-cacheredis:7-alpineRedis 缓存管理inventree-serverinventree/inventree:stablegunicorn Web 服务InvenTree 主进程inventree-workerinventree/inventree:stabledjango-q 后台任务进程inventree-proxycaddy:alpineCaddy 反向代理 静态文件服务关键设计要点均可在 docker-compose.yml 中验证镜像版本策略默认使用inventree/inventree:${INVENTREE_TAG:-stable}即 STABLE 稳定版如需最新开发版在.env中将INVENTREE_TAG改为latest或指定具体发布版本号如INVENTREE_TAG0.7.5。配置外置原则README 注释明确要求你不应该修改 docker-compose.yml 中的任何内容所有变更通过.env文件完成。数据库名、用户名、密码分别由INVENTREE_DB_NAME、INVENTREE_DB_USER、INVENTREE_DB_PASSWORD强制提供缺少即报错退出。数据卷持久化数据卷必须映射到容器内/home/inventree/data${INVENTREE_EXT_VOLUME}:/home/inventree/data:zDockerfile 中对应环境变量为INVENTREE_DATA_DIR/home/inventree/data。健康检查链数据库使用pg_isready、缓存使用redis-cli ping、Web 服务通过invoke server-health --address http://localhost:${INVENTREE_WEB_PORT:-8000}检查、Worker 通过invoke worker-health检查心跳文件、代理检查/api/system/health/。inventree-server依赖数据库与缓存健康后才启动形成完整的依赖拓扑。启动命令在contrib/container目录下cp .env.example .env # 按需修改 .env 配置 docker compose up -d关于容器内部实现Dockerfile 采用多阶段构建multi-stageinventree_base基础镜像 →builder_stage编译 Python 依赖与前端 →production生产镜像gunicorn 启动与dev开发镜像Django 开发服务器 Vite 热更新监听 5173 端口。生产镜像以gunicorn -c ./gunicorn.conf.py InvenTree.wsgi启动开发镜像则以invoke dev.server启动。3.2 单行安装脚本Packager.ioREADME 提供了单行安装命令wget -qO install.sh https://get.inventree.org bash install.sh该脚本在仓库中对应 contrib/install.sh 与 contrib/installer/src/root_command.sh。从安装器源码可以确认其工作流程发行版检测读取/etc/os-release、lsb_release等文件检测操作系统当前仅支持Ubuntu 24.04/26.04与Debian 13对已 EOL 的旧版本如 Ubuntu 20.04/22.04、Debian 12 及以下会明确提示不再支持并建议手动安装安装依赖自动安装curl配置软件源通过packager.io的 GPG 密钥与.list源文件将 InvenTree 打包进 apt 软件源安装sudo apt-get install inventree -y完成安装。该脚本还支持--no-call导出NO_CALLtrue用于跳过实际安装回调与--dry-run仅打印要执行的命令两个标志参数。3.3 裸机安装与 Procfile 进程模型README 同时给出 Bare Metal 安装途径。仓库根目录的 Procfile 明确了生产环境的进程模型web: env/bin/gunicorn --chdir $APP_HOME/src/backend/InvenTree -c src/backend/InvenTree/gunicorn.conf.py InvenTree.wsgi -b 0.0.0.0:$PORT worker: env/bin/python src/backend/InvenTree/manage.py qcluster即web 进程gunicorn 提供 HTTP 服务与worker 进程django-q 集群处理后台任务分离运行。这与 Docker Compose 中的inventree-server/inventree-worker设计一一对应。3.4 生命周期管理invoke 任务体系仓库通过 tasks.py 中的 invoke 任务统一管理安装、迁移、更新、备份与服务器启动。核心任务包括invoke install安装requirements.txt中的依赖并自动安装插件可--skip-plugins--dev安装开发依赖--uv使用 uv 包管理器invoke migrate执行数据库迁移runmigrationsmigrate --run-syncdb可--detect自动生成新迁移随后自动重建 MPTT 树模型与缩略图invoke update一键更新——按顺序执行依赖安装、翻译编译、备份、迁移、前端编译/下载、静态文件收集、设置清理invoke backup/invoke restore数据库与媒体文件的备份/恢复支持--compress、--encryptGPG、--clean等选项invoke server开发服务器、invoke gunicorn生产服务器、invoke worker后台任务、invoke superuser创建管理员账号invoke export_records/invoke import_records以 JSON 格式导出/导入全部数据库记录导出文件会附带版本元数据来源版本、API 版本、Django 版本、commit 等导入时会做严格的元数据校验版本不匹配会给出INVE-W13警告或INVE-E16错误。四、配置系统详解InvenTree 的配置核心位于 config_template.yaml这是一个可直接复制为config.yaml使用的模板。需要注意的最重要规则是环境变量的优先级高于配置文件中的值例如INVENTREE_DB_NAME、INVENTREE_DEBUG等环境变量会覆盖 YAML 中的同名配置。4.1 数据库与基础配置database: # engine: mysql | postgresql | sqlite3 # name: Database name # user: Database username # password: Database password # host: Database host address # port: Database host port # site_url: http://localhost:8000 # 或环境变量 INVENTREE_SITE_URL debug: False # 生产环境必须为 False4.2 日志与调试模板提供了细粒度的日志控制log_level: WARNING # 可选 DEBUG / INFO / WARNING / ERROR / CRITICAL json_log: False # 是否以 JSON 格式输出日志INVENTREE_JSON_LOG db_logging: False # 数据库级日志 write_log: False # 写入日志文件INVENTREE_WRITE_LOG console_log: True # 输出到 stdout同时还有debug_querycount、debug_silk、debug_silk_profiling、debug_shell等进阶调试开关。4.3 邮件服务支持三种邮件后端SMTP、Console、Anymail。对应的 YAML 配置段所有选项均可使用INVENTREE_EMAIL_前缀环境变量覆盖email: sender: # backend: django.core.mail.backends.smtp.EmailBackend host: port: 25 username: password: tls: False ssl: False4.4 插件系统插件是 InvenTree 最重要的扩展机制plugins_enabled: False # 或环境变量 INVENTREE_PLUGINS_ENABLED # plugin_noinstall: True # plugin_file: /path/to/plugins.txt # plugin_dir: /path/to/plugins/从 tasks.py 可以看到invoke plugins会读取plugins.txt文件安装全部插件并执行collectplugins收集插件静态文件。插件生态的完整介绍见 插件文档 与 mixins 参考支持 API、事件、导出、标签、机器、邮件、通知、报表、定时任务、UI 等多种 Mixin 扩展点。4.5 存储后端storage: target: local # 可选 local / s3 / sftp支持本地文件系统、S3 兼容对象存储含access_key、bucket_name、region_name、endpoint_url等参数以及 SFTP 远程存储。4.6 后台任务与缓存background: workers: 4 timeout: 90 max_attempts: 5 cache: enabled: false host: inventree-cache port: 6379background段控制 django-q 后台 worker 的并发数与超时cache段则配置 Redis 外部缓存。4.7 安全相关配置allowed_hostsDjangoALLOWED_HOSTS模板默认允许所有主机*但注释明确提示这不安全trusted_origins反向代理场景下的CSRF_TRUSTED_ORIGINSlogin_attempts: 5与login_confirm_days: 3登录尝试次数与确认时限remote_login_enabled远程/代理登录需谨慎配置cors跨域设置基于 django-cors-headers。4.8 其他配置language: en-us、timezone: UTC默认语言与时区sentry_enabled: False错误上报可自定义sentry_dsnauto_update: False自动迁移开关admin_user/admin_email/admin_password首次启动自动创建管理员也可从admin_password_file读取customize管理后台标题、登录提示、Logo 等 UI 定制social_backends/ldapSSO 与 LDAP 认证。五、集成与扩展README 强调 InvenTree 被设计为可扩展extensible的系统并提供了多种与外部应用集成或添加自定义插件的途径InvenTree API完整的 REST API详见 API 文档 与 API Schema支持认证、分页、过滤等Python 模块官方 Python 客户端库示例见 Python 使用示例插件接口invoke plugins安装管理插件插件可横跨 API、事件、报表、机器、标签、邮件、通知、UI 等多个维度扩展第三方工具通过 API 与外部系统如 ERP、条形码扫描、电子商务平台对接。值得留意的是仓库还提供 metadata 文档说明 InvenTree 基于 OpenAPI 的 Schema 化 API 设计便于工具链自动生成客户端。六、配套移动应用README 明确指出 InvenTree 有配套的移动端 Appcompanion mobile app允许用户随时随地访问库存控制信息与功能上架于 Google PlayAndroid与 Apple App StoreiOS。移动端通过 REST API 与后端连接相关接入说明见 App 文档。七、安全策略与社区治理行为准则CODE_OF_CONDUCT.md 承诺为所有用户提供安全友好的环境安全策略SECURITY.md 遵循行业最佳实践项目还提供专门的安全文档页贡献指南CONTRIBUTING.md 欢迎社区贡献开发相关指引见 开发文档翻译Web 应用的多语言翻译通过 Crowdin 社区贡献完成仓库中 locale 目录 已包含 40 语言的.po翻译文件许可证项目以MIT License分发见 LICENSE。八、如何继续深入如果你希望进一步研究 InvenTree快速体验使用单行安装脚本或docker compose up -d部署一个实例体验零件管理、库存调整、采购/销售订单、BOM 与生产装配等核心流程阅读源码入口后端入口为 manage.py配置解析在 config.pyAPI 路由定义在 urls.py阅读测试各业务模块part、stock、order、company、build 等均配有test_api.py/tests.py例如 part 模块测试可作为理解接口行为的权威参考前端开发frontend README 说明了 React 前端的技术组织方式router.tsx 展示了页面路由结构。小结InvenTree 是一套以 Django/DRF 为后端、React 为前端、django-q 处理后台任务、支持多数据库与对象存储、具备完整 REST API 与插件生态的开源库存管理系统。其核心优势在于清晰的领域模块划分、灵活的配置体系YAML 环境变量双重驱动与多种开箱即用的部署方案。无论你是想快速搭建个人/团队库存管理系统还是希望基于其 API 与插件机制构建深度定制的物料管理体系本文涉及的架构、部署与配置知识都是直接可用的起点。【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考