Mobilizon 5.2.4 常用 CLI 命令与工具详解

目标：系统梳理 Mobilizon 5.2.4 的两套管理工具——mobilizon_ctl CLI（用户/群组/媒体/Relay/维护/迁移）与 GraphQL API（/api），全部命令、选项与回显来自 2026-11-02 实测（kaihuri/mobilizon:5.2.4-amd64 容器，宿主端口 8160）。配置参数见站内文章 《Mobilizon 5.2.4 配置参数详解》，部署见 《Mobilizon Docker Compose 部署指南》。

⚠️ 首要纠偏：管理工具名是 mobilizon_ctl，不是 mobilizon.cli；它源自 Pleroma 的 mix 任务 wrapper。Docker 容器内路径 /bin/mobilizon_ctl，Release 安装路径 ./bin/mobilizon_ctl。

一、mobilizon_ctl 三种调用形态

同一命令在不同安装形态下的前缀（官方 CLI 页 + 实测）：

RPC 机制（help 原文实测）：mobilizon_ctl 默认通过 RPC 调用进正在运行的实例进程执行非迁移类命令；如需禁用（如实例已停机仍要跑任务），设环境变量 MOBILIZON_CTL_RPC_DISABLED。迁移类命令（migrate/rollback）不走 RPC。

help / 迁移 / 回滚

docker compose exec mobilizon mobilizon_ctl help

Usage: mobilizon_ctl COMMAND [ARGS]
    The known commands are:
        migrate          Execute database migrations (needs to be done after updates)
        rollback [VERSION]  Rollback database migrations (needs to be done before downgrading)
    and any mix tasks under Mobilizon namespace, for example
    `mix mobilizon.users.show COMMAND` is equivalent to `mobilizon_ctl users.show COMMAND`

Docker 场景一般无需手工 migrate——entrypoint 首启与升级 up -d 时自动执行（B2 实测）；rollback 用于降版本前。

二、命令域总览（容器内枚举实测）

输入裸域名（如 mobilizon_ctl actors）可列出该域全部子命令。5.2.4 实测存在的完整清单：

纠偏②：任务书/旧资料中设想的 geoip、addresses、search、database 等任务在 5.2.4 不存在（实测枚举无此域）。

三、users 域

3.1 users.new（实测建管理员成功）

docker compose exec mobilizon mobilizon_ctl users.new admin@mobilizon.localhost \
  --admin --profile-username g25admin --profile-display-name G25Admin \
  --password 'Y0urP4ssw0rd'

选项：--password/-p（缺省则随机生成，除非 --provider）；--admin / --moderator；--profile-username（同时建首个 profile，未给 display-name 时同值复用）；--profile-display-name（未给 username 时自动转换生成合法 username）；--provider（目前仅 ldap）。

坑（实测复现）：--profile-display-name "带空格 名字" 经 mobilizon_ctl 参数转发后被 OptionParser 拆散，报 MatchError。规避：用无空格显示名，或确保引号穿透到容器内（sh -c 包一层）。

3.2 users.show / modify / delete / clean

mobilizon_ctl users.show admin@mobilizon.localhost
# 实测回显：status: Activated 2026-11-01 20:05:08Z / Role: administrator / @g25admin

• users.show：邮箱是否已确认、是否 moderator/admin、全部 profile。
• users.modify 旧邮箱 [--email 新邮箱] [--password …] [--admin|--moderator|--user] [--enable|--disable]：改密/提权/禁用账号的运维入口（Web UI 不可用时的自救手段）。
• users.delete 模式 [选项]：支持批量——--assume-yes/-y 免确认；--all-matching-email-domain 按邮箱域批删；--all-matching-ip 按注册 IP 批删；--include-groups-where-admin 连带删除其管理的群组。
• users.clean [-v] [-d 天数] [--dry-run]：手跑"未确认用户清理"（对应 Oban 周期任务 CleanUnconfirmedUsersWorker 与 remove_unconfirmed_users 配置）；--dry-run 只列不删且隐含 verbose。

四、actors 域

4.1 actors.new 建 profile / 群组（实测）

# 给已有用户加 profile
mobilizon_ctl actors.new --email admin@mobilizon.localhost --username g25admin --display-name G25Admin
# 建群组（--group-admin 必填，指向已有 profile username）
mobilizon_ctl actors.new --type group --username g25group --display-name G25Group --group-admin g25admin
# 实测成功 → 组 actor @g25group（id=4）

--type 默认 person，建组必须显式 group。GraphQL 建群组活动要求组织者对组有权限——先建组再以组名义发布是实测走通的路径（个人 attributedTo 直接代发被拒）。

4.2 show / refresh / delete / utils

• actors.show <actor_username>：本地或联邦 actor 均可（mygroup@remote.example.com），回显归属用户、基本资料。
• actors.refresh <actor>：联邦排障主力——远端 actor 数据过期/丢失时手工刷新（对应 actor_stale_period 配置）；支持单个或全部。
• actors.delete：删 profile 或群组。
• actors.utils：辅助工具任务（描述为空，谨慎在生产试跑）。

五、media / relay / maintenance 域

5.1 media.cleanorphan（纠偏①主角）

官方文档页写 media.clean_orphan（1.0.3 引入），5.2.4 实测子命令为 media.cleanorphan（无下划线）：

