Movim 0.35.4 常用 CLI 命令与工具详解

目标：逐条实测讲清 Movim v0.35.4 的命令行入口 php daemon.php（Symfony Console，12 个子命令）的全部用法、参数与真实回显，并覆盖配套工具 composer movim:migrate 与 XMPP 侧辅助命令 prosodyctl。已在 Debian 13 (trixie) + PHP 8.4.15 + PostgreSQL 15 + Prosody 13.0.1、安装路径 /var/www/movim（运行用户 www-data）环境实测通过。

一、环境信息

操作系统：Debian 13 (trixie)（x86_64），PHP 8.4.15
Movim：v0.35.4（VERSION 文件实测 = v0.35.4），安装路径 /var/www/movim
数据库：PostgreSQL 15（库/用户 movim，演示口令 q1w2e3r4）
XMPP 服务器：Prosody 13.0.1（域 movim.local）
执行身份：除特殊说明外，所有 daemon.php 命令均以 www-data 用户在 /var/www/movim 目录执行（su -s /bin/bash www-data 进入后执行，避免 root 运行导致目录属主漂移，见第五章注意事项）

二、工具概览

Movim 的全部运维入口集中在一个 Symfony Console 应用：项目根 daemon.php。实测 php daemon.php list 回显（完整原样）：

Console Tool

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  clearImagesCache     Clear all the images from the cache and the database
  clearTemplatesCache  Clear the internal templates cache
  compileLanguages     Compile and cache the languages files
  compileOpcache       Compile and cache PHP files in Opcache
  compileStickers      Compile and cache the stickers files
  completion           Dump the shell completion script
  config               Change the configuration
  emojisToJson         Compile the supported emojis to Json
  galener              Manage the Galener worker
  help                 Display help for a command
  importEmojisPack     Add a custom emojis pack to the instance
  list                 List commands
  sessionsTree         Display the current sessions tree
  setAdmin             Set an account admin
  start                Start the daemon

按用途归类：运行控制（start / sessionsTree / galener）、配置与账号（config / setAdmin）、缓存与编译（clearTemplatesCache / clearImagesCache / compileLanguages / compileOpcache / compileStickers / emojisToJson / importEmojisPack）。

⚠️ 注意：php daemon.php -V 实测只输出 Console Tool，不带版本号（Symfony Console 未注入版本）——查版本看根目录 VERSION 文件或管理面板。另外旧资料里 start -u/-p 以指定账号密码启动的参数在 v0.35.4 已不存在（help start 实测仅有 -d/--debug）。

三、前置条件

已完成安装与数据库迁移（composer movim:migrate，见 4.1 的 start 检查链——迁移缺失时 daemon 会拒绝启动并提示该命令）；
.env 已配置 DAEMON_URL 等必需键（参数含义与默认值见《Movim 0.35.4 配置参数详解》）；
以 www-data 身份执行，cache/、log/、public/cache/ 可写；
XMPP 服务器可达（daemon 连接逻辑：先查 DNS SRV，无则回退 tcp://<域名>:5222）。

四、daemon.php 各命令详解

4.1 start —— 启动守护进程

help start 实测仅一个选项：-d, --debug（Output XMPP logs）。启动检查链（源码 DaemonCommand.php 实测归纳）：phinx 迁移状态（缺则提示 composer movim:migrate）→ 必需 PHP 扩展（dom/imagick/intl/mbstring/openssl/pdo/simplexml/xml）→ DAEMON_URL（未配则报 Please configure DAEMON_URL in .env 退出）→ 目录可建 → admin 存在（无则提示 php daemon.php setAdmin {jid}）。通过后自动执行模板清理与语言/贴纸/Opcache 编译，并派生 avatarhandler / resolver / pusher 三个 worker。成功横幅实测（节选）：

Movim daemon launched
Base URL: https://127.0.0.1:8148/
😋 Avatar Handler Worker launched
🌍 Resolver Worker launched
🔔 Pusher Worker launched
Connect to tcp://movim.local:5222, peer_name: movim.local
XMPP socket launched

💡 说明：Opcache 在 PHP CLI 关闭时会提示 Opcache is disabled, it is strongly advised to enable it in PHP CLI php.ini（实测源码检查），建议 opcache.enable_cli=1。生产通常由 systemd 托管常驻（官方模板 etc/movim.service），start 前台形态适合调试。

4.2 setAdmin —— 设置/移除管理员

help setAdmin 实测：Usage: setAdmin [options] [--] <jid>；参数 jid（User Jabber ID）；选项 -r, --remove。

