InvenTree 1.6.1 常用 CLI 命令详解

目标：逐条实测 InvenTree 1.6.1 的两套命令入口——invoke 任务集（官方运维入口）与 python manage.py Django 管理子命令，全部回显取自 1.6.1 真实运行实例（2026-10-23 实测）。InvenTree 1.6.1 的 invoke 任务命名与旧版有差异（连字符命名 + int./dev. 命名空间），本文以实例实测为准。

一、环境信息

InvenTree 版本：1.6.1（commit be48891，2026-10-22）
运行时：Python 3.14.8 + Django 5.2.17 + invoke 2.x
部署形态：五服务栈（部署篇同款），数据目录 /opt/inventree/data
命令入口一：invoke（任务定义文件 tasks.py，位于源码根目录）
命令入口二：python manage.py（位于源码树 src/backend/InvenTree/ 目录）
实测时点：2026-10-23

二、CLI 体系总览

2.1 两个入口的分工

入口	位置	定位	典型场景
`invoke`	源码根目录（`tasks.py`）	官方运维编排入口：把安装、迁移、备份、静态文件、翻译、前端等步骤封装成任务	安装、更新、备份恢复、健康检查
`python manage.py`	`src/backend/InvenTree/`	Django 原生管理命令：迁移、建号、数据操作、诊断	建管理员、看迁移状态、ORM 操作

invoke 任务内部大多是对 manage.py 命令的封装加前置步骤（例如 invoke migrate 在跑完迁移后还会重建内部结构与缩略图）。

2.2 任务清单（实测 `invoke --list`）

cd /opt/inventree/src && invoke --list

Available tasks:

  backend-trans                     Compile backend Django translation files.
  backup                            Backup the database and media files.
  build-docs                        Build the required documents for building
                                    the docs. Optionally build the
                                    documentation using mkdocs.
  export-records                    Export all database records to a file.
  frontend-download                 Download a pre-build frontend from GitHub
                                    if you dont want to install nodejs on your
                                    machine.
  import-records                    Import database records from a file.
  install                           Install required python packages for
                                    InvenTree.
  listbackups                       List available backup files.
  migrate                           Performs database migrations. This is a
                                    critical step if the database schema has
                                    been altered.
  monitor                           Monitor the worker performance.
  plugins                           Installs all plugins as specified in
                                    'plugins.txt'.
  remove-mfa                        Remove MFA for a user.
  restore                           Restore the database and media files.
  server-health                     Check if the web server is healthy by
                                    requesting /api/system/health/.
  static                            Copies required static files to the
                                    STATIC_ROOT directory, as per Django
                                    requirements.
  superuser                         Create a superuser/admin account for the
                                    database.
  update                            Update InvenTree installation.
  version                           Show the current version of InvenTree.
  wait                              Wait until the database connection is
                                    ready.
  worker                            Run the InvenTree background worker
                                    process.
  worker-health                     Check if the background worker is healthy
                                    by reading the heartbeat file.
  dev.delete-data                   Delete all database records!
  dev.docs-server                   Start a local mkdocs server to view the
                                    documentation.
  dev.frontend-server               Start frontend development server.
  dev.frontend-test                 Start the playwright test runner for the
                                    frontend code.
  dev.gunicorn                      Launch a gunicorn webserver.
  dev.import-fixtures               Import fixture data into the database.
  dev.schema                        Export current API schema.
  dev.server                        Launch a (development) server using
                                    Django's in-built webserver.
  dev.setup-dev                     Sets up everything needed for the dev
                                    environment.
  dev.setup-test                    Setup a testing environment.
  dev.shell                         Launch a Django shell.
  dev.test                          Run unit-tests for InvenTree codebase.
  dev.test-translations             Add a fictional language to test if each
                                    component is ready for translations.
  dev.translate                     Rebuild translation source files. Advanced
                                    use only!
  int.backend-compilemessages       Compile backend Django translation files
                                    without loading InvenTree settings.
  int.clean-settings                Clean the setting tables of old settings.
  int.clear-generated               Clear generated files from `invoke update`.
  int.export-definitions            Export various definitions.
  int.export-settings-definitions   Export settings definition to a JSON file.
  int.frontend-build                Build frontend.
  int.frontend-check                Check if frontend is available.
  int.frontend-compile              Generate react frontend.
  int.frontend-install              Install frontend requirements.
  int.frontend-trans                Compile frontend translations.
  int.rebuild-models                Rebuild database models with MPTT
                                    structures.
  int.rebuild-thumbnails            Rebuild missing image thumbnails.
  int.showmigrations                Show the migration status of the database.

