HestiaCP 1.10.5 常用 CLI 命令与工具详解

目标：系统讲解 HestiaCP 1.10.5 的 v-* 命令行工具体系——从用户、网站、DNS、邮件、数据库的资源创建，到查询、变更、暂停、删除的生命周期管理，再到备份恢复与命令检索，每条命令均附真实执行回显。Web 面板的每一个操作底层都对应一条 v-* 命令，掌握 CLI 即掌握面板的全部自动化能力。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
HestiaCP 版本：1.10.5（hestia 1.10.5-1+ubuntu22.04）
CLI 工具目录：/usr/local/hestia/bin/，共 524 条 v-* 命令（ls | wc -l 实测）
示例账号：管理员 admin / q1w2e3r4；演示用户 webmaster / q1w2e3r4；演示域名 demo1.com（CLI 生态示例域名）
服务状态：全组件安装（apache2+nginx+bind9+exim4+dovecot+mariadb+vsftpd+fail2ban）

二、工具概览

v-* 命令按动词前缀分为五大类，命令名即语义（<对象>-<动作>-<资源>）：

前缀	语义	代表命令
`v-add-`	创建/绑定	v-add-user、v-add-web-domain、v-add-mail-account
`v-list-`	查询/列表	v-list-users、v-list-web-domains、v-list-sys-info
`v-change-`	修改属性	v-change-user-password、v-change-sys-config-value
`v-suspend-` / `v-unsuspend-`	暂停/恢复	v-suspend-user、v-unsuspend-web-domain
`v-delete-`	删除	v-delete-user、v-delete-web-domain
其他	运维动作	v-backup-user、v-restart-service、v-search-command、v-update-*

所有命令统一约定：成功静默（无输出、退出码 0），失败输出 Error 并返回非 0；支持管道可读输出（默认）与 JSON/CSV 等格式（追加 json/plain/csv 作为最后一个参数）。不带参数运行任意命令会打印 Usage 用法行。

权限模型：admin 用户可执行全部命令；普通用户（如 webmaster）只能对自己名下资源执行受限子集，本文示例均以 root 身份调用（等价于 admin 会话）。

三、前置条件

已安装 HestiaCP 1.10.5 并可用 v-list-sys-info 查到版本（安装见安装指南篇）；
命令行以 root 登录；CLI 位于 /usr/local/hestia/bin/（PATH 已由 /etc/profile.d/hestia.conf 注入，直接敲 v- 前缀命令即可，本文写全路径以便核对）；
需要一个可用作演示的域名（本文用 demo1.com，生产环境替换为自己的域名）。

四、各工具详解

4.1 v-add-user：创建用户

创建面板用户，语法 v-add-user USER PASSWORD EMAIL [PACKAGE] [NAME]。不带参数运行先看用法：

/usr/local/hestia/bin/v-add-user

实测回显：

Usage: v-add-user USER PASSWORD EMAIL [PACKAGE] [NAME]

创建演示用户 webmaster：

/usr/local/hestia/bin/v-add-user webmaster q1w2e3r4 webmaster@example.com default "Web Master"

实测回显（成功即静默）：

（无输出，退出码 0）

验证 + 重复创建的报错实测：

/usr/local/hestia/bin/v-add-user webmaster q1w2e3r4 webmaster@example.com

实测回显：

Error: user webmaster exists

退出码实测为 4（Hestia 用不同错误码区分 E_EXISTS=4、E_INVALID=1 等，脚本化时可据此分支）。

4.2 v-add-web-domain / v-add-dns-domain / v-add-mail-domain：三类域名

同一个域名在 Hestia 中分三类资源独立管理，v-add-domain 可三类一次建齐，分立命令便于按需创建：

# Web 站点（自动绑定服务器 IP，生成 nginx/apache 配置）
/usr/local/hestia/bin/v-add-web-domain webmaster demo1.com

# DNS Zone（生成 BIND Zone 文件，参数：用户 域名 IP）
/usr/local/hestia/bin/v-add-dns-domain webmaster demo1.com 10.89.61.2

# 邮箱域（生成 Exim/Dovecot 配置与 DKIM）
/usr/local/hestia/bin/v-add-mail-domain webmaster demo1.com

实测回显：三条命令均静默成功（退出码 0）。创建后验证：

/usr/local/hestia/bin/v-list-web-domains webmaster

实测回显：

DOMAIN   IP   TPL   SSL   DISK   BW   SPND   DATE
------   --   ---   ---   ----   --   ----   -----
demo1.com 56.155.135.124 default no 0 0 no 2026-10-21

