Iceshrimp.NET v2026.1.3-beta 常用 CLI 命令与工具详解

本文逐项实测 Iceshrimp.NET 后端自带 CLI 的全部子命令（--help 所列 16 项），并整理配套 Web 管理工具与数据库维护命令。全部回显为 2026-11-02 实测记录，环境为《Iceshrimp.NET v2026.1.3-beta Docker Compose 部署指南》所建部署（示例账号 root，管理员）。选型背景见《Iceshrimp.NET v2026.1.3-beta 介绍与选型指南》，配置参数含义见《Iceshrimp.NET v2026.1.3-beta 配置参数详解》。

一、命令入口

1.1 统一入口

Iceshrimp.NET 没有独立的命令行程序，全部维护命令由后端主程序 Iceshrimp.Backend 的启动参数承担。官方 deploying-to-docker 页给出的 Compose 场景标准入口（实测可用）：

docker compose run --entrypoint ./Iceshrimp.Backend web <命令或选项>

本文实测均在命令中加了 --rm（一次性执行后自动清理运行实例）。裸机部署直接 ./Iceshrimp.Backend <命令>；systemd 场景临时停服执行即可。

1.2 共性行为

任何子命令执行时都会先走同一段初始化（实测回显）：

info: [core] Iceshrimp.Backend > Iceshrimp.NET v2026.1.3-beta+a998dc6e57, codename "phenidate" (example.test)
info: [core] Iceshrimp.Backend > Validating configuration...
info: [core] Iceshrimp.Backend > Verifying database connection...

即：每条维护命令都会完整校验配置并连接数据库，配置错误会在这里直接失败（数据库连接失败的排障实录见部署篇 11.3）。涉及媒体管线的命令还会多一行处理器声明：

info: [core] Iceshrimp.Backend.Core.Services.ImageProcessing.ImageProcessor > Using [LibVips, ImageSharp] for image processing.

1.3 帮助信息（实测全文）

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --help

实测回显（逐行照抄）：

Usage: ./Iceshrimp.Backend [options...]

General options & commands:
 -h, -?, --help        Prints information on available command line arguments.
 --migrate             Applies pending migrations.
 --migrate-and-start   Applies pending migrations, then starts the application.
 --printconfig         Prints the example config.
 --recompute-counters  Recomputes denormalized database counters.
 --migrate-storage     Migrates all files currently stored locally to the
                       configured object storage bucket.
 --cleanup-storage     Removes dangling media files from disk / object storage.
                       Append --dry-run to log files instead of deleting them.
 --fixup-media         Fixes up cached remote drive files with missing files.
                       Append --dry-run to log files instead of processing them.
 --migrate-from-js     Migrates an iceshrimp-js database to an Iceshrimp.NET one.
 --https               For development purposes only. Listens using https
                       instead of http on the specified port.
 --environment <env>   Specifies the ASP.NET Core environment. Available options
                       are 'Development' and 'Production'.

User management commands:
 --create-user <username>        Creates a new user with the specified username
                                 and a randomly generated password.
 --create-admin-user <username>  Creates a new admin user with the specified
                                 username and a randomly generated password.
 --reset-password <username>     Resets the password of the specified user.
 --grant-admin <username>        Grants admin privileges to the specified user.
 --revoke-admin <username>       Revokes admin privileges of the specified user.

二、通用选项与命令详解

2.1 --printconfig：导出示例配置

打印发布产物内置的完整示例配置（349 行，21 个节），重定向落盘即得 configuration.ini 底本：

docker run --rm iceshrimp.dev/iceshrimp/iceshrimp.net:v2026.1.3-beta --printconfig > config/configuration.ini

升级版本后建议重新导出一份对照差异（dev 与 release 的配置差异实例见配置详解第十四节）。

2.2 --migrate / --migrate-and-start：数据库迁移

正常启动流程已自动执行迁移，这两个命令用于「先迁移后启动」的受控升级（官方推荐大版本升级流程：停服 → --migrate → 检查 → 启动）。实测空跑回显：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --migrate
info: [core] Iceshrimp.Backend > Iceshrimp.NET v2026.1.3-beta+a998dc6e57, codename "phenidate" (example.test)
info: [core] Iceshrimp.Backend > Validating configuration...
info: [core] Iceshrimp.Backend > Verifying database connection...
info: [core] Iceshrimp.Backend > No migrations are pending.

--migrate-and-start 行为相同，只是迁移完成后继续拉起应用进程。

2.3 --recompute-counters：重算反范式计数器

重算用户/帖子/实例的冗余计数字段（粉丝数、发帖数等）。官方 database-maintenance 页将其列为数据修复手段之一。实测回显：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --recompute-counters
info: [core] Iceshrimp.Backend > Validating configuration...
info: [core] Iceshrimp.Backend > Verifying database connection...
info: [core] Iceshrimp.Backend > Recomputing note, user & instance counters, this will take a while...