Default task: version

要点：

任务名用连字符（export-records、server-health），默认任务为 version（裸跑 invoke 等价 invoke version）。
1.6.1 把内部维护任务收进 int. 命名空间（int.rebuild-models、int.clean-settings 等），开发任务收进 dev. 命名空间（dev.test、dev.server 等）。旧版文档里无前缀的 rebuild_models/clean_settings 在 1.6.1 直接敲会报 No idea what 'rebuild_models' is!（本实例实测）。

2.3 执行环境说明

下文所有 invoke … 均在源码根目录（tasks.py 所在目录）执行；所有 python manage.py … 均在 src/backend/InvenTree/ 目录执行。部署实例中两条路径分别对应 /opt/inventree/src 与 /opt/inventree/src/backend/InvenTree。示例回显中反复出现的两行是运行环境的固定横幅，与命令结果无关：

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

INVE-W3：源码目录不含 git 元数据（部署实例用的是包化源码），仅在带 --git 语义的路径上有意义，可忽略。
116 objects imported automatically：python manage.py shell 自带的模型导入横幅。

三、invoke 任务详解

3.1 版本与环境信息

invoke version（默认任务）

invoke version

INVE-W3: Could not detect git information.

InvenTree - inventree.org
The Open-Source Inventory Management System


Python paths:
Executable  /usr/local/bin/python
Environment /usr/local
Invoke Tool /usr/local/lib/python3.14/site-packages/invoke/__init__.py

Installation paths:
Base        /home/inventree
Config      /home/inventree/data/config.yaml
Plugin File /home/inventree/data/plugins.txt
Media       /home/inventree/data/media
Static      /home/inventree/data/static
Backup      /home/inventree/data/backup

Versions:
InvenTree   1.6.1
API         561
Python      3.14.8
Django      5.2.17
Node        N/A
Yarn        N/A

Environment:
Platform    Docker
Debug       False

Commit hash: be48891
Commit date: 2026-10-22

💡 排障价值：这条命令一屏看清版本（1.6.1 / API 561）、四个关键路径（Config/Plugin/Media/Backup）、运行环境与调试状态——报障时先跑它，比翻配置快。Node/Yarn N/A 是正常现象：打包安装内置预编译前端，无需 Node（裸机源码安装且未装 Node 时也会是 N/A，可用 invoke frontend-download 下载预编译前端）。

3.2 健康检查三件套

invoke server-health（参数 --address，默认 http://127.0.0.1:8000）

invoke server-health --address "http://localhost:8000"