💡 说明：IP 列显示的是服务器 NAT 出口 IP（安装时自动登记，见 v-list-sys-ips），Web 配置实际监听内网 IP——/home/webmaster/conf/web/demo1.com/nginx.conf 中 listen 10.89.61.2:80 与 proxy_pass http://10.89.61.2:8080 可佐证双层架构。

4.3 v-add-database：创建数据库

语法 v-add-database USER DB_USER DB_PASS [DB] [HOST] [TYPE]，数据库名与账号自动加 用户名_ 前缀：

/usr/local/hestia/bin/v-add-database webmaster demouser q1w2e3r4 demo1db
/usr/local/hestia/bin/v-list-databases webmaster

实测回显：

DATABASE           USER                HOST       TYPE   DISK  SPND  DATE
--------           ----                ---        ----   ---   ---   ----
webmaster_demo1db  webmaster_demouser  localhost  mysql  0     no    2026-10-21

实际生成的库名为 webmaster_demo1db、账号 webmaster_demouser（前缀防跨用户冲突），在 phpMyAdmin 与站点配置中使用这两个全名。

4.4 v-list-* 查询体系（重点命令实测）

系统信息与 IP：

/usr/local/hestia/bin/v-list-sys-info
/usr/local/hestia/bin/v-list-sys-ips

实测回显：

HOSTNAME            OS      VER    ARCH    HESTIA  RELEASE  UPTIME  LA
--------            --      ---    ----    ------  -------  ------  --
hestia.example.com  Ubuntu  22.04  x86_64  1.10.5  release  2396    0.87  /  1.00  /  1.32

IP          MASK           NAT             STATUS  WEB  DATE
--          ----           ---             ------  ---  ----
10.89.61.2  255.255.255.0  56.155.135.124  shared  1    2026-10-21

服务运行状态（含每服务 CPU/内存占用）：

/usr/local/hestia/bin/v-list-sys-services

实测回显：

NAME        STATE    CPU  MEM   UPTIME
----        -----    ---  ---   ------
apache2     running  0    457   0
php8.5-fpm  running  0    11    2
nginx       running  0    49    2
bind9       running  0.1  257   0
exim4       running  0    17    1
dovecot     running  0    0     1
mariadb     running  0.3  1397  1
vsftpd      running  0    1     1
cron        running  0    0     1
ssh         running  0    1     0
iptables    running  0    0     0
fail2ban    running  0.2  154   2

用户列表（面板首页同源数据）：

/usr/local/hestia/bin/v-list-users

实测回显（webmaster 建成后）：

USER       ROLE   PKG      WEB  DNS  MAIL  DB  DISK  BW  SPND  DATE
----       ----   ---      ---  ---  ----  --  ---   --  ----  ----------
admin      admin  default  1    0    0     0   0     0   no    2026-10-21
webmaster  user   default  1    1    1     1   0     0   no    2026-10-21

输出格式切换：任意 v-list-* 命令末尾追加 json / plain / csv 即切换格式，便于脚本消费：

/usr/local/hestia/bin/v-list-users json | head -5

实测回显（节选）：

