ISPConfig 3.3.2p1 常用 CLI 命令与工具详解

目标：系统梳理 ISPConfig 3.3.2p1 安装后在服务器上落地的全部命令行工具（服务引擎、周期任务、升级补丁、备份、静默安装配置生成、卸载等），给出每个工具的位置、调用方式与实测回显，让运维可以不进面板完成日常服务器侧操作。本文所有命令均在 Ubuntu 22.04.5 LTS 实装的 3.3.2p1 环境实测，输出逐行照抄。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS；主机名 server1.example.com
• ISPConfig：3.3.2p1（安装路径 /usr/local/ispconfig/，官方自动安装器部署）
• 组件版本：MariaDB 10.6.23 / Apache 2.4.52 / PHP 8.1.34 / Postfix 3.6.4 / Dovecot 2.3.16 / BIND 9.18.39 / Rspamd 4.2.3
• 面板端口：8080（管理界面）、8081（Apps）；日志目录 /var/log/ispconfig/（实测包含 auth.log、cron.log、httpd/、install.log、ispconfig.log）

二、工具概览

ISPConfig 的 CLI 工具集中在两个位置：/usr/local/ispconfig/server/（引擎与任务脚本）和 /usr/local/ispconfig/server/scripts/（维护工具）。实测清单（ls 回显）：

