Inboxen 2026.2.22.0.27.49 常用 CLI 命令与工具详解

目标：把 Inboxen 2026.2.22.0.27.49 日常运维要用的命令行工具一次讲全——inboxen 命令族（含 4 个项目专属命令）、账号/数据库/静态资源管理命令、Salmon 与 Celery 两个常驻进程的 CLI、以及日志排障手段。本文全部命令与输出均在《Debian 12 安装 Inboxen 2026.2.22.0.27.49 指南》的实测环境执行取得，逐行照录。

一、环境信息

项目	值
操作系统	Debian GNU/Linux 12.15 (bookworm)
Inboxen 版本	2026.2.22.0.27.49（pip 包安装，venv 位于 `/opt/inboxen/env`，命令为 `/opt/inboxen/env/bin/inboxen`）
Python	3.12.12
应用目录	`/opt/inboxen/app`（工作目录，`inboxen.config` 所在处）
常驻进程	Celery worker + beat、Salmon（PID 21618）、Gunicorn
收信域名	inboxen.lan（另有实验中创建的 second.lan）
管理员账号	admin / q1w2e3r4
实测日期	2026-10-26

以下命令均在 /opt/inboxen/app 目录执行（pip 包形态下配置与数据路径都相对工作目录解析）。为简洁，下文用 inboxen 指代 /opt/inboxen/env/bin/inboxen、salmon 指代 /opt/inboxen/env/bin/salmon、celery 指代 /opt/inboxen/env/bin/celery。

二、CLI 入口与命令总览

pip 包安装后 venv 里自带 inboxen 入口命令，它是 Django manage.py 的等价物，聚合了 Django 全部管理命令与 Inboxen 项目专属命令。inboxen help 输出（实测逐行照录）：

Type 'inboxen help <subcommand>' for help on a specific subcommand.

Available subcommands:

[auth]
    changepassword
    createsuperuser

[contenttypes]
    remove_stale_contenttypes

[debug_toolbar]
    debugsqlshell

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

[inboxen]
    createdomain
    disowned
    feeder
    url_stats

[otp_static]
    addstatictoken

[sessions]
    clearsessions

[staticfiles]
    collectstatic
    findstatic
    runserver

[two_factor]
    two_factor_disable
    two_factor_status

日常运维最常用的是 [inboxen] 组 4 个专属命令与 [django]/[auth]/[staticfiles]/[sessions] 组里的少数几个。所有子命令共享一组通用参数（以 feeder --help 实测输出为样例）：

options:
  -h, --help            show this help message and exit
  --inbox INBOX
  --version             Show program's version number and exit.
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Display a full stack trace on CommandError exceptions.
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

💡 说明：每个管理命令执行前都会先跑一遍 system check，因此输出里常带一条 caches.W003 告警（缓存路径写相对路径所致，配置详解篇已给消除方法），不影响命令执行。

三、[inboxen] 组：四个项目专属命令

3.1 createdomain：登记收信域名

收件箱地址的 @ 后缀必须先登记。用法 inboxen createdomain <域名>，实测：

$ inboxen createdomain second.lan
second.lan created!

重复创建同一域名报错退出（实测 EXIT=1）：

$ inboxen createdomain second.lan
CommandError: Domain already exists.

⚠️ 域名登记只是数据库记录，收信链路还要 Postfix 侧同步放行（relay_domains + transport_maps，见配置详解篇第十节）。

3.2 disowned：列出无主收件箱（公网收信校验表）

disowned 输出「没有归属用户」的收件箱地址，官方帮助原文即注明用途："For use with Internet facing mail servers"。实测（环境里有一个无主收件箱 sydgue@inboxen.lan）：

$ inboxen disowned
sydgue@inboxen.lan

--postfix 参数把输出格式化为 Postfix 可直接使用的「拒绝应答」表，实测（cat -A 展示制表符与行尾）：

$ inboxen disowned --postfix | cat -A
sydgue@inboxen.lan^I501 5.1.1 Address no longer in use$

即每行 地址<TAB>501 5.1.1 Address no longer in use。配合 Postfix 的 check_recipient_access 把这张表投进收信流程，无主地址在 SMTP 会话阶段就被 501 拒收，不再进入 Salmon——公网实例控制垃圾流量与数据库膨胀的利器。

3.3 feeder：把 mbox 存档导入系统

feeder <mbox路径> [--inbox 地址] 把一个 mbox 格式邮件存档经 SMTP 灌进 Inboxen（迁移历史邮件、灌测试数据的工具）。先准备两封信的 mbox，实测导入到 shiunb@inboxen.lan：

$ inboxen feeder /root/test.mbox --inbox shiunb@inboxen.lan
Done!

（进度条逐封刷新，此处节选末行。）导入前后落库计数实测对比：

BEFORE: EMAIL-TOTAL: 3
AFTER:  EMAIL-TOTAL: 5

--inbox 指定的地址必须是已存在且可收信的收件箱（内部走 Inbox.objects.from_string 校验，不存在报 CommandError: Inbox does not exist）；省略 --inbox 时按每封信的收件头路由。feeder --help 全文见第二节样例。

