4 篇博文 含有标签「cPanel」

cPanel 138 装在 AlmaLinux 10 上，安装顺利、面板能开——真正的坑集中在新机收尾阶段：安全硬化、面板资源修复、域名挂载，每一步都有反直觉的行为在等着。

在为客户执行 中国合规托管与站点迁移 项目时遇到此问题——新生产机按硬化标准交付，收尾阶段三类故障在同一台 AlmaLinux 10 上集齐，本文按场景拆解。

TL;DR​

三个场景各有「表面正确、实际无效」的陷阱：TFA 给用户写完 secret 登录却不出验证码步骤——策略总开关没开，所有用户级配置不生效；前端库「缺失」要先用官方 manifest 判真伪——一部分文件上游本就不在那条 cpanelsync 树里，一部分是 digest 缓存污染让 upcp 假装成功；Park 域名被 NS 归属校验拒绝——DNS 在云上时走 userdata include 注入 ServerAlias 才是正路。

场景一：WHM 前端共享库「缺失」，先判真伪再修复​

排查面板异常时发现 /usr/local/cpanel/base/libraries 不存在——先别急着当缺陷修。cPanel 138 上游本就没有这个路径，前端共享库的真实位置在别处：

• base/frontend/jupiter/libraries/——符号链接农场，链接指向 ../../../../3rdparty/share/<lib>，由 jupiter 独立的 cpanelsync 树分发（含 sortablejs、ui-fonts、fontawesome、cldr）
• base/unprotected/libraries/——同机制，托管旧库

判定文件是否真缺失，不要看单一路径，拉官方 manifest 对比：

curl -sO http://httpupdate.cpanel.net/cpanelsync/138/<树>/.cpanelsync.bz2
bzcat .cpanelsync.bz2 | grep <目标路径>
# 条目格式：d===./路径===755 （目录）
#           l===./链接名===777===目标 （符号链接）

第二条铁律：base/ 不全是 cpanelsync 分发。v138 的 cpanel-* RPM（bootstrap5、ace-editor、sortablejs 等）直接把库装进 /usr/local/cpanel/3rdparty/share/<lib>/<版本>，cpanelsync 只负责把符号链接铺进主题树。RPM 侧用 rpm -V <包名> 验，cpanelsync 侧用 manifest 验，两边都要查。

如果确认缺失、跑 upcp --sync 却报成功而文件没回来，检查 digest 缓存：/usr/local/cpanel/.cpanelsync.digest 及主题树各自的 .cpanelsync.digest 被中断的更新污染后，--sync 会跳过缺失文件且退出码为 0。删掉对应 digest 文件再跑 upcp --force 强制全量校验，缺什么补什么。

--sync 报成功不等于文件齐全，最终以页面实际加载为准——用 headless Chromium 收集 console error 与 4xx 以上请求，比任何退出码都诚实。

这个场景在硬化机上还有两个运维坑：

• root 通路首选云助手 aliyun ecs RunCommand（带外、免 SSH、自带审计）；--InstanceId.1 传实例 ID，CommandContent 传原始脚本而非 base64。临时提权的 sudoers 文件必须配 /etc/cron.d 自清理行，回收后用 sudo -n whoami 验证——应报 a password is required 才算收干净
• 批量探测 cpsrvd 会被限流：shell 循环逐条 curl 几十次后全部返回 000，误判成大面积 404。改单 curl 进程多 URL（keepalive 复用连接）即正常。另外 pkill -f 会匹配到自己 bash -c 的命令行，匹配串务必加 [] 技巧或直接用 PID

WHM 页面返回 200 也不代表登录态有效——登录页同样是 200。要抓 <title> 或 body 特征文本（如 Two-Factor Authentication 页的标题）做判断。

场景二：root 硬化连环坑​

硬化目标：root 不走 SSH、面板加 TFA、sudo 最小白名单。每一步都有前置条件。