耗时与库规模成正比，小库数秒完成（实测全新库执行后立即退出）。

2.4 --migrate-storage：本地媒体迁往对象存储

把当前存于本地的全部媒体文件迁移到 [Storage:ObjectStorage] 配置的目标桶。前置条件：对象存储节已正确配置（参数逐项含义见配置详解 8.3）。本次实测环境为纯本地存储、未配置对象存储，故未执行该命令——在未配置 ObjectStorage 时不要运行，它会因缺少目标桶而失败或误动。迁移前先按第五节备份媒体目录。

2.5 --cleanup-storage：清理孤儿媒体

删除磁盘/对象存储中数据库已不引用的媒体文件。官方强烈建议先 --dry-run（只列出将被删除的文件而不删）：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --cleanup-storage --dry-run
info: [core] Iceshrimp.Backend > Verifying database connection...
info: [core] Iceshrimp.Backend.Core.Services.ImageProcessing.ImageProcessor > Using [LibVips, ImageSharp] for image processing.
info: [core] Iceshrimp.Backend.Core.Services.StorageMaintenanceService > Loaded 1 files from database.
info: [core] Iceshrimp.Backend.Core.Services.StorageMaintenanceService > Looking for orphaned files on disk, please wait...
info: [core] Iceshrimp.Backend.Core.Services.StorageMaintenanceService > Finished removing 0 orphaned files.

实测全新环境：数据库 1 个文件（管理员 identicon 头像），孤儿 0。

2.6 --fixup-media：修复缺失的远端缓存媒体

校验数据库引用的远端缓存文件，缺失的重新拉取。同样支持 --dry-run 先列清单：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --fixup-media --dry-run
info: [core] Iceshrimp.Backend.Core.Services.StorageMaintenanceService > Validating all files, this may take a long time...
info: [core] Iceshrimp.Backend.Core.Services.StorageMaintenanceService > Finished validating 0 files, of which 0 would have been fixed up.

适用场景：媒体目录误删、磁盘故障后的批量修复；与 [Storage] 节 MediaRetention（默认 30d）的缓存过期逻辑配合理解。

2.7 --migrate-from-js：从 iceshrimp-js 迁移

官方唯一的跨项目迁移工具，把 iceshrimp-js（Misskey 系）数据库整体转换为 Iceshrimp.NET 结构。属于一次性大工程操作，执行前务必阅读官方 migration-guide 页（https://kb.iceshrimp.dev/s/docs/doc/migration-guide-XRdCqvbu31 ，查询日期 2026-11-02）并对源库做完整备份。本次实测环境无 iceshrimp-js 库，未执行。

2.8 --https 与 --environment

--https：官方 help 明确标注「For development purposes only」，以 HTTPS 直接监听指定端口，仅限开发调试；生产一律用反代终结 TLS（见部署篇第八节）。
--environment <env>：指定 ASP.NET Core 环境，可选 Development/Production。实测服务日志默认 Hosting environment: Production。

三、用户管理命令

3.1 --create-user：创建普通用户

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --create-user alice

实测回显：

info: [core] Iceshrimp.Backend > Using [LibVips, ImageSharp] for image processing.
info: [core] Iceshrimp.Backend > Successfully created user.
info: [core] Iceshrimp.Backend > Username: alice
info: [core] Iceshrimp.Backend > Password: IrWKOEfHSGhojUFp

密码随机生成并打印，不接受人工输入（实测 stdin 喂入无效，见部署篇 11.4）。创建后让用户自行登录改密，或走 change-password 接口。

3.2 --create-admin-user：创建管理员

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --create-admin-user root

实测回显：

info: [core] Iceshrimp.Backend > Creating user root...
info: [core] Iceshrimp.Backend > Successfully created admin user.
info: [core] Iceshrimp.Backend > Username: root
info: [core] Iceshrimp.Backend > Password: GdqlVrwypjUbooNy

这是官方 post-install 指引的「首个管理员创建方式」。注意 [Security] 节 Registrations = Closed 时 Web 注册入口关闭，CLI 是唯一建号通道。

3.3 --reset-password：重置密码

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --reset-password root

实测回显（随机新密码，同样不可人工指定）：

info: [core] Iceshrimp.Backend > Resetting password for user root...
info: [core] Iceshrimp.Backend > Password for user root was reset to: EmcqfS3r3unEAX0d

3.4 --grant-admin / --revoke-admin：授予/撤销管理员

v2025.1-beta6 起取代了旧版「SQL 手工 UPDATE user 表」的提权方式（官方 post-install 页口径）。实测：

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --grant-admin alice
info: [core] Iceshrimp.Backend > Granted admin privileges to user alice.

