Netbox 4.7 常用 CLI 命令与工具详解

Netbox 4.7.3 命令行运维全集：manage.py 全套管理命令（nbshell/migrate/rqworker/dumpdata 等）实测回显、systemd 与 journalctl 服务排查、pg_dump 备份升级流程，含 housekeeping 移除等实测发现。

NetboxNetboxDCIM2026/10/22

Netbox 4.7 常用 CLI 命令与工具详解

目标：把 Netbox 4.7.3 日常运维要用到的全部命令行工具一次讲透——manage.py 全套管理命令（nbshell、migrate、rqworker、dumpdata 等）、systemd 服务管理、日志排查与数据库备份升级实操。全部命令与回显均在 Ubuntu 24.04.5 LTS + Netbox 4.7.3（Django 6.1.2 / Python 3.12.3）环境实测逐条采集；参数默认值以 manage.py help <子命令> 实测输出为准。

一、环境信息

  • 操作系统：Ubuntu 24.04.5 LTS（x86_64）
  • Netbox：v4.7.3（Django 6.1.2 / Python 3.12.3 / gunicorn 26.2.0 / django-rq 4.2.0 / RQ 2.12.0）
  • 部署形态：官方 Release Archive + venv（/opt/netbox-4.7.3/，软链 /opt/netbox）+ gunicorn/systemd + nginx，安装过程见本系列《Ubuntu 24.04 安装 Netbox 4.7 指南》
  • systemd 单元：netbox.service（Web WSGI）、netbox-rq.service（后台队列 worker）、postgresql、redis-server、nginx
  • 演示账号：admin / q1w2e3r4（超级用户）
  • venv 路径：/opt/netbox/venv/；manage.py 路径：/opt/netbox/netbox/manage.py

二、工具概览

Netbox 的 CLI 体系分三层：manage.py 管理命令（应用层，跑在 venv 里）、systemd/journalctl（进程与日志层）、PostgreSQL/Redis 客户端（数据层）。python3 manage.py help 的完整子命令清单实测如下（v4.7.3 全量，按所属 app 分组）：

[auth]
    changepassword
    createsuperuser

[contenttypes]
    remove_stale_contenttypes

[core]
    makemigrations
    nbshell
    rqworker
    syncdatasource
    upgrade

[dcim]
    buildschema
    trace_paths

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    migrate
    optimizemigration
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver

[django_rq]
    rqcron
    rqenqueue
    rqresume
    rqscheduler
    rqstats
    rqsuspend
    rqworker-pool

[drf_spectacular]
    spectacular

[extras]
    populate_image_sizes
    rebuild_config_context_cache
    reindex
    renaturalize
    runscript
    webhook_receiver

[ipam]
    rebuild_prefixes

[rest_framework]
    generateschema

[sessions]
    clearsessions

[social_django]
    clearsocial

[staticfiles]
    collectstatic
    findstatic
    runserver

[strawberry_django]
    export_schema

[taggit]
    deduplicate_tags
    remove_orphaned_tags

[thumbnail]
    thumbnail

[utilities]
    calculate_cached_counts
    rebuild_ltree_paths

💡 技术拓展：manage.py 是 Django 的管理入口（django.core.management），所以 [django] 组的子命令对一切 Django 项目通用；[core]/[dcim]/[extras]/[ipam] 等组才是 Netbox 自有命令。shell 与 nbshell 的区别：shell 是裸 Django shell（需自己 import 模型），nbshell 预导入全部 Netbox 模型并提供 lsapps()/lsmodels() 帮助函数——日常运维一律用 nbshell。

命令运行的标准前置（每次都要）：

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py <命令>

三、前置条件

  1. 已按安装指南完成部署，两个 systemd 服务运行中（否则部分命令如 rqstats 拿不到 worker 数据）：
systemctl is-active netbox netbox-rq

active
active
  1. venv 已就绪且 migrate 已执行（本文所有命令实测库内迁移记录 812 条）；
  2. 交互式命令（nbshell/dbshell/changepassword）在 SSH 终端运行；脚本/CI 场景注意第四章标注的非交互限制。

四、manage.py 核心管理命令详解

4.1 nbshell：Netbox 专用交互式 Shell