TFA 策略总开关是前置条件。 twofactorauth_set_tfa_config 给用户写入 secret 后，登录表单并不一定出现动态码步骤——twofactorauth_policy_status 的 is_enabled 必须为 1（用 twofactorauth_enable_policy 开启），否则 WHM 登录只验密码。浏览器实测：开策略前密码直进，开后出现「Enter the security code」页。

CLI 配置 TFA 还有两个细节：twofactorauth_set_tfa_config 的验证码参数是 tfa_token 不是 code（传 code 被静默忽略，报「security code is invalid」）；TOTP 码必须用服务器时钟计算——两端时钟差 23 秒就跨窗口，本地算的码必拒。secret 落盘在 /var/cpanel/authn/twofactor_auth/tfa_userdata.json。

无 root SSH 时跑 API 的正路是会话 + cpsess 路径。 create_user_session 拿到链接、curl cookie-jar 登录后，API 调用必须带 cpsess 前缀：https://host:2087/cpsessNNN/json-api/<function>，直接打 /json-api/ 报 "Token denied"。create_user_session 的 service 参数是 whostmgrd（带 d），whostmgr/cpanel 都报参数无效，合法值只有 cpaneld/webmaild/whostmgrd 三个。

sudoers 是全序列精确匹配。 白名单条目里连 --output=json 的位置和参数顺序都被锁定，调用命令任何增删改都会被静默降级为密码认证——而 opsuser 密码锁定时就是直接拒绝。改命令必须同步改 /etc/sudoers.d/ 对应文件。

whmapi1 三个易踩点： 真实路径 /usr/local/cpanel/bin/whmapi1（统一写真实路径，软链路径匹配性存疑）；默认输出 YAML，喂 jq 前必须 --output=json；sethostname 的参数名是 hostname 不是 domain——写 domain= 会静默传空直接空跑，且 cPanel 拒绝 whm./cpanel./webmail. 等自动前缀做 hostname。NS 角色禁用的机器上 sethostname 收尾报 dnsadmin socket「Connection refused」属预期，不影响切换；切换后 create_user_session 返回的 URL 主机名自动更新，cpsrvd 证书由 AutoSSL 机制约 1 分钟内自动签发。