docker compose run --rm --entrypoint ./Iceshrimp.Backend web --revoke-admin alice
info: [core] Iceshrimp.Backend > Revoked admin privileges of user alice.

四、Web 管理工具

4.1 管理面板与队列面板

管理员登录后访问 https://<WebDomain>/admin（实例元数据、用户管理、联邦黑白名单、中继等）与 https://<WebDomain>/queue（各队列积压与失败作业，配合 [Performance:QueueConcurrency]、[Queue:JobRetention] 调参）。实测未登录访问两者均返回 302 跳登录页。

4.2 内置 API 文档

v2026.1-beta 起后端内置 Scalar/Swagger UI 的人类可读 API 文档（官方 CHANGELOG 原文），前端调试页（note/用户「about」页）可直接查看 API 应答与 ActivityPub 表示。

4.3 对外 API 验证命令（实测）

部署完成后用三条 curl 快速验证联邦与客户端兼容性（Host 头校验的坑见部署篇 11.1）：

curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/api/v1/instance
→ "version": "4.2.1 (compatible; Iceshrimp.NET/2026.1.3-beta)"

curl -s -H "Host: ice.example.test" http://127.0.0.1:8129/nodeinfo/2.1
→ "software":{"name":"Iceshrimp.NET","version":"2026.1.3-beta+a998dc6e57","codename":"phenidate",...},"protocols":["activitypub"]

curl -s -H "Host: example.test" "http://127.0.0.1:8129/.well-known/webfinger?resource=acct:root@example.test"
→ "href":"https://ice.example.test/users/at2flvxvfcmfvnsm"

Mastodon 第三方客户端走标准授权码流程（密码模式在 v2026.1.3-beta 不可用，实测见部署篇 11.5）。

五、数据库维护命令

官方 post-install 页的两条硬要求（查询日期 2026-11-02）：

每日定时 VACUUM ANALYZE：官方建议低峰期 cron 执行（默认自动清理策略识别能力不足）；
不要手工改库：EF 迁移管理下的表结构手改极易造成不可逆损坏，有疑问先去官方讨论室。

备份实测（Compose 场景借助数据库服务自带的客户端工具，经服务名 TCP 连接，密码走 PGPASSWORD）：

docker compose run --rm -e PGPASSWORD='<数据库密码>' --entrypoint sh db \
  -c "pg_dump -h db -U iceshrimp iceshrimp > backup.sql"

实测全新库导出 7702 行 SQL（pg_dump -h db -U iceshrimp iceshrimp | wc -l 回显 7702）。查询用户表实测：

docker compose run --rm -e PGPASSWORD='<数据库密码>' --entrypoint sh db \
  -c "psql -h db -U iceshrimp -d iceshrimp -tAc \"SELECT username, \\\"isAdmin\\\" FROM \\\"user\\\" ORDER BY username\""
alice|f
root|t

注意：pg_dump 走 Unix socket 直连会失败（一次性运行实例里没有正在监听的 socket，实测报错 connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed），必须 -h db 走 TCP。

六、日志与日常运维

实时日志：docker compose logs -f web；历史排查：docker compose logs web --since 30m；
日志降噪/调试：[Logging:LogLevel] 节递归分级（见配置详解第十节），环境变量 NO_COLOR=1/LOG_TIMESTAMPS=1 控制彩色与时间戳；
服务重启（配置中需重启生效的节改完后）：docker compose restart web；
升级：改 compose 版本标签 → docker compose up -d（自动增量迁移），流程与回滚注意见部署篇第九节。

七、命令速查表

命令	用途	需停服	实测状态
`--help`	列全部子命令	否	✅ 全文见 1.3
`--printconfig`	导出示例配置	否	✅ 349 行
`--migrate`	执行待处理迁移	是（避免与运行实例并发）	✅ No migrations are pending.
`--migrate-and-start`	迁移后启动	—	与默认启动行为一致
`--recompute-counters`	重算计数器	建议停服	✅
`--cleanup-storage [--dry-run]`	清孤儿媒体	否	✅ dry-run
`--fixup-media [--dry-run]`	修复缺失缓存媒体	否	✅ dry-run
`--migrate-storage`	本地→对象存储	建议停服	⚠️ 本环境无对象存储，未执行
`--migrate-from-js`	iceshrimp-js 迁移	是	⚠️ 无源库，未执行
`--create-user` / `--create-admin-user`	建号（随机密码）	否	✅
`--reset-password`	重置密码（随机）	否	✅
`--grant-admin` / `--revoke-admin`	提权/撤权	否	✅
`--https` / `--environment`	开发用 TLS / 环境	—	默认 Production（实测日志确证）