3.4 url_stats：Web 访问日志的 URL 命名统计

url_stats <文件|-> 读入一列 URL（- 为 stdin），统计命中的命名路由分布，用于分析访问日志里哪些功能被使用。实测：

$ printf "/inbox/shiunb@inboxen.lan/\n/user/account/login/\n/admin/inboxen/inbox/\n/not-a-real-page/\n" | inboxen url_stats -
URLs:
{'single-inbox': 1, 'user-login': 1}

Non-matches:
{'/not-a-real-page/', '/admin/inboxen/inbox/'}

命中项输出「命名路由名: 次数」；未匹配项（包括不存在页面与后台路由）进 Non-matches。官方帮助给出的用法是与 awk 管道配合：awk '{print $3}' /path/to/access.log | inboxen url_stats -。

四、账号与会话管理命令

4.1 createsuperuser：创建管理员

$ DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 inboxen createsuperuser --noinput --username admin --email admin@inboxen.lan
Superuser created successfully.

--noinput 非交互模式配合 DJANGO_SUPERUSER_PASSWORD 环境变量，可写成初始化脚本；重复执行对已存在用户名报错退出。

4.2 changepassword：改密码

交互式两次输入新密码（changepassword --help 实测头部）：

usage: inboxen changepassword [-h] [--database {default}] [--version]
                              [-v {0,1,2,3}] [--settings SETTINGS]
                              [--pythonpath PYTHONPATH] [--traceback]
                              [--no-color] [--force-color]
                              [username]

Change a user's password for django.contrib.auth.

忘记 admin 密码时的标准处置就是 inboxen changepassword admin。

4.3 two_factor_status / two_factor_disable：两步验证管理

Inboxen 登录流程内嵌两步验证向导。查某用户的 2FA 状态（实测）：

$ inboxen two_factor_status admin
admin: disabled

若用户开启 2FA 后丢失验证器被锁在门外，用 inboxen two_factor_disable admin 关闭后即可重新登录。

4.4 clearsessions：清理过期会话

$ inboxen clearsessions

（无正常输出；settings.py 的 beat 任务表已把它排进每日 02:12 的 sessions 任务自动执行，手动跑用于立即清理。）会话存储是 cached_db（数据库 + 缓存双层），会话表长期不清会缓慢膨胀。

五、数据库与静态资源命令

5.1 migrate：应用数据库迁移

首次初始化必跑，实测尾部回显：

  Applying otp_totp.0003_add_timestamps... OK
  Applying search.0001_initial_squashed... OK
  Applying sessions.0001_initial... OK
  Applying tickets.0001_initial_squashed... OK
  Applying two_factor.0001_squashed_0008_delete_phonedevice... OK

幂等：重复执行输出 No migrations to apply.。

5.2 showmigrations：核对迁移状态

$ inboxen showmigrations inboxen
inboxen
 [X] 0001_initial_squashed (36 squashed migrations)

[X] 表示已应用。Inboxen 的迁移已压成 squash 包，每个应用一行。

5.3 collectstatic：收集静态资源

$ inboxen collectstatic --noinput

26 static files copied to '/opt/inboxen/app/static_content'.
System check identified some issues:

WARNINGS:
?: (caches.W003) Your 'default' cache LOCATION path is relative. Use an absolute path instead.

⚠️ 版本差异提示：2026.2.22.0.27.49 的 pip 包自带编译好的静态资源，collectstatic 只是把包内资源复制到 static_root（实测 26 个文件）；但源码仓形态首启实测复制 57 个文件。无论哪种形态，/static/ 的 Nginx 根目录都要指向 static_root 解析出的绝对路径。

5.4 check：部署体检

$ inboxen check
System check identified some issues:

WARNINGS:
?: (caches.W003) Your 'default' cache LOCATION path is relative. Use an absolute path instead.

System check identified 1 issue (0 silenced).

升级版本或改配置后先跑 check，把 WARNING 清零再继续。

5.5 shell 与 dbshell：交互式工具箱

inboxen shell 是 Django ORM 交互环境，本文多篇的探针脚本都从它执行。两个高频用法实测：

$ inboxen shell
>>> from django.contrib.auth.models import User
>>> from inboxen.models import Inbox, Domain
>>> u = User.objects.get(username="admin")
>>> d = Domain.objects.get(domain="inboxen.lan")
>>> i = Inbox.objects.create(domain=d, user=u)
>>> print(i.inbox + "@" + d.domain)
shiunb@inboxen.lan

$ inboxen shell
>>> from inboxen.models import Email
>>> print("EMAIL-TOTAL:", Email.objects.count())
EMAIL-TOTAL: 3

inboxen dbshell 直接进入 psql 连接（走 database 配置段），用于无法用 ORM 表达的排查。dumpdata/loaddata 做 JSON 级数据导出导入，sendtestemail 可测试 Django 发信链路（--managers/--admins 发给配置里的管理员列表）。