sshd drop-in 首值生效。 AlmaLinux 主 sshd_config 的 Include sshd_config.d/*.conf 在文件顶部，drop-in 先于主文件正文解析，而 sshd 取首个出现的值——所以 drop-in 能压过主文件正文；drop-in 之间按文件名字典序（000- 排在 00- 前）。改完必跑 sshd -t 加 sshd -T | grep -E 'permitrootlogin|passwordauthentication|allowusers' 确认最终生效值再 reload。

Host Access Control 在这套组合上无效。 cPanel 138 + AlmaLinux 10 的 cpsrvd 不链接 libwrap（tcp_wrappers 已从 RHEL 系移除），写 /etc/hosts.allow 规则并重启 cpsrvd 后实测照样放行。应用层白名单交给 firewalld rich rules；hosts.allow 留着无害，未来版本若恢复 libwrap 会自动生效。

AlmaLinux 10 的三个验证盲区： last 恒空——systemd 256 弃用 wtmp，登录记录只在 journal（root 可 journalctl -u sshd）；opsuser 执行 /usr/bin/su 报 Permission denied（exec 层被限），root 密码有效性只能经 WHM 表单或 VNC 验证；/etc/ssh/sshd_config.d/、/etc/cron.d/*（600 权限）、/var/cpanel/authn/ 对 opsuser 不可读，硬化复核须在 WHM Terminal 或 VNC 完成。

场景三：域名 NS 不在本机，别名挂载被拒​

uapi Park park domain=test.xxx 被拒：域名的 NS（托管在阿里云）"not associated with this server"——cPanel 会校验域名权威 NS 是否指向本机，而国内实践中 DNS 常年托管在云 DNS，这条校验天然过不去。

不改域名 NS 的官方正路是 userdata include 注入 ServerAlias：

# http 与 https 各放一份
/etc/apache2/conf.d/userdata/std/2_4/<user>/<domain>/alias.conf
/etc/apache2/conf.d/userdata/sssl/2_4/<user>/<domain>/alias.conf

注意 ssl 侧目录是 sssl/2_4（部分版本写作 ssl/2_4，以 httpd.conf 中未注释的 include 行为准）。内容一行：

ServerAlias test.xxx

然后 /scripts/rebuildhttpdconf 重建。目录名写错时 include 行会保持注释状态、静默不生效——验证方法是看 httpd.conf 里 Include "...userdata..." 行有没有注释前缀。

命中验证：httpd -S 看别名落在哪个 vhost，再对比各 vhost 的 domlog 是否进了请求。

一个衔接提醒：用 ServerAlias 挂进来的域名不归 AutoSSL 管理，证书不会自动签发——处理方式见 cPanel AutoSSL 不签发证书？排除列表与 vhost 证书路径。

常见问题​

sshd 配置了 PermitRootLogin no 为什么 root 还能登录？​

AlmaLinux 主 sshd_config 的 Include 指令在文件顶部，sshd_config.d/ 下的 drop-in 先于主文件正文解析，而 sshd 对同名配置项取首个出现的值——所以 drop-in 能压过主文件，反之若主文件里有更早生效的值就以它为准。drop-in 之间按文件名字典序排序。改完必跑 sshd -t 语法检查，再用 sshd -T | grep permitrootlogin 确认最终生效值。

WHM 登录时的两步验证要怎么开启？​

先用 twofactorauth_enable_policy 打开策略总开关——策略未启用时，即使用户已写入 TOTP secret，登录表单也不会出现动态码输入步骤，登录退化为仅密码。给用户配置 secret 用 twofactorauth_set_tfa_config，注意验证码参数名是 tfa_token 而不是 code，且 TOTP 码必须用服务器时钟计算，两端时钟差 20 多秒就会跨窗口导致验证码被拒。

cPanel 服务器文件缺失怎么判断是不是真的缺了？​

不要看单一路径下结论，先拉 cPanel 官方 manifest 对比：httpupdate.cpanel.net 的 cpanelsync 路径下每个版本每个树都有 .cpanelsync.bz2 清单，bzgrep 检索目标路径即可确认上游是否存在该文件。同时注意 base/ 目录不全是 cpanelsync 分发——bootstrap5、sortablejs 这类库由 RPM 安装，要用 rpm -V 验证。两侧都查过才能判定真缺失。

在阿里云 ECS 上用 cpmove 归档恢复 cPanel 账户，restorepkg 报成功、httpd -S 里 namevhost 一目了然——浏览器打开域名，看到的却是服务器的默认页。

在为客户执行 中国合规托管与站点迁移 项目时遇到此问题——两个中国站点整体搬迁到阿里云中国区的 cPanel 环境，恢复完成后第一次公网验证就命中了这道云架构题。

TL;DR​

阿里云 ECS 的网卡上只有私网 IP，公网 IP 是边缘 NAT、不落在本机。从旧服务器迁来的 vhost 绑定了那个本机不存在的公网地址，运行时永不匹配，所有流量落进通配默认 vhost。解法是把三处 IP 记录一起改掉（/etc/wwwacct.conf、/var/cpanel/users/、/var/cpanel/userdata/）再重建 httpd.conf；新账户的默认 IP 写进 /etc/mainip，从源头避免复发。

问题现象​

迁移每一步看起来都成功：restorepkg 无报错，Apache 配置里 namevhost 也在。但公网验证全部落空——任何域名都指向同一个 defaultwebpage 跳转页，主站的 domlog 恒为空。

铁证是一条静态文件请求：挑一个真实存在、从未改动过的文件（如 /some-real-page.html）直接访问，返回 404，而且 404 错误页的样式来自 /var/www/html/*.shtml——那是 cPanel 默认站点的目录。自己的站点目录根本没接到请求。

$ httpd -S | grep example.cn
203.0.113.10:80                   example.cn ...

vhost 绑的是 203.0.113.10——旧服务器的公网 IP。而这台新机器的网卡上，根本没有这个地址。

根因​

公网 IP 不在本机。 hostname -I 只返回 172.28.100.10 这样的私网地址。阿里云 ECS 的公网 IP 是边缘 NAT：流量先到阿里云网关，再转发到实例的私网地址，公网 IP 从头到尾不出现在网卡上。

恢复归档原样继承了旧 IP。 旧服务器是公网 IP 直落网卡的传统 VPS，vhost 里记录的就是公网地址。cpmove 把这套配置原样搬来，vhost 的 Address 指向一个本机不存在的地址。

Apache 运行时按 IP:Port 匹配 vhost：请求进来，目标地址对不上任何 namevhost，于是全部落进 *:80 的默认 vhost（DocumentRoot 指向 /var/www/html）。这就是默认页、domlog 为空、404 样式对不上号三个现象的共同源头。

解决方案​

1. 坐实 NAT 环境。 一条命令：

hostname -I
# 172.28.100.10   ← 只有私网段即坐实

2. 三处 IP 记录一起改，缺一不可。 cPanel 的 IP 信息存了三份，各自服务不同流程——只改 userdata 能让 rebuild 出正确 vhost，但 wwwacct.conf 不改的话，下次创建账户又会写错。

# 2a. 全局默认（新建账户向导读取）
sed -i 's/^ADDR=.*/ADDR=172.28.100.10/' /etc/wwwacct.conf

