Mastodon 4.7.3 常用 CLI 命令详解

目标：把 Mastodon v4.7.3 的运维命令体系一次讲透——tootctl 全部命令组的逐条实测（含完整回显）与 rails/rake 运维任务，覆盖账号生命周期、缓存统计、媒体清理、域名封禁、内容维护、实例设置、升级辅助与销站工具。所有命令在 Ubuntu 22.04 + Mastodon 4.7.3 实测环境执行，回显逐行照抄。部署与配置背景见《Mastodon 4.7.3 Docker Compose 部署指南》(https://www.quzuo.net/document/rGlBZFpVtwc8) 与《Mastodon 4.7.3 配置参数详解》(https://www.quzuo.net/document/gKgvPIshrgaz)。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64），6 核 / 20GB 内存
Mastodon：v4.7.3（bin/tootctl version 回显 4.7.3）
数据库：PostgreSQL 14.24（库名 mastodon）；缓存/队列：Redis 7.4.11；Elasticsearch：未启用
实例域名：mastodon.local；实例内现有本地账号 1 个：admin（实测期间曾增删过 moderator/tmpuser 等测试账号，相关回显中的计数含义见对应小节说明）
命令统一入口：部署目录 /opt/mastodon 下 bin/tootctl <子命令>（Compose 形态前缀 docker compose exec -T web，已在本节下文命令中省略）
实例设置层基线：注册关闭（Setting.registrations_mode 回显 none）

二、命令体系概览

2.1 两大入口与调用方式

Mastodon 的运维命令分两大入口：

入口	定位	调用形态
`bin/tootctl`	日常运维主入口：账号/媒体/域名/缓存/设置/销站	`bin/tootctl <组> <子命令> [参数]`
`bin/rails`	框架级任务：密钥生成、迁移状态、实例初始化向导	`bin/rails <task>` 或 `bin/rails runner '<ruby>'`

所有命令在部署目录执行；任何组都可先看帮助：bin/tootctl <组> help <子命令>。

2.2 tootctl 顶层命令树

bin/tootctl tree 一次打印全部组与子命令（实测回显）：

mastodon:c_l_i:accounts
  ├─ approve (Approve pending accounts)
  ├─ backup (Request a backup for a user)
  ├─ create (Create a new user account)
  ├─ cull (Remove remote accounts that no longer exist)
  ├─ delete (Delete a user)
  ├─ fix_duplicates (Find duplicate remote accounts and merge them)
  ├─ follow (Make all local accounts follow account specified by USERNAME)
  ├─ merge (Merge two remote accounts into one)
  ├─ migrate (Migrate a local user to another account)
  ├─ modify (Modify a user account)
  ├─ prune (Prune remote accounts that never interacted with local users)
  ├─ refresh (Fetch remote user data and files)
  ├─ reset_relationships (Reset all follows and followers for a user)
  ├─ rotate (Generate and broadcast new keys)
  └─ unfollow (Make all local accounts unfollow account specified by ACCT)

💡 说明：tree 的输出按「组」分块（本节为 accounts 组），全部顶层组为 accounts / cache / canonical_email_blocks / domains / email_domain_blocks / emoji / feeds / ip_blocks / maintenance / media / preview_cards / search / self-destruct / settings / statuses / upgrade / version（bin/tootctl help 可列出顶层清单）。

2.3 版本与帮助

bin/tootctl version

实测回显：

4.7.3

三、账号管理组（accounts）

3.1 create：创建账号

bin/tootctl accounts create tmpuser --email tmpuser@mastodon.local --confirmed --approve

实测回显（随机密码每次不同，需记录）：

OK
New password: 84afbbeff5718e3c8624d74c93bf61fa

参数口径：--confirmed 跳过邮箱确认（创建即激活）；--approve 通过审批（注册模式为 approved 时必需）；--role Owner 绑定内置角色（可选 Owner/Admin/Moderator，角色名不符实测报 Cannot find user role with that name）。

⚠️ 命名规则踩坑实录：用户名只允许字母、数字、下划线，不含连字符——实测 accounts create tmp-user 直接失败：

Failure/Error: account.username
    invalid

改名 tmpuser 后创建成功（如上回显）。

3.2 modify：改邮箱/角色/锁定状态

bin/tootctl accounts help modify 的选项清单（实测回显）：

Usage:
  tootctl accounts modify USERNAME

Options:
  [--role=ROLE]                                                       
  [--remove-role], [--no-remove-role], [--skip-remove-role]           
  [--email=EMAIL]                                                     
  [--confirm], [--no-confirm], [--skip-confirm]                       
  [--enable], [--no-enable], [--skip-enable]                          
  [--disable], [--no-disable], [--skip-disable]                       
  [--disable-2fa], [--no-disable-2fa], [--skip-disable-2fa]           
  [--approve], [--no-approve], [--skip-approve]                       
  [--reset-password], [--no-reset-password], [--skip-reset-password]

实测改邮箱：

bin/tootctl accounts modify tmpuser --email tmpuser2@mastodon.local

实测回显：

OK

💡 说明：--reset-password 会替换为随机密码并打印在回显里；--disable 锁定账号（冻结登录）、--enable 解锁；--disable-2fa 摘除两步验证（账号被锁死时的自救通道）。

3.3 delete：删除账号

bin/tootctl accounts delete tmpuser

实测回显：

Deleting user with 0 statuses, this might take a while...
OK

3.4 backup / rotate：备份请求与密钥轮换

bin/tootctl accounts backup tmpuser

实测回显（归档在后台生成，完成后出现在导出页/存储 Backups 计数中）：

OK

bin/tootctl accounts rotate tmpuser

实测回显（轮换后向联邦广播新公钥，远端实例拉取更新）：

OK

3.5 follow / unfollow：全站关注开关

让全部本地账号关注/取关某个账号（联邦迁移、公告账号场景用）：

bin/tootctl accounts follow admin

实测回显：

OK, followed target from 2 accounts

bin/tootctl accounts unfollow admin

实测回显：

OK, unfollowed target from 1 accounts

💡 说明：计数为该命令遍历的本地账号记录数——实例内存在内部记录与已删除账号残留的 tombstone 记录时，数字会大于在用账号数（3.6 的核对查询可列出全部记录）。

3.6 cull / prune：远端账号清理

cull 清理「远端已不存在」的账号，prune 清理「从未与本地互动」的远端账号。本实例无远端账号，实测为空转回显：

bin/tootctl accounts cull

实测回显：

Progress: |====================================================================|
Visited 0 accounts, removed 0

bin/tootctl accounts prune

实测回显：

Progress: |====================================================================|
OK, pruned 0 accounts

核对账号清单（tootctl 没有账号列表命令，直接查库最直接）：

psql -U postgres -d mastodon -c "select a.id, a.username, (u.id is not null) as has_user from accounts a left join users u on u.account_id=a.id where a.domain is null order by a.id;"

实测回显：

         id         |     username      | has_user 
--------------------+-------------------+----------
                -99 | mastodon.internal | f
 117509968321287485 | admin             | t
 117510106118726463 | moderator         | f
 117510220121800788 | tmpuser           | f

（has_user=f 的行即已删账号的残留记录与内部 actor mastodon.internal。）

四、缓存与统计组（cache）

4.1 recount：重建互动计数缓存

bin/tootctl cache recount statuses

实测回显：

OK, recounted 5 records

（转发/点赞等计数与真实行数对齐；实例数据量大时该命令耗时可预估。）

4.2 clear：清空缓存

bin/tootctl cache clear

实测回显：

OK

五、媒体与表情组（media / emoji）

5.1 media usage：媒体占用统计

bin/tootctl media usage

实测回显：

Object         Total    Local
Attachments    5.92 KB  5.92 KB
Custom Emoji   0 Bytes  0 Bytes
Avatars        0 Bytes  0 Bytes
Headers        0 Bytes  0 Bytes
Preview Cards  0 Bytes  
Backups        7.69 KB  
Settings       0 Bytes

5.2 media remove：清理远端媒体缓存

bin/tootctl media remove --days=0 --dry-run

实测回显：

Progress: |====================================================================|
Removed 0 media attachments (approx. 0 Bytes) (DRY RUN)

💡 说明：该命令清理的是远端媒体在本地缓存副本（不影响本地原创媒体），--days 默认 7；--prune-profiles/--remove-headers 扩展到远端头像与横幅；始终先用 --dry-run 预演是安全实践。完整参数见 bin/tootctl media help remove。

5.3 emoji purge：清空自定义表情缓存

bin/tootctl emoji purge

实测回显：

OK

5.4 emoji export：导出自定义表情包

mkdir -p /tmp/emoji-out
bin/tootctl emoji export /tmp/emoji-out --overwrite
ls -la /tmp/emoji-out/

实测回显：

Exported 0
-rw-r--r-- 1 mastodon mastodon   35 Oct 27 01:12 export.tar.gz

⚠️ 踩坑实录：路径参数被当作目录处理（导出文件固定命名为 export.tar.gz 落在该目录下）——实测传入完整文件路径 /tmp/emoji-export.tar.gz 时直接报错：

No such file or directory @ rb_sysopen - /tmp/emoji-export.tar.gz/export.tar.gz

六、域名与封禁组（domains / email_domain_blocks / ip_blocks / canonical_email_blocks）

6.1 domains crawl：联邦发现统计

bin/tootctl domains crawl

实测回显（单实例无已知远端域）：

Progress: ||
Visited 0 domains, 0 failed (20s elapsed)
Total servers: 0
Total registered: 0

6.2 domains purge：清除某域的全部本地缓存

bin/tootctl domains purge nonexistent.example

实测回显：

Progress: |====================================================================|
Removed 0 accounts
Removed 0 custom emojis

6.3 email_domain_blocks：邮箱域封禁（反垃圾注册）

bin/tootctl email_domain_blocks add blocked-mail.example
bin/tootctl email_domain_blocks list
bin/tootctl email_domain_blocks remove blocked-mail.example

实测回显（依次）：

Added 1, skipped 0

blocked-mail.example

Removed 1, skipped 0, failed 0

6.4 ip_blocks：IP 封禁

bin/tootctl ip_blocks add 203.0.113.0/24 --severity no_access --comment 'doc-demo'
bin/tootctl ip_blocks export
bin/tootctl ip_blocks remove 203.0.113.0/24

实测回显（依次）：

Added 1, skipped 0, failed 0

203.0.113.0/24

Removed 1, skipped 0

💡 说明：--severity 三档——no_access（完全拒绝）、sign_up_requires_approval（可登录但注册需审批）、sign_up_block（仅禁止注册）；export 输出可直接喂给其他网关工具。与配置层 EMAIL_DOMAIN_ALLOWLIST（放行白名单，见配置篇 3.9）方向相反，本组是拒绝清单。

6.5 canonical_email_blocks：规范化邮箱封禁

bin/tootctl canonical_email_blocks find test@mastodon.local

实测回显：

test@mastodon.local is not blocked

（该组封的是「规范化后的邮箱地址」——同一邮箱加 +后缀、加点号变体也会被识别拦截，专治滥用注册的邮箱变体伎俩。）

七、内容与搜索组（statuses / preview_cards / search）

7.1 statuses remove：清理久远未引用帖子

bin/tootctl statuses remove

实测回显：

Progress: |====================================================================|
Done after 0.029016971588134766s, removed 0 out of 0 conversations.
Removing temporary database indices to restore write performance...
Running "ANALYZE conversations"...

💡 说明：默认清理超过 90 天的本地非置顶帖子（可 --days=N 调整），执行期间会先建临时索引、结束时重建并 ANALYZE——数据量大时是重操作，安排在低峰执行。

7.2 preview_cards remove：清理链接预览缓存

bin/tootctl preview_cards remove

实测回显：

Progress: |====================================================================|
Removed media from 0 preview cards (approx. 0 Bytes)

7.3 search deploy：重建搜索索引

bin/tootctl search deploy

实测回显（ES 未启用时的报错，首行）：

Connection refused - Connection refused - connect(2) for "localhost" port 9200 (localhost:9200) (Elastic::Transport::Transport::Error)

⚠️ 说明：该命令只服务于 Elasticsearch 全文搜索——未启用 ES（ES_ENABLED=false）的实例无需也不能执行；启用路径见配置篇 3.6。

八、设置与维护组（settings / feeds / upgrade / self-destruct / maintenance）

8.1 settings：实例设置（立即生效）

bin/tootctl settings help

实测回显：

Commands:
  tootctl settings help [COMMAND]                    # Describe subcommands o...
  tootctl settings registrations SUBCOMMAND ...ARGS  # Manage state of regist...
  tootctl settings tree                              # Print a tree of all av...

注册开关三态实测（open → close，含读回验证，完整过程见配置篇 2.2）：

bin/tootctl settings registrations open     # OK / Opened registrations
bin/tootctl settings registrations close    # OK / Closed registrations
bin/rails runner "puts Setting.registrations_mode"   # none

（第三态 approved 为「注册需人工审批」。）

8.2 feeds：重建时间线

bin/tootctl feeds build admin

实测回显：

OK

（重建指定账号或全部账号的首页时间线缓存；时间线异常空白时的第一修复手段。）

8.3 upgrade：存储模式升级

bin/tootctl upgrade help storage-schema

实测回显：

Usage:
  tootctl upgrade storage-schema

Options:
      [--dry-run], [--no-dry-run], [--skip-dry-run]  
                                                     # Default: false
  -v, [--verbose], [--no-verbose], [--skip-verbose]  
                                                     # Default: false

（把旧版文件存储路径迁移到 v4.x 统一模式，跨大版本升级后按需执行；本实测 4.7.3 全新部署无需执行。）

8.4 self-destruct：销站工具（只可帮助，不可随手执行）

bin/tootctl help self-destruct

实测回显：

Usage:
  tootctl self-destruct

Description:
  Erase the server from the federation by broadcasting account delete
  activities to all known other servers. This allows a "clean exit" from
  running a Mastodon server, as it leaves next to no cache behind on other
  servers.

⚠️ 该命令会向全联邦广播删除本站全部账号并清空本地数据，属不可逆操作（且要求持有 LOCAL_DOMAIN 域名邮箱以完成交互确认），本实测仅采集帮助输出、未执行。正常运维中它只应出现在「永久关站」的最后一步。

九、rails/rake 运维命令

9.1 密钥生成三件套

bin/rails secret

实测回显（128 位十六进制串，每跑一次一条，用于 SECRET_KEY_BASE / OTP_SECRET）：

a97e0042af2aeacb969f23dcf582d10c89782dbeab1b56c5a739def5ea96cfc234bd17ba7bf27c9ab01c21041c46d8c1f9bf15b09b80f30d58a37a7e286246c9

bin/rails mastodon:webpush:generate_vapid_key

实测回显（一次一对）：

VAPID_PRIVATE_KEY=sPE_epR0kkkBjn0tP5IHnL9mKry1-oI9OyFbCVBtQP4=
VAPID_PUBLIC_KEY=BDb3Q9IWqpgNkubHJN7mTSiV-Ak4vyQo5A5jBD8ZEjWFXb1rTkXf25iICAhSyrpRaLdBFoMItWV7sBJjUO4Olqo=

bin/rails db:encryption:init

实测回显（已配置密钥时的保护性拒绝，生成新密钥需 IGNORE_ALREADY_SET_SECRETS=true 前缀，运行中实例严禁）：

Secrets for this server have already been set, this step can likely be ignored!
In the unlikely event you need to generate new secrets, re-run this command with `IGNORE_ALREADY_SET_SECRETS=true`.

9.2 迁移状态核查

bin/rails db:migrate:status

实测回显（头尾节选，全量 500+ 行）：

database: mastodon

 Status   Migration ID    Migration Name
--------------------------------------------------
   up     20160220174730  Create accounts

   up     20260803172525  Add target account index to follow requests
   up     20260804081821  Convert materialized views to tables
   up     20260805130216  Fix generated annual reports foreign key
   up     20260812154114  Remove index keypairs on account

（版本跨度一目了然：迁移号从 2016 到 2026；down 状态行即未落库的迁移，升级后核查必看。）

9.3 任务清单与初始化向导

bin/rails -T | grep mastodon:

实测回显：

bin/rails mastodon:setup                       # Configure the instance for production use
bin/rails mastodon:webpush:generate_vapid_key  # Generate VAPID key

（mastodon:setup 是交互式安装向导——逐项询问域名、数据库、SMTP 并自动写入 .env.production，全新部署的图形化替代路径；本文实测采用手工写配置方式，二者产物等价。）

9.4 rails runner：一线运维的瑞士军刀

任意 Ruby 在应用环境内执行，四个高频实战（回显均为实测原文）：

核验账号密码（改密后自查）：

bin/rails runner "puts User.find_by(email:'admin@mastodon.local').valid_password?('q1w2e3r4')"

实测回显：

true

设置固定密码（随机密码改为已知值）：

bin/rails runner "u=User.find_by(email:'admin@mastodon.local'); u.password='q1w2e3r4'; u.save!; puts 'saved'"

实测回显：

saved

读实例设置：

bin/rails runner "puts Setting.registrations_mode"

实测回显：

none

为管理员签发 API 令牌（4.7.3 默认关闭密码授权流，控制台签发是最直接的测试通道；应用凭据来自 POST /api/v1/apps 的注册回显）：

bin/rails runner "app=Doorkeeper::Application.find_by(name:'tootctl-test'); u=User.find_by(email:'admin@mastodon.local'); t=Doorkeeper::AccessToken.create_for(application: app, resource_owner: u, scopes: 'read write'); puts t.token"

实测回显（令牌示例）：

DN7osteeiaOPz8IIpB32yNVpc-n7Pez8fqN5CW0Rw_A

签发后立即经 verify_credentials 核验身份（实测回显：admin Owner statuses: 5）。

十、命令选择建议

场景	首选命令	备选/关联
新建管理员/测试账号	`accounts create ... --confirmed --role Owner`	`rails runner` 改密（9.4）
账号锁定/解锁/摘 2FA	`accounts modify ... --disable/--enable/--disable-2fa`	—
用户自助导出数据	`accounts backup`	—
时间线异常空白	`feeds build <用户>`	`cache recount statuses`
计数与真实数据不一致	`cache recount <类型>`	—
磁盘紧张	`media usage` 先看占用 → `media remove --dry-run` 预演	`preview_cards remove`
防垃圾注册	`email_domain_blocks add` / `canonical_email_blocks`	注册开关 `settings registrations`
恶意来源封禁	`ip_blocks add --severity`	`ip_blocks export` 复用清单
开关联邦搜索	`search deploy`（ES 启用后）	配置篇 3.6
版本升级核查	`rails db:migrate:status`	`upgrade storage-schema`
全部清点/定位	`tootctl tree` + `rails -T`	—

十一、常见问题

Q1：命令前缀为什么是 docker compose run --rm web 或 docker compose exec -T web？ Mastodon 应用本体在 web 服务进程的工作目录内，tootctl/rails 必须在 /opt/mastodon 环境中执行。一次性任务用 run --rm（自带独立进程，结束即清理），对运行中服务附加操作用 exec -T；源码部署形态则直接 cd /opt/mastodon && bin/tootctl ...，命令本体完全一致。

Q2：accounts create 报 Failure/Error: account.username invalid？ 用户名含连字符等非法字符（3.1 实测）——只允许字母、数字、下划线。注意与电子邮件地址规则区分。

Q3：accounts create 时 --role Owner 报 Cannot find user role with that name？ 角色名必须精确匹配内置值 Owner / Admin / Moderator（区分大小写），详见部署篇 4.7 实录。

Q4：哪条命令清空了全部数据？怎么安全销站？ 没有任何常规运维命令会清库——media remove/statuses remove 等都有明确边界且建议先 --dry-run。唯一的全站清除工具是 self-destruct（8.4），仅在永久关站时使用。

Q5：emoji export 报 No such file or directory .../export.tar.gz？ 路径参数必须是目录，导出文件固定落 <目录>/export.tar.gz（5.4 实录）；目录不存在时先 mkdir -p。

Q6：删除过的账号还会出现在哪些统计里？ 账号删除保留 tombstone 记录（3.6 的 psql 核对可见 has_user=f 行），accounts follow/unfollow 等全站遍历命令的计数会包含这些记录（3.5 说明）。

十二、参考链接

官方 tootctl 文档：https://docs.joinmastodon.org/admin/tootctl/
官方升级指引（含 upgrade/storage-schema 口径）：https://docs.joinmastodon.org/admin/upgrading/
本专栏认知篇：《Mastodon 4.7.3 介绍与选型指南》(https://www.quzuo.net/document/gzKZrJqqJRK5)
本专栏部署篇：《Mastodon 4.7.3 Docker Compose 部署指南》(https://www.quzuo.net/document/rGlBZFpVtwc8)
本专栏配置篇：《Mastodon 4.7.3 配置参数详解》(https://www.quzuo.net/document/gKgvPIshrgaz)