$ ls /usr/local/ispconfig/server/*.php
/usr/local/ispconfig/server/backup-now.php
/usr/local/ispconfig/server/cron.php
/usr/local/ispconfig/server/cron_daily.php
/usr/local/ispconfig/server/cron_debug.php
/usr/local/ispconfig/server/server.php

$ ls /usr/local/ispconfig/server/scripts/
create_daily_nginx_access_logs.sh
create_jailkit_chroot.sh
create_jailkit_programs.sh
create_jailkit_user.sh
generate_autoinstall_conf.sh
ispconfig_htaccess.php
ispconfig_patch
ispconfig_update.php
ispconfig_update.sh
letsencrypt_post_hook.sh
letsencrypt_pre_hook.sh
letsencrypt_renew_hook.sh
update_from_dev.sh
update_from_dev_stable.sh
update_from_svn.sh
update_runner.sh
update_stable.sh
vlogger

💡 说明：ISPConfig 没有 ispconfig --version 式的统一 CLI 命令，"命令行管理"=上述脚本 + 数据库直查。版本常量在 /usr/local/ispconfig/interface/lib/config.inc.php（实测第 62 行 define('ISPC_APP_VERSION', '3.3.2p1');）。

三、前置条件

• 以 root 执行（脚本内部读写 /usr/local/ispconfig/ 与数据库凭据）。
• php-cli 可用（自动安装器已装，php -v 实测 PHP 8.1.34 (cli) (built: Jul 3 2026 05:35:47) (NTS)）。
• 理解调用约束：server.php/cron.php 实际由 root crontab 每分钟驱动（crontab -l 实测）：

* * * * * /usr/local/ispconfig/server/server.sh 2>&1 | while read line; do echo `/bin/date` "$line" >> /var/log/ispconfig/cron.log; done
* * * * * /usr/local/ispconfig/server/cron.sh 2>&1 | while read line; do echo `/bin/date` "$line" >> /var/log/ispconfig/cron.log; done

手工调用与定时任务并存时避免同刻并发（引擎有锁，错开执行即可）。

四、各工具详解

4.1 服务引擎：server.sh / server.php

server.sh 是 crontab 实际调用的入口，做两件事（脚本原文逻辑）：以受控 PHP 参数运行 server.php（同步配置），再运行 /usr/local/ispconfig/security/check.php（安全检查）。server.php 可单独手工触发一次全量同步：

cd /usr/local/ispconfig/server && php -q server.php

实测回显：

finished server.php.

输出极简是设计使然：过程日志落在 /var/log/ispconfig/ispconfig.log。适用场景：面板改完配置不想等下一分钟；升级/排障后强制落配置。

4.2 周期任务：cron.sh / cron.php / cron_daily.php / cron_debug.php

• cron.sh → cron.php：分钟级周期任务调度（服务状态监控进 sys_log、到期备份、流量统计等）。
• cron_daily.php：每日任务集合，由 cron.php 在每日凌晨触发，也可手工执行（会跑日志分析/统计/配额核对，耗时与站点量相关）。
• cron_debug.php：排障利器——不跑整轮，按任务名单独触发。

php /usr/local/ispconfig/server/cron_debug.php

实测回显（不携带参数时的用法提示，原文照抄）：

Usage: cron_debug.php <job-name>

给出任务名即可单跑该任务（任务名即 server/cron.d/ 目录下的脚本名，如邮件统计、监控类任务文件）。

4.3 升级入口：ispconfig_update.sh

官方升级命令。脚本头注释与逻辑实测要点：先把自身复制为 .exec 再 exec（防升级过程中脚本文件被覆盖，对应官方 issue #4227），最终转调 ispconfig_update.php 并透传全部参数，注释原文明确支持 --autoinstall=/path/to/autoinstall.conf.php 静默升级。

/usr/local/ispconfig/server/scripts/ispconfig_update.sh

实测行为：交互式询问是否检测最新版本并升级（生产执行前先 mariadb-dump dbispconfig > /root/dbispconfig.sql 备库、tar -czf /root/ispconfig-etc.tar.gz /usr/local/ispconfig 备目录）。本文未实际执行升级（环境停在 3.3.2p1 最新稳定版），执行时按交互提示作答即可；升级后版本用 4.1 的版本常量复核。

配套包装脚本（同目录实测在列）：update_stable.sh（稳定通道）、update_from_dev.sh / update_from_dev_stable.sh（开发通道）、update_from_svn.sh（历史遗留的 SVN 通道）、update_runner.sh（被升级入口调用的执行器）。

4.4 补丁工具：ispconfig_patch

/usr/local/ispconfig/server/scripts/ispconfig_patch，PHP 脚本（文件头版权信息实测确认来源为官方仓库），用于从官网拉取并应用单个补丁，适合不整版升级、只打安全补丁的场景：

php /usr/local/ispconfig/server/scripts/ispconfig_patch

交互式确认后应用补丁。3.3.2p1 这类 pN 补丁即可由它单独打入。

4.5 立即备份：backup-now.php

/usr/local/ispconfig/server/backup-now.php，脚本实测头部：加载 lib/config.inc.php 与 lib/app.inc.php 并 set_time_limit(0)，即以面板框架身份执行一次备份流程（备份对象与保留策略取自面板服务器配置中的备份设置）：

php /usr/local/ispconfig/server/backup-now.php

备份产物落 /var/backup/（与面板计划备份同目录；实测卸载脚本输出原文亦确认该目录为备份目录："Backups in /var/backup/ ... are not deleted"）。

4.6 静默升级应答生成：generate_autoinstall_conf.sh

实测脚本头（原文节选）：

# ISPConfig Autoinstall Configuration Generator
# This script generates an autoinstall.conf.php file for unattended updates

它把当前服务器的升级交互答案导出为 /usr/local/ispconfig/server/lib/autoinstall.conf.php，供 ispconfig_update.sh --autoinstall=... 无人值守升级使用。要求 root（脚本内置 id -u 检查，实测非 root 报 Error: This script must be run as root）。安装阶段（非升级）的静默应答样例则在安装 tar 包 docs/autoinstall_samples/ 内（autoinstall.ini.sample 与 autoinstall.conf_sample.php，实测 tar -tzf 查得）。

4.7 Jailed SSH 工具族

create_jailkit_chroot.sh、create_jailkit_programs.sh、create_jailkit_user.sh 三个脚本负责 jailkit chroot 环境与被限制用户。日常由面板在创建 Shell 用户时自动调用；手工重建某个站点的 chroot 时按"chroot 路径"参数调用。前提是 jailkit 已装（自动安装器默认安装，实测包列表含 jailkit）。

4.8 自动安装器本体：ispconfig.ai.php

位于安装包解包目录（官方脚本默认 /tmp/ispconfig-ai/ispconfig.ai.php）。--help 实测全文与参数逐项说明已沉淀在安装篇（含 --channel/--lang/--use-php/--no-*/--i-know-what-i-am-doing 等全部参数），此处不重复；需要重跑安装或以不同参数重建服务器时，参见 《Ubuntu 22.04 安装 ISPConfig 3.3.2p1 指南》第四章。