# 新账户的默认 IP，一并写好
echo 172.28.100.10 > /etc/mainip

# 2b. 账户级记录
sed -i 's/^IP=.*/IP=172.28.100.10/' /var/cpanel/users/example

# 2c. userdata 全量替换——rebuildhttpdconf 只认这里
cd /var/cpanel/userdata/example
for f in *; do
  [ -f "$f" ] && sed -i 's/^ip: .*/ip: 172.28.100.10/' "$f"
done

2c 里的 [ -f "$f" ] 不是多余：userdata 目录里混有 scope 这类 socket 文件，不加判断 sed 会直接报错。

3. 重建并重启。

/scripts/rebuildhttpdconf
/scripts/restartsrv_httpd

4. 验证。 httpd -S 里 namevhost 的地址应变成私网 IP；服务器上可用带 Host 头的请求自测命中哪个 vhost：

curl -s -H "Host: example.cn" http://172.28.100.10/some-real-page.html -o /dev/null -w "%{http_code}\n"
# 200 ← 不再是默认 vhost 的 404

最后从外部机器访问域名确认页面正常，domlog 开始进请求。

边界与变体​

• 全新装机场景：先写好 /etc/wwwacct.conf 的 ADDR 和 /etc/mainip 再建账户，从源头避免 vhost 绑错地址；本例是恢复迁移踩的坑，全新建户同样适用。
• 不止阿里云：AWS 弹性 IP 等云厂商的 NAT 化公网 IP 机制相同，凡是「公网 IP 不出现在 hostname -I 里」的环境，cPanel 的 IP 配置都要按私网写。
• 本机验证盲区：在服务器上用 127.0.0.1 或公网地址自测都会命中默认 vhost 造成误判，要连私网 IP 并带 Host 头。

常见问题​

网站访问跳到默认页面怎么办？​

先确认命中了哪个 vhost：主站域名日志（domlog）恒为空、请求真实存在的静态文件返回 404 且错误页样式来自默认站点目录，就是命中了默认 vhost。再用 httpd -S 对照 hostname -I，看 vhost 绑定的地址是否真的在本机网卡上——云服务器 NAT 架构下公网 IP 不在网卡，绑了就永不匹配。

网站访问跳到默认页面为什么打不开？​

根因是地址不匹配：阿里云 ECS 网卡上只有私网 IP，公网 IP 由边缘网关 NAT 转发、不落在本机；从旧服务器恢复的 vhost 绑定了那个本机不存在的公网地址，Apache 运行时按 IP:Port 匹配 vhost，永不命中，所有流量落进通配默认 vhost。把三处 IP 配置改成私网 IP 并重建 httpd.conf 即可恢复。

