Pleroma 2.11.0 常用 CLI 命令详解

本文以 Docker Compose 官方镜像在跑实例（Pleroma 2.11.0，内部版本 2.11.0-develop）为对象，梳理 pleroma_ctl / mix pleroma.* 命令族：生命周期、用户管理、实例生成、配置双轨、OAuth 应用、中继、前端、数据库维护、emoji 包、邮件与摘要共 12 类任务，逐条给出实测回显；含 robots_txt 任务在发布制品中不存在、frontend list/config help 子命令缺失、emoji manifest 拉取失败等 8 条实测踩坑。命令输入输出均为 2026-11-02 实测，逐行照抄（长 SQL debug 行以「…（SQL 日志略）」截断）。

一、命令体系总览

1.1 三种等价形态

Pleroma 的运维命令本质是 Elixir 的 Mix 任务（命名空间 mix pleroma.*）。同一任务有三种调用形态：

官方文档对全部任务的通用前提（general_cli_task_info 原文）：

"Every command should be ran as the pleroma user from it's home directory. For example if you are superuser, you would have to wrap the command in su pleroma -s $SHELL -lc "$COMMAND"." "The mix command should be prefixed with the name of environment your Pleroma server is running in, usually it's MIX_ENV=prod"

1.2 pleroma_ctl 的 eval/rpc 双派发机制（实测脚本源码）

pleroma_ctl 是发布制品自带的 POSIX sh 包装脚本（/opt/pleroma/bin/pleroma_ctl，实查源码节选）：

if [ "$ACTION" = "update" ]; then
        update "$@"
elif [ "$ACTION" = "migrate" ] || [ "$ACTION" = "rollback" ] || [ "$ACTION" = "create" ] || [ "$ACTION $SUBACTION" = "instance gen" ] || [ "$PLEROMA_CTL_RPC_DISABLED" = true ]; then
        "$SCRIPTPATH"/pleroma eval 'Pleroma.ReleaseTasks.run(['"${PREPARED_ARGS%%,}"'])'
else
        "$SCRIPTPATH"/pleroma rpc 'Pleroma.ReleaseTasks.run(['"${PREPARED_ARGS%%,}"'])'
fi

• 离线派发（eval）：create/migrate/rollback/instance gen 四类在独立 BEAM 节点执行（实例可以不在跑）；
• 在线派发（rpc）：其余任务默认连入正在运行的节点执行（可读到运行时配置、直接写库生效）；
• 设 PLEROMA_CTL_RPC_DISABLED=true 可强制全部走离线节点；
• 参数以 Elixir 二进制字面量逐字节编码传递（脚本注释原文：避免含空格的引号参数被二次拆分）。

pleroma_ctl help 实测回显（节选）：

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl help
Usage: pleroma_ctl COMMAND [ARGS]

    The known commands are:

        create
          Create database schema (needs to be executed only once)

        migrate
          Execute database migrations (needs to be done after updates)

        rollback [VERSION]
          Rollback database migrations (needs to be done before downgrading)

        update [OPTIONS]
          Update the instance.

          Options:
          --branch  Update to a specified branch, instead of the latest version of the current one.
          --flavour Update to a specified flavour (CPU architecture+libc), instead of the current one.
          --zip-url Get the release from a specified url. If set, renders the previous 2 options inactive.
          --no-rm   Do not erase previous release's files.
          --tmp-dir Download the temporary files to a specified directory.

    and any mix tasks under Pleroma namespace, for example `mix pleroma.user COMMAND` is
    equivalent to `pleroma_ctl user COMMAND`

    By default pleroma_ctl will try calling into a running instance to execute non migration-related commands,
    if for some reason this is undesired, set PLEROMA_CTL_RPC_DISABLED environment variable.

1.3 任务全集（发布制品实查）

OTP 制品内实际打包的 Mix 任务模块清单（实查 /opt/pleroma/lib/pleroma-2.11.0-develop/ebin/ 下 Elixir.Mix.Tasks.Pleroma.*.beam）：