docker compose exec mobilizon mobilizon_ctl media.cleanorphan --dry-run -v
# 选项：-v/--verbose 列出将删文件；-d/--days 孤儿判定天数；--dry-run 只列不删（隐含 -v）

对应配置 remove_orphan_uploads/orphan_upload_grace_period_hours 与 Oban 周期任务 CleanOrphanMediaWorker。

5.2 relay 域（实例级活动中继）

mobilizon_ctl relay.follow example.org     # 关注远端实例的公开活动中继
mobilizon_ctl relay.unfollow example.org
mobilizon_ctl relay.refresh example.org    # 爬取远端实例公开 outbox
mobilizon_ctl relay.accept                 # 文档 CLI 页未列，5.2.4 实测存在

配合配置 allow_relay（默认 true）；nodeinfo 实测 services.outbound=[atom1.0]、hasRelay 字段可查实例 relay 状态。

5.3 maintenance 域

mobilizon_ctl maintenance.detectspam -l -d   # 3.1.0 引入：检测存量垃圾
# 选项：-d/--dry_run 只列不建举报；-v 详细；-l/--local_only 只看本地（官方推荐）；
#       -f/--forward_reports 把远端内容的举报转发回源实例（误报多，慎用）

mobilizon_ctl maintenance.testemails         # 文档 CLI 页未列，实测存在：SMTP 发信测试

六、instance gen（Release 安装初始化）

Docker 场景不需要（entrypoint 全自动）；Release 安装用它交互生成配置与建库 SQL：

sudo -u mobilizon ./bin/mobilizon_ctl instance gen \
  --output /etc/mobilizon/config.exs --output-psql setup_db.psql \
  --domain mz.example.com --instance-name "MyZ" --admin-email a@example.com \
  --dbhost localhost --dbname mobilizon --dbuser mobilizon --dbpass '…' \
  --listen-port 4000
# 缺省选项会进入交互式问答；-f/--force 覆盖已有文件
# 随后：sudo -u postgres psql -f setup_db.psql && ./bin/mobilizon_ctl migrate

注意：新版文档默认输出路径为 config/runtime.exs（Elixir releases 风格），旧版为 config.exs；Docker 镜像内仍是 /etc/mobilizon/config.exs。

七、GraphQL API（/api）工具面

CLI 之外，/api 是脚本化管理的主入口（实测全链）：

# 1. 登录取 JWT（Guardian，sub "User:1"）
curl -s http://127.0.0.1:8160/api -H 'Content-Type: application/json' -d \
 '{"query":"mutation{login(email:\"admin@mobilizon.localhost\",password:\"…\"){accessToken refreshToken}}"}'

# 2. 带 token 调用
curl -s http://127.0.0.1:8160/api -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" -d '{"query":"{loggedPerson{id preferredUsername}}"}'
# → {"id":3,"preferredUsername":"g25admin"}

实测要点：

• 建活动：createEvent 参数平铺（title/description/beginsOn/endsOn/attributedToId/organizerActorId/visibility/joinOptions/status…），organizerActorId 必填；EventJoinOptions={EXTERNAL,FREE,INVITE,RESTRICTED}。成功返回 uuid（如 0e9dfbac-…）与 url、status:CONFIRMED。
• 参与者：joinEvent(eventId:1, actorId:5) → role:PARTICIPANT；管理侧 event{participants{total elements{role actor{preferredUsername}}}} → total=2（CREATOR+PARTICIPANT）；ParticipantStats 含 going/participant/notConfirmed/notApproved/rejected/creator/moderator/administrator 计数。
• 分页字段是 total/elements（不是 content/totalElements）。
• introspection：匿名被拒；admin token 下用 {__schema{queryType{fields{name}}}}（不是 queryFields）可枚举 42 个查询字段（config/instances/statistics/actionLogs/todo…）。
• instance(domain:) 查的是远端实例：本地域名 404、instances 表为空；本地生效配置用 config 查询（见 C1）。
• 匿名可查的实例统计面：Instance 类型含 eventCount/groupCount/personCount/mediaSize/followersCount/software/softwareVersion 等字段（introspection 实测）。

八、联邦排障 curl 工具箱

九、运维速查

十、纠偏与坑清单（汇总）

1. media.cleanorphan（实测）≠ 文档 media.clean_orphan；报 ** (Mix) The task ... could not be found 时先跑 mobilizon_ctl media 看枚举。
2. 工具名 mobilizon_ctl（Release/Docker）/ mix mobilizon.*（源码），无 mobilizon.cli。
3. relay.accept、maintenance.testemails 文档 CLI 页未列但实测存在；geoip/addresses 等任务不存在。
4. 带空格参数 MatchError（users.new display-name，实测复现，见 3.1 坑注）。
5. instance 裸跑报 FunctionClauseError——必须带 gen 子命令。
6. mobilizon_ctl 默认 RPC 进运行中实例：实例停机时非迁移命令可能失败，用 MOBILIZON_CTL_RPC_DISABLED=1 退回直连模式。
7. GraphQL introspection 匿名禁用；分页读 total/elements；本地配置查询用 config 而非 instance(domain:)。

取证说明：本文子命令枚举、help 回显、users/actors/media/relay/maintenance 执行结果与 GraphQL 行为均为 2026-11-02 在 5.2.4 容器内实测；文档语义核对自 docs.mobilizon.org CLI 章节（Last update 2026-05-07）。