nbshell 预导入全部 Netbox 模型，是排查数据、批量修正、做小实验的首选工具。实测启动横幅与建删对象：

echo "from dcim.models import Site
Site.objects.all().delete()
print('sites after delete:', Site.objects.count())
s, created = Site.objects.get_or_create(name='dc-01', defaults={'slug': 'dc-01', 'status': 'active'})
print('created:', created, '| site:', s.name, s.slug, '| status:', s.status)
print('total sites:', Site.objects.count())
exit" | python3 manage.py nbshell

实测回显（首建场景）：

### NetBox interactive shell (netbox-server)
### Python v3.12.3 | Django v6.1.2 | NetBox Community v4.7.3
### lsapps() & lsmodels() will show available models. Use help(<model>) for more info.
>>> >>> (1, {'dcim.Site': 1})
>>> sites after delete: 0
>>> >>> created: True | site: dc-01 dc-01 | status: active
>>> total sites: 1
>>> Use exit() or Ctrl-D (i.e. EOF) to exit
>>>
now exiting InteractiveConsole...

要点：

  • 横幅即"自检"：确认实例名（netbox-server）、Python/Django/Netbox 三层版本；
  • Site.objects.all().delete() 返回 (1, {'dcim.Site': 1})——删除对象时 Django 同步报告各模型删除数量，删站点会级联带出设备等（本例库内仅此一个站点）；
  • lsapps() 列出全部已装 app，实测：
circuits - Circuits
core - Core
dcim - DCIM
extras - Extras
ipam - IPAM
tenancy - Tenancy
users - Users
virtualization - Virtualization
vpn - VPN

⚠️ 排障实录：在管道/脚本里给 nbshell 喂多行 Python 时，try/except、for 等块语句结束后必须补一个空行，否则报 runsource/compile 类语法错误——交互式控制台靠空行判断块结束。脚本场景更推荐把逻辑写成 manage.py shell -c "<单行>" 或自定义脚本文件。

4.2 createsuperuser / changepassword：账号管理

创建超级用户——交互终端直接运行，按提示输入用户名/邮箱/密码即可。非交互（脚本/CI）必须加 --noinput 并用环境变量传密码：

DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 python3 manage.py createsuperuser --noinput --username admin --email admin@example.com

实测回显：

Superuser created successfully.

⚠️ 非交互环境漏掉 --noinput 会得到 Superuser creation skipped due to not running in a TTY.（实测报错原文）——Django 的 TTY 保护，不是故障。

修改密码——changepassword 需输两遍；管道喂入时 Django 会警告密码回显（仅测试环境可接受）：

printf "q1w2e3r4\nq1w2e3r4\n" | python3 manage.py changepassword testop

实测回显：

/usr/lib/python3.12/getpass.py:91: GetPassWarning: Can not control echo on the terminal.
  passwd = fallback_getpass(prompt, stream)
Warning: Password input may be echoed.
Password:
Warning: Password input may be echoed.
Password (again):
Changing password for user 'testop'
Password changed successfully for user 'testop'

4.3 migrate / showmigrations：数据库模式管理

showmigrations 查看迁移应用状态（[X] 已应用），实测尾部：

 [X] 0020_alter_wirelesslan__region_and_more
 [X] 0021_ltree_paths
 [X] 0022_denormalization_triggers
 [X] 0023_wirelesslangroup_drop_unique_constraint
 [X] 0024_fix_ltree_cascade_triggers

migrate --check 校验"是否有未应用迁移"，有未应用迁移时退出码非 0——监控/升级前置检查的标准用法：

python3 manage.py migrate --check
echo "rc=$?"

实测回显：

rc=0

migrate 正式应用迁移（升级后由 upgrade.sh 自动调用）；手动执行形式：

python3 manage.py migrate

新装/升级时典型输出（实测节选）：

  Applying ipam.0001_squashed... OK
  Applying virtualization.0001_squashed_0022... OK
  Applying extras.0002_squashed_0059...

💡 说明：跨版本升级永远走官方 upgrade.sh（见 5.4 节），它会按依赖顺序执行 migrate + trace_paths + clearsessions + collectstatic，不要单独裸跑 migrate 跳过其他步骤。

4.4 dbshell：直连 PostgreSQL