💡 技术拓展：建收件箱必须走 Inbox.objects.create(domain=…, user=…) 这个 QuerySet 入口——它内部循环生成随机本地部份、补时间戳、落唯一性重试；直接构造模型实例 Inbox(user=…, domain=…) 会踩两个实测坑：created 列非空约束报错，或本地部份为空。随机名逻辑与保留字校验（abuse/postmaster 等 70 余个系统地址不可占用）都封装在管理器里。

六、常驻进程工具：salmon 与 celery

6.1 salmon：收信进程管理

Salmon 收信进程（inboxen.router）用自带 CLI 管理，需两个环境变量：

export DJANGO_SETTINGS_MODULE=inboxen.settings
export SALMON_SETTINGS_MODULE=inboxen.router.config.settings

启动、查状态、停止实测（启动后 sleep 5 再查）：

$ salmon start --pid run/router.pid --boot inboxen.router.config.boot
$ salmon status --pid run/router.pid
Salmon running with PID 21618
$ salmon stop --pid run/router.pid

stop 读 pid 文件发信号，配合 ps 确认进程退出。注意 salmon start 的 daemonize 行为在不同环境表现不完全一致（部署篇实测遇到过不返回的情况），编排进自启动脚本时建议放后台并显式核对 salmon status。

6.2 celery：任务进程管理

worker 与 beat 启动命令（B1 篇实测，-f 指定各自日志文件）：

celery -A inboxen worker -l warning --events -Ofair -f logs/celery-worker.log
celery -A inboxen beat -l warning -f logs/celery-beat.log

worker 在线状态实测：

$ celery -A inboxen status
->  celery@mail.inboxen.lan: OK

1 node online.

节点名为主机名。1 node online 是判断任务链路（收信落库依赖 worker）是否健康的最快手段；beat 无常驻连接，状态看 logs/celery-beat.log。

6.3 进程核对速查

ps -ef | grep -E 'celery|salmon|gunicorn' | grep -v grep

健康运行时应看到：celery worker 主进程 + 并发子进程、celery beat、salmon（读 run/router.pid 核对）、gunicorn 2 个 worker。

七、日志与排障工具

工具/文件	用途	实测要点
`/var/log/mail.log`	Postfix 收信日志	`maillog_file` 配置后直写；`grep <队列ID> /var/log/mail.log` 看投递全程，`status=sent (250 OK)` 为成功基准（实测样例 `8AC83124B50B … relay=::1[::1]:8823 … status=sent`）
`logs/salmon.log` / `salmon.err` / `salmon.out`	Salmon 收信管道日志	debug 模式下 salmon 日志级别为 DEBUG，路由异常可见；`run/undeliverable` 目录存放无法路由的信件
`logs/celery-worker.log` / `celery-beat.log`	任务进程日志	worker 日志为空且进程消失 = broker 连不上（Redis 传输包缺失的实测表现）
`logs/gunicorn-access.log` / `-error.log`	Web 请求日志	502/301 类问题先看这里再查 Nginx
`celery -A inboxen status`	worker 健康探测	`1 node online.` 为健康基准
`salmon status --pid run/router.pid`	收信进程探测	`Salmon running with PID …` 为健康基准
`inboxen check`	配置体检	WARNING 清零为准
curl + Cookie	Web 可见性验证	实测三步：GET 登录页取 `csrfmiddlewaretoken` → POST 带 `login_view-current_step=auth` 等四字段 → 带 Cookie 访问 `/inbox/<地址>/` grep 主题词

telnet 投信排障的两条实测铁律：DATA 正文必须以单独一行 . 结束、必须等到 250 … Ok: queued as … 响应后才能发 QUIT；会话提前断开会静默丢信（队列空、无日志）。

八、命令速查表

场景	命令
登记收信域	`inboxen createdomain inboxen.lan`
建管理员	`DJANGO_SUPERUSER_PASSWORD=… inboxen createsuperuser --noinput --username admin --email …`
首次初始化	`inboxen migrate && inboxen collectstatic --noinput`
升级后体检	`inboxen check && inboxen showmigrations`
公网拒收无主地址	`inboxen disowned --postfix` 接入 Postfix `check_recipient_access`
导入历史邮件	`inboxen feeder /path/to.mbox --inbox user@domain`
分析访问日志	`awk '{print $3}' access.log \| inboxen url_stats -`
改密码 / 解 2FA	`inboxen changepassword admin` / `inboxen two_factor_disable admin`
清过期会话	`inboxen clearsessions`
收信进程管理	`salmon start/status/stop --pid run/router.pid --boot inboxen.router.config.boot`
任务进程探测	`celery -A inboxen status`
数据备份	`inboxen dumpdata --natural-foreign --natural-primary > data.json`（配合 `pg_dump` 整库备份更完整）

九、参考链接

官方代码仓（management commands 取证）：https://codeberg.org/Inboxen/Inboxen（2026-10-26 查询）
官方 Getting Started（make salmon-start 等原始流程）：https://inboxen.readthedocs.io/en/latest/getting_started.html（2026-10-26 查询）
站内关联：《Inboxen 2026.2.22.0.27.49 介绍与选型指南》、《Debian 12 安装 Inboxen 2026.2.22.0.27.49 指南》、《Inboxen 2026.2.22.0.27.49 配置参数详解》