Misskey 2026.10.1 常用 CLI 命令与工具详解

目标：把 Misskey 2026.10.1 部署后能用上的命令行工具全部实测一遍——内置 CLI 的真实命令面（比想象中小得多）、官方文档与产物入口的差异、pnpm 脚本形态的迁移/连接检查工具、psql/redis-cli 直查手段，以及「CLI + API 免交互发贴」联动链路。全部命令与回显均为 2026-11-02 在部署篇实例上实测。部署过程见《Misskey 2026.10.1 Docker Compose 部署指南》，参数含义见《Misskey 2026.10.1 配置参数详解》。

一、环境信息与 CLI 入口

载体：部署篇的 web 服务（预构建产物 misskey/misskey:2026.10.1，Node.js v26.12.1，应用目录 /misskey，运行用户 UID/GID 991）。
官方文档的 CLI 口径（misskey-hub Docker 安装页"How to execute CLI command"，实测摘录）：
```
sudo docker compose run --rm web node packages/backend/built/tools/foo bar
```
这是泛化占位示例（tools/foo bar 为示意路径）。本产物实测的编译入口是 packages/backend/built/cli.js，以下均以实测入口为准。
本文实测可用的 CLI 入口（进入 web 服务执行）：
```
docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js <命令>'
```
-r reflect-metadata 是必须显式携带的预加载（原因见第三章崩溃实录）。

💡 技术拓展：进入容器化应用执行管理命令的常见通道对比——

通道形态特点
docker exec（本文）在运行中实例内执行与线上同进程环境、同配置快照
docker compose run --rm（官方文档）起一次性新实例执行后销毁隔离好，但多花一次容器启动
宿主安装 CLI 应用无独立 CLI 包 Misskey 不适用（CLI 在产物内）
API 直连 curl + token 不依赖容器通道，可远程运维

Misskey 内置 CLI 面很小（第二章），日常运维主力实际是第三、四章的 pnpm 脚本与第九章的 API 通道。

通道	形态	特点
`docker exec`（本文）	在运行中实例内执行	与线上同进程环境、同配置快照
`docker compose run --rm`（官方文档）	起一次性新实例执行后销毁	隔离好，但多花一次容器启动
宿主安装 CLI	应用无独立 CLI 包	Misskey 不适用（CLI 在产物内）
API 直连	curl + token	不依赖容器通道，可远程运维

二、内置 CLI 命令全集（实测 + 源码核对）

CLI 源码（产物内 packages/backend/src/cli.ts，实测核对）是一个 switch 分发，全部命令只有三个：

命令	源码行为	help 中是否列出
`help`	打印可用命令清单	—
`ping`	`CommandService.ping()` 打印 `pong`	否（help 清单漏列）
`reset-captcha`	清空 meta 中全部验证码配置	是
其他任意值	`Unrecognized command` + `process.exit(1)`	—

注意两点实测认知：其一，ping 可用但 help 不列（help 只印 help/reset-captcha 两行）；其二，CLI 启动会完整初始化 Nest 应用上下文（连 DB/Redis），每条命令前都带一串启动日志，耗时约 1 秒。

2.1 help（实测）

docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js help'

实测回显（节选，Nest 初始化行略去中间重复项）：

INFO *	[core.nest]	NestFactory: Starting Nest application...
INFO *	[core.nest]	InstanceLoader: QueueModule dependencies initialized
INFO *	[core.nest]	InstanceLoader: RepositoryModule dependencies initialized
INFO *	[core.nest]	InstanceLoader: CommandModule dependencies initialized
INFO *	[core.nest]	InstanceLoader: GlobalModule dependencies initialized
INFO *	[SearchService]	-- Provider: sqlLike
INFO *	[core.nest]	InstanceLoader: CoreModule dependencies initialized
Available commands:
  help - Displays this help message
  reset-captcha - Resets the captcha

Provider: sqlLike 顺带确认全文搜索配置已生效（配置篇第六章）。

2.2 ping（实测）

docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js ping'

回显尾部：

pong

ping/pong 是「CLI 通道 + DB/Redis 连接全通」的最快自检（Nest 上下文初始化成功即隐含连接可用）。

2.3 reset-captcha（实测）

docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js reset-captcha'

回显尾部：

Captcha has been reset.

源码行为（CommandService.resetCaptcha() 实测核对）：经 MetaService.update 把 hCaptcha / mCaptcha / reCAPTCHA / Turnstile / Testcaptcha 五套验证码的 enable 位与 key 全部清空——典型场景：管理面板配错验证码参数导致登录页卡死、无法进面板自救时，用这条命令把验证码层复位。

