mosparo 1.5.13 常用 CLI 命令详解

本文是 mosparo 专栏的运维篇。mosparo 基于 Symfony Console,全部管理能力走 php bin/console。文中每条命令的输入与回显均为 2026-10-28 在实测实例(Debian 12 + Apache + MariaDB,安装于 /var/www/mosparo)上执行的原文;个别含敏感信息的输出已脱敏标注。部署与配置背景见《mosparo 1.5.13 安装部署指南》与《mosparo 1.5.13 配置参数详解》。

一、进入命令行与命令全景

所有命令都在安装目录下执行:

root@mosparo-lab:~# cd /var/www/mosparo
root@mosparo-lab:/var/www/mosparo# php bin/console list
Symfony 6.4.48 (env: prod, debug: false)

list 输出很长,可直接看 mosparo 自有命名空间(实测共 8 条),这是本文的主线:

命令	用途
`mosparo:health`	健康检查
`mosparo:cleanup-database`	执行数据库清理(计划任务核心)
`mosparo:export`	导出项目配置
`mosparo:import`	导入项目配置
`mosparo:rule-package:refresh`	刷新全部规则包
`mosparo:rule-package:import`	导入规则包内容
`mosparo:geoip2:download-database`	下载 GeoIP2 国家库
`mosparo:self-update`	在线升级 mosparo

其余高频命令来自 Symfony/Doctrine 框架层,本文挑实测过的讲:about、cache:clear、debug:dotenv、debug:router、dbal:run-sql、doctrine:migrations:status、security:hash-password、mailer:test。

二、健康与信息

2.1 mosparo:health

实例体检:检查配置、数据库连接等基础项,是排障和监控探针的首选。实测:

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:health

Health check
============

 [OK] Everything okay

出问题时此处会列出失败项;监控脚本可按退出码 0/非 0 判定,配合 HTTP 端点 /api/v1/health/check(白名单见配置篇 3.2 节)做主动探测。

2.2 about

查看运行时画像(Symfony 版本、缓存目录大小、PHP 版本等)。实测节选:

root@mosparo-lab:/var/www/mosparo# php bin/console about | head -25
 -------------------- --------------------------------- 
  Symfony                                               
 -------------------- --------------------------------- 
  Version              6.4.48                           
  Long-Term Support    Yes                              
  End of maintenance   11/2026 (in +33 days)            
  End of life          11/2027 (in +398 days)           
 -------------------- --------------------------------- 
  Kernel                                                
 -------------------- --------------------------------- 
  Type                 Mosparo\Kernel                   
  Environment          prod                             
  Debug                false                            
  Charset              UTF-8                            
  Cache directory      ./var/cache/prod (23.0 MiB)      
  Build directory      ./var/cache/prod (23.0 MiB)      
  Log directory        ./var/log (0 B)                  
 -------------------- --------------------------------- 
  PHP                                                   
 -------------------- --------------------------------- 
  Version              8.2.35                           
  Architecture         64 bits                          
  Intl locale          en_US_POSIX                      
  Timezone             UTC (2026-10-28T13:02:46+00:00)  
  OPcache              true

三、清理:cleanup-database

这是 mosparo 必须配计划任务的原因所在:提交数据、过期令牌、规则包缓存都靠它周期清理(保留期参数见配置篇 3.1 节)。实测:

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:cleanup-database
root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:cleanup-database -v

 [INFO] Cleanup result: COMPLETED

注意实测行为差异:不带 -v 时成功无输出(适合 crontab),带 -v 才打印 Cleanup result: COMPLETED(适合人工确认)。生产建议 crontab 写法:

*/5 * * * * cd /var/www/mosparo && /usr/bin/php bin/console mosparo:cleanup-database >> /var/log/mosparo-cleanup.log 2>&1

四、项目配置导入导出

4.1 mosparo:export

把项目配置(通用/设计/安全参数,不含提交数据与密钥)导出为 JSON,用于环境迁移、评审留档。先看用法再实测:

root@mosparo-lab:/var/www/mosparo# php bin/console help mosparo:export | sed -n '1,6p'
Description:
  Exports the configuration of a project.

Usage:
  mosparo:export [options] [--] <projectId> [<filePath>]

