Akkoma 3.20.1 常用 CLI 命令与工具详解
Akkoma 3.20.1 运维 CLI 全景：mix pleroma 任务族的实例生成、用户管理、配置双轨迁移、前端安装、数据库维护与 OAuth 应用创建，附 8 条实测踩坑（命名空间、子命令缺失、参数不支持）与免交互发贴全链路回显。
Akkoma 3.20.1 常用 CLI 命令与工具详解
目标：把 Akkoma 3.20.1 的运维 CLI（mix 任务族）讲全——实例生成、用户管理、配置迁移、前端安装、数据库维护、中继/表情包/OAuth 应用，每条命令的回显都是 2026-11-02 在真实运行实例上的实测记录，包括踩到的子命令不存在、参数不支持等坑。部署上下文见 《Akkoma 3.20.1 Docker Compose 部署指南》，配置参数语义见 《Akkoma 3.20.1 配置参数详解》。
一、环境信息与 CLI 入口
- 组件与版本：Akkoma 3.20.1（
3.20.1-0-gbc62dd8），Elixir 1.15.4 / OTP 26，PostgreSQL 14.24。 - 命名空间事实（实测纠偏）：Akkoma 从 Pleroma 分支而来，mix 任务命名空间至今仍是
mix pleroma.*，不存在mix akkoma.instance/mix akkoma.user这类任务名；mix help全表（见第二章）中akkoma前缀任务为零。OTP 发行版对应入口是./bin/pleroma_ctl <任务>，源码/编排部署则是mix <任务>。 - 编排部署下的执行方式：官方
docker-resources/manage.sh把任意命令透传进应用服务：
#!/bin/sh
docker compose run --rm akkoma $@
下文命令一律写成 ./docker-resources/manage.sh mix ... 形式；裸机源码部署直接 mix ...，OTP 部署换成 ./bin/pleroma_ctl ...。所有回显开头普遍有一行 fatal: No names found, cannot describe anything.（浅克隆仓库无 tag 导致 git describe 失败，无害），摘录时保留首见、后文从略。
二、任务总览（mix help 实测节选）
mix pleroma.app # Creates trusted OAuth App
mix pleroma.config # Manages the location of the config
mix pleroma.count_statuses # Re-counts statuses for all users
mix pleroma.database # A collection of database related tasks
mix pleroma.digest # Manages digest emails
mix pleroma.docs # Generates docs from descriptions.exs
mix pleroma.ecto.migrate # Wrapper on `ecto.migrate` task.
mix pleroma.emoji # Manages emoji packs
mix pleroma.frontend # Manages bundled Pleroma frontends
mix pleroma.instance # Manages Pleroma instance
mix pleroma.notification_settings # Enable&Disable privacy option for push notifications
mix pleroma.relay # Manages remote relays
mix pleroma.robots_txt # Generate robots.txt
mix pleroma.search # Manages elasticsearch
mix pleroma.security # Security-related tasks, like e.g. checking for signs past exploits were abused.
mix pleroma.uploads # Migrates uploads from local to remote storage
mix pleroma.user # Manages Pleroma users
除 pleroma.* 外，标准 Elixir 任务照常可用：mix ecto.migrate、mix phx.server、mix deps.get、mix compile 等（部署篇实测用的就是 mix ecto.migrate）。
三、mix pleroma.instance：实例配置生成
mix help pleroma.instance 实测输出的完整选项表：
* `-f`, `--force` - overwrite any output files
* `-o <path>`, `--output <path>` - the output file for the generated
configuration
* `--output-psql <path>` - the output file for the generated PostgreSQL
setup
* `--domain <domain>` - the domain of your instance
* `--instance-name <instance_name>` - the name of your instance
* `--admin-email <email>` - the email address of the instance admin
* `--notify-email <email>` - email address for notifications
* `--dbhost <hostname>` - the hostname of the PostgreSQL database to use
* `--dbname <database_name>` - the name of the database to use
* `--dbuser <username>` - the user (aka role) to use for the database
connection
* `--dbpass <password>` - the password to use for the database connection
* `--rum <Y|N>` - Whether to enable RUM indexes
* `--indexable <Y|N>` - Allow/disallow indexing site by search engines
* `--db-configurable <Y|N>` - Allow/disallow configuring instance from
admin part
* `--uploads-dir <path>` - the directory uploads go in when using a local
uploader
* `--static-dir <path>` - the directory custom public files should be
read from (custom emojis, frontend bundle overrides, robots.txt, etc.)
* `--listen-ip <ip>` - the IP the app should listen to, defaults to
127.0.0.1
* `--listen-port <port>` - the port the app should listen to, defaults to
4000
* `--strip-uploads-metadata <Y|N>` - use ExifTool to strip uploads of
metadata when possible
* `--read-uploads-description <Y|N>` - use ExifTool to read image
descriptions from uploads
* `--anonymize-uploads <Y|N>` - randomize uploaded filenames
* `--dedupe-uploads <Y|N>` - store files based on their hash to reduce
data storage requirements if duplicates are uploaded with different
filenames
* `--skip-release-env` - skip generation of the release environment file
* `--release-env-file` - release environment file path
官方说明：任何选项不给就进入交互式问答。实测执行与回显：
./docker-resources/manage.sh mix pleroma.instance gen
Writing config to config/generated_config.exs.
Writing the postgres script to config/setup_db.psql.
Writing /opt/akkoma/static/robots.txt.
All files successfully written! Refer to the installation instructions for your platform for next steps.
三个生成物的语义与逐项解说见配置篇第二、三章。
四、mix pleroma.user：用户管理
4.1 子命令全集（mix help 实测节选）
new（选项 --name/--bio/--password/--moderator/--admin/-y）、list、invite（--expires-at DATE、--max-use NUMBER）、invites、revoke_invite <token>、rm <nickname>、delete_activities <nickname>、sign_out <nickname>、activate、deactivate、deactivate_all_from_instance <instance>、reset_password、reset_mfa、set <nickname> [--admin/--confirmed/--locked/--moderator 及其 --no-* 反义]、tag、untag、confirm、confirm_all、unconfirm_all、fix_follow_state localuser remoteuser@example.com。
4.2 创建管理员（实测）
./docker-resources/manage.sh mix pleroma.user new root root@localhost --password q1w2e3r4 --admin -y
A user will be created with the following information:
- nickname: root
- email: root@localhost
- password: q1w2e3r4
- name: root
- bio:
- moderator: false
- admin: true
...
User root created
...
Admin status of root: true
实测行为确认：--password 给定则不再随机；-y 跳过 Continue? 确认；新用户 is_confirmed: true 免邮箱验证（INSERT 回显中可见）。
4.3 列出本地用户（实测）
./docker-resources/manage.sh mix pleroma.user list
root moderator: false, admin: true, locked: false, is_active: true
4.4 生成密码重置链接（实测）
./docker-resources/manage.sh mix pleroma.user reset_password root
Generated password reset token for root
URL: /api/v1/pleroma/password_reset/5TCC0bWVWvrFR7ZpeRTE0olv1vt6NEb0MIo6qU7fOiQ%3D
拼上实例域名打开该 URL 即可设新密码——忘记密码的 root 也能靠它救回。
4.5 权限位调整（set）与两个不存在/不支持的写法（排障实录）
正确用法只接受四个布尔开关（--admin/--confirmed/--locked/--moderator 及 --no-*）。实测两种错误姿势：
想改显示名而用 set --name：
** (MatchError) no match of right hand side value: {[], [], [{"--name", nil}]}
(pleroma 3.20.1-0-gbc62dd8) lib/mix/tasks/pleroma/user.ex:193: Mix.Tasks.Pleroma.User.run/1
想整体更新用户而用 update 子命令：
** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.User.run/1
The following arguments were given to Mix.Tasks.Pleroma.User.run/1:
# 1
["update", "root", "--name", "Akkoma", "Admin"]
Attempted function clauses (showing 10 out of 28):
def run(-["new", nickname, email | rest]-)
def run(-["rm", nickname]-)
def run(-["reset_password", nickname]-)
def run(-["reset_mfa", nickname]-)
def run(-["activate", nickname]-)
def run(-["deactivate", nickname]-)
def run(-["deactivate_all_from_instance", instance]-)
def run(-["set", nickname | rest]-)
def run(-["tag", nickname | tags]-)
def run(-["untag", nickname | tags]-)
...
(18 clauses not shown)
结论：CLI 改不了昵称/显示名/简介，这些走 Web 设置或 API；CLI 只管账号生命周期与权限位。
五、mix pleroma.config：数据库配置层
子命令族与语义（mix help pleroma.config 实测全文要点）：migrate_to_db、migrate_from_db [--env=<env>] [-d] [--path=<path>]、dump [group [key]]、groups、delete [--force] <group> [key]、[--force] reset、dump_to_file <group> <key> <path>、load_from_file <path>、filter_whitelisted。
关键前置条件（官方原文）：执行 migrate_to_db 前必须在文件配置里加 config :pleroma, configurable_from_database: true。实测未开启时的拒绝行为：
./docker-resources/manage.sh mix pleroma.config groups
ConfigDB not enabled. Please check the value of :configurable_from_database in your configuration.
dump_to_file/load_from_file 的用途官方说得很直白：批量改复杂值（典型是 MRF）时导出 JSON、编辑、再导入，比在管理 UI 里点更安全。双轨机制的完整解说见配置篇第九章。
六、mix pleroma.frontend：前端安装
mix help pleroma.frontend 实测要点：安装语法 frontend install <frontend> [--ref <ref>] [--file <file>] [--build-url <build-url>] [--path <path>] [--build-dir <build-dir>]；已知前端为 admin-fe、masto-fe、pleroma-fe（帮助原文如此，但见 6.2 的实测反差）；落盘模板 ${instance_static}/frontends/${name}/${ref}，且安装会整目录替换。
6.1 成功安装（实测）
./docker-resources/manage.sh mix pleroma.frontend install pleroma-fe --ref stable
Downloading pleroma-fe (stable)...
02:12:22.102 [info] Downloading pre-built bundle for pleroma-fe
02:12:22.113 [debug] Outbound: get https://akkoma-updates.s3-website.fr-par.scw.cloud/frontend/stable/akkoma-fe.zip
Installing pleroma-fe (stable) to /opt/akkoma/static/frontends/pleroma-fe/stable
Frontend pleroma-fe (stable) installed to /opt/akkoma/static/frontends/pleroma-fe/stable
6.2 三个实测坑
坑一：没有 list 子命令。 run/1 只有 install 两条函数子句：
** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.Frontend.run/1
Attempted function clauses (showing 2 out of 2):
def run(-["install", "none" | _args]-)
def run(-["install", frontend | args]-)
查看已装前端只能列目录：
static/frontends/:
admin-fe
mastodon-fe
pleroma-fe
坑二：masto-fe 装不上，mastodon-fe 才行。 用帮助文本里列的名字 masto-fe（那是仓库名）安装被拒：
** (RuntimeError) Configured third-party frontend without a bugtracker; refusing install.
(pleroma 3.20.1-0-gbc62dd8) lib/pleroma/frontend.ex:37: Pleroma.Frontend.install/2
改用配置 frontends.available 的键名即成功：
Downloading mastodon-fe (akkoma)...
03:18:44.375 [info] Downloading pre-built bundle for mastodon-fe
03:18:44.382 [debug] Outbound: get https://akkoma-updates.s3-website.fr-par.scw.cloud/frontend/akkoma/masto-fe.zip
Installing mastodon-fe (akkoma) to /opt/akkoma/static/frontends/mastodon-fe/akkoma
Frontend mastodon-fe (akkoma) installed to /opt/akkoma/static/frontends/mastodon-fe/akkoma
坑三：install none 子句存在——frontend install none 用于卸载/清空 primary 前端指向（源码子句之一），日常少用。
七、mix pleroma.database：数据库维护
mix help pleroma.database 实测输出的子命令全集：remove_embedded_objects [--vacuum]、prune_objects [option ...]、prune_orphaned_activities [--limit n] [--no-singles] [--no-arrays]、update_users_following_followers_counts、fix_likes_collections、vacuum analyze / vacuum full、ensure_expiration、set_text_search_config english、prune_task、clean_inlined_replies、resync_inlined_caches [--no-announcements --no-likes --no-reactions --no-replies-count]。
官方警示（帮助原文）："Do not run these tasks 'just in case' if everything is fine your instance." 最有运维价值的是远端贴文清理组合，帮助里给出的推荐起手式：
prune_objects --keep-followed posts --keep-threads --keep-non-public
# followed by
prune_orphaned_activities --no-singles
prune_orphaned_activities --no-arrays
# and finally, using psql to manually run:
# VACUUM ANALYZE;
# REINDEX TABLE objects;
# REINDEX TABLE activities;
prune_objects 按 :instance, remote_post_retention_days（默认 90 天）清理远端贴文；--vacuum 会跑 VACUUM FULL，帮助原文警告需预留约 1/3 库大小的空闲磁盘且期间实例基本不可用。中文/日文全文检索用 set_text_search_config（配合仓库 docs/configuration/howto_search_cjk.md）。
八、其余任务速览（含实测）
8.1 pleroma.relay
子命令 follow <relay_url> / unfollow <relay_url> / list。实测 relay list 首次执行会顺带把本地中继账号建出来（INSERT 回显 nickname: "relay", actor_type: "Application"），随后无待处理订阅时输出为空：
./docker-resources/manage.sh mix pleroma.relay list
（第二次执行：无任何输出，RC=0）
8.2 pleroma.emoji
子命令 ls-packs / get-packs <pack ...> / gen-pack PACK-URL / reload（reload 仅 OTP 可用）。实测 ls-packs 当前不可用（排障实录）：默认 manifest 仍指向 Pleroma 旧站，返回空体导致解码崩溃：
03:14:43.715 [debug] Outbound: get https://git.pleroma.social/pleroma/emoji-index/raw/master/index.json
** (Jason.DecodeError) unexpected end of input at position 0
(pleroma 3.20.1-0-gbc62dd8) lib/mix/tasks/pleroma/emoji.ex:18: Mix.Tasks.Pleroma.Emoji.run/1
用 -m/--manifest PATH/URL 指定可用 manifest 可绕过；自定义 emoji 更常见的路径是直接放 static/emoji/ 或走管理端。
8.3 pleroma.robots_txt
只有一个子句 disallow_all（实测传其他参数直接 FunctionClauseError）：
** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.RobotsTxt.run/1
Attempted function clauses (showing 1 out of 1):
def run(-["disallow_all"]-)
instance gen 时按 --indexable 已生成对应 robots.txt，实测当前内容（允许索引）：
User-Agent: *
Disallow:
8.4 pleroma.count_statuses / pleroma.digest / pleroma.uploads / pleroma.security
count_statuses：重算所有用户贴文计数，实测回显一行Done。digest test <nickname> [since_date]：向指定用户试发摘要邮件（依赖 SMTP 配置）。uploads migrate_local <target_uploader> [--delete]+uploads rewrite_media_domain <old_url> <new_url> [--dry-run]：本地→S3 迁移两连。security：mix help显示 "There is no documentation for this task"，用于排查历史漏洞利用痕迹。
8.5 pleroma.app：创建受信 OAuth 应用（实测）
./docker-resources/manage.sh mix pleroma.app create -n cli-demo -r urn:ietf:wg:oauth:2.0:oob
cli-demo successfully created:
App client_id: vUeWCF2ItTozx52nmqyUIr1SzBRYS-CQgW5jWEHeslE
App client_secret: UUsYLcgN9SYLk0xouBhNkvaOpyVaJ3IQ1zQOyMDd3ZA
默认 scopes 为 read, write, follow, push（INSERT 回显可见），-s 可改。建的是 trusted: true 应用，配合口令授权可免浏览器授权流——脚本化运维的入口。
九、CLI + API 联动：免交互发贴全链路实测
用上节 client_id/client_secret 走 Mastodon 兼容 OAuth 口令授权：
=== token ===
{"id":2,"scope":"read write follow","me":"https://localhost:8129/users/by-id/BC1W3JR9LKovXVNMoq","refresh_token":"9T0VM6LKeAGoybONFyck68Oo4bo0TPY-powbe0MSFuU","access_token":"hG0rbSU5O9pyWu5sHAY5A4LMCd16VCN6SGrb0b7nxbY","created_at":1793587571,"expires_in":3153600000,"token_type":"Bearer"}
=== verify ===
{"id": "BC1W3JR9LKovXVNMoq", "username": "root", "acct": "root", "statuses_count": 1, "created_at": "2026-11-02T02:12:08.000Z"}
=== post ===
{"id": "BC1Z71dW94SZBwHhK4", "created_at": "2026-11-02T02:46:25.000Z", "content": "Akkoma 3.20.1 deploy verified: OAuth password grant timeline OK", "visibility": "public", "url": "https://localhost:8129/notice/BC1Z71dW94SZBwHhK4"}
=== public tl ===
BC1Z71dW94SZBwHhK4 Akkoma 3.20.1 deploy verified: OAuth password grant timeline OK
BC1WA8mX5CkB09Dxbs Hello Akkoma from quzuo test <a class="hashtag" data-tag="akkomatest" href="http
=== home tl ===
BC1Z71dW94SZBwHhK4 Akkoma 3.20.1 deploy verified: OAuth password grant timeline OK
BC1WA8mX5CkB09Dxbs Hello Akkoma from quzuo test <a class="hashtag" data-tag="akkomatest" href="http
expires_in: 3153600000（100 年）说明受信应用 token 长期有效，适合备份脚本、监控脚本使用。
十、排障实录汇总
| # | 命令 | 现象 | 根因 | 处置 |
|---|---|---|---|---|
| 1 | mix akkoma.instance gen | 任务不存在 | Akkoma 保留 pleroma.* 命名空间 | 用 mix pleroma.instance gen |
| 2 | mix pleroma.user set root --name X | MatchError {[], [], [{"--name", nil}]} | set 无 --name 选项 | 昵称/显示名走 Web/API 改 |
| 3 | mix pleroma.user update ... | FunctionClauseError（28 子句无 update） | 无此子命令 | 用 set/tag/rm 等 |
| 4 | mix pleroma.frontend list | FunctionClauseError（仅 2 子句） | 无 list 子命令 | ls static/frontends/ |
| 5 | mix pleroma.frontend install masto-fe | refusing install（无 bugtracker） | 用了仓库名而非 available 键 | 改 mastodon-fe |
| 6 | mix pleroma.config groups | ConfigDB not enabled. | 总闸未开 | 文件里置 configurable_from_database: true |
| 7 | mix pleroma.emoji ls-packs | Jason.DecodeError | 默认 manifest 指向 Pleroma 旧站返回空 | -m 自定义 manifest |
| 8 | mix pleroma.robots_txt regenerate | FunctionClauseError | 仅实现 disallow_all | 重新 gen 或手改文件 |
十一、小结与关联
Akkoma 的 CLI 面继承自 Pleroma：mix pleroma.* 任务族覆盖实例生成、账号、配置双轨、前端、数据库维护全生命周期；帮助文本内嵌官方文档站片段（mix help pleroma.user 直接渲染 markdown 手册），./bin/pleroma_ctl 与 mix 两种前缀语义一致。运维记住三条实测铁律：改配置要重启、set 只管权限位、前端安装用 available 键名。
- 选型与架构背景：《Akkoma 3.20.1 介绍与选型指南》
- 部署全流程实测：《Akkoma 3.20.1 Docker Compose 部署指南》
- 配置参数逐项解说：《Akkoma 3.20.1 配置参数详解》