2.4 未知命令（实测）

docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js not-a-command'

回显尾部：

Unrecognized command: not-a-command
Use "help" to see available commands.

退出码非 0（源码 process.exit(1)）。

三、pnpm run cli 崩溃实录（Node 26 产物缺陷）

产物 package.json 里有 cli 脚本（pnpm compile-config && node ./built/cli.js），直觉上应该优先用它，实测必崩：

docker exec misskey-web sh -c 'cd /misskey/packages/backend && pnpm cli help'

实测回显（节选，中间为压缩 bundle 源码行）：

$ pnpm compile-config && node ./built/cli.js help
$ node ./scripts/compile_config.js
/misskey/.config/default.yml → /misskey/built/.config.json
Configuration compiled ✓
file:///misskey/packages/backend/built/common-CnVkpb5e.js:1
...
TypeError: Reflect.getOwnMetadata is not a function
    at file:///misskey/packages/backend/built/common-CnVkpb5e.js:1:2695
    at file:///misskey/packages/backend/built/tslib.es6-DN0uNiw9.js:1:2130
    at __decorate (file:///misskey/packages/backend/built/tslib.es6-DN0uNiw9.js:1:2011)
    at ModuleJob.run (node:internal/modules/esm/module_job:569:25)

Node.js v26.12.1
[ELIFECYCLE] Command failed with exit code 1.

根因定位（实测源码 + 对照实验）：cli.ts 首行 import 'reflect-metadata'，但产物经 rolldown 打包后该导入在 ESM 求值序列中未先于 Nest 装饰器代码生效，Reflect.getOwnMetadata polyfill 缺失即崩。修复就是第一章入口里的 -r reflect-metadata——让 Node 在入口模块前预加载 polyfill：

node -r reflect-metadata ./built/cli.js help   # ✓ 正常
pnpm cli help                                  # ✗ TypeError: Reflect.getOwnMetadata is not a function

⚠️ 要点：这是「Node 26 + rolldown 打包 + reflect-metadata」组合的产物级缺陷，Web 主进程（pnpm run start 通道）不受影响；只有走 built/cli.js 的 CLI 需要预加载参数。

四、连接检查：check:connect 不是 CLI 子命令（排障实录）

想复用 CLI 做连通性检查，把 pnpm 脚本名当子命令传入，实测失败：

docker exec misskey-web sh -c 'cd /misskey/packages/backend && node -r reflect-metadata ./built/cli.js check:connect'

Unrecognized command: check:connect
Use "help" to see available commands.

check:connect 实为 pnpm 脚本（package.json 定义 pnpm compile-config && node ./scripts/check_connect.js）：

docker exec misskey-web sh -c 'cd /misskey/packages/backend && pnpm check:connect'

实测回显：

$ pnpm compile-config && node ./scripts/check_connect.js
$ node ./scripts/compile_config.js
/misskey/.config/default.yml → /misskey/built/.config.json
Configuration compiled ✓

脚本静默通过、退出码 0（实测 RC=0）——无报错即 DB/Redis 全通。与第二章 ping 的取舍：check:connect 不拉 Nest 上下文、更快更轻；ping 验证的是完整应用装配。

五、迁移与配置编译工具链

首启/升级的数据层动作全部由产物脚本承担（部署篇 9.2 节实测），手工执行入口：

脚本	实测命令	行为
配置编译	`pnpm compile-config`	`.config/default.yml → built/.config.json`（配置篇二章）
迁移	`pnpm typeorm migration:run -d ormconfig.js`	TypeORM 按 `built/.config.json` 连库执行增量迁移
迁移+启动（CMD）	`pnpm run migrateandstart`	上两步串联 + 拉起服务，即容器默认命令

ormconfig.js（产物根目录，实测核对）关键事实：

const isConcurrentIndexMigrationEnabled = process.env.MISSKEY_MIGRATION_CREATE_INDEX_CONCURRENTLY === '1';
...
migrationsTransactionMode: isConcurrentIndexMigrationEnabled ? 'each' : 'all',

数据源参数直接复用 loadConfig()（与主进程同一份配置快照，不存在「CLI 连错库」的口径分裂）；
大实例升级建议设 MISSKEY_MIGRATION_CREATE_INDEX_CONCURRENTLY=1：迁移事务模式从「全部一个事务」改为「每迁移一事务」，配合迁移内并发建索引，降低锁表窗口（配置篇 2.2 节 env 表）。

手工触发一次迁移（实测，已最新时空跑）：

docker exec misskey-web sh -c 'cd /misskey/packages/backend && pnpm typeorm migration:run -d ormconfig.js' 2>&1 | tail -3

No migrations are pending

六、psql 直查手册（PostgreSQL 18.6）

数据库直查走 db 服务（凭据来自 docker.env）：

docker exec misskey-db psql -U misskey -d misskey -tAc "select version();"

PostgreSQL 18.6 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit

高频运维查询（全部实测）：

# 业务表总数（首启 349 迁移的落地规模）
docker exec misskey-db psql -U misskey -d misskey -tAc \
  "select count(*) from pg_tables where schemaname='public';"
# → 117

# 已执行迁移数
docker exec misskey-db psql -U misskey -d misskey -tAc "select count(*) from migrations;"
# → 349

# 贴文数
docker exec misskey-db psql -U misskey -d misskey -tAc "select count(*) from note;"
# → 2

# 用户表结构核对
docker exec misskey-db psql -U misskey -d misskey -c '\d "user"' | head -8

                                             Table "public.user"
            Column            |           Type           | Collation | Nullable |           Default           
------------------------------+--------------------------+-----------+----------+-----------------------------
 id                           | character varying(32)    |           | not null | 
 updatedAt                    | timestamp with time zone |           |          | 
 lastFetchedAt                | timestamp with time zone |           |          | 
 username                     | character varying(128)   |           | not null |

⚠️ 排障实录：select id, username, isBot from user;（不带引号）实测报错：
ERROR:  column "id" does not exist
LINE 1: SELECT id, username, "isBot" FROM user;
               ^
根因：user 是 PostgreSQL 保留字，裸写被解析到系统视图 pg_user 系。表名必须 "user" 加引号，驼峰列名同样要引号（"isBot"）。管理员标记也不在 "user" 表列中——role/role_assignment 表实测为空表（本地管理员走 API 层 isAdmin 字段，见第九章 /api/i 回显）。

七、redis-cli 直查手册（Redis 7.4.12）

docker exec misskey-redis redis-cli ping
# → PONG

docker exec misskey-redis redis-cli info server | sed -n '2,6p'

redis_version:7.4.12
redis_git_sha1:00000000
redis_git_dirty:0
redis_build_id:a3bb3c7b72c4210a
redis_mode:standalone

docker exec misskey-redis redis-cli DBSIZE
# → 65

docker exec misskey-redis redis-cli KEYS '*' | head -6

127.0.0.1:8138:queue:db:db:stalled-check
127.0.0.1:8138:queue:system:system:repeat:checkExpiredMutings:1793607900000
127.0.0.1:8138:limit:ip-2vdb0h:signin:min
127.0.0.1:8138:queue:system:system:id
127.0.0.1:8138:queue:objectStorage:objectStorage:meta
127.0.0.1:8138:queue:system:system:repeat:cleanCharts:1793664000000

键空间速读（实测归纳）：

前缀模式	内容	运维含义
`<url-host>:queue:<队列>:...`	BullMQ 作业队列（system/db/objectStorage/userlist 等）	积压排查入口；`stalled-check`/`repeat:` 为心跳与定时作业
`<url-host>:list:userTimeline:*`	时间线列表缓存	清缓存 = 删对应用户键
`<url-host>:limit:ip-*:signin:min`	登录按 IP 分钟限流状态	429 锁定的直接证据（部署篇第十一章）

前缀即实例 host（配置篇第五章 prefix 默认值行为），多实例共用 Redis 时靠它天然隔离。

八、其余运维通道速览

管理面板：登录后访问 /admin（浏览器通道，实例设置/用户管理/审核等全部业务策略项在这里，与 default.yml 文件参数正交）；
日志：docker logs misskey-web（access 日志需配置篇第十章 statusClasses 开启，实测 4xx/5xx 行可直接 grep）；
备份：停写窗口下打包 ./db、./files、./redis、.config 四目录即可整体迁移（bind 挂载布局的意义，部署篇第五章）。

九、CLI + API 联动：免交互发贴全链路实测

内置 CLI 不管业务数据，日常「脚本化运维」实际走 API 通道。全链路四步（全部实测回显）：

第 1 步登录取 token（口令 q1w2e3r4，演示账号 root）：

curl -s -X POST http://127.0.0.1:8138/api/signin-flow \
  -H 'Content-Type: application/json' \
  -d '{"username":"root","password":"q1w2e3r4"}'

{"finished":true,"id":"at2j3aq0wb6e0003","i":"lTWbYiUooUCjelCZ"}

第 2 步身份与权限核对：

curl -s -X POST http://127.0.0.1:8138/api/i \
  -H 'Content-Type: application/json' -d '{"i":"lTWbYiUooUCjelCZ"}'

{"id": "at2j3aq0wb6e0003", "username": "root", "isAdmin": true, "isModerator": true, "notesCount": 1, "createdAt": "2026-11-02T07:55:27.624Z"}

第 3 步发贴：

curl -s -X POST http://127.0.0.1:8138/api/notes/create \
  -H 'Content-Type: application/json' \
  -d '{"i":"lTWbYiUooUCjelCZ","text":"Misskey 2026.10.1 deploy verified via API"}'

{"createdNote":{"id":"at2kj3wqcfdt0003","createdAt":"2026-11-02T08:35:44.906Z","userId":"at2j3aq0wb6e0003","text":"Misskey 2026.10.1 deploy verified via API","visibility":"public","renoteCount":0,"repliesCount":0,"reactionCount":0,"fileIds":[],"files":[]}}

（输出节选，实测首尾；user 子对象字段略。）

第 4 步落盘复核（psql）：

docker exec misskey-db psql -U misskey -d misskey -tAc "select count(*) from note;"

API 发贴 → 数据库计数 +1，闭环成立。

⚠️ 排障实录：限流窗口。第 1 步之前若有多次错口令尝试，正确请求也会返回 429（TOO_MANY_AUTHENTICATION_FAILURES，实测见部署篇第十一章）——脚本化调用务必先确认 limit:ip-*:signin:min 键已过期，或为自动化单独签发 token（管理面板「注册应用」通道）避免走口令登录。

十、排障实录汇总

#	现象	根因	处置
1	`pnpm cli help` 崩溃 `TypeError: Reflect.getOwnMetadata is not a function`	Node 26 + rolldown 打包下 reflect-metadata 预加载失效	改 `node -r reflect-metadata ./built/cli.js` 直调
2	CLI `help` 里没有 ping，以为 ping 不存在	源码 help 清单漏列	直接跑 `ping`，实测输出 `pong`
3	`cli.js check:connect` 报 `Unrecognized command`	它是 pnpm 脚本不是 CLI 子命令	`pnpm check:connect`（RC=0 静默即通过）
4	官方文档 CLI 路径 `built/tools/foo bar` 找不到	文档为泛化占位示例	实际入口 `packages/backend/built/cli.js`
5	`from user` 报 `column "id" does not exist`	PG 保留字	`"user"` 加引号
6	在 `"user"` 表找管理员标记找不到列	本地管理员走 API 层/角色体系	`POST /api/i` 看 `isAdmin`
7	正确口令登录 429	按 IP 分钟级限流（Redis `limit:ip-*:signin:min`）	等窗口过期；自动化改用固定 token
8	每条 CLI 命令都刷一屏 Nest 日志、耗时 ~1s	CLI 完整初始化应用上下文	属正常；只要轻检查用 `pnpm check:connect`

十一、小结与关联

Misskey 2026.10.1 的「CLI」真实构成是三层：内置 cli.js 只有 help/ping/reset-captcha（且需要 -r reflect-metadata 补丁式入口）、运维动作主体是 pnpm 脚本（compile-config / typeorm migration / check:connect，全部幂等可重放）、业务操作走全 POST API（signin-flow 拿 token → 任意端点）。psql/redis-cli 直查补齐观测面：117 表、349 迁移、<host>: 前缀键空间是三个最常引用的基线数。

部署全过程：《Misskey 2026.10.1 Docker Compose 部署指南》
参数含义与生效实测：《Misskey 2026.10.1 配置参数详解》
选型与架构背景：《Misskey 2026.10.1 介绍与选型指南》

参考链接

官方仓库：https://github.com/misskey-dev/misskey（packages/backend/src/cli.ts、CommandService.ts、ormconfig.js）
官方 Docker 安装文档（CLI 一节）：https://misskey-hub.net/docs/for-admin/install/guides/docker/
TypeORM 迁移文档：https://typeorm.io/migrations
BullMQ：https://docs.bullmq.io/（Redis queue:* 键结构）
PostgreSQL 保留字：https://www.postgresql.org/docs/current/sql-keywords-appendix.html