两个位置参数:项目 ID、输出文件路径(省略则打到 stdout)。可选开关 --generalSettings、--designSettings、--securitySettings 控制导出范围。实测导出到文件:

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:export 1 /tmp/project1-export.json
                     
  Export completed.  
                     
root@mosparo-lab:/var/www/mosparo# head -c 200 /tmp/project1-export.json
{"specificationsVersion":"5.0","exportedAt":"2026-10-28T13:09:35+00:00","project":{"name":"Demo \u7ad9\u70b9","description":"...

导出 JSON 里能直接看到全部安全参数默认值(minimumTimeSeconds=10、delay 30/30/60/1.5、lockout 60/60/300/1.2、PoW 复杂度 5 等),配置篇第五节的参数表即来源于此。

4.2 mosparo:import

把导出的 JSON 灌回项目(常用于把测试环境调好的参数复制到生产):

root@mosparo-lab:/var/www/mosparo# php bin/console help mosparo:import | sed -n '1,7p'
Description:
  Imports the configuration from a file into a project.

Usage:
  mosparo:import [options] [--] <projectId> <filePath>

用法与 export 对称:指定目标项目 ID 与文件路径。同名开关控制导入范围,导入内容覆盖目标项目对应设置。

五、规则包与 GeoIP

5.1 mosparo:rule-package:refresh

刷新项目挂载的全部规则包(拉取最新规则并重建缓存)。实测当前实例未挂载任何规则包,命令静默完成:

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:rule-package:refresh
root@mosparo-lab:/var/www/mosparo# echo $?
0

挂载规则包后,该命令应进入计划任务(建议与 cleanup 错峰,如每小时一次),否则规则包只会按后台设置的时间被动刷新。历史别名 mosparo:rulesets:refresh 仍可用(list 输出实测将其列为本命令别名)。

5.2 mosparo:geoip2:download-database

下载 MaxMind GeoIP2 Lite 国家库(供后台按国家/大洲规则使用)。该命令需要 MaxMind 账号凭据,未配置时实测直接报错——这本身就是一个排障实录:

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:geoip2:download-database
Account ID or license key not specified.

处置:先在后台「Administration → GeoIP2」填入 MaxMind 的 Account ID 与 License key(免费注册 GeoLite2 即可获得),再执行本命令;数据库文件落地于 var/data/geoip2/(实测该目录随发行包预置)。

六、升级:mosparo:self-update

在线升级到最新版,实测查看用法(升级动作本身未在本文执行,生产升级前先看后台提示的目标版本与官方更新说明):

root@mosparo-lab:/var/www/mosparo# php bin/console mosparo:self-update --help
Description:
  Updates mosparo to the newest available version.

Usage:
  mosparo:self-update

升级前置习惯:php bin/console mosparo:health 确认当前健康 → 数据库备份(见第八节)→ 执行升级 → 再次 mosparo:health + 登录后台核对 mosparo_installed_version。升级服务受 MOSPARO_UPDATES_ENABLED 开关控制(默认开)。

七、诊断类命令(实测)

7.1 dbal:run-sql — 直连执行 SQL

root@mosparo-lab:/var/www/mosparo# php bin/console dbal:run-sql 'SELECT COUNT(*) AS tables_cnt FROM information_schema.tables WHERE table_schema="mosparo"'
 ------------ 
  tables_cnt  
 ------------ 
  29          
 ------------

走的是 mosparo 自己的数据库连接(免再输密码),适合快速核对表结构/数据量。安装完成后 schema 共 29 张表。

7.2 doctrine:migrations:status — 核对迁移状态

root@mosparo-lab:/var/www/mosparo# php bin/console doctrine:migrations:status | head -12
+----------------------------------------------------------------------------------------------------------------------+
| Configuration                                                                                                        |
+----------------------+----------------------+------------------------------------------------------------------------+
| Storage              | Type                 | Doctrine\Migrations\Metadata\Storage\TableMetadataStorageConfiguration |
|                      | Table Name           | doctrine_migration_versions                                            |
|                      | Column Name          | version                                                                |
|----------------------------------------------------------------------------------------------------------------------|
| Database             | Driver               | Doctrine\DBAL\Driver\PDO\MySQL\Driver                                  |
|                      | Name                 | mosparo                                                                |
|----------------------------------------------------------------------------------------------------------------------|
| Versions             | Previous             | DoctrineMigrations\Version20261002174814                               |
|                      | Current              | DoctrineMigrations\Version20261003174251                               |

升级后核对 Current 是否到达最新、Executed 与 Available 是否一致;不一致时按官方升级说明执行 doctrine:migrations:migrate。

7.3 debug:dotenv / debug:router

debug:dotenv:列出环境变量加载顺序与最终值(配置篇第一、三节实测数据的来源);
debug:router:列出全部路由,排查 API 端点路径首选,如 php bin/console debug:router | grep api/v1。

7.4 cache:clear

改配置后的标准动作,实测成功时无输出:

root@mosparo-lab:/var/www/mosparo# php bin/console cache:clear
root@mosparo-lab:/var/www/mosparo#

7.5 security:hash-password

生成密码哈希(排查登录问题时校验哈希格式)。实测:

root@mosparo-lab:/var/www/mosparo# php bin/console security:hash-password 'q1w2e3r4'
 ! [NOTE] Self-salting hasher used: the hasher generated its own built-in salt. 

 [OK] Password hashing succeeded

八、备份与恢复(全流程实测)

mosparo 的全部状态 = 数据库 + 安装目录内三类文件:config/env.mosparo.php(数据库凭据、encryption_key,丢了历史提交就解不开了)、var/data/(规则包缓存、GeoIP2 库、导入导出文件)、.env.local(如创建过)。

备份:

root@mosparo-lab:~# mariadb-dump mosparo > /tmp/mosparo-backup.sql
root@mosparo-lab:~# ls -la /tmp/mosparo-backup.sql
-rw-r--r-- 1 root root 40186 Oct 28 13:09 /tmp/mosparo-backup.sql
root@mosparo-lab:~# tar czf /tmp/mosparo-files.tgz -C /var/www/mosparo config/env.mosparo.php var/data .env.local

恢复(实测:先删库重建再导入,验证备份可用):

root@mosparo-lab:~# mariadb -e 'DROP DATABASE mosparo; CREATE DATABASE mosparo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;'
root@mosparo-lab:~# mariadb mosparo < /tmp/mosparo-backup.sql
root@mosparo-lab:~# cd /var/www/mosparo && php bin/console mosparo:health

Health check
============

 [OK] Everything okay

实测回环(备份 40186 字节 → 删库 → 重建 → 导入 → health OK)一次通过。恢复后建议顺手清一次缓存(cache:clear),再登录后台抽查提交记录页。

九、排障实录

1. mailer:test 缺参数直接 CRITICAL

实测现象:裸跑 php bin/console mailer:test 报 Not enough arguments (missing: "to"). 且日志里出现 console.CRITICAL。命令需要收件人参数;继续实测带收件人:

root@mosparo-lab:/var/www/mosparo# php bin/console mailer:test admin@lab.local --subject 'mosparo mail test'
In AbstractStream.php line 87:
                                                                               
  Connection to "process /usr/sbin/sendmail -bs" has been closed unexpectedly

原因:mosparo 未配置 SMTP 时默认走 sendmail://default,本机没有 MTA 监听,连接即断。处置:要么装配 Postfix,要么在后台设置里改 SMTP 发信;该命令可作为邮件配置修改后的快速验证器。

2. rule-package:refresh 静默无输出

实测现象:未挂载规则包时命令零输出、退出码 0(见 5.1 节)。不要把"没输出"当成故障;先确认项目是否已添加规则包(后台 → 项目 → Rule packages),再查 var/log/prod-*.log。

3. 清理命令在 crontab 里不生效

常见原因链:crontab 用了相对路径(必须 cd /var/www/mosparo && 后再调);php 不在 cron 的 PATH(用绝对路径 /usr/bin/php);从未观察到结果(去掉重定向先手动跑一遍看回显)。

十、参考

安装与目录结构:《mosparo 1.5.13 安装部署指南》
配置参数与生效机制:《mosparo 1.5.13 配置参数详解》
组件定位与版本背景:《mosparo 1.5.13 介绍与选型指南》
官方文档:documentation.mosparo.io(查询日期 2026-10-28)