Server is healthy (http://localhost:8000/api/system/health/)

invoke worker-health ——注意必须在后台工作进程的运行环境里执行（它读工作进程写的心跳文件）。在工作进程环境外执行会得到失败回显（本实例实测）：

Heartbeat file not found: /tmp/inventree_worker_heartbeat
Worker health check failed

切到工作进程运行环境后（实测）：

Worker is healthy (last heartbeat 0m 3s ago)

invoke wait ——等待数据库连接就绪（内部调用 manage.py wait_for_db），开机自检脚本、升级脚本的第一步常用它：

INVE-W3: Could not detect git information.

（无额外输出即等待通过，退出码 0。）

invoke monitor ——工作进程性能监控面板（内部调用 manage.py qmonitor），周期性刷新输出集群状态表；以非交互方式运行可截到一帧（实测，Ctrl+C 退出）：

   Host       Id      State      Pool       TQ        RQ        RC        Up

83980cd90  eabb2ea8    Idle       4         0

（Host=集群短 ID，State=Idle 表示空闲，Pool=4 对应 background.workers 配置的 4 个工作线程，TQ=排队任务数。）

3.3 安装与更新

invoke update（核心命令） ——官方安装文档的标准更新动作：装依赖 → 装插件 → 编译翻译 → 自动备份 → 迁移 → 收集静态文件 → 清理旧设置。实测全流程回显：

Updating InvenTree installation...
Installing required python packages...
Installing required python packages from '/home/inventree/src/backend/requirements.txt'
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
Installed package manager
Installing required python packages from '/home/inventree/data/plugins.txt'
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
INVE-W3: Could not detect git information.
Dependency installation complete
Skipping backend translation compilation (INVENTREE_DOCKER flag set)
Backing up InvenTree database...
INVE-W3: Could not detect git information.
Backing up InvenTree media files...
INVE-W3: Could not detect git information.
Backup completed successfully
Running InvenTree database migrations...
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
InvenTree database migrations completed
Skipping frontend update (INVENTREE_DOCKER flag set)
Collecting static files...
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
Static files collected successfully
InvenTree update complete
Cleaning old settings from the database...
INVE-W3: Could not detect git information.
Settings cleaned successfully

常用参数（1.6.1 tasks.py 实读）：--skip-backup（跳过自动备份，不推荐）、--skip-static、--no-frontend、--verbose。

⚠️ 两个 Skipping … 是打包安装的预期行为（INVENTREE_DOCKER 标志位使然，见 invoke version 回显的 Environment 段）：翻译与前端由安装包构建期处理。裸机源码安装跑 invoke update 会完整执行这两步。

invoke install / invoke plugins ——install 装基础依赖（首次安装用，更新场景 update 会自动做）；plugins 按 plugins.txt 清单安装插件。

invoke static ——单独收集静态文件（改了前端资源/升级后单独补跑）：

invoke static

Collecting static files...
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
Static files collected successfully

invoke migrate ——单独跑数据库迁移（update 已包含迁移步骤，此任务适合只想动库不看其他时用）：

invoke migrate

INVE-W3: Could not detect git information.
Running InvenTree database migrations...
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
InvenTree database migrations completed
Rebuilding internal database structures
INVE-W3: Could not detect git information.
Rebuilding image thumbnails in /home/inventree/data/media
INVE-W3: Could not detect git information.

⚠️ 1.5.0 起的行为变更（官方 CHANGELOG #12323）：invoke migrate 默认只应用存量迁移，不再生成新迁移；需要生成时加 --detect。

3.4 备份与恢复

invoke backup ——备份数据库与媒体文件，落 backup 目录（路径见 invoke version 回显）。参数（1.6.1 实读）：--compress（默认 True）、--encrypt、--skip-db/--skip-media、--path 自定义位置、--clean。

invoke backup

Backing up InvenTree database...
INVE-W3: Could not detect git information.
Backing up InvenTree media files...
INVE-W3: Could not detect git information.
Backup completed successfully

invoke listbackups ——列出可用备份：

invoke listbackups

Finding available backup files...
INVE-W3: Could not detect git information.
Name                                     Datetime
InvenTree-db-2026-10-23-145759.psql.bin.gz 10/23/26 14:57:59
InvenTree-media-2026-10-23-145802.tar.gz 10/23/26 14:58:02

InvenTree-db-2026-10-23-145759.psql.bin.gz
InvenTree-db-2026-10-23-145759.psql.bin.gz.metadata
InvenTree-media-2026-10-23-145802.tar.gz

备份落盘（实测目录清单）：

ls -l /opt/inventree/data/backup/

total 32
-rw-r--r-- 1 root root 16951 Oct 23 22:57 InvenTree-db-2026-10-23-145759.psql.bin.gz
-rw-r--r-- 1 root root   465 Oct 23 22:57 InvenTree-db-2026-10-23-145759.psql.bin.gz.metadata
-rw-r--r-- 1 root root  5605 Oct 23 22:57 InvenTree-media-2026-10-23-145802.tar.gz

invoke restore ——从备份恢复数据库与媒体文件，参数含 --path、--db-file/--media-file、--skip-db/--skip-media、--restore-allow-newer-version（1.6.1 实读）。恢复是覆盖性动作：先停服务进程，确认备份文件后执行，恢复完成再启动。空库冷恢复的完整闭环（销毁→重建→恢复数据）见部署篇第十一章；此任务恢复的是 invoke backup 产生的备份集。

3.5 数据导出与导入

invoke export-records ——把数据库记录导出为文件（默认 data.json，可 --filename 指定）。常用参数：--include-email、--include-permissions、--include-tokens、--prettify（1.6.1 实读）：

invoke export-records --filename /opt/inventree/data/export-records-1.6.1.zip

Exporting database records to file '/opt/inventree/data/export-records-1.6.1.zip'
INVE-W3: Could not detect git information.
INVE-W3: Could not detect git information.
Running data post-processing step...
INVE-W3: Could not detect git information.
Data export completed

ls -lh /opt/inventree/data/export-records-1.6.1.zip

-rw-r--r-- 1 root root 21K Oct 23 15:07 /opt/inventree/data/export-records-1.6.1.zip

invoke import-records ——从文件导入记录，参数含 --clear（先清库，危险）、--ignore-conflicts、--rebuild-trees（默认 True，导入后重建树结构）。适合跨库搬迁（如从 SQLite 迁到 PostgreSQL）。

3.6 用户与安全

invoke superuser ——交互式创建管理员（内部调用 manage.py createsuperuser，逐步提示输入用户名/邮箱/密码）。非交互方式见 4.4 节。

invoke remove-mfa ——管理员账号被锁在 MFA 验证之外时的救援命令，需提供 --username 或 --mail（不给参数会拒绝执行）：

invoke remove-mfa --username admin

INVE-W3: Could not detect git information.
Removed all (0) MFA methods for user admin
done

（本次实测 admin 未启用 MFA，故移除 0 项；命令逻辑本身工作正常。）

3.7 int. 内部维护任务（1.6.1 新命名空间）

invoke int.rebuild-models ——重建 MPTT 树结构（分类/库位等层级表），层级数据异常时使用：

invoke int.rebuild-models

Rebuilding internal database structures
INVE-W3: Could not detect git information.

invoke int.rebuild-thumbnails ——重建缺失的图片缩略图（媒体文件迁移/恢复后用）。

invoke int.clean-settings ——清理设置表中的过期项（update 收尾步骤同款）：

invoke int.clean-settings

Cleaning old settings from the database...
INVE-W3: Could not detect git information.
Settings cleaned successfully

invoke int.showmigrations ——迁移状态总览（等价 manage.py showmigrations，见 4.2 节）。

3.8 dev. 开发任务与长驻进程

dev.* 命名空间面向开发环境：dev.server（Django 内置开发服务器）、dev.test（单元测试）、dev.shell（Django shell）、dev.schema（导出 API schema）、dev.delete-data（清空全部数据，仅在开发库使用）等，生产环境不涉及，此处仅列清单（见 2.2 节）不展开。

生产形态的两个长驻进程：

invoke worker ——后台任务工作进程（django-q2），官方部署形态即以它作为 worker 的启动命令；前台运行，Ctrl+C 退出。
Web 服务进程：1.6.1 生产形态由 gunicorn 直接承载（dev.gunicorn 为开发调试用），日常运维不需要手动拉起，重启交给进程管理器（部署篇第十章）。

四、python manage.py 常用子命令

以下命令统一在 src/backend/InvenTree/ 目录执行（回显中的 INVE-W3/116 objects 横幅见 2.3 节说明）。

4.1 check（诊断）

python manage.py check

INVE-W3: Could not detect git information.
System check identified no issues (0 silenced).

升级后、改配置后的第一顺位自检命令。

4.2 showmigrations（迁移状态）

python manage.py showmigrations | tail -8

INVE-W3: Could not detect git information.
 [X] 0006_rename_taggeditem_content_type_object_id_taggit_tagg_content_8fc721_idx
users
 [X] 0001_squashed_0015_alter_userprofile_type (15 squashed migrations)
 [X] 0016_remove_legacy_user_sessions_table
 [X] 0017_apitoken_hmac_digest_apitoken_issued_by_and_more
 [X] 0018_tippresult
usersessions
 [X] 0001_initial

全部 [X] 表示迁移已应用。users 应用的 0001_squashed_0015_… (15 squashed migrations) 正是 1.6.0 的迁移压缩成果（官方 CHANGELOG #12830，见《InvenTree 1.6.1 介绍与选型指南》）。排查「是否还有未应用迁移」用 showmigrations | grep '\[ \]'（无输出即干净）。

4.3 makemigrations（生成迁移——注意 1.5 起行为变化）

python manage.py makemigrations

INVE-W3: Could not detect git information.
No changes detected

生产实例无插件改动时即 No changes detected。⚠️ 与 invoke 层的对应规则一致：1.5.0 起 invoke migrate 默认不生成迁移，makemigrations 仅在代码层（含插件的 models 变更）需要落迁移时使用。

4.4 createsuperuser（非交互建号）

DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 python manage.py createsuperuser --noinput --username testadmin --email testadmin@localhost

INVE-W3: Could not detect git information.
Superuser created successfully.

--noinput + DJANGO_SUPERUSER_PASSWORD 环境变量实现免交互建号（密码经环境变量传入，不留命令历史）。验证与清理（ORM 实操）：

python manage.py shell -c "from django.contrib.auth import get_user_model; print(list(get_user_model().objects.values_list('username', 'is_superuser')))"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

[('admin', True), ('testadmin', True)]

python manage.py shell -c "from django.contrib.auth import get_user_model; get_user_model().objects.filter(username='testadmin').delete(); print('testadmin deleted')"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

testadmin deleted

4.5 collectstatic（静态文件）

python manage.py collectstatic --noinput | tail -3

INVE-W3: Could not detect git information.

0 static files copied to '/home/inventree/data/static', 697 unmodified, 1301 post-processed.

（invoke static 是它的封装加前置检查；路径即配置篇 static_root 的运行时落点。）

4.6 shell（ORM 操作入口）

python manage.py shell -c "from django.conf import settings; print(settings.TIME_ZONE)"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

UTC

shell -c 适合脚本化查询；交互式 REPL 直接 python manage.py shell（或 invoke dev.shell）。配置项层面的批量核验示例见《InvenTree 1.6.1 配置参数详解》 3.5 节。

4.7 其他常用子命令速查

命令	用途	备注
`manage.py migrate`	应用数据库迁移	invoke migrate 已封装加后续步骤
`manage.py dbshell`	进入数据库命令行（psql/mysql/sqlite3）	需数据库客户端可用
`manage.py wait_for_db`	等待数据库就绪	invoke wait 的底层
`manage.py qmonitor`	django-q2 队列监控	invoke monitor 的底层
`manage.py check`	系统诊断	4.1 节实测
`manage.py help`	列出全部子命令	按应用分组

五、组合运用：三条高频工作流

5.1 例行升级（官方推荐路径）

invoke update

update 自带「先备份再迁移」，一次完成依赖安装、插件安装、备份、迁移、静态文件、设置清理六个环节（回显见 3.3 节）；升级后用 invoke server-health 与 manage.py check 验活。部署形态下的版本升级流程（改版本标签→拉新→重建）见部署篇第十章。

5.2 定期备份

invoke backup && invoke listbackups

备份集（库 + 媒体两个压缩文件）落在 backup 目录，配合外部定时器做异地轮转；恢复演练用 invoke restore（先停服务）。

5.3 跨库/跨实例搬迁

invoke export-records --filename /tmp/inventree-export.zip   # 旧实例导出
invoke import-records --filename /tmp/inventree-export.zip   # 新实例导入
invoke int.rebuild-models                                    # 导入后重建树结构

数据库引擎切换（如 SQLite→PostgreSQL）走「导出记录 → 新库迁移（invoke migrate）→ 导入记录」链路，import-records 默认导入后重建树结构与缩略图。

六、常见问题

6.1 任务名报 `No idea what 'xxx' is!`

1.6.1 的 invoke 任务是连字符命名且 int./dev. 前缀必带：rebuild_models → int.rebuild-models、clean_settings → int.clean-settings、showmigrations → int.showmigrations（本实例实测复现了报错原文）。不确定名字时先 invoke --list。

6.2 worker-health 在 server 侧执行失败

invoke worker-health 读取的是工作进程写出的心跳文件（/tmp/inventree_worker_heartbeat），必须在 worker 进程运行环境中执行；在 Web 服务进程环境执行得到 Heartbeat file not found 失败回显（3.2 节实测）。

6.3 每条命令前的 INVE-W3 是报错吗

不是。INVE-W3: Could not detect git information. 只表示源码目录没有 git 仓库元数据（包化安装的常态），不影响任何功能；带 git 元数据的裸机源码安装不会出现。

6.4 superuser 想免交互创建

invoke superuser 固定交互式（1.6.1 源码 manage_interactive('createsuperuser') 实读）。免交互走 manage.py createsuperuser --noinput + DJANGO_SUPERUSER_PASSWORD（4.4 节实测）；首启自动建号走配置项 INVENTREE_ADMIN_*（部署篇 4.2 节）。

6.5 update 输出里有 WARNING: Running pip as the 'root' user

这是 pip 对 root 身份运行的标准提醒，官方安装包默认以 root 执行安装步骤，属预期行为非故障；生产裸机安装建议用专用系统用户（官方文档安装器已处理）。

七、参考链接

官方 invoke 文档：https://docs.inventree.org/en/latest/start/invoke/
tasks.py（1.6.1 tag）：https://github.com/inventree/InvenTree/blob/1.6.1/tasks.py
官方升级文档：https://docs.inventree.org/en/latest/upgrade/
Django 管理命令参考：https://docs.djangoproject.com/en/5.2/ref/django-admin/
站内关联：《InvenTree 1.6.1 Docker Compose 部署指南》、《InvenTree 1.6.1 配置参数详解》

InvenTree 1.6.1 常用 CLI 命令详解

InvenTree 1.6.1 常用 CLI 命令详解

一、环境信息

二、CLI 体系总览

2.1 两个入口的分工

2.2 任务清单（实测 invoke --list）

2.3 执行环境说明

三、invoke 任务详解

3.1 版本与环境信息

3.2 健康检查三件套

3.3 安装与更新

3.4 备份与恢复

3.5 数据导出与导入

3.6 用户与安全

3.7 int. 内部维护任务（1.6.1 新命名空间）

3.8 dev. 开发任务与长驻进程

四、python manage.py 常用子命令

4.1 check（诊断）

4.2 showmigrations（迁移状态）

4.3 makemigrations（生成迁移——注意 1.5 起行为变化）

4.4 createsuperuser（非交互建号）

4.5 collectstatic（静态文件）

4.6 shell（ORM 操作入口）

4.7 其他常用子命令速查

五、组合运用：三条高频工作流

5.1 例行升级（官方推荐路径）

5.2 定期备份

5.3 跨库/跨实例搬迁

六、常见问题

6.1 任务名报 No idea what 'xxx' is!

6.2 worker-health 在 server 侧执行失败

6.3 每条命令前的 INVE-W3 是报错吗

6.4 superuser 想免交互创建

6.5 update 输出里有 WARNING: Running pip as the 'root' user

七、参考链接

2.2 任务清单（实测 `invoke --list`）

6.1 任务名报 `No idea what 'xxx' is!`