php daemon.php setAdmin movim@movim.local
# User movim@movim.local is now admin

数据库侧验证（psql -U movim -d movim）——users 表主键列名是 id（存 JID）：

select id, admin from users;
--        id         | admin
-- ------------------+-------
--  movim@movim.local | t

移除用 php daemon.php setAdmin movim@movim.local -r。

4.3 config —— 修改实例配置（写 configuration 表）

help config 实测选项（全部 VALUE_REQUIRED）：--info / --description / --timezone / --restrictsuggestions / --chatonly / --disableregistration / --loglevel / --locale / --xmppdomain / --xmppdescription / --xmppwhitelist / --gifapikey。

php daemon.php config --info="Movim 演示实例（quzuo.net 实测）" --xmppdomain=movim.local
# The configuration key info has been updated from Demo instance by CLI to Movim 演示实例（quzuo.net 实测）
# The configuration key xmppdomain has been updated from movim.local to movim.local

三个实测要点：其一，只有落在源码 Configuration.php fillable 白名单内的键才会写库；其二，--timezone 虽在 help 里出现但不在白名单，执行后无任何回显、静默忽略（v0.35.4 实测，详解见《配置参数详解》5.7）；其三，首次执行任一 config 选项会自动创建 configuration 表首行（实测 id=1、locale=en、loglevel=0、maxsessions=0）。

4.4 sessionsTree —— 会话树观测

排障第一现场：查看 daemon worker 与在线会话状态。实测有活跃会话时：

⚙️  Movim Daemon 🔧 1 👤 1
╰─ 🔧 moUbKF2sctYINewz (1)
   ╰─ 👤 🟠 75598950ab73ae0d7d5cc6a4f80cc88e movim@movim.local (0)

无会话时：⚙️ Movim Daemon 🔧 0 👤 0。help sessionsTree 附带的官方图例（实测原样）：

Structure ⚙️  - 🔧 worker-id - 👤⚪ session-id (<connected sockets>)
Session status 🔴 Launched | 🟠 XMPP Socket connected | 🟢 XMPP Session started

🟠 表示该会话的 XMPP socket 已连通、🟢 表示 XMPP 会话已完全建立——判断「登录卡在哪个环节」直接看这个颜色。

4.5 缓存与编译类命令

四条维护命令实测回显：

php daemon.php clearTemplatesCache
# Template cache cleared

php daemon.php compileLanguages
# Compiled hash file
# po files compiled

php daemon.php compileStickers
# miho compiled ...（共 8 包：miho/zemarmot/racoon/rage/meme/noblerimou/movim/mochi）
# 239 stickers compiled

php daemon.php compileOpcache
# 6705/6705 | Compiling...
# 6706/6706 | Files compiled

（compileStickers 输出节选（实测首尾）：逐包 8 行 + 汇总行；compileOpcache 为进度条末两行。）这四条在 start 时会自动执行一遍，手工执行用于改模板/语言包后热更。

4.6 clearImagesCache —— 清空图片缓存（带交互确认）

实测直接执行会先确认：

239 images will be deleted from the file cache and from the database, Movim will have to redownload them from the XMPP network after the daemon restart, are you sure about this [y/N] ? Aborting

输入 y 后的完整流程实测（输出节选，中间 8 个贴纸包逐行略）：

🧹 Removing all the files
🔧 Clearing the contacts table
🔧 Clearing the infos table
🗜️  Recompiling the stickers
miho compiled
...（8 包逐行）
239 stickers compiled
✨ All good, please restart your daemon to rebuild the caches

⚠️ 注意：该命令会连带清 contacts/infos 表数据并要求重启 daemon 重建缓存——图片是重新从 XMPP 网络下载的，网络差的环境慎用。

4.7 emojisToJson —— emoji 清单编译（权限陷阱实录）

输出为逐行 emoji 名（数千行，输出节选（实测首尾）：首行起逐名打印，尾部汇总 3939 emojis saved）。实测在 public/scripts/ 对 www-data 不可写时，汇总行照常打印但 JS 文件并未更新：

[02-Nov-2026 07:46:13 UTC] PHP Warning:  file_put_contents(/var/www/html/public/scripts/movim_emojis_list.js): Failed to open stream: Permission denied in /var/www/html/src/Movim/Console/EmojisToJsonCommand.php on line 69
3939 emojis saved