dbshell 按 DATABASES 配置自动连库（等效 psql，无需手动带密码）。实测看表清单与迁移记录数：

echo "\dt" | python3 manage.py dbshell 2>&1 | head -8

实测回显：

                         List of relations
 Schema |                  Name                   | Type  | Owner
--------+-----------------------------------------+-------+--------
 public | auth_group                              | table | netbox
 public | auth_group_permissions                  | table | netbox
 public | auth_permission                         | table | netbox
 public | circuits_circuit                        | table | netbox
 public | circuits_circuitgroup                   | table | netbox

echo "SELECT count(*) FROM django_migrations;" | python3 manage.py dbshell

实测回显：

 count
-------
   812
(1 row)

4.5 dumpdata：数据导出（JSON）

按 app 或模型导出 JSON，用于小规模数据迁移、备份抽查、跨实例对照：

python3 manage.py dumpdata dcim.Site --indent 2 | head -22

实测回显：

[
{
  "model": "dcim.site",
  "pk": 4,
  "fields": {
    "created": "2026-10-22T11:00:42.690Z",
    "last_updated": "2026-10-22T11:00:42.690Z",
    "custom_field_data": {},
    "owner": null,
    "description": "",
    "comments": "",
    "name": "dc-01",
    "slug": "dc-01",
    "status": "active",
    "region": null,
    "group": null,
    "tenant": null,
    "facility": "",
    "time_zone": null,
    "physical_address": "",
    "shipping_address": "",
    "latitude": null,
    "longitude": null,
    "asns": []

💡 说明：dumpdata 适合业务数据的轻量导出；全库备份用 pg_dump（见 5.3 节），前者不含迁移状态与序列信息，后者才是完整恢复单元。

4.6 check / diffsettings：配置体检

check 校验配置合法性与系统完整性，改 configuration.py 后必跑：

python3 manage.py check

实测回显：

System check identified no issues (0 silenced).

diffsettings 对比 Django 默认列出全部生效配置（### 标记差异行），核对配置是否真正生效：

python3 manage.py diffsettings | head -8

实测回显（节选）：

ALLOWED_HOSTS = ['*']
API_TOKEN_PEPPERS = {1: 'UwJKwgp%SpYB+&s8RXB4_#BE7Sa@fftR%WafsYAFc2w_GSWbmq'}  ###
AUTHENTICATION_BACKENDS = ['netbox.authentication.RemoteUserBackend', 'netbox.authentication.ObjectPermissionBackend']
AUTH_USER_MODEL = 'users.User'
BASE_DIR = '/opt/netbox-4.7.3/netbox'  ###
BASE_PATH = ''  ###
BULK_UPDATE_CHUNK_SIZE = 5000  ###
CACHES = {'default': {'BACKEND': 'django_redis.cache.RedisCache', 'LOCATION': 'redis://localhost:6379/1', 'OPTIONS': {'CLIENT_CLASS': 'django_redis.client.DefaultClient', 'USERNAME': '', 'PASSWORD': ''}}}

参数含义的逐项解读见本系列《Netbox 4.7 配置参数详解》第三章。

4.7 rqworker / rqstats：后台任务队列族

Netbox 的 Webhook、报表、自定义脚本、批量操作都走 RQ 队列（Redis 队列），由 netbox-rq 服务常驻消费。手动调试用的核心命令：

rqstats 队列全景（实测）：

python3 manage.py rqstats


Django RQ CLI Dashboard

------------------------------------------------------------------------------------------
| Name           |    Queued |    Active |  Deferred |  Finished |    Failed |   Workers |
------------------------------------------------------------------------------------------
| default        |         0 |         0 |         0 |         2 |         0 |         1 |
| high           |         0 |         0 |         0 |         0 |         0 |         1 |
| low            |         0 |         0 |         0 |         0 |         0 |         1 |
------------------------------------------------------------------------------------------

三队列（high/default/low）与 systemd 里 worker 的消费顺序一致。

rqworker 手动启动 worker（参数实测自 manage.py help rqworker）：

timeout 8 python3 manage.py rqworker high default low

实测回显（8 秒后外部超时，worker 优雅退出）：

11:05:23 Worker c27802443dc74af9a68d09e4292933c4: started with PID 5126, version 2.12.0
11:05:23 Worker c27802443dc74af9a68d09e4292933c4: subscribing to channel rq:pubsub:c27802443dc74af9a68d09e4292933c4
11:05:23 *** Listening on high, default, low...
11:05:23 Worker c27802443dc74af9a68d09e4292933c4: cleaning registries for queue: high
11:05:23 Worker c27802443dc74af9a68d09e4292933c4: cleaning registries for queue: default
11:05:23 Worker c27802443dc74af9a68d09e4292933c4: cleaning registries for queue: low
11:05:28 Worker c27802443dc74af9a68d09e4292933c4 [PID 5126]: warm shut down requested
11:05:28 Worker c27802443dc74af9a68d09e4292933c4: unsubscribing from channel rq:pubsub:c27802443dc74af9a68d09e4292933c4

关键参数（manage.py help rqworker 实测节选）：

usage: manage.py rqworker [-h] [--worker-class WORKER_CLASS] [--pid PID]
                          [--burst] [--with-scheduler] [--name NAME]
                          [--queue-class QUEUE_CLASS] [--job-class JOB_CLASS]
                          [--worker-ttl WORKER_TTL] [--max-jobs MAX_JOBS]
                          [--max-idle-time MAX_IDLE_TIME]
                          [--serializer SERIALIZER] [--version] [-v {0,1,2,3}]
                          ...
  args                  The queues to work on, separated by space
  --burst               Run worker in burst mode
  • args：要消费的队列名，空格分隔（与 netbox-rq.service 的 rqworker high default low 一致）；
  • --burst：清空现有积压后退出，积压治理利器（systemd 常驻之外临时开一个跑积压）。

同族命令速查：rqsuspend/rqresume（暂停/恢复队列处理，升级窗口用）、rqenqueue（手动投递任务）、rqworker-pool（多进程池 worker）、rqcron（注册周期任务）、rqscheduler（调度器）。

⚠️ 排障实录：rqstats 显示 Workers=0 而页面后台任务一直排队 → systemctl status netbox-rq 看服务是否 active；若频繁重启，journalctl -eu netbox-rq 查 worker 崩溃原因（常见为 Redis 密码不匹配或 tasks 库被误 flush）。

4.8 trace_paths / clearsessions：数据一致性维护对

这组命令由官方 upgrade.sh 在每次升级时自动执行（脚本原文实测：COMMAND="python3 netbox/manage.py trace_paths --no-input" 与 COMMAND="python3 netbox/manage.py clearsessions"），也可手动跑：

trace_paths 检查并补全线缆/电源路径的缓存（实测空库场景）：

python3 manage.py trace_paths --no-input

实测回显：

Found no missing power feed paths; skipping
Found no missing power outlet paths; skipping
Found no missing power port paths; skipping
Finished.

clearsessions 清理过期会话（幂等，可进 cron）：

python3 manage.py clearsessions
echo "rc=$?"

实测回显：

rc=0

4.9 collectstatic：静态资源收集

upgrade.sh 已自动执行；重复执行是幂等的（对照实测）：

python3 manage.py collectstatic --noinput

实测回显（第二次运行）：

0 static files copied to '/opt/netbox-4.7.3/netbox/static', 543 unmodified.

4.10 housekeeping 命令已移除

老版本（v4.2 之前）资料里常见的 manage.py housekeeping 在 v4.7.3 实测已不存在：

python3 manage.py housekeeping

实测回显：

Unknown command: 'housekeeping'
Type 'manage.py help' for usage.

其历史职责已被拆分承接：过期会话清理并入 clearsessions（upgrade.sh 每次升级都会调用，实测脚本原文 Removing expired user sessions (python3 netbox/manage.py clearsessions)...），周期性后台任务由 [django_rq] 组的 rqcron/rqscheduler 体系接管。旧文档遇到 housekeeping 一律按此映射替换。

五、服务器运维命令

5.1 systemd 服务管理

Netbox 生产形态共 5 个服务单元，逐个管理（每个单元单独一条命令）：

systemctl is-active netbox netbox-rq
systemctl is-enabled netbox netbox-rq
systemctl status netbox

systemctl status netbox 实测回显：

● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-22 10:29:49 UTC; 6s ago
       Docs: https://docs.netbox.dev/
   Main PID: 7133 (gunicorn)
      Tasks: 6 (limit: 94371)
     Memory: 1.0G (peak: 1.0G)
        CPU: 19.058s
     CGroup: /system.slice/netbox.service
             ├─7133 /opt/netbox-4.7.3/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ├─7136 /opt/netbox-4.7.3/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ├─7137 /opt/netbox-4.7.3/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ├─7138 /opt/netbox-4.7.3/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ├─7139 /opt/netbox-4.7.3/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi

常用节奏：改配置后 systemctl restart netbox netbox-rq；只改 nginx 后 systemctl reload nginx；确认自启 systemctl is-enabled <单元>。

5.2 journalctl 日志排查

Web 服务日志（gunicorn 输出经 systemd 收集）：

journalctl -u netbox -n 6 --no-pager

实测回显（含两个真实故障样本）：

Oct 22 10:32:01 netbox-server gunicorn[82]: [2026-10-22 10:32:01 +0000] [82] [ERROR] Control server error: [Errno 13] Permission denied: '/nonexistent'
Oct 22 10:52:22 netbox-server gunicorn[82]: [2026-10-22 10:52:22 +0000] [82] [CRITICAL] WORKER TIMEOUT (pid:201)
Oct 22 10:52:22 netbox-server gunicorn[82]: [2026-10-22 10:52:22 +0000] [201] [INFO] Worker exiting (pid: 201)
Oct 22 10:52:25 netbox-server gunicorn[82]: [2026-10-22 10:52:25 +0000] [82] [ERROR] Worker (pid:201) exited with code 1.
Oct 22 10:52:25 netbox-server gunicorn[1549]: [2026-10-22 10:52:25 +0000] [1549] [INFO] Booting worker with pid: 1549
Oct 22 10:52:25 netbox-server gunicorn[82]: [2026-10-22 10:52:25 +0000] [82] [ERROR] Control server error: [Errno 13] Permission denied: '/nonexistent'
  • WORKER TIMEOUT (pid:201) → Worker exiting → Booting worker：某请求超过 gunicorn timeout=120 被强杀并自动重生，gunicorn 自愈但该请求失败；处置见安装指南 FAQ Q5；
  • Permission denied: '/nonexistent'：systemd 用户无家目录导致的控制服务器噪音报错，不影响服务，消除方式见安装指南 FAQ Q6。

队列 worker 日志：journalctl -u netbox-rq -n 20 --no-pager；配置合法性错误会在启动瞬间出现 Python 堆栈，journalctl -eu netbox 直接看最后一条。

5.3 PostgreSQL 备份与恢复

全库逻辑备份（含全部表结构、数据与迁移状态）：

sudo -u postgres pg_dump netbox > /var/backups/netbox-$(date +%F).sql
ls -lh /var/backups/netbox-*.sql | tail -1

实测回显（本实例刚完成初始化、仅少量演示数据时的体积供参考）：

-rw-r--r-- 1 root root 944K Oct 22 11:17 /var/backups/netbox-2026-10-22.sql

备份文件头实测：

--
-- PostgreSQL database dump
--

规模参考：空库即含 208 张表（grep -c '^CREATE TABLE' 实测），随资产数据增长备份体积近似线性增长，建议生产环境每日 cron + 保留 7~30 天。

恢复（先建空库再灌入）：

sudo -u postgres psql -c 'CREATE DATABASE netbox_restore OWNER netbox;'
sudo -u postgres psql -d netbox_restore -f /var/backups/netbox-2026-10-22.sql

⚠️ 注意：恢复目标是空库；官方升级文档特别提醒不要把备份恢复到已初始化的新版本库上（v4.7.1 曾修复"从 v4.7.0 dump 恢复导致层级路径触发器缺失"的问题，见官方 release notes）。

5.4 升级流程：upgrade.sh

官方升级三步（以小版本升级为例）：

cd /opt
wget https://github.com/netbox-community/netbox/archive/refs/tags/v4.7.4.tar.gz
tar -xzf v4.7.4.tar.gz
ln -sfn /opt/netbox-4.7.4/ /opt/netbox
/opt/netbox/upgrade.sh

upgrade.sh 依次自动完成：venv 依赖更新（pip）→ manage.py migrate → trace_paths --no-input → clearsessions → 离线文档构建 → collectstatic。实测尾部输出（升级后必看）：

WARNING: No existing virtual environment was detected. A new one has
been created. Update your systemd service files to reflect the new
Python and gunicorn executables. (If this is a new installation,
this warning can be ignored.)

netbox.service ExecStart:
  /opt/netbox-4.7.3/venv/bin/gunicorn

netbox-rq.service ExecStart:
  /opt/netbox-4.7.3/venv/bin/python

After modifying these files, reload the systemctl daemon:
  > systemctl daemon-reload
--------------------------------------------------------------------
Upgrade complete! Don't forget to restart the NetBox services:
  > sudo systemctl restart netbox netbox-rq

升级完成后重启服务并复核版本：

systemctl restart netbox netbox-rq
curl -sk https://127.0.0.1/api/status/ | python3 -m json.tool | grep netbox-version

实测回显：

    "netbox-version": "4.7.3",

💡 说明：/api/status/ 是免认证端点，返回 netbox-version / python-version / django-version / rq-workers-running 等运行时事实（实测 rq-workers-running: 2），是升级后健康检查的第一站。

六、注意事项

  1. manage.py 必须在 venv 里跑：source /opt/netbox/venv/bin/activate 后再执行，否则要么找不到依赖、要么把包装进系统 Python 污染环境；
  2. 改配置 = 改文件 + check + 重启双服务，漏掉重启是"配置不生效"的第一大原因（详见《Netbox 4.7 配置参数详解》第三章）；
  3. 不要用 runserver 对外服务：manage.py runserver 仅限开发调试（官方明确 Not for production use），生产一律 gunicorn + systemd；
  4. 跨版本升级只走 upgrade.sh：手动裸跑 migrate 会漏掉静态资源、路径缓存与会话清理；
  5. dumpdata/pg_dump 分工：业务数据抽查/搬迁用 dumpdata，整机备份恢复用 pg_dump；
  6. rqworker 手动调试记得退出：--burst 模式清完积压自动退出；前台调试用 timeout N 包裹，避免占用队列 worker 名额。

七、常见问题（FAQ）

Q1：manage.py 报 ModuleNotFoundError 或 command not found: python3 之外的奇怪依赖错误 没进 venv。先 source /opt/netbox/venv/bin/activate && cd /opt/netbox/netbox。

Q2：createsuperuser 提示 skipped due to not running in a TTY 见 4.2 节：非交互环境用 DJANGO_SUPERUSER_PASSWORD=<密码> createsuperuser --noinput --username <u> --email <e>。

Q3：changepassword 报 GetPassWarning 且密码明文回显 管道喂密码的正常现象（终端无法关闭回显），仅限受控环境使用；交互 SSH 下运行则无此警告。

Q4：页面后台任务一直"排队"不执行 python3 manage.py rqstats 看 Workers 列：0 说明 netbox-rq 服务死了 → systemctl status netbox-rq + journalctl -eu netbox-rq；有 worker 但 Queued 持续增长 → 看 Failed 列与 worker 日志中的任务异常堆栈。

Q5：housekeeping 报 Unknown command v4.7.3 已移除该命令（4.10 节实测），改用 clearsessions + rqcron 体系。

Q6：journalctl 里出现 WORKER TIMEOUT gunicorn 超时强杀慢请求（默认 120 秒），worker 自动重生。排查慢请求来源（报表/批量导出），必要时调大 /opt/netbox/gunicorn.py 的 timeout 后 systemctl restart netbox。

Q7：migrate --check 在监控里告警 说明有未应用的迁移——多半是升级时没跑 upgrade.sh 或跑了一半。补跑 /opt/netbox/upgrade.sh（幂等）后恢复 rc=0。

Q8：dbshell 提示对等连接失败/认证失败 dbshell 读 configuration.py 的 DATABASES；报错时先核对 python3 manage.py diffsettings | grep ^DATABASES 与 2.2 节建库信息一致（用户名/密码/主机）。

八、参考链接

本系列其他文档：《Ubuntu 24.04 安装 Netbox 4.7 指南》（部署实测）、《Netbox 4.7 配置参数详解》（参数手册）、《Netbox 介绍与选型指南》（认知与选型）。