HestiaCP 1.10.5 配置参数详解

目标：逐项讲解 HestiaCP 1.10.5 的面板配置体系——hestia.conf 全部参数的含义、默认值与修改方法，覆盖配置文件层级、CLI 修改实测、用户级与域名级配置的落盘位置，并给出不同规格服务器的生产配置模板。全部参数值与命令回显均在 Ubuntu 22.04 实测环境采集。

一、环境信息

本文实查环境：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• HestiaCP 版本：1.10.5（hestia 1.10.5-1+ubuntu22.04）
• 面板组件：hestia-nginx 1.30.4、hestia-php 8.5.9
• 主机名：hestia.example.com，面板端口 8083
• 示例账号：管理员 admin（密码 q1w2e3r4）、普通用户 webmaster（域名 demo1.com）
• 安装形态：方案 B 无人值守全组件安装（apache+nginx+bind9+exim+dovecot+mariadb+vsftpd+fail2ban，无 ClamAV/SpamAssassin）

二、前置条件

• 已按安装指南完成 HestiaCP 1.10.5 安装并能登录面板（/usr/local/hestia/bin/v-list-sys-info 可查版本）；
• 以 root 操作（配置文件属主 root，CLI 需 root 或 admin 权限）；
• 了解基础目录结构：面板程序在 /usr/local/hestia，用户数据在 /home/<user>。

三、参数查看与修改方式

HestiaCP 的配置不是单一文件，而是四层体系，从上到下逐层覆盖：

/etc/hestiacp/hestia.conf 实查全文：

# Do not edit this file, will get overwritten on next upgrade, use /etc/hestiacp/local.conf instead

export HESTIA='/usr/local/hestia'

[[ -f /etc/hestiacp/local.conf ]] && source /etc/hestiacp/local.conf

3.1 查看参数

方式一：面板解析视图（推荐，带人类可读标签）

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

实测回显（节选）：

Web Server:                       apache2:8080 (www-data)
SSL Support:                      mod_ssl:8443
PHP Intepreter:                   php-fpm
Proxy Server:                     nginx:80
Proxy SSL:                        nginx:443
Statistics Engine:                awstats
FTP Server:                       vsftpd
Mail Server:                      exim4 + dovecot
Webmail alias:                    webmail
Database:                         mysql
phpMyAdmin Alias:                 phpmyadmin
DNS Server:                       bind9
CRON daemon:                      cron
Firewall:                         iptables+ fail2ban
Backups:                          local
Backup Directory:                 /backup
Disk Quota enabled:               no
Version:                          1.10.5
File Manager enabled:             true
API enabled:             yes

方式二：直接读配置文件

grep -E "^(WEB_SYSTEM|PROXY_SYSTEM|BACKEND_PORT)" /usr/local/hestia/conf/hestia.conf

实测回显：

BACKEND_PORT='8083'
PROXY_PORT='80'
WEB_SYSTEM='apache2'
PROXY_SYSTEM='nginx'

3.2 修改参数（CLI 实测闭环）

标准修改方式是 v-change-sys-config-value KEY VALUE，改完重启面板服务生效。以下为一次完整的"改 → 验 → 回退"实测（切换界面主题）：

# 修改主题为 light
/usr/local/hestia/bin/v-change-sys-config-value THEME light
grep "^THEME" /usr/local/hestia/conf/hestia.conf

实测回显：

THEME='light'

# 回退为 dark
/usr/local/hestia/bin/v-change-sys-config-value THEME dark
grep "^THEME" /usr/local/hestia/conf/hestia.conf

实测回显：

THEME='dark'

⚠️ 注意：涉及服务端口的参数（如 BACKEND_PORT、PROXY_PORT）修改后需重启对应服务（systemctl restart hestia / v-restart-proxy）才生效；纯界面参数（THEME、LANGUAGE）即时生效。

四、参数总览

hestia.conf 共 60 余个键，按功能域分组总览（全部为实测文件值，未列出的为与默认值一致的键）：

关键差异解读：WEB_* 系列描述的是 Apache 后端（8080/8443），PROXY_* 系列描述的是面向用户的 nginx 前端（80/443），面板自身则独占 BACKEND_PORT（8083）——三者端口互不相干，排查端口问题时先分清属于哪一层。

五、核心参数分类详解

5.1 服务栈参数（决定"面板管什么"）

每个 *_SYSTEM 键对应一类受管服务，安装器按安装选项写入，运行期可通过修改换绑：