App  Config  CountStatuses  Database  Digest  Docs  Ecto  Ecto.Migrate  Ecto.Rollback
Email  Emoji  Frontend  Instance  NotificationSettings  OpenapiSpec  RefreshCounterCache
Relay  RobotsTxt  Search.Indexer  Search.Meilisearch  TestRunner  Uploads  User

⚠️ 注意：beam 存在 ≠ pleroma_ctl 白名单放行——RobotsTxt 模块在制品里，但 pleroma_ctl robots_txt 实测报「task does not exist」（见第十三章排障实录，文档与发布行为存在出入）。

二、生命周期四命令

migrate 实测形态（入口脚本调用 $HOME/bin/pleroma_ctl migrate，回显见部署篇）：末行 == Migrated 20260725000000 in 0.0s 后进入 -- Starting!。

三、用户管理（pleroma.user / pleroma_ctl user）

任务族子命令全集（实查制品内 lib/mix/tasks/pleroma/user.ex 的 run 头 + 官方文档）：new / rm / list / set / tag / untag / activate / deactivate / deactivate_all_from_instance / confirm / reset_password / reset_mfa / invite / invites / revoke_invite / delete_activities。

3.1 user new（建号）

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl user new tester tester@example.com --password q1w2e3r4 -y
A user will be created with the following information:
  - nickname: tester
  - email: tester@example.com
  - password: q1w2e3r4
  - name: tester
  - bio:
  - moderator: false
  - admin: false
...（SQL 日志略）
User tester created

选项（官方文档逐条）：--name --bio --password（不传则随机生成并打印）--moderator/--no-moderator --admin/--no-admin -y/--assume-yes（免交互确认）。

⚠️ 排障实录 ①：重复建号不报友好错误，直接抛 MatchError（实测原样，changeset 内容截断）：

** (MatchError) no match of right hand side value: {:error, #Ecto.Changeset<action: :insert, ..., errors: [email: {"has already been taken", [constraint: :unique, constraint_name: "users_email_index"]}], ...>}
    (pleroma 2.11.0-develop) lib/mix/tasks/pleroma/user.ex:76: Mix.Tasks.Pleroma.User.run/1

两点教训：a) 建号前先 user list 或查库查重；b) 异常栈会明文打印 changeset（含 RSA 私钥与口令），生产环境注意日志权限与脱敏。

3.2 user list（本地用户一览）

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl user list
admin moderator: false, admin: true, locked: false, is_active: true
relay moderator: false, admin: false, locked: false, is_active: true
tester moderator: false, admin: false, locked: false, is_active: true

💡 说明：输出不含 internal.fetch 系统账号（查询条件过滤 nickname IS NULL 与 internal.% 前缀，实测库内 4 行、list 显 3 行）。

3.3 user invite / invites / revoke_invite（邀请制）

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl user invite --max-use 1
Generated user invite token reusable
http://localhost:8148/registration/snuj78otJ2RZIa71pCsIwvpv7pMvbW9PVIhA7yF0C68%3D

选项：--expires-at DATE、--max-use NUMBER。邀请链接直接是注册页 URL；配合 :instance invites_enabled: true 生效。invites 列出现有令牌，revoke_invite <token> 吊销。

3.4 其余子命令速查

四、实例生成（pleroma.instance / pleroma_ctl instance gen）

OTP 路线首装的核心命令（本实验容器路线由 docker.exs 环境变量替代，未实测执行——它会生成/覆盖配置文件）。免交互全参数形态（官方文档逐条照录）：

./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /etc/pleroma/setup_db.psql \
  --domain social.example.com --instance-name "Example Social" \
  --admin-email admin@example.com --notify-email notifications@example.com \
  --dbhost localhost --dbname pleroma_dev --dbuser pleroma --dbpass q1w2e3r4 \
  --rum N --indexable Y --db-configurable N \
  --uploads-dir /home/pleroma/pleroma/uploads --static-dir /home/pleroma/pleroma/instance_static \
  --listen-ip 127.0.0.1 --listen-port 4000 \
  --strip-uploads-location Y --read-uploads-description N --anonymize-uploads N --dedupe-uploads Y

