Socialhome 0.24.0 常用 CLI 命令与工具详解

目标：把 Socialhome 0.24.0 的命令行运维面讲全——它是标准 Django 项目，manage.py 即运维总线：用户与远端 profile 清理、五级 RQ 队列与 Dramatiq 巡检、Haystack 搜索索引重建、迁移与密钥生成，每条命令的输入输出都是 2026-11-02 在真实运行实例上的实测记录，包括踩到的「测试专用命令在生产环境直接崩溃」等坑。部署上下文见《Socialhome 0.24.0 Docker Compose 部署指南》，文中变量含义见《Socialhome 0.24.0 配置参数详解》。

一、运行入口与回显噪声

所有命令在后端应用根（官方裸机路线为 ~/socialhome，仓库内含 manage.py）执行：

python manage.py <命令>

本文实验环境后端跑在编排服务单元内，等价入口为 docker compose exec backend python manage.py <命令>（回显原样照抄）。

每次执行都会先刷三段固定噪声，读回显时直接跳过（成因见部署篇排障）：

/app/config/settings/common.py:32: UserWarning: !!! No .env file found!
  warnings.warn("!!! No .env file found!")
...
The `drf-haystack` project urgently needs new maintainers!
...（大段上游弃用公告，2026-01-01 归档倒计时）
ERROR 2026-11-02 09:30:40,520 entities 191 127638320968576 get_user_private_key - no profile for http://127.0.0.1:8135/u/None/

第三行 ERROR ... get_user_private_key 只在 FEDERATION_USER 未设置时出现——它本身就是配置缺失的诊断信号（含义见配置篇第六章）。

二、命令全景

python manage.py help 按 Django app 分组列出全部子命令（实测清单，2026-11-02）。与运维直接相关的自有/扩展组：

组	命令
`[users]`	`delete_stale_profiles`、`delete_users_and_profiles`、`merge_remote_profiles`
`[content]`	`create_dummy_content`（仅开发环境可用，见第九章踩坑）
`[tasks]`	`rq_job_types`、`runscheduler`
`[django_rq]`	`rqworker`、`rqstats`、`rqcron`、`rqscheduler`、`rqenqueue`、`rqsuspend`、`rqresume`、`rqworker-pool`
`[django_dramatiq]`	`rundramatiq`
`[haystack]`	`rebuild_index`、`update_index`、`clear_index`、`haystack_info`、`build_solr_schema`
`[account]`	`account_unsetmultipleprimaryemails`
`[authtoken]`	`drf_create_token`
`[daphne]`	`runserver`（ASGI 开发服务器）
`[django_extensions]`	`shell_plus`、`generate_secret_key`、`print_settings`、`show_urls`、`reset_db`、`graph_models`、`describe_form`、`notes` 等 40+
标准 `[django]`	`check`、`migrate`、`showmigrations`、`makemigrations`、`createcachetable`、`dbshell`、`dumpdata`/`loaddata`、`flush`、`sendtestemail`、`diffsettings`、`collectstatic` 等

💡 说明：官方裸机部署由 Circus 常驻拉起 rqworker highest high default low lowest、runscheduler、rundramatiq、Daphne 四类进程（进程行实测见部署篇第十节），本文的命令级操作是在已跑实例上做巡检与维护，不是替代常驻进程。

三、用户与内容治理命令

3.1 delete_users_and_profiles：删号/删远端内容/锁垃圾号

官方 running 文档专节「Deleting users and locking remote profiles」提供。实测 --help：

usage: manage.py delete_users_and_profiles [-h] [--users USERS] [--profiles PROFILES]
                                           [--lock-remote-profiles] ...

三种用法（官方原文流程，UUID 逗号分隔可批量，每个目标都会弹确认对话框）：

# 删本地用户及其内容（本地内容会自动向远端发撤回）
python manage.py delete_users_and_profiles --users <uuid>

# 删远端 profile 的本地内容
python manage.py delete_users_and_profiles --profiles <uuid>