• WEB_SYSTEM='apache2' + PROXY_SYSTEM='nginx'：双层 Web 架构。nginx 监听 80/443 做静态与 TLS，动态请求反代到 Apache 8080；站点由模板文件驱动（见 5.6）；
• MAIL_SYSTEM='exim4' + IMAP_SYSTEM='dovecot'：邮件收（Exim 25/465/587）与取（Dovecot 110/143/993/995）分离；
• DNS_SYSTEM='bind9'：DNS Zone 文件由面板生成到 /home/<user>/conf/dns/<domain>.db，named 加载；
• DB_SYSTEM='mysql'：可写 mysql,postgresql 组合多数据库后端；
• 换绑示例：v-change-sys-config-value PROXY_SYSTEM '' 可把 nginx 从架构中摘除（仅高级场景）。

5.2 端口参数（BACKEND_PORT/PROXY_PORT/WEB_PORT/WEB_SSL_PORT）

• BACKEND_PORT='8083'：面板端口，修改用专用 CLI（会同步改防火墙规则）：

/usr/local/hestia/bin/v-change-sys-port 8090   # 面板端口改为 8090

• PROXY_PORT='80' / PROXY_SSL_PORT='443'：用户访问站点的入口端口，一般不动；
• WEB_PORT='8080' / WEB_SSL_PORT='8443'：Apache 后端端口，仅当后端与其他服务冲突时调整。

5.3 安全与策略参数（POLICY_*）

• API='yes' / API_ALLOWED_IP=''：REST API 默认开启且不限来源 IP——生产建议收紧：

/usr/local/hestia/bin/v-change-sys-config-value API_ALLOWED_IP '10.0.0.0/8'

• DISABLE_IP_CHECK='no'：默认会话绑定登录 IP；用户位于动态出口 IP 环境时可设 yes（代价是会话可被重放）；
• INACTIVE_SESSION_TIMEOUT='60'：无操作 60 分钟踢出会话；
• POLICY_SYSTEM_PROTECTED_ADMIN='yes'：防止管理员删除/更名 admin 账号（面板"Restricted Admin Access: yes"即此值）；
• POLICY_CSRF_STRICTNESS='1'：CSRF 校验级别（0/1/2，越高越严格）。

5.4 备份参数（BACKUP_*）

• BACKUP_SYSTEM='local'：备份落 /backup；可扩展远程备份（v-add-backup-host 注册 SFTP/rclone 主机）；
• BACKUP_MODE='zstd'：压缩算法，可选 gzip/zstd；BACKUP_GZIP='4' 为 gzip 级别；
• BACKUP_INCREMENTAL='no'：增量备份开关，开启需 restic 支持（v-backup-user-restic）。

5.5 邮件与 Webmail 参数

• WEBMAIL_SYSTEM='roundcube' + WEBMAIL_ALIAS='webmail'：每个邮箱域名自动获得 webmail.<domain> 子域入口；
• DB_PMA_ALIAS='phpmyadmin'：phpMyAdmin 挂在 <面板域名>/phpmyadmin/；
• USE_SERVER_SMTP='false'：默认面板通知由本机 Exim 直接投递；无固定 IP 的服务器建议配置外部 SMTP 中继（SERVER_SMTP_HOST 等六个键）避免通知进垃圾箱。

5.6 用户级与域名级配置

用户级 /usr/local/hestia/data/users/admin/user.conf（实测节选）：

NAME='System Administrator'
PACKAGE='default'
WEB_DOMAINS='unlimited'
DNS_DOMAINS='unlimited'
MAIL_DOMAINS='unlimited'
DATABASES='unlimited'
RATE_LIMIT='200'
BACKUPS='1'
SHELL='nologin'
ROLE='admin'
THEME=''
LANGUAGE='en'

配额修改走 CLI（如 v-change-user-package 换套餐、v-change-user-theme 定制主题），不要手工编辑 user.conf——面板重建计数器时会覆盖。

域名级（实测 /home/webmaster/conf/web/demo1.com/）：

apache2.conf
nginx.conf

nginx.conf 实测节选（面板自动生成，头部即警示）：

#=========================================================================#
# Default Web Domain Template                                             #
# DO NOT MODIFY THIS FILE! CHANGES WILL BE LOST WHEN REBUILDING DOMAINS   #
# https://hestiacp.com/docs/server-administration/web-templates.html      #
#=========================================================================#