要点：任何选项缺省会交互式追问；--output-psql 生成配套的 setup_db.psql（建角色建库脚本，交给 sudo -u postgres psql 执行）；--db-configurable Y 即开启数据库配置轨；--listen-ip 默认 127.0.0.1（生产同样建议只监听回环，由反代接入）。

五、配置管理（pleroma.config / pleroma_ctl config）

八个子命令全集与语义见本专栏配置篇第五章（migrate_to_db / migrate_from_db / dump / groups / delete / reset / fix_mrf_policies / filter_whitelisted）。实测回显：

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl config groups
（无输出——本实例 DB 配置轨为空）

⚠️ 排障实录 ②：config help / config list 等不存在的子命令直接 FunctionClauseError（原样）：

** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.Config.run/1
    The following arguments were given to Mix.Tasks.Pleroma.Config.run/1:
        # 1
        ["help"]
    (pleroma 2.11.0-develop) lib/mix/tasks/pleroma/config.ex:17: Mix.Tasks.Pleroma.Config.run/1

六、OAuth 应用（pleroma.app / pleroma_ctl app）

创建受信应用（trusted app，免授权码直发 token，适合服务端集成）：

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl app create -n d1app -r urn:ietf:wg:oauth:2.0:oob
d1app successfully created:
App client_id: Ysxd9lgCQX330z08KPTa8PLCCT0J8P32as_p9gaNj6I
App client_secret: UVkpj_JX3PJace02_5TvJEhaPNKlbbPu9HZ5JaiwtD0

可选 -s SCOPES（如 read,write,follow,push）。与 API 路线（POST /api/v1/apps）的差异：CLI 建的是 trusted 应用，Mastodon API 建的是普通应用；注意 API 路线参数必须用复数 redirect_uris（部署篇排障 ⑥）。

七、中继管理（pleroma.relay / pleroma_ctl relay）

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl relay list
（无输出——当前无订阅）

子命令：relay follow <relay_url> / relay unfollow <relay_url> / relay list。中继用于订阅全网公共时间线（大中继如 https://relay.mastodon.host/relay），小实例慎用——流量会显著放大。

八、前端管理（pleroma.frontend / pleroma_ctl frontend）

子命令（官方文档）：install <frontend> [--ref <ref>] [--file <file>] [--build-url <url>] [--path <path>] [--build-dir <dir>]、switch <frontend>、uninstall <frontend>。已知前端名（frontends.available 注册表实查 7 个）：admin-fe、fedi-fe、glitch-lily、kenoma、pl-fe、pleroma-fe、soapbox。

装管理前端实例（官方文档原样）：

./bin/pleroma_ctl frontend install admin-fe --ref stable

产物落 ${instance_static}/frontends/${name}/${ref}，安装即整目录替换；随后在配置里设 [:frontends, :admin] 指向它（配置篇 4.5）。

⚠️ 排障实录 ③：没有 list 子命令（与直觉相反，实测原样）：

** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.Frontend.run/1
    The following arguments were given to Mix.Tasks.Pleroma.Frontend.run/1:
        # 1
        ["list"]
    (pleroma 2.11.0-develop) lib/mix/tasks/pleroma/frontend.ex:14: Mix.Tasks.Pleroma.Frontend.run/1

查已装前端：看 static_dir/frontends/ 目录树，或 pleroma rpc 'IO.inspect(Pleroma.Config.get([:frontends, :available]))'。

九、数据库维护（pleroma.database / pleroma_ctl database）

官方文档对整族的警告原文：

"These mix tasks can take a long time to complete. Many of them were written to address specific database issues that happened because of bugs in migrations or other specific scenarios. Do not run these tasks "just in case" if everything is fine your instance."

实测一条安全项 vacuum analyze：

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl database vacuum analyze
12:20:15.254 [info] Running VACUUM ANALYZE.
vacuum analyze; []