# 删远端内容并锁定该 profile（拒收其后续内容，垃圾号处置）
python manage.py delete_users_and_profiles --profiles <uuid> --lock-remote-profiles

官方红字警告：任何删除都是永久的，只能靠数据库与上传文件备份恢复；UUID 务必核对两遍。UUID 从 profile 页或 shell 查（User.objects.get(...).profile.uuid，实测 admin 的 profile uuid 为 0598121f-4e4d-4a8f-921c-aca8707ffccb）。

3.2 delete_stale_profiles：清理失联的远端 profile

实测 --help 关键参数：

usage: manage.py delete_stale_profiles [-h] [--instance INSTANCE]
                                       [--last-modified LAST-MODIFIED]
                                       [--max MAX] [--start-from START-FROM] ...

Delete stale remote profiles. Attempts to delete stale remote profiles. If a
profile can't be retrieved or if it has not been updated since the specified
date, delete it.

用途：远端实例消亡后本地残留大量僵尸 profile，--last-modified 给截止日期、--instance 按来源实例过滤、--max 限量、--start-from 断点续跑。

3.3 merge_remote_profiles：双协议重复 profile 合并

实测 --help：

usage: manage.py merge_remote_profiles [-h] [--fid FID] [--max MAX] ...

Merge remote profiles. Attempts to merge remote profiles where the profile has
both a Diaspora protocol identifier and ActivityPub protocol identifier. The
profile will be made primarily ActivityPub. All content will be migrated to
the other profile and the dupe deleted.

这是双协议服务端特有的问题：同一个人先后以 Diaspora handle 和 AP actor 入站，本地出现两个 profile。命令把重复对合并为 AP 为主、内容迁移、删副本；--fid 指定单个远端 FID，不给则全量扫描。

四、shell 与账号管理

官方 running 文档给出的三件套（均为 manage.py shell_plus 交互，实测可用）：

python manage.py shell_plus   # django-extensions 增强 shell，模型自动导入

邮件确认（无邮件服务时让用户直接可登录）：

from allauth.account.models import EmailAddress
EmailAddress.objects.filter(email=<email>).update(verified=True)

提权管理员（官方原文流程）：

from socialhome.users.models import User
User.objects.filter(username=<username>).update(is_staff=True, is_superuser=True)

建超管：python manage.py createsuperuser（部署篇第九节实测，建号后 handle 自动生成为 用户名@SOCIALHOME_DOMAIN）。

零散但常用的：

python manage.py drf_create_token <username>          # 给用户发 REST API token（DRF authtoken）
python manage.py account_unsetmultipleprimaryemails   # 清理 allauth 多 primary 邮箱异常数据

五、队列与后台任务

django-rq 轨（五级队列）。巡检首选 rqstats——实测回显：

$ python manage.py rqstats
Django RQ CLI Dashboard

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

同族命令：rqworker <队列...>（手工起 worker，常驻已由 Circus 拉起）、rqenqueue（手工入队）、rqsuspend/rqresume（暂停/恢复队列）、rqscheduler（定时任务执行器）、rqcron。

任务类型分布（自有命令，实测 --help 描述）：

usage: manage.py rq_job_types [-h] ...
List count of distinct job types currently queued.

队列里堆了什么任务用它看，比 rqstats 的数字更具体。

Dramatiq 轨：manage.py rundramatiq 即 Circus 常驻拉起的那行进程（实测进程参数 --processes 6 --threads 8 --worker-shutdown-timeout 600000），进程数/线程数由 DRAMATIQ_NPROCS/DRAMATIQ_NTHREADS 控制（配置篇第七章）。

APScheduler 轨：manage.py runscheduler。实测 --help 原文警告：

Run APScheduler. Note! Only run this once. If using the provided `circus.ini`
configuration, or using the provided official Docker image, this scheduler
will already be running.

——用官方制品/官方 circus 配置时不要再手工跑第二个调度器，定时任务会翻倍执行。

六、搜索索引

Socialhome 搜索为 Haystack + Xapian 本地索引，落盘 /app/var/xapian-index（持久卷，实测目录见部署篇第十节）。