cPanel 账户迁移到阿里云后要改哪些 IP 配置？​

三处一起改：/etc/wwwacct.conf 的 ADDR（全局默认）、/var/cpanel/users/ 下账户文件的 IP=、/var/cpanel/userdata/ 下所有文件的 ip: 字段，改完执行 /scripts/rebuildhttpdconf 并重启 httpd。新建账户的默认 IP 由 /etc/mainip 决定，迁移前先写好私网 IP 可从源头避免复发。

在 cPanel 服务器上照常打开自己的网站，浏览器却报「您的连接不是私密连接」——点开证书详情，发行者是一串 cPanel 安装时生成的临时主机名，与站点域名毫无关系。

在为客户执行 中国合规托管与站点迁移 项目时遇到此问题——海外客户的两个中国站点迁入合规托管环境，「证书长期失效、访客浏览器报不安全」正是迁移前的主要遗留问题之一，最终定位为本文所述的两处根因叠加。

TL;DR​

浏览器报证书不安全、证书为自签，多数情况不是 CA 故障，而是 Let's Encrypt 正式证书从未成功签发。按顺序排查两处：先查 AutoSSL 域名排除列表（whmapi1 get_autossl_user_excluded_domains），清掉后用 start_autossl_check_for_one_user 立即触发签发；若签发成功但公网拿到的仍是自签证书，则查自定义 vhost 是否写死了 SSLCertificateFile。面板显示 already optimal 不等于覆盖完整，一切以公网实际拿到的证书 SAN 为准。

问题现象​

外部机器对站点域名做一次证书检查：

$ openssl s_client -connect example.cn:443 -servername example.cn </dev/null 2>/dev/null \
    | openssl x509 -noout -subject -issuer -dates
subject=C = US, O = cPanel, L = Houston, ST = TX, OU = SSL Support, CN = 203-0-113-10.cprapid.com
issuer=C = US, O = cPanel, L = Houston, ST = TX, OU = SSL Support, CN = 203-0-113-10.cprapid.com
notBefore=May 21 00:00:00 2026 GMT
notAfter=Aug 19 00:00:00 2026 GMT

三个信号叠在一起：issuer 与 subject 完全相同（自签）、CN 是 cPanel 安装时生成的 cprapid 临时主机名（与站点域名无关）、有效期对应 cPanel 服务证书。也就是说，访客拿到的是 cPanel 的自签服务证书，Let's Encrypt 正式证书从未出现在公网。

更迷惑的是 WHM 里的 AutoSSL 状态一切正常：provider 是 Let's Encrypt、每日任务照常运行、没有任何报错。翻 AutoSSL 日志才能看到真实原因：

User-excluded domains: 9 (mail.example.cn, webmail.example.cn, ...)

账户下全部 9 个域名都在排除列表里——AutoSSL 认为这是用户意愿，每天跑到这一步就跳过，然后报一句「already optimal」收工。

根因​

根因一：域名排除列表挡住了签发（主因）。 AutoSSL 为每个 cPanel 账户维护一份排除域名列表，列表内的域名不参与签发。它不报错、不告警，每日任务照常执行——所以面板上看起来一切正常。排除列表有三个常见来源：

• 早期手动排除过：当时域名可能 DNS 未就绪或还在测试，排除之后忘了清
• cpmove 整包迁移原样带走：从归档恢复时，旧机的排除状态和旧证书一起落到新机
• 新建子域自动加入：cPanel 创建子域时，默认把它连同 www.* 一起写进排除列表

根因二：自定义 vhost 写死了证书路径。 清完排除列表、日志确认签发成功之后，外部验证拿到的仍然是自签证书——签发了，但没生效。这台服务器曾为公网 IP 路由加过一段自定义 Apache 配置（镜像 vhost），其中 SSLCertificateFile 写死为 /var/cpanel/ssl/cpanel/cpanel.pem（cPanel 自签服务证书）。cPanel 标准 httpd.conf 里的 vhost 只绑主 IP，公网流量全部命中镜像 vhost，AutoSSL 的签发结果自然永远看不见。