（以上为实测报错字面量原文，路径以实际部署为准。）判定成功不能只看 3939 emojis saved，要确认无 Warning 行或检查目标 JS 文件 mtime。

4.8 galener —— 音视频 worker 管理

help galener 实测：Usage: galener <action>，action 为必填参数（start/stop/restart；status 走 default 分支）。

php daemon.php galener status
# 🔴 Not running

未配置 Galener（GALENER_* 键留空，见《配置参数详解》5.3）时任何 action 都无从拉起，status 恒为 🔴。

4.9 importEmojisPack —— 导入自定义 emoji 包

help importEmojisPack 实测：Usage: importEmojisPack <manifest-url>，参数必填且须为合法 URL（指向符合 Movim 规范的 pack manifest）。

五、辅助工具与系统命令

5.1 composer movim:migrate —— 数据库迁移

phinx 封装：composer movim:migrate。迁移记录表实测（psql）：

select column_name from information_schema.columns where table_name='phinxlog';
-- migration | migration_file        （无 name 列）

select max(migration) from phinxlog;
-- 20261014193958  （CreateVersionsTable，v0.35.4 最新迁移）

升级版本后必须先跑迁移再启动 daemon，否则 start 检查链直接提示（见 4.1）。

5.2 prosodyctl —— XMPP 侧配套

Movim 的账号与连接对端在 XMPP 服务器，常用两条实测：

prosodyctl --version
# Prosody 13.0.1

prosodyctl about
# （节选）Data dir /var/lib/prosody、Config dir /etc/prosody、Source dir /usr/lib/prosody；
# Plugin dirs 含 "/var/lib/prosody/custom_plugins - not a directory!" 与 ";/usr/lib/prosody/modules/"

账号开通（Movim 走 internal_plain 认证）：prosodyctl register <user> movim.local <密码>。

六、注意事项

统一用 www-data 执行：root 跑过一次 daemon.php（如 compile*/emojisToJson）会把 cache/、public/scripts/ 属主改走，后续 www-data 写入报 Permission denied（4.7 实录）；补救 chown -R www-data: /var/www/movim/cache /var/www/movim/log /var/www/movim/public；
-V 无版本号：查版本用 cat VERSION（实测 v0.35.4）；
config 白名单外键静默忽略：--timezone 实测无回显不落库（4.3）；banner/maxsessions 无 CLI 入口，走管理面板或 SQL；
改配置后重启 daemon：INSTALL.md 明示部分配置需重启守护进程生效；clearImagesCache 的回显也直接要求重启；
交互命令注意：clearImagesCache 有 [y/N] 确认，脚本化执行需喂 y（实测 printf 'y\n' | php daemon.php clearImagesCache 可行）。

七、常见问题

Q1：start 提示 Please configure DAEMON_URL in .env 退出？ DAEMON_URL 是启动硬检查（4.1），配置公网 URL 后重试。

Q2：start 报缺 PHP 扩展？ 按提示补齐 dom/imagick/intl/mbstring/openssl/pdo/simplexml/xml（Debian：apt install php-imagick php-intl php-mbstring php-xml php-pgsql 等），扩展清单以源码 UtilsHelper.php::requiredExtensions() 实测为准。

Q3：start 提示需要迁移？ 执行 composer movim:migrate（5.1），完成后 php daemon.php start 即通过检查链。

Q4：galener 报 Not enough arguments (missing: "action")？ action 必填（4.8）：php daemon.php galener start|stop|restart|status。

Q5：sessionsTree 全是 🔴 上不了 🟠/🟢？ daemon 到 XMPP 的连接未建立：检查 JID 域名解析、5222 连通性与证书信任（排障实录见《Movim 0.35.4 Docker Compose 部署指南》第十一章 Q7/Q8）。

Q6：emojisToJson 显示 saved 但前端 emoji 没更新？ 看有无 file_put_contents ... Permission denied Warning（4.7）——DB 写入与 JS 文件写入是两条路，后者失败不影响汇总行。

八、参考链接

源码：daemon.php、src/Movim/Console/（各命令实现）、src/Movim/Daemon/DaemonCommand.php（启动检查链）
官方安装文档：仓库根 INSTALL.md（systemd 模板 etc/movim.service）
Symfony Console 文档：https://symfony.com/doc/current/components/console.html
Prosody 管理工具：https://prosody.im/doc/prosodyctl
本专栏姊妹篇：《Movim 0.35.4 介绍与选型指南》、《Movim 0.35.4 Docker Compose 部署指南》、《Movim 0.35.4 配置参数详解》