{
    "admin": {
        "ROLE": "admin",
        "PACKAGE": "default",
        "WEB_DOMAINS": "1",
    ...

4.5 v-change-* 修改与 v-suspend-*/v-delete- 生命周期

# 改用户密码（示例统一用 q1w2e3r4）
/usr/local/hestia/bin/v-change-user-password webmaster q1w2e3r4

# 暂停/恢复用户（暂停后其全部站点/邮箱停止服务）
/usr/local/hestia/bin/v-suspend-user webmaster
/usr/local/hestia/bin/v-list-users | grep webmaster
/usr/local/hestia/bin/v-unsuspend-user webmaster

# 删除资源（删除用户会级联删除其全部站点/域名/数据库/备份）
/usr/local/hestia/bin/v-delete-web-domain webmaster demo1.com
/usr/local/hestia/bin/v-delete-user webmaster

v-suspend-user 后查询实测回显（SPND 列变 yes）：

webmaster  user   default  1    1    1     1   0     0   yes   2026-10-21

⚠️ 注意：v-delete-user 不可逆且级联删除全部资源，生产操作前先 v-backup-user 全量备份。

4.6 v-backup-user 备份与恢复

/usr/local/hestia/bin/v-backup-user webmaster

实测回显：

-- SUMMARY --
2026-10-21 07:45:36 Local: /backup/webmaster.2026-10-21_07-45-36.tar
2026-10-21 07:45:36 Size: 1 MB
2026-10-21 07:45:36 Runtime: 1 minute

/usr/local/hestia/bin/v-list-user-backups webmaster

实测回显：

BACKUP                             TYPE   SIZE  TIME  DATE
------                             ----   ---   ---   ----
webmaster.2026-10-21_07-45-36.tar  local  1     1     2026-10-21

恢复用 v-restore-user webmaster webmaster.2026-10-21_07-45-36.tar（可指定只恢复 web/dns/mail/db 子系统）。备份策略（次数、排除目录）在用户套餐（v-add-user-package）与 v-update-user-backup-exclusions 中管理。

4.7 v-search-command：命令检索器

524 条命令记不住时用检索器按关键词过滤：

/usr/local/hestia/bin/v-search-command backup

实测回显（节选）：

Command Search Results
=================================
v-add-backup-host
v-add-backup-host-restic
v-backup-user
v-backup-user-config
v-backup-user-restic
v-backup-users
v-backup-users-restic
v-delete-backup-host
v-delete-backup-host-restic
v-delete-user-backup

4.8 服务与系统级运维命令

# 重启单类服务（web=nginx+apache，每行一个动作）
/usr/local/hestia/bin/v-restart-web
/usr/local/hestia/bin/v-restart-mail
/usr/local/hestia/bin/v-restart-dns

# 单独启停某个服务
/usr/local/hestia/bin/v-start-service exim4
/usr/local/hestia/bin/v-stop-service dovecot

# 面板自身与组件批量升级
/usr/local/hestia/bin/v-update-sys-hestia-all

# 重建用户配置（模板变更后重生成全部站点配置）
/usr/local/hestia/bin/v-rebuild-user webmaster

4.9 REST API 调用入口

CLI 与 API 同源：API 端点即面板地址 https://<服务器IP>:8083/api/，用 v-add-access-key（或面板内生成）创建 API Key 后以 POST user/hash/cmd/arg1... 调用，cmd 就是 v-* 命令名。API 开关与白名单见 API/API_ALLOWED_IP 配置项（见《HestiaCP 1.10.5 配置参数详解》5.3 节）。快速自测：

/usr/local/hestia/bin/v-generate-api-key

实测回显（返回 32 位 Key 串，实际生成于本环境）：

yuNXa9r1sNsDg1GAYyaJfaRnZuzd1plN

带权限约束的正式创建用 v-add-access-key（用法实测：Usage: v-add-access-key USER [PERMISSIONS] [COMMENT] [FORMAT]）。

⚠️ 注意：示例 Key 仅演示格式，真实 Key 等同于账号密码，生成后立即妥善保存，泄露需立刻 v-delete-access-key 吊销。

五、注意事项

静默成功原则：v-* 命令成功无输出，脚本中务必用 $? 或 set -e 判断结果，退出码非 0 即失败（4=E_EXISTS、1=E_INVALID 等）；
参数顺序固定：每条命令的 USER/DOMAIN 等位置参数不可换序，可选项在最后；不确定就裸跑命令看 Usage；
输出格式：给脚本消费时统一在末尾加 json（稳定结构），人看用默认表格；
级联删除：v-delete-user / v-delete-web-domains（复数）是批量级联删除，慎用；
不要手工改数据文件：/usr/local/hestia/data/users/ 下的 conf 是面板的"数据库"，绕过 CLI 直接改会导致计数器与真实状态漂移，改后必须 v-rebuild-user 重建。

六、常见问题（FAQ）

Q1：命令报 Error: not enough arguments？

定位：位置参数缺省，常见于漏传域名或用户名；
解决：裸跑该命令查看 Usage 行（如 v-add-user 输出 Usage: v-add-user USER PASSWORD EMAIL [PACKAGE] [NAME]），按序补齐参数。

Q2：提示 Error: user webmaster exists（退出码 4）？

定位：资源已存在，v-add-* 系列不做幂等覆盖；
解决：先 v-list-* 确认现状；确需重建则先 delete 再 add，或改用 v-change-* 修改属性。

Q3：root 执行报 Error: You are not logged in？

定位：CLI 鉴权依赖会话上下文，通过 su 切换（非 su -）时环境变量丢失；
解决：用 su - root（完整登录壳）或直接 SSH root 会话执行。

Q4：v-list- 输出乱码或列错位？*

定位：非 UTF-8 终端locale 引起；
解决：export LANG=C.UTF-8 后重试；或改用 json 格式输出规避表格对齐问题。

七、参考链接

官方 CLI 文档：https://docs.hestiacp.com/admin_docs/cli.html
全部命令源码（bin 目录）：https://github.com/hestiacp/hestiacp/tree/release/bin
GitHub 仓库：https://github.com/hestiacp/hestiacp
同系列篇目：《HestiaCP 介绍与选型指南》、《Ubuntu 22.04 安装 HestiaCP 1.10.5 指南》、《HestiaCP 1.10.5 配置参数详解》