Froxlor 2.3.16 常用 CLI 命令与工具详解
Froxlor 2.3.16 唯一 CLI 入口 froxlor-cli（Symfony Console，11 个子命令）逐条实测详解：cron 四作业与 run-task 编号、install 无人值守与 sysinfo、config-services 七选项、user 查解锁、switch-server-ip、config-diff 模板对比、update/sessionclean/validate-acme-webroot 实测回显、api-call 格式纠偏（Unknown command→Domains.listing 成功）与 26 个 API 模块清单（Ubuntu 22.04 + PHP 8.2.35 实测，2026-11-02）。
FroxlorFroxlor面板虚拟主机PHP自托管2026/11/03
Froxlor 2.3.16 常用 CLI 命令与工具详解
目标：把 Froxlor 2.3.16 唯一的命令行入口
bin/froxlor-cli（Symfony Console 应用，11 个子命令）逐条讲透——参数含义、真实回显、与 Web 界面的分工，含 api-call 格式纠偏与三个"功能未启用"类提示的实测记录。已在 Ubuntu 22.04 服务器 + Froxlor 2.3.16（PHP 8.2.35 CLI / MariaDB 10.11.19）实测通过。
Froxlor 的 CLI 是面板与操作系统之间的执行层：安装、服务接管、配置渲染、任务作业全部走 froxlor-cli，系统 cron 里那条每 5 分钟的命令调的也是它。组件背景见《Froxlor 介绍与选型指南》，部署过程见《Froxlor 2.3.16 Docker Compose 部署指南》，参数含义见《Froxlor 2.3.16 配置参数详解》。
一、环境信息
| 项目 | 取值 |
|---|---|
| 服务器操作系统 | Ubuntu 22.04（x86_64） |
| Froxlor 版本 | 2.3.16（db_version 202608210） |
| CLI 入口 | /var/www/html/froxlor/bin/froxlor-cli（PHP 脚本，Symfony Console 应用） |
| 调用形态 | php /var/www/html/froxlor/bin/froxlor-cli <froxlor:命令> [参数] |
| PHP CLI | 8.2.35（注意：面板生成的 cron 命令行硬编码 /usr/bin/php，见第五章第 1 条） |
| 数据库 | MariaDB 10.11.19，凭据读 /var/www/html/froxlor/lib/userdata.inc.php |
| 演示环境形态 | Docker Compose 栈（项目 froxlor-2.3.16-stack）；进入服务后所有命令与主机安装形态完全一致（本文命令均在服务内以 root 执行） |
| 面板账号 | admin / q1w2e3r4 |
| 调度文件 | /etc/cron.d/froxlor（面板自管，见 4.1） |
二、工具概览
froxlor-cli 不带参数即打印帮助与命令清单（实测 --version 与 list 合并回显节选）：
php /var/www/html/froxlor/bin/froxlor-cli --version
php /var/www/html/froxlor/bin/froxlor-cli
froxlor-cli 2.3.16
Usage:
command [options] [arguments]
Options:
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-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 and 3 for debug
Available commands:
completion Dump the shell completion script
help Display help for a command
list List commands
froxlor
froxlor:api-call Run an API command as given user
froxlor:config-diff Shows differences in config templates between OS versions
froxlor:config-services Configure system services
froxlor:cron Regulary perform tasks created by froxlor
froxlor:install Installation process to use instead of web-ui
froxlor:php-sessionclean Cleans old php-session files from tmp folder
froxlor:switch-server-ip Easily switch IP addresses e.g. after server migration
froxlor:update Check for newer version and update froxlor
froxlor:user Various user actions
froxlor:validate-acme-webroot Validates the Le_Webroot value is correct for froxlor managed domains with Let's Encrypt certificate.
11 个 froxlor 子命令的分工速查：
| 命令 | 一句话用途 | 日常频率 |
|---|---|---|
froxlor:cron | 任务作业引擎：渲染 Web/DNS/邮件配置、统计流量、发用量报告（系统 cron 每 5 分钟自动调） | 被动高频，手动多用于排障/强制重渲 |
froxlor:install | 无人值守安装 / 打印示例 JSON / 查系统信息 | 安装期、巡检 |
froxlor:config-services | 按发行版模板安装并接管下游服务配置 | 安装/迁移/重建 |
froxlor:user | 查用户详情、解锁被锁定账号、改口令 | 排障 |
froxlor:switch-server-ip | 迁移后批量换 IP | 迁移 |
froxlor:config-diff | 对比不同发行版配置模板差异 | 升级发行版评估 |
froxlor:update | 检查/执行版本更新 | 升级 |
froxlor:php-sessionclean | 清理过期 PHP 会话文件（FPM 环境） | 由 cron 调用 |
froxlor:validate-acme-webroot | 校验/修正域名 Le_Webroot | LE 排障 |
froxlor:api-call | 以指定用户身份调用 JSON API 命令 | 自动化对接 |
completion | 生成 shell 补全脚本（Symfony 自带） | 一次性 |
三、前置条件
- 面板已完成安装（未装时除
froxlor:install外全部命令会因读不到userdata.inc.php而失败）； - 以 root 或 www-data 身份执行：
userdata.inc.php实测权限-rw------- www-data www-data，其他账号读不到数据库凭据；config-services/switch-server-ip需要 root（写/etc、重载服务）； - 进入执行通道：主机形态直接 SSH；本演示环境为
docker compose exec froxlor bash； - 建议为长输出命令配
--no-ansi（| tee落盘时避免 ANSI 码）。
四、各工具详解
4.1 froxlor:cron：任务作业引擎
完整帮助（实测全量回显）：
php /var/www/html/froxlor/bin/froxlor-cli froxlor:cron --help
Usage:
froxlor:cron [options] [--] [<job>...]
Arguments:
job Job(s) to run
Options:
-r, --run-task=RUN-TASK Run a specific task [1 = re-generate configs, 4 = re-generate dns zones, 9 = re-generate rspamd configs, 10 = re-set quotas, 99 = re-create cron.d-file] (multiple values allowed)
-f, --force Forces given job or, if none given, forces re-generating of config-files (webserver, nameserver, etc.)
-d, --debug Output debug information about what is going on to STDOUT.
-N, --no-fork Do not fork to background (traffic cron only).
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-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
四个作业名（job 参数，对应安装生成的调度文件，实测 /etc/cron.d/froxlor 全文）：
# automatically generated cron-configuration by froxlor
# do not manually edit this file as it will be re-generated periodically.
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
#
*/5 * * * * root /usr/bin/nice -n 5 /usr/bin/php -q /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'tasks' -q 1> /dev/null
0 0 * * * root /usr/bin/nice -n 5 /usr/bin/php -q /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'traffic' -q 1> /dev/null
5 0 * * * root /usr/bin/nice -n 5 /usr/bin/php -q /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'usage_report' -q 1> /dev/null
0 */6 * * * root /usr/bin/nice -n 5 /usr/bin/php -q /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'mailboxsize' -q 1> /dev/null
| 作业 | 调度 | 职责 |
|---|---|---|
tasks | 每 5 分钟 | 核心：消费任务队列，把数据库期望状态渲染成 vhost/zone/邮件表等并 reload 服务、维护本调度文件自身 |
traffic | 每日 0 点 | 解析 Web/邮件日志累计客户流量（-N 可阻止其 fork 后台，便于调试） |
usage_report | 每日 0:05 | 磁盘/流量用量报告邮件（阈值 system.report_*） |
mailboxsize | 每 6 小时 | 同步邮箱实际占用到配额表 |
手动强制跑一次（排障/立即生效首选），实测 froxlor:cron 'tasks' -f -d 全量回显：
Checking froxlor file permissions...OK
Running "tasks" job (forced) (debug)
[information] TasksCron: Searching for tasks to do
[notice] Creating passwd file
[notice] Writing 0 entries to passwd file
[notice] Succesfully wrote passwd file
[notice] Creating group file
[notice] Writing 0 entries to group file
[notice] Succesfully wrote group file
[notice] Creating shadow file
[notice] Writing 0 entries to shadow file
[notice] Succesfully wrote shadow file
[information] apache::createIpPort: creating ip/port settings for 10.89.68.10:80
[debug] 10.89.68.10:80 :: inserted vhostcontainer
[information] apache::writeConfigs: rebuilding /etc/apache2/sites-enabled/
[information] apache::writeConfigs: rebuilding /etc/apache2/froxlor-htpasswd/
[information] apache::writeConfigs: rebuilding /etc/apache2/sites-enabled/
[information] Froxlor\Cron\Http\Apache::reload: reloading Froxlor\Cron\Http\Apache
[notice] Checking system's last guid
[notice] Checking system's OS version
解读：开头 Checking froxlor file permissions...OK 是前置自检；随后依次生成 libnss-extrausers 三件套（passwd/group/shadow，本环境 0 条目）、重建 IP/端口 vhost 配置块（回显中的 vhostcontainer）并 reload Apache；-r 编号（1/4/9/10/99）用于只重渲某一类配置而不跑全队列，例如改完 DNS 参数后 froxlor:cron -r 4、调度文件被误删后 froxlor:cron -r 99。
4.2 froxlor:install：安装与系统信息
php /var/www/html/froxlor/bin/froxlor-cli froxlor:install --help
Usage:
froxlor:install [options] [--] [<input-file>]
Arguments:
input-file Optional JSON array file to use for unattended installations
Options:
-p, --print-example-file Outputs an example JSON content to be used with the input file parameter
-c, --create-userdata-from-str=CREATE-USERDATA-FROM-STR Creates lib/userdata.inc.php file from string created by web-install process
-s, --show-sysinfo Outputs system information about your froxlor installation
三种用法全部实测：
-p打印示例 JSON：输出与 Web 向导字段一一对应的模板（mysql_host/admin_user/distribution/serveripv4/webserver等），照抄改值即可无人值守安装；<input-file>无人值守安装：完整流程与全量回显见部署篇 4.9/4.10（本演示环境即此方式装成）；-s查系统信息（巡检入口，实测回显）：
┌────────────────┬───────────────────────────┐
│ Key │ Value │
├────────────────┼───────────────────────────┤
│ Froxlor │ 2.3.16 (202608210) │
│ Update-channel │ stable │
│ Hostname │ panel.froxlor.test │
│ Install-dir │ /var/www/html/froxlor/ │
│ PHP CLI │ 8.2.35 │
│ PHP SAPI │ mod_php │
│ Webserver │ apache2 │
│ Kernel │ 7.0.0-38-generic (x86_64) │
│ Database │ 10.11.19-MariaDB-ubu2204 │
│ Distro config │ bookworm │
│ IP addresses │ 10.89.68.10 (80) │
└────────────────┴───────────────────────────┘
-c 是把 Web 向导末步生成的凭据串落成 userdata.inc.php 的通道，CLI 安装路线用不到。
4.3 froxlor:config-services：服务接管配置
php /var/www/html/froxlor/bin/froxlor-cli froxlor:config-services --help
Usage:
froxlor:config-services [options]
Options:
-c, --create Create a services list configuration for the --apply option.
-a, --apply=APPLY Configure your services by given configuration file/string. To create one run the command with the --create option.
-l, --list Output the services that are going to be configured using a given config file (--apply option). No services will be configured.
-d, --daemon=DAEMON When used with --apply you can specify one or multiple daemons. These will be the only services that get configured. (multiple values allowed)
-i, --import-settings=IMPORT-SETTINGS Import settings from another froxlor installation. This can be done standalone or in addition to --apply.
-A, --yes-to-all Install packages without asking questions (Debian/Ubuntu only currently)
-D, --delete-file If --apply is called with a local file, remove it after successful configurations.
工作流：-c 交互式生成服务选型 JSON（distro/dns/http/smtp/mail/antispam/ftp/system 数组）→ -a '<JSON或文件>' 应用；-l 干跑预览将配置哪些服务（不落盘）；-d 只重配指定段（如 -d http）；-A 免确认装包；-i 从另一台安装导入设置（迁移利器）。安装器末尾打印的就是完整 -a 串：
php /var/www/html/froxlor/bin/froxlor-cli froxlor:config-services \
-a '{"distro":"bookworm","dns":"x","http":"apache24","smtp":"postfix_dovecot","mail":"dovecot_postfix2","antispam":"rspamd","ftp":"proftpd","system":["cron","libnssextrausers","logrotate","goaccess"]}' \
--yes-to-all
实测输出节选（首尾，完整 567 行排障实录见部署篇 4.10/11.1–11.3）：
Creating missing certificate /etc/ssl/froxlor_selfsigned.pem
--- Configuring: HTTP ---
Configuring 'apache24'
Installing required packages
apache2 is already the newest version (2.4.69-1~deb13u1).
--- Configuring: SMTP ---
Configuring 'postfix_dovecot'
E: Unable to locate package postfix
...
--- Configuring: ANTISPAM ---
Configuring 'rspamd'
Setting up rspamd (3.12.1-1) ...
--- Configuring: FTP ---
Configuring 'proftpd'
Creating file "/etc/proftpd/proftpd.conf"
...
sh: 1: /usr/bin/php: not found
All services have been configured
⚠️ 注意：该命令会覆盖被接管服务的既有配置（先自动备份），官方安装器也要求以 root 在服务器 shell 执行；编排栈重建后 Apache 配置丢失，重放本命令 +
froxlor:cron 'tasks' -f即可恢复（部署篇第五章实录）。
4.4 froxlor:user：用户查询与解锁
php /var/www/html/froxlor/bin/froxlor-cli froxlor:user --help
Usage:
froxlor:user [options] [--] <user> [<admin>]
Arguments:
user Loginname of the target user
admin Loginname of the executing admin/reseller user [default: "admin"]
Options:
-u, --unlock Unlock user after too many failed login attempts
-p, --change-passwd Set new password for given user
-s, --show-info Output information details of given user
-s 查面板管理员 admin 全字段（实测回显节选，首尾）：
----------------------- --------------------
adminid 1
loginname admin
password [hidden]
name Administrator
email admin@froxlor.test
def_language en
ip -1
customers -1
customers_used 0
...
diskspace -1024
traffic -1048576
traffic_used 0
deactivated 0
lastlogin_succ 1793625410
lastlogin_fail 0
loginfail_count 0
theme Froxlor
type_2fa 0
api_allowed 1
gui_access 1
----------------------- --------------------
要点：-1 表示不限额（配额类字段），-1024/-1048576 是磁盘/流量的"无限制"哨兵值；lastlogin_succ/loginfail_count 直接对应 login.maxloginattempts 锁定机制。
-u 解锁（实测）：
php /var/www/html/froxlor/bin/froxlor-cli froxlor:user admin -u
User admin unlocked successfully
不存在的用户（实测）：
php /var/www/html/froxlor/bin/froxlor-cli froxlor:user nosuchuser -s
Unknown user 'nosuchuser'
-p 交互式设置新口令（遵循 panel.password_* 策略校验）。客户账号同样可用，第二个位置参数 <admin> 指定以哪个管理员权限执行。
4.5 froxlor:switch-server-ip：迁移换 IP
php /var/www/html/froxlor/bin/froxlor-cli froxlor:switch-server-ip --help
Usage:
froxlor:switch-server-ip [options]
Options:
-s, --switch=SWITCH Switch IP-address pair. A pair is separated by comma. For example: --switch=A,B (multiple values allowed)
-l, --list List all IP addresses currently added for this server in froxlor
-l 实测回显（本环境仅一个 IP/端口）：
--- ------------- ------
# IP address Port
--- ------------- ------
1 10.89.68.10 80
--- ------------- ------
迁移场景：新机 IP 为 192.0.2.7 时执行 --switch=10.89.68.10,192.0.2.7，面板同步改 panel_ipsandports 表与 system.ipaddress 并触发配置重建——比手改数据库安全（vhost 文件名、DNS 校验、system.mysql_access_host 白名单会联动）。
4.6 froxlor:config-diff：发行版模板对比
php /var/www/html/froxlor/bin/froxlor-cli froxlor:config-diff --help
Usage:
froxlor:config-diff [options] [--] [<from> [<to>]]
Arguments:
from OS version to compare against
to OS version to compare from
Options:
-l, --list List all possible OS versions
--diff-params=DIFF-PARAMS Additional parameters for `diff`, e.g. --diff-params="--color=always"
-l 实测回显：
The following OS version templates are available:
bookworm Debian Bookworm (12.x)
bullseye Debian Bullseye (11.x)
trixie Debian Trixie (13.x)
focal Ubuntu Focal (20.04) [deprecated]
jammy Ubuntu Jammy (22.04)
noble Ubuntu Noble (24.04)
本演示环境 distribution=bookworm 而基底实为 trixie（distro_mismatch=1，见配置篇 7.3），跑 froxlor:config-diff bookworm trixie 量化两线差异（实测节选）：
Deprecated: trim(): Passing null to parameter #1 ($string) of type string is deprecated in /var/www/html/froxlor/lib/Froxlor/Cli/ConfigDiff.php on line 136
# FTP-server : ProFTPd : /etc/proftpd/modules.conf
3a4
> LoadModule mod_ident.c
4a6,8
> LoadModule mod_delay.c
> LoadModule mod_ls.c
> LoadModule mod_xfer.c
6c10,11
< LoadModule mod_ident.c
---
> LoadModule mod_tls_fscache.c
> LoadModule mod_tls_shmcache.c
31a37
> LoadModule mod_memcache.c
解读：差异集中在 ProFTPd 模块加载表（trixie 线多载 tls_fscache/shmcache/memcache 等模块）与缩进排版；首行 Deprecated: trim() 是 PHP 8.2 下的无害警告。升级发行版前用这条命令评估面板生成配置会怎么变，是 Froxlor 独有的严谨设计。
4.7 froxlor:update：版本检查与更新
php /var/www/html/froxlor/bin/froxlor-cli froxlor:update --help
Usage:
froxlor:update [options]
Options:
-c, --check-only Only check for newer version and exit
-o, --show-update-options Show possible update option parameter for the update if any. Only usable in combination with "check-only".
-O, --update-options=UPDATE-OPTIONS Parameter list of update options. (multiple values allowed)
-d, --database Only run database updates in case updates are done via apt or manually.
-m, --mail-notify Additionally inform administrator via email if a newer version was found
-A, --yes-to-all Do not ask for download, extract and database-update, just do it (if not --check-only is set)
-i, --integer-return Return integer whether a new version is available or not (implies --check-only). Useful for programmatic use.
实测执行 froxlor:update（无参）：
PHP zip extension not found, please ensure it is installed and activated
定位：更新器要下载/解包 Release tarball，依赖 PHP zip 扩展；本演示环境未编译该扩展（安装期 WARNING 已预告）。解决：docker-php-ext-install zip（需 libzip-dev）后重跑；编排化部署更推荐"改版本号重建"路线替代面板内自更新（部署篇 11.5）。-d 则专用于 apt/手工换码后只补跑数据库结构迁移，跨小版本升级（如 2.3.15→2.3.16）后必跑。
4.8 froxlor:php-sessionclean：会话文件清理
php /var/www/html/froxlor/bin/froxlor-cli froxlor:php-sessionclean --help
Usage:
froxlor:php-sessionclean [<max-lifetime>]
Arguments:
max-lifetime The number of seconds after which data will be seen as "garbage" and potentially cleaned up. Defaults to "1440"
实测执行：
PHP-FPM not enabled for this installation.
本环境面板与客户站点均走 mod_php（phpfpm.enabled=0），会话由 PHP 自身回收，此命令无事可做；启用 PHP-FPM 后它清理各池 tmpdir 下的过期会话文件（默认阈值 1440 秒），由 cron 体系调度。
4.9 froxlor:validate-acme-webroot：ACME 路径校验
php /var/www/html/froxlor/bin/froxlor-cli froxlor:validate-acme-webroot --help
Usage:
froxlor:validate-acme-webroot [options]
Options:
-A, --yes-to-all Do not ask for confirmation, update files if necessary
实测执行：
[INFO] Let's Encrypt not activated in froxlor settings.
LE 未启用（system.leenabled=0）直接退出。用途：启用 LE 后若域名 vhost 里的 Le_Webroot 与实际校验目录不符（典型：手工改过站点根目录），此命令逐域检查并可 -A 自动修正——签发失败排障先跑它。
4.10 froxlor:api-call：命令行调 JSON API
php /var/www/html/froxlor/bin/froxlor-cli froxlor:api-call --help
Usage:
froxlor:api-call [options] [--] <user> <api-command> [<parameters>]
Arguments:
user Loginname of the user you want to run the command as
api-command The command to execute in the form "Module.function"
parameters Parameters to pass to the command as JSON array
Options:
-s, --show-params Show possible parameters for given api-command (given command will *not* be called)
格式纠偏实录：最初按"直觉小写"传 domain.domain_list、froxlor.version 等形式，全部得到同一句：
Unknown command
定位：api-command 必须是 Module.function，其中 Module 取命令文件名、首字母大写，function 是类方法名。实测模块清单（ls lib/Froxlor/Api/Commands/）：
Admins.php Certificates.php Cronjobs.php Customers.php DataDump.php DirOptions.php DirProtections.php DomainZones.php Domains.php EmailAccounts.php EmailDomains.php EmailForwarders.php EmailSender.php Emails.php FpmDaemons.php Froxlor.php Ftps.php HostingPlans.php IpsAndPorts.php MysqlServer.php Mysqls.php PhpSettings.php SshKeys.php SubDomains.php SysLog.php Traffic.php index.html
即 26 个可用模块（Domains、Customers、EmailAccounts、SubDomains、Ftps、Mysqls、HostingPlans、IpsAndPorts、Certificates、SysLog、Traffic……）。改对格式后实测成功：
php /var/www/html/froxlor/bin/froxlor-cli froxlor:api-call admin Domains.listing '{}'
{
"data": {
"count": 0,
"list": []
}
}
（本环境尚未添加域名，count: 0 即如实回显。）-s 可在调用前打印任意命令的参数表，实测 Domains.add -s 节选：
-------- ----------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Type Name Description
-------- ----------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
string domain domain-name
int customerid optional, required when called as admin (if $loginname is not specified)
string loginname optional, required when called as admin (if $customerid is not specified)
int adminid optional, default is the calling admin's ID
array ipandport optional list of ip/ports to assign to domain, default is system-default-ips
int subcanemaildomain optional, allow subdomains of this domain as email domains, 1 = choosable (default no), 2 = choosable(default yes), 3 = always, default 0 (never)
bool isemaildomain optional, allow email usage with this domain, default 0 (false)
bool email_only optional, restrict domain to email usage, default 0 (false)
...
bool writeaccesslog optional, Enable writing an access-log file for this domain, default 1 (true)
（输出节选（实测首尾），完整 20+ 参数含 alias/specialsettings/dkim/registration_date 等。）这条通道与 HTTP api.php 同源（api.enabled 开关 + API 密钥仅约束 HTTP 侧；CLI 以服务内用户身份直接执行），适合开通脚本先本地验证再上 HTTP。
4.11 completion：shell 补全
php /var/www/html/froxlor/bin/froxlor-cli completion bash
实测输出为 Symfony 标准补全脚本（节选首 5 行）：
# This file is part of the Symfony package.
#
# (c) Fabien Potencier <fabien@symfony.com>
#
# For the full copyright and license information, please view
落盘 source 后 froxlor-cli froxlor:<TAB> 可补全 11 个子命令；zsh/fish 换参数即可。
五、注意事项
/usr/bin/php路径假设：面板生成的 cron.d 行与 config-services 模板都硬编码/usr/bin/php（实测回显见 4.1），PHP 装在非标准路径的环境（如/usr/local/bin/php）必须建符号链接或改system.croncmdline，否则任务作业静默失败（部署篇 11.3 实录）；- cron 作业幂等但吃锁：手工
froxlor:cron 'tasks' -f与系统调度并发时后者会因文件锁跳过，属正常；排障看结果建议配-d； - config-services 覆盖性：会重写被接管服务配置（自动备份），生产执行前先
-l干跑确认波及范围； - api-call 大小写敏感：
Module.function模块名首字母大写（4.10 纠偏实录），参数是合法 JSON（空参也要传'{}'）； - update 依赖 zip 扩展、sessionclean 依赖 PHP-FPM、validate-acme-webroot 依赖 Let's Encrypt 启用——三者未启用时的实测提示见 4.7/4.8/4.9，不是故障；
- 跨大版本升级（2.2→2.3）先换代码再
froxlor:update -d补数据库迁移，并按官方 Migration Guide 重渲配置。
六、常见问题
6.1 api-call 一律报 Unknown command
命令格式不符 Module.function（模块名大小写错误最常见）。用 4.10 的模块清单核对首字母大写的模块名，参数位不传或传非法 JSON 也会报错；先用 -s 验证命令存在（它只查不跑）。
6.2 froxlor:update 报 PHP zip extension not found
缺 PHP zip 扩展（实测回显见 4.7）。装扩展后重跑，或走镜像重建升级路线；仅补数据库结构用 -d（不需要 zip）。
6.3 froxlor:php-sessionclean 报 PHP-FPM not enabled
本安装未启用 PHP-FPM（phpfpm.enabled=0，实测回显见 4.8），命令按设计空转。启用 FPM 后自动恢复实际清理功能。
6.4 froxlor:validate-acme-webroot 提示 Let's Encrypt not activated
system.leenabled=0 时的正常短路（实测回显见 4.9）。先在面板"设置→Let's Encrypt"完成注册启用，再跑校验。
6.5 手动跑 cron 任务后站点仍 403/配置没生成
检查三件事：/etc/cron.d/froxlor 里 croncmdline 的 PHP 路径是否存在（注意事项 1）；任务是否真在跑（SELECT value FROM panel_settings WHERE varname='last_tasks_run' 时刻是否更新，配置篇 7.5）；重建环境 Apache 配置层丢失需重放 config-services -a（部署篇第五章实录）。
七、参考链接
- 官方 CLI 脚本文档：https://docs.froxlor.org/latest/admin-guide/cli-scripts/
- 官方 API 文档：https://docs.froxlor.org/latest/admin-guide/api/
- GitHub 源码（Commands 目录，11 个 CLI 命令定义于
lib/Froxlor/Cli/）：https://github.com/Froxlor/Froxlor - Symfony Console 文档（completion/全局参数出处）：https://symfony.com/doc/current/console.html
- 同系列：《Froxlor 介绍与选型指南》、《Froxlor 2.3.16 Docker Compose 部署指南》、《Froxlor 2.3.16 配置参数详解》
章节目录