两处根因是叠加关系：只清排除列表，签发成功但公网看不到；只改 vhost，镜像层指向了正式证书路径，可 AutoSSL 根本没签出来。先修一、再修二，缺一不可。

解决方案​

1. 外部定位。 在服务器之外的机器上跑证书检查（不要在服务器本机验证，见文末注意事项），确认 issuer 与 subject 相同后，到 WHM 服务器查排除列表：

whmapi1 get_autossl_user_excluded_domains username=example

2. 清理排除列表。 domain 参数可以重复传多个，一次放行所有需要签发的域名：

whmapi1 remove_autossl_user_excluded_domains \
  username=example domain=example.cn domain=www.example.cn

mail、webmail 这类服务子域如果没有 DNS 解析或不需要证书，保留排除是合理取舍——清掉只会让每轮 DCV 验证报错刷日志，并签不出任何证书。

3. 立即触发签发。 AutoSSL 每日任务要等调度，手动触发立刻执行：

whmapi1 start_autossl_check_for_one_user username=example

两个函数名细节：这个函数没有不带 _for_one_user 的短版本；参数名是 username 不是 user。拿不准函数名时直接翻模块源码：

grep -i autossl /usr/local/cpanel/Whostmgr/API/1/SSL.pm

命令行等价物是 /usr/local/cpanel/bin/autossl_check --user=example。签发过程看日志：/var/cpanel/logs/autossl/ 下按时间戳建目录，日志混有二进制字符，用 grep -a 或 strings 过滤后再读。

4. 签发成功但公网仍旧证书，查自定义 vhost。 日志里 ACME 请求成功、证书已经落盘，公网拿到的却还是旧证书，说明流量没走标准 vhost。检索自定义配置里的写死路径：

grep -rn "SSLCertificateFile" /etc/apache2/conf.d/includes/post_virtualhost_global.conf

把写死的 cpanel.pem 换成按域名管理的证书路径：

SSLCertificateFile /var/cpanel/ssl/apache_tls/example.cn/combined

改完执行 /scripts/restartsrv_httpd 重启。这个 include 文件是自定义配置，cPanel 重建 httpd.conf 不会覆盖它，后续续期自动生效，改一次即可。

5. 最终验证。 回到外部机器重跑第 1 步的命令：issuer 应变成 Let's Encrypt 的中间证书（R3/R10/R11，随 LE 轮换），SAN 应包含站点域名。Let's Encrypt 证书有效期 90 天，此后 AutoSSL 每日任务自动续期，无需再管。

迁移与子域场景的变体​

• cpmove 迁移后：排除列表和旧证书状态会原样带到新机，旧 LE 证书的 SAN 往往只有主域和 www。恢复完成后主动清一次排除列表、触发一次签发，别等每日任务。
• 新建子域：cPanel 会自动把它连同 www.test.* 加进排除列表，建完需要再移除一次；没有 DNS 解析的 www.test.* 建议保持排除，避免每轮 DCV 验证报错。
• ServerAlias 方式挂载的域名：通过 userdata include 注入的别名不归 AutoSSL 管，手工编辑 userdata 的 parked_domains 再跑 updateuserdomains 也会被静默丢弃。正路是用官方 API 建子域：

uapi --user=example SubDomain addsubdomain domain=test rootdomain=example.cn dir=/home/example/public_html

注意参数名是 rootdomain，写成 parentdomain 会被静默忽略并报「You must specify a main domain」。

常见问题​

网站证书有问题是什么原因？​

用 openssl 查看证书：issuer 与 subject 相同、CN 不含你的域名，说明站点在用自签证书，正式证书从未签发。最常见的两处根因是域名被加进 AutoSSL 排除列表、自定义 vhost 写死了证书路径。Let's Encrypt 证书有效期 90 天，排除障碍签发一次后由 AutoSSL 每日任务自动续期。

AutoSSL 显示 already optimal 但证书还是自签的，怎么办？​

