PdfDing 1.14 常用 CLI 命令与工具详解

目标：讲清 PdfDing v1.14.1 容器内管理命令的完整清单与用法——账号管理、健康自检、数据导出导入、邮件诊断、维护清理五大类，每条命令配容器内实测回显。需要说明：PdfDing 不提供 REST API，也没有独立 CLI 二进制，全部管理能力集中在 Django manage.py 管理命令体系内，本文即该体系的实测手册。测试日期 2026-10-29。

一、环境信息

二、工具概览

PdfDing 的 CLI 本质是 Django 管理命令：容器入口固定为 docker exec pdfding-1.14.1 python pdfding/manage.py <子命令>。由于镜像内置了 django-extensions 与 djhuey，命令清单比原生 Django 更丰富。manage.py --help 的完整分组（实测输出）：

[account]
    account_unsetmultipleprimaryemails

[auth]
    changepassword
    createsuperuser

[contenttypes]
    remove_stale_contenttypes

[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

[djhuey]
    create_huey_tables
    run_huey

[sessions]
    clearsessions

[staticfiles]
    collectstatic
    findstatic
    runserver

[users]
    clean_up
    make_admin

按运维场景归组后，日常真正高频的命令如下（本文逐条实测）：

其余多为开发期命令（makemigrations、test、startapp 等）与镜像构建期命令（collectstatic），自托管运维一般用不到，见 §5 注意事项。

三、前置条件

1. 容器运行中（docker compose ps 状态 Up），以下命令示例统一使用容器名 pdfding-1.14.1（按你的 container_name 替换）；
2. 命令统一从宿主机经 docker exec 执行，工作目录任意（manage.py 以相对路径 pdfding/manage.py 引用，镜像已设好工作目录）；
3. 涉及数据库写入的命令（建号、改密、回灌）建议避开用户活跃时段；dumpdata 只读可随时执行。

四、各工具详解

4.1 createsuperuser——创建超级管理员

部署后创建初始管理员（邮箱即登录用户名，密码经环境变量注入实现免交互）：

docker exec \
  -e DJANGO_SUPERUSER_EMAIL=admin@pdfding.local \
  -e DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 \
  pdfding-1.14.1 \
  python pdfding/manage.py createsuperuser --noinput --username admin@pdfding.local

实测回显：

Superuser created successfully.

两个实测行为值得注意：

• --noinput 模式必须带 --username，漏掉直接报错（实测）：

CommandError: You must use --username with --noinput.

• 密码强度校验在非交互路径不生效：交互式创建时 q1w2e3r4 会被 allauth 的 common-password 校验拦截（与注册页一致），但走环境变量的非交互路径可成功创建。这方便了测试环境，生产环境请自律使用强密码。

创建后的账号还要能登录：ACCOUNT_EMAIL_VERIFICATION=TRUE（默认）下需持有已验证邮箱。命令行创建的超管没有邮箱记录，可在 shell 中补一条（见 §4.4）。

4.2 make_admin——提升已有用户为管理员

users 应用自带的专属命令，把指定邮箱的用户置为管理员（is_staff + is_superuser）：

docker exec pdfding-1.14.1 python pdfding/manage.py make_admin -e demo@pdfding.local

实测：对存在的用户执行静默成功（无任何输出，退出码 0），权限即时生效——该用户在 /admin/users 管理页获得 Admin 徽章。

对不存在的邮箱执行（实测回显，traceback 节选）：

  File "/home/nonroot/.venv/lib/python3.12/site-packages/django/db/models/query.py", line 722, in get
    raise self.model.DoesNotExist(
django.contrib.auth.models.User.DoesNotExist: User matching query does not exist.

退出码 1。脚本化授权时以退出码判断成败即可。

4.3 changepassword——修改用户密码

docker exec -it pdfding-1.14.1 python pdfding/manage.py changepassword demo@pdfding.local

交互式两次输入新密码，走 Django 完整密码校验（弱密码会被拦截，实测与注册页同规则）。注意它是强制交互命令：在无 TTY 的管道中执行会因读不到输入报 EOFError（实测），因此 CI/脚本场景改用 shell 调 set_password（§4.4）。

4.4 shell——ORM 交互与脚本（shell_plus 增强版）

shell 是排障与自动化的瑞士军刀。镜像内置 django-extensions，启动时自动导入全部模型（实测 banner：29 objects imported automatically），-c 传入语句即可单行执行：

docker exec pdfding-1.14.1 python pdfding/manage.py shell -c \
  "qs = Pdf.objects.all(); print('PDF 总数:', qs.count()); [print(p.name, '| 标签:', [t.name for t in p.tags.all()]) for p in qs]"

实测回显：

PDF 总数: 4
PdfDing Lab Report | 标签: ['质检', 'lab/报表']
second-doc | 标签: ['自动导入', 'consume']
third-consume | 标签: ['自动导入', 'consume']
sample-report | 标签: ['批量导入']

三个高价值用法（均实测）：

1. 补已验证邮箱（解决 §4.1 的登录阻塞）：

from allauth.account.models import EmailAddress
EmailAddress.objects.get_or_create(
    user=User.objects.get(username='admin@pdfding.local'),
    email='admin@pdfding.local', verified=True, primary=True)

2. 非交互改密码（替代 §4.3）：

u = User.objects.get(username='demo@pdfding.local')
u.set_password('新的强密码'); u.save()

3. 核对运行时配置（配置排障首选，见 《PdfDing 1.14 配置参数详解》 §3.2）：

from django.conf import settings
print(settings.ALLOWED_HOSTS, settings.EMAIL_BACKEND)

模型探索提示：Pdf 模型没有 user 字段（实测 Pdf.user 抛 FieldError），PDF 与用户的归属经 Collection 关联——查询某用户的文件应走 Collection.objects.filter(owner=...).pdfs 方向，而非假设直接外键。

4.5 check——健康自检

docker exec pdfding-1.14.1 python pdfding/manage.py check

实测回显：

System check identified no issues (0 silenced).

升级镜像后、改配置后、排查 500 错误前先跑它：配置错误（如非法默认主题值）、模型不一致都会在此暴露，零输出问题则把注意力转向日志与请求层。

4.6 showmigrations / migrate——迁移核查与执行

showmigrations 列出全部迁移及应用状态（实测节选）：

account
 [X] 0001_initial
 [X] 0002_email_max_length
 ...
auth
 [X] 0001_initial
 ...
contenttypes
 [X] 0001_initial

正常实例全部为 [X]。容器启动时 entrypoint.sh 已自动执行 migrate（启动日志 Running migrations 段），升级版本后无需手动执行迁移；手动 migrate 只用于确认状态或修复中断的升级。

4.7 dumpdata / loaddata——数据导出与回灌

导出 PDF 元数据为 JSON（只读操作，可热备）：

docker exec pdfding-1.14.1 python pdfding/manage.py dumpdata pdf.Pdf

实测输出节选（单条记录）：

[{"model": "pdf.pdf", "pk": "2c0556a1-9972-4e1c-b15c-5efa5f3d1a39", "fields":
{"archived": false, "creation_date": "2026-10-29T16:05:20.999Z", "collection": "1",
"current_page": 1, "description": "", "file_directory": "", "file": "1/default/pdf/third-consume.pdf",
"last_viewed_date": "2000-01-01T00:00:00Z", "name": "third-consume", "number_of_pages": 1,
"preview": "1/default/previews/2c0556a1-….png", "revision": 0, "starred": false, "thumbnail": "1/default/thumbnails/2c…

（4 条记录合计约 2.5KB；记录里可见 PDF 主键为 UUID、文件路径挂在该用户的 media 目录下。）

回灌到同一实例（同主键幂等 upsert）实测：

docker exec pdfding-1.14.1 sh -c \
  'python pdfding/manage.py dumpdata pdf.Pdf > /tmp/fixture.json && python pdfding/manage.py loaddata /tmp/fixture.json'

实测回显：

Installed 4 object(s) from 1 fixture(s)

定位说明：dumpdata 导出的是元数据（不含 PDF 文件本体），跨实例迁移需配合 media 目录整体拷贝；users.User 的导出包含密码哈希字段，注意导出文件的保管（见 §5）。

4.8 sendtestemail——邮件链路诊断

docker exec pdfding-1.14.1 python pdfding/manage.py sendtestemail demo@pdfding.local

实测回显（EMAIL_BACKEND=CONSOLE 时邮件全文打印到 stdout；SMTP 后端时此命令即验证真实投递）：

Subject: Test email from 45c81fbb1594 on 2026-10-29 …
From: info@127.0.0.1
To: demo@pdfding.local
…（正文）

实测踩坑：该命令的收件人是位置参数，sendtestemail --to demo@… 会报 unrecognized arguments（部分 Django 版本文档写法不同，以实测为准）。另外发件人 info@127.0.0.1 印证了 EMAIL_ADDRESS 默认值跟随 HOST_NAME 拼接的行为（配置详解篇 §5.4）。

与邮件相关的另一个高频诉求——密码重置链接的获取：CLI 没有直达命令，走登录页「Forgot password?」提交邮箱后，CONSOLE 后端把含重置链接的邮件打进容器日志（实测主题 [127.0.0.1:8139] Password Reset Email，链接形如 /accountpassword/reset/key/2-…=），docker logs 中复制即可。

4.9 clean_up / clearsessions——维护清理

# 清理删除时间已过的分享（users 应用）
docker exec pdfding-1.14.1 python pdfding/manage.py clean_up

实测回显：

Cleaning up shared PDFs with a deletion date in the past.

# 清理数据库中过期的登录会话（静默，退出码 0）
docker exec pdfding-1.14.1 python pdfding/manage.py clearsessions

clean_up 已被容器启动序列内置（每次启动自动执行一次）；设置了「定时删除」的分享链接，其到期失效既依赖启动时的这次清理，也依赖 Huey 周期任务，长期不重启的实例重启一次即可触发补扫。clearsessions 需自行安排周期执行（可加进宿主 crontab）。

4.10 慎用/少用命令一览

五、注意事项

1. 输出即泄密：diffsettings 会明文回显含 SECRET_KEY 在内的全部生效配置（实测确认），dumpdata users.User 含密码哈希——这两类命令的输出不要贴进公开的 issue/日志平台；
2. 交互命令需要 TTY：changepassword、交互式 createsuperuser、交互式 shell 必须配 docker exec -it；管道环境用 --noinput + 环境变量或 shell -c 替代（§4.3）；
3. shell 的自动导入：django-extensions 的 shell_plus 已把全部模型导入命名空间，直接用 Pdf、User、Collection 即可，无需 import（重复 import 无害但多余）；
4. 模型字段以实测为准：文档与直觉都不可靠时，用 shell -c "print([f.name for f in Pdf._meta.get_fields()])" 列出真实字段再写查询，避免 FieldError（Pdf 无 user 字段是本次实测踩到的坑）；
5. 启动序列已托管的事不要重做：migrate（启动自动执行）、clean_up（启动自动执行）、run_huey（后台已托管）——重复执行轻则冗余，重则任务抢占；
6. SQLite 并发约束：所有写库命令与在线服务共享同一个 db.sqlite3，低写入量下无碍，但避免在批量 loaddata 的同时进行上传等写操作。

六、常见问题

6.1 dbshell 报 sqlite3 未安装

实测回显：

CommandError: You appear not to have the "sqlite3" program installed or on your path.

原因：官方镜像为 alpine 精简构建，未带 sqlite3 CLI。处理：改用 shell 的 ORM 查询（§4.4）；或宿主机装有 sqlite3 时直接只读打开挂载出来的 db/db.sqlite3。

6.2 createsuperuser 报 You must use --username with --noinput

--noinput 非交互模式必须显式提供用户名。完整可用命令见 §4.1。

6.3 make_admin 报 User matching query does not exist

邮箱不存在（注意是登录用户名而非昵称）。先用 §4.4 的 User.objects.filter(username__icontains='…') 核对真实用户名再执行。

6.4 脚本里 changepassword 卡死或报 EOFError

它是强制交互命令，无 TTY 环境读不到输入。脚本场景用 shell -c + set_password（§4.4 用法 2）。

6.5 sendtestemail 报 unrecognized arguments

收件人是位置参数：sendtestemail demo@pdfding.local，不带 --to（§4.8）。

6.6 用户注册报 This password is too common.

注册页与交互式改密走 allauth 强度校验；非交互 createsuperuser（环境变量传密码）绕过校验。生产请统一使用强密码，不要依赖该绕过路径。

七、参考链接

• Django 管理命令官方文档（dumpdata/loaddata/check 等语义）：https://docs.djangoproject.com/en/5.x/ref/django-admin/
• django-extensions（shell_plus 增强的来源）：https://django-extensions.readthedocs.io/
• PdfDing 主仓库（users 应用 make_admin/clean_up 源码）：https://codeberg.org/mrmn/PdfDing
• 官方文档站 Guides（管理员与用户管理）：https://docs.pdfding.com/guides/admin_users/
• 相关文档：《PdfDing 介绍与选型指南》、《PdfDing 1.14 Docker Compose 部署指南》、《PdfDing 1.14 配置参数详解》