haystack_info（实测回显）：

$ python manage.py haystack_info
Number of handled 2 index(es).
  - Model: Profile by Index: <socialhome.users.search_indexes.ProfileIndex object at 0x7a57253d38f0>
  - Model: Tag by Index: <socialhome.content.search_indexes.TagIndex object at 0x7a57253d37d0>

——全文检索只覆盖 profile 与 tag 两类模型（内容搜索走 API 层）。

rebuild_index（全量重建，实测回显）：

$ python manage.py rebuild_index --noinput
Removing all documents from your index because you said so.
All documents removed.
Indexing 1 profiles
Indexing 0 tags

日常增量用 update_index，清空用 clear_index。升级时是否需要重建索引以官方 Updating 文档与 Changelog 为准——官方明说 Docker 路线「any actions required by a backend upgrade will be handled by just updating the image tag and recreating」，但「sometimes extra manual steps might be required or an update could take a long time due to database migrations」（来源：https://socialhome.readthedocs.io/en/latest/updating.html，查询日期 2026-11-02）。

七、迁移与数据库

migrate：后端制品启动脚本自动执行（实测启动日志逐条 Applying ... OK，见部署篇第七节），手工场景是升级排障时补跑；
showmigrations：核对迁移进度。实测尾部（users 应用已到 0057）：

 [X] 0054_alter_profile_avatar_url_and_more
 [X] 0055_profile_protocols
 [X] 0056_profile_users_profile_fid_upper
 [X] 0057_populate_protocols

createcachetable：Django DB 缓存表（首次装必备）；
dbshell：直达 PostgreSQL 命令行（凭 DATABASE_URL）；
dumpdata/loaddata、flush：标准数据搬运/清库；
django-extensions 的 reset_db：开发机重开用，生产禁用。

八、实用工具命令

# 生成 DJANGO_SECRET_KEY（实测回显）
$ python manage.py generate_secret_key
-*ck+vw@ixcte5_hzk^+1b0=t!%+vic_p!h0q_)2p_jvu5o1v1

# 打印生效配置（排查环境变量是否注入成功）
python manage.py print_settings

# 列出全部 URL 路由（对照 LB 分流前缀清单极有用）
python manage.py show_urls

# 与 Django 默认配置比对差异
python manage.py diffsettings

# 官方邮件排障：向指定地址发测试邮件
python manage.py sendtestemail admins

九、排障实录

create_dummy_content 在生产环境直接崩溃（实测）：该命令 import 测试工厂，而生产依赖不含 factory_boy：

  File "/app/socialhome/content/management/commands/create_dummy_content.py", line 5, in <module>
    from socialhome.content.tests.factories import PublicContentFactory
  File "/app/socialhome/content/tests/factories.py", line 1, in <module>
    import factory
ModuleNotFoundError: No module named 'factory'

——它只属于开发环境（跑 pytest 的虚拟环境里有 factory_boy），别在生产实例上调。

rqstats -i 1 是循环刷新模式：加 -i <秒> 后命令永不退出、持续重绘表格，非交互脚本里会挂住（本文实测挂了两分钟才掐掉）；巡检脚本用不带 -i 的一次性输出。
制品内没有 ps 等工具：排查进程要用 /proc/*/cmdline 遍历（部署篇第十节方法）。
manage.py help 顶部同样刷三段噪声（第一章），不影响清单内容；命令名拼错时报错会提示 Type 'manage.py help <subcommand>'。

十、小结与关联

Socialhome 的 CLI 运维面 = Django 标准动作 + 三个自有治理命令（users/tasks/content 组）+ 双任务体系巡检（rqstats/rq_job_types/rundramatiq/runscheduler）。记住三条纪律：调度器只跑一份；删除命令不可逆先备份；dummy 数据命令仅限开发环境。

部署与进程实测：《Socialhome 0.24.0 Docker Compose 部署指南》；
命令涉及的变量与默认值：《Socialhome 0.24.0 配置参数详解》；
产品定位与选型：《Socialhome 0.24.0 介绍与选型指南》。