4.9 卸载：uninstall.php

位于安装 tar 包 install/uninstall.php。实测运行（确认词必须完整 yes，输入 y 会被取消）：

cd /tmp/ispconfig3_install/install
printf "yes\n" | php -q uninstall.php

实测回显（结果行）：

>> Uninstalling ISPConfig 3...

Backups in /var/backup/ and log files in /var/log/ispconfig are not deleted.Finished uninstalling.

卸载删除 dbispconfig 数据库、ispconfig 数据库用户与 /usr/local/ispconfig/ 目录；/var/backup/ 与 /var/log/ispconfig/ 有意保留。完整卸载与残留清理流程见安装篇第九章。

4.10 证书钩子与日志分流

• letsencrypt_pre_hook.sh / letsencrypt_post_hook.sh / letsencrypt_renew_hook.sh：证书签发与续期前后由 acme.sh 自动调用，用于在签发/续期时停启面板 Web 服务，无需手工执行。
• vlogger：Apache 场景下按虚拟主机分流访问日志的小工具（面板站点日志管道使用）；排查站点日志缺失时先确认它随 Apache 正常运行。

五、注意事项

1. 配置变更优先进面板：面板改参 → server.php 同步是正道；直接改 /etc 下服务配置会在下一轮同步被面板生成的配置覆盖（配置层原理见 《ISPConfig 3.3.2p1 配置参数详解》第三章）。
2. 升级前三件套：备库（mariadb-dump dbispconfig）、备目录（/usr/local/ispconfig）、确认当前版本（ISPC_APP_VERSION 常量）。
3. 凭据卫生：安装器在 /root/ispconfig-install-log/setup-* 留有含密码的调试日志（安装结束原话警告），阅后删除；/var/log/ispconfig/cron.log 会记录任务输出，属可留存的运行日志。
4. 手工触发限频：server.php/cron.php 每分钟已被 crontab 调用，手工补跑错开时段即可，无需额外加锁（引擎自带锁机制）。

六、常见问题

Q1：手工执行 server.php 报数据库连接失败？ 确认 MySQL/MariaDB 在跑（systemctl is-active mariadb）且 server/lib/config.inc.php 中 db_password 与实际一致（改过数据库口令需同步两处 config，见配置篇 FAQ 5）。

Q2：cron_debug.php 提示 Usage 后任务名填什么？ 填 cron.php 调度的任务脚本名（/usr/local/ispconfig/server/cron.d/ 目录下的文件名，如监控、统计类任务）。执行后同样在 /var/log/ispconfig/ 留痕。

Q3：ispconfig_update.sh 能否全自动无人值守？ 可以：先用 generate_autoinstall_conf.sh 生成应答文件，再 ispconfig_update.sh --autoinstall=/usr/local/ispconfig/server/lib/autoinstall.conf.php（参数透传机制实测见 4.3 节脚本注释原文）。

Q4：补丁和整版升级先做哪个？ pN 补丁（安全修复）用 ispconfig_patch 即时打入；功能版本升级走 ispconfig_update.sh 整版流程。两者都要先备份。

七、参考链接

• 官方代码仓库（本文工具脚本均出自该仓库 install/server 目录）：https://git.ispconfig.org/ispconfig/ispconfig3

• 3.3.2 发布说明：https://www.ispconfig.org/blog/ispconfig-3-3-2-released/

• 安装全流程：《Ubuntu 22.04 安装 ISPConfig 3.3.2p1 指南》；参数体系：《ISPConfig 3.3.2p1 配置参数详解》。

• 本专栏系列：《ISPConfig 介绍与选型指南》。