already optimal 只表示该账户无需补签，不等于覆盖完整。先查排除列表（get_autossl_user_excluded_domains）——哪怕从没手动排除过，cpmove 迁移会带走旧机状态、新建子域也会被自动加进列表（本例单账户 9 个域名全部在列）；清掉后用 start_autossl_check_for_one_user 立即触发签发，别等每日调度。

网站证书不可信怎么办？​

分两步：先在服务器外的机器用 openssl s_client 确认公网实际拿到的证书；再到 /var/cpanel/logs/autossl/ 按时间戳翻签发日志定位卡点。注意本机验证要连实际业务 IP，连 127.0.0.1 会命中默认 vhost 造成误判。签发链路打通后，90 天有效期的证书由每日任务自动续期，不需要人工干预。

在全新服务器上装 cPanel，安装器跑完报「完成」，建户、装站却接连出问题——这类故障的共同点是：报错的地方不是坏的地方。

在为客户执行 中国合规托管与站点迁移 项目时遇到此问题——在阿里云中国区从零搭建 cPanel/WHM 托管环境，装机阶段的三类故障在同一台机器上接连出现，逐一排掉后才进入站点迁移。

TL;DR​

全新装机阶段有三类高频故障，共同特征是「表面成功、实际残缺」：安装器某阶段失败不回滚、报完成但 MariaDB 没装上；未跑 Basic Setup 向导时 wwwacct.conf 为空，建户被连环拦截；国内机器拉 httpupdate.cpanel.net 只有约 50 KB/s，RPM 下载超时还会反过来造成第一类故障。验收装机只看「三件套」：MariaDB RPM 齐全、mysql 服务在跑、客户端能连上库。

场景一：安装报完成，MariaDB 却没装上​

WordPress 报 Database Error，服务器上 mysql 命令不存在，systemctl is-active mysql 返回 inactive——而 cPanel 安装器明明显示安装成功，面板也打得开。

翻安装日志的尾部，真凶藏在那里：

(FATAL): The background process "SQL Databases and dependent apps" failed ... error number 127

SQL 阶段的 MariaDB RPM 事务因为下载失败没有装上，但安装器的后续阶段照常执行、照常收尾，最终界面依然显示「完成」。安装「成功」不等于组件齐全——安装器不会因为一个阶段失败而回滚或阻断全局。

修复顺序：

1. 核实缺口：rpm -q MariaDB-server，大概率报未安装
2. 补装全套 RPM：MariaDB-server、MariaDB-client、MariaDB-devel、MariaDB-shared、MariaDB-common 一个不能少
3. 补完 RPM 还没完——/usr/local/cpanel/scripts/securemysql 不足以让恢复工具连上库，restorepkg 会报 Missing: admin_mysql_password。需要生成 /root/.my.cnf（含 client 段密码）并对 root@localhost 执行 SET PASSWORD

装机验收别信安装器退出码，跑三件套：

rpm -qa | grep -i maria
systemctl is-active mysql
mysql -N -e "select version()"

三条全绿，SQL 阶段才算真的完成。

场景二：首次建户，wwwacct.conf 连环报错​

restorepkg 或手动建户，每轮被一个缺失键拦下，按顺序分别是：Please setup a nameserver → Missing HOMEDIR → Missing DEFMOD → Missing LOGSTYLE → Missing SCRIPTALIAS。

根因很直接：全新 WHM 没跑过 Basic Setup 向导时，/etc/wwwacct.conf 是空文件，而账户创建强校验它。坑在于这个文件的报错机制——每轮只报一个缺失键，逐个补要试五轮以上。

正确做法是一次写全标准键集：

cat > /etc/wwwacct.conf <<'EOF'
ADDR 172.28.100.10
CLUSTERED_DNS disabled
DEFMOD default
ETHDEV eth0
FTPHOMEDIR 0
HOMEDIR /home
HOMEMATCH home
LANG english
LOGSTYLE semicolon
MINUID 500
NS ns1.example-ns.com
NS2 ns2.example-ns.com
SCRIPT x3
SCRIPT x3parked
SCRIPT x3addon
SCRIPTALIAS y
EOF