任务全集（官方文档 database.md 照录）：

十、emoji 包管理（pleroma.emoji / pleroma_ctl emoji）

子命令：ls-packs [(-m|--manifest PATH/URL)]、get-packs [选项] <pack ...>、gen-pack PACK-URL、reload（reload 仅 OTP 制品可用）。

⚠️ 排障实录 ④：emoji ls-packs 默认从网络拉官方 manifest，本实验环境实测拉回空内容直接炸 JSON 解析（原样）：

** (Jason.DecodeError) unexpected end of input at position 0
    (jason 1.4.5) lib/jason.ex:92: Jason.decode!/2
    (pleroma 2.11.0-develop) lib/mix/tasks/pleroma/emoji.ex:18: Mix.Tasks.Pleroma.Emoji.run/1

处置：用 -m 指定本地 manifest 文件路径绕开网络；或确认制品所在网络能访问 git.pleroma.social 的包仓库端点。

get-packs 会「fetch, verify and install」——校验 SHA256 后解入 STATIC-DIR/emoji/PACK-NAME；gen-pack 面向分享自制包（下载 zip→问答→生成 manifest 条目与文件清单）。

十一、邮件与摘要（pleroma.email / pleroma.digest）

💡 说明：本实验未配置 SMTP（出厂 docker.exs 不含 mailer 组，Pleroma 默认 Local 适配器不发真信），故 email/digest 仅收录官方命令面、未实测发信；SMTP 参数组（Pleroma.Mailer + :email 主题/正文配置）见配置篇体系。

十二、上传迁移与搜索索引（pleroma.uploads / pleroma.search）

• uploads migrate_local <target_uploader> [--delete]：把本地 uploads 目录整体迁往 S3 等远端 uploader（--delete 迁移后删本地）；
• 制品内另有 Search.Indexer（重建搜索索引）与 Search.Meilisearch（Meilisearch 外置检索集成，2.11 新增）两族，对应配置组见配置篇；
• 杂项任务：CountStatuses（统计）、NotificationSettings（通知设置迁移）、RefreshCounterCache（计数缓存刷新）、OpenapiSpec/Docs（规范与文档生成，开发向）。

十三、robots_txt 与「文档-制品」出入（排障重点）

官方文档给出 OTP 形态：

./bin/pleroma_ctl robots_txt disallow_all

实测（本镜像内）两种写法均被拒：

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl robots_txt disallow_all
The task robots_txt does not exist
$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl pleroma.robots_txt disallow_all
The task pleroma.robots_txt does not exist

⚠️ 排障实录 ⑤（结论）：Mix.Tasks.Pleroma.RobotsTxt.beam 确实在制品 ebin 里（1.3 节实查），但 pleroma_ctl 的 ReleaseTasks 派发层不放行该任务名——文档所述与发布行为存在出入。替代做法（效果等价）：直接把 restrictive robots.txt 写入 static_dir（/var/lib/pleroma/static/robots.txt），Pleroma 按静态目录优先规则对外提供：

User-agent: *
Disallow: /

源码安装形态 mix pleroma.robots_txt disallow_all 不受此限。

十四、踩坑汇总

十五、站内阅读

• 部署与入口脚本机制：《Pleroma 2.11.0 Docker Compose 部署指南》
• 配置组与双轨迁移详解：《Pleroma 2.11.0 配置参数详解》
• 架构与版本溯源：《Pleroma 2.11.0 介绍与选型指南》
• 同族分支对照：《Akkoma 3.20.1 常用 CLI 命令与工具详解》

实测说明：本文回显产生于 2026-11-02 在跑的 Pleroma 2.11.0 实例（Ubuntu 24.04.5 / Docker 29.9.2）；SQL debug 长行按「…（SQL 日志略）」截断，异常栈中的密钥内容已截断，其余逐行照抄；文档命令面来源为官方仓库 docs/administration/CLI_tasks/*.md 各页（查询日期 2026-11-02）。