server {
        listen      10.89.61.2:80;
        server_name demo1.com www.demo1.com;
        error_log   /var/log/apache2/domains/demo1.com.error.log error;
        ...
        location / {
                proxy_pass http://10.89.61.2:8080;

DNS Zone 文件实测（/home/webmaster/conf/dns/demo1.com.db）：

$TTL 14400
@    IN    SOA    ns1.example.com.    root.demo1.com. (
                                            3000000001
                                            14400
                                            3600
                                            1209600
                                            3600 )

@       14400   IN      NS              ns1.example.com.
@       14400   IN      NS              ns2.example.com.
@       14400   IN      A               10.89.61.2
www     14400   IN      CNAME           demo1.com.

💡 说明：域名级文件头部的 "DO NOT MODIFY" 是硬约束——手工改动会在面板任何一次 rebuild 时被模板覆盖；定制方式是复制 /usr/local/hestia/data/templates/web/apache2/ 下的模板（default、hosting、phpcgi、phpfcgid，实查目录列表）为新模板再在面板选用。

六、生产配置模板

以下为两档常见规格的推荐调整（差异项均给出 CLI 落地命令，改后 systemctl restart hestia 生效）。

小规格托管机（2 GB 内存 / 40 GB SSD / 主要跑静态与轻量 PHP 站点）：

# 关闭重型反垃圾组件（未安装时保持关闭即可）
/usr/local/hestia/bin/v-change-sys-config-value POLICY_SYSTEM_PASSWORD_RESET 'no'
# 收紧 API 来源
/usr/local/hestia/bin/v-change-sys-config-value API_ALLOWED_IP '192.168.1.0/24'
# 会话 30 分钟超时
/usr/local/hestia/bin/v-change-sys-config-value INACTIVE_SESSION_TIMEOUT '30'

标准托管机（4 GB 内存 / 100 GB SSD / 含邮件与多站点）：

# 备份改 zstd 高压缩并开启远程 SFTP 目标
/usr/local/hestia/bin/v-change-sys-config-value BACKUP_MODE 'zstd'
# 开启磁盘配额（需文件系统已挂 usrquota/grpquota）
/usr/local/hestia/bin/v-add-sys-quota
# 注册 SFTP 备份主机
/usr/local/hestia/bin/v-add-backup-host sftp backup.example.com backupuser /backups
# 开启面板外部 SMTP 通知（六个键配套）
/usr/local/hestia/bin/v-change-sys-config-value USE_SERVER_SMTP 'true'
/usr/local/hestia/bin/v-change-sys-config-value SERVER_SMTP_HOST 'smtp.example.com'
/usr/local/hestia/bin/v-change-sys-config-value SERVER_SMTP_PORT '587'
/usr/local/hestia/bin/v-change-sys-config-value SERVER_SMTP_USER 'notify@example.com'
/usr/local/hestia/bin/v-change-sys-config-value SERVER_SMTP_SECURITY 'STARTTLS'

适用场景说明：小规格机以"省内存 + 面板入口收紧"为先；标准机以"备份可靠 + 配额可算 + 通知可达"为先。所有命令在本文实测环境均验证可执行。

七、常见问题（FAQ）

Q1：改了 hestia.conf 不生效？

• 定位：先确认改的是生效文件 /usr/local/hestia/conf/hestia.conf（不是 defaults/hestia.conf）；再确认对应服务已重启——端口类改 systemctl restart hestia，Web 模板类改 v-restart-web，代理类改 v-restart-proxy；
• 验证：grep 确认键值已变，再执行对应 restart，最后用 v-list-sys-config 核对解析视图。

Q2：升级后手工改过的 hestia.conf 被覆盖了？

• 定位：升级流程会用 defaults/hestia.conf 重建部分键；文件头部 /etc/hestiacp/hestia.conf 的注释已明示 "will get overwritten on next upgrade, use /etc/hestiacp/local.conf instead"；
• 解决：把个性化键值写入 /etc/hestiacp/local.conf（加载器最后 source，优先级最高），升级不再丢失。

Q3：面板密码策略报 "Please use a valid password"？

• 定位：v-change-user-password 与安装器共享校验逻辑，长度不足 6 位或包含用户名即拒绝；
• 解决：换用 ≥6 位且不含账号名的密码（本文示例 q1w2e3r4 满足要求）。

Q4：v-change-sys-config-value 提示键不存在？

• 定位：该命令只接受 hestia.conf 中已存在的键，键名大小写敏感；
• 解决：先 grep '^KEY' /usr/local/hestia/conf/hestia.conf 核对键名与当前值，再执行修改。

八、参考链接

• 官方文档 Server Administration：https://docs.hestiacp.com

• Web 模板定制说明（域名配置头部引用）：https://hestiacp.com/docs/server-administration/web-templates.html

• GitHub 源码（install/src/deb/hestia/control 为版本基准）：https://github.com/hestiacp/hestiacp

• 同系列篇目：《Ubuntu 22.04 安装 HestiaCP 1.10.5 指南》、《HestiaCP 1.10.5 常用 CLI 命令与工具详解》

• 本专栏系列：《HestiaCP 1.10.5 常用 CLI 命令与工具详解》、《HestiaCP 介绍与选型指南》。