三个细节：

• ADDR 写私网 IP 而不是公网——NAT 架构下公网 IP 不在本机网卡上，绑错的后果在 cPanel 网站全跳默认页？阿里云 ECS 上 vhost 绑公网 IP 不生效 一篇里完整拆过
• whmapi1 set_nameserver 的参数名是单数 nameserver（值 bind/powerdns/disabled），与 get_nameserver_config 返回的复数字段不同；且 NS 校验读取的是 wwwacct.conf 的 NS/NS2，不是 cpanel.config 里的 ns1/ns2
• 真实 DNS 在云 DNS 时，NS 填名义值即可，CLUSTERED_DNS disabled 配合使用

建户失败时，详情在 /var/cpanel/transfer_sessions/<会话>/master.log 的 JSON 里（搜 failure）；注意 view_transfer 命令本身会 tail 阻塞，排查时别被挂住。

场景三：国内服务器拉 cpanel.net 只有 50 KB/s​

场景一的 RPM 下载失败，根源往往在这里：阿里云上海 ECS 到 httpupdate.cpanel.net 的全部镜像 IP 实测只有约 50 KB/s（国际站同区同速，排除代理中转的价值）；同一个源，家庭宽带实测 1.8-6 MB/s。

加速方案是让服务器借用本地线路：本地机器开远程动态 SOCKS，服务器装 proxychains-ng 走隧道执行安装命令：

# 本地机器：开远程动态 SOCKS
ssh -N -R 1080 root@<服务器IP>

# 服务器：装 proxychains-ng 后，让安装器走隧道
proxychains4 -q sh latest

实测从 50 KB/s 提到 708 KB/s，约 14 倍。但三个坑必须绕开：

• proxychains 配置必须加 localnet 豁免内网段（10/8、172.16/12、100.64/10 等），并且去掉 proxy_dns——否则阿里云内网镜像域名（mirrors.cloud.aliyuncs.com）被送进隧道直接失败
• tinyproxy 与 httpupdate.cpanel.net 不兼容，稳定返回 404，别用它做隧道出口
• 清理安装进程别用 pkill -f "sh latest"——它会匹配到自己 ssh 会话的命令行，把连接自己杀掉（ssh 退出码 255 的元凶），改用 PID 精确清理

装完即拆：隧道生命周期等于本地 ssh 进程，服务器上的 proxychains-ng 与配置文件用完即卸，不留加速配置。若安装中断已造成 RPM 缺失，cPanel 自愈用 /usr/local/cpanel/scripts/sysup 补齐——本例中 splitlogs 缺失导致 httpd 起不来，就是 sysup 加手动补 RPM 修好的。

常见问题​

cPanel 安装包在国内下载要多久？​

国内云服务器直连 httpupdate.cpanel.net 的全部镜像 IP 实测只有约 50 KB/s，安装器下载 MariaDB 这类 RPM 时可能直接超时失败；同样的源在家宽环境实测 1.8-6 MB/s。可行的加速是用本地线路建反向 SOCKS 隧道配合 proxychains 代理安装器，实测可提到约 708 KB/s（约 14 倍），装完即拆、不在服务器留任何加速配置。

cPanel 面板安装完成后要验证哪些组件？​

至少三件套：rpm -qa | grep -i maria 确认 MariaDB 全套装齐、systemctl is-active mysql 确认服务在跑、mysql -N -e "select version()" 确认能连。同时翻安装日志尾部搜 FATAL——安装器某阶段失败会照常跑完后续并报完成，日志是唯一能暴露缺口的地方。

cPanel 创建账户连环报 Missing 是什么原因？​

全新 WHM 没跑过 Basic Setup 向导时 /etc/wwwacct.conf 是空文件，而账户创建会强校验它。这个文件的缺失键每轮只报一个，逐个补要试五轮以上；正确做法是一次写全标准键集（ADDR、HOMEDIR、DEFMOD、LOGSTYLE、SCRIPTALIAS、NS/NS2 等），nameserver 键还要用单数形式。