运维与排障 / 2026-09-30
3x-ui 面板:指定版本、随机凭据、证书自动续期
从一台干净的 Debian 13 装起:为什么不装"最新版"、安装脚本随机生成的端口与路径为什么会丢、以及用 acme.sh 把证书续期交给 cron。
面板类工具最容易被当成"一键脚本"用掉,直到某天证书过期、面板路径忘了、端口冲突,才发现当初那行命令打印过什么,谁也没记。
这台机器是 AWS 东京的 Lightsail 实例,Debian 13,纯净系统。下面是这次装完之后真正落在文件上的东西。
别直接装 latest
3x-ui 的版本迭代很快,latest 偶尔会带来面板打不开的问题。稳妥做法是先看 release 列表,选一个社区反馈稳定的版本号,再用 @版本 的形式安装:
# 示例:先查可用版本,再指定安装
bash <(curl -Ls https://raw.githubusercontent.com/MHSanaei/3x-ui/master/install.sh)
安装后核对一次版本与监听端口:
x-ui status
ss -lntp | grep -E 'x-ui|2053'
如果安装脚本提示了自定义端口、自定义 webBasePath,这些都是随机生成的,且只在安装时打印一次。错过就只能改配置文件:
# /usr/local/x-ui/config.json 里改 webPort / webBasePath,然后重启
x-ui restart
我的做法是安装输出直接重定向到一台本地机器的日志文件,装完把日志归档。面板登录信息属于凭据,不能进笔记、不能进仓库,只进一个单独的 secrets 文件。
证书:用 acme.sh 而不是面板自带
面板自带证书申请有时会卡在 DNS 验证上。用 acme.sh 走 DNS-01 更稳,也更适合自动化:
curl https://get.acme.sh | sh -s email=<邮箱>
export CF_Token="<Cloudflare API Token>"
acme.sh --issue --dns dns_cf -d <域名> --keylength ec-256
签发完成后把证书装到面板读的位置,并注册自动续期:
acme.sh --install-cert -d <域名> --ecc \
--key-file /root/cert/<域名>.key \
--fullchain-file /root/cert/<域名>.crt \
--reloadcmd "x-ui restart"
--reloadcmd 是关键。证书文件换了但进程不重载,浏览器看到的还是旧证书,症状是"续期明明成功了却仍报过期"。
续期要验证,不要假设
acme.sh --list # 看下次续期时间
acme.sh --renew -d <域名> --force # 手动跑一次
手动跑通一次再交给 cron,能省掉很多"到期那天才发现"的事故。cron 由 acme.sh 安装时自动写入,位置在用户 crontab 里,不要和别人手写的备份任务混在一起改。
还剩下的两件事
- 防火墙:面板端口、节点端口、SSH 端口三者的开放策略要分开写,面板端口不要对公网长期开放。
- 快照:Lightsail 支持实例快照,装完这一套之后先打一个。以后再折腾出问题,回滚是分钟级的事,重装是小时级的事。
证书为什么会在面板里"自己失效"
3x-ui 的证书路径是写在面板配置里的绝对路径。acme.sh 续期后虽然更新了文件,但:
- 面板缓存了证书内容(Xray 进程没重启)
- 续期脚本写到了另一个路径
- 文件权限变了(
600改成644后 Xray 读不到)
三种都表现为"证书过期",但只有第 3 种会在日志里明确报 permission denied。
正确的续期钩子
acme.sh --install-cert -d node.example.com \
--key-file /root/cert/node.key \
--fullchain-file /root/cert/node.crt \
--reloadcmd "x-ui restart"
关键是 --reloadcmd 里要重启 Xray 而不只是重载面板。只 reload 面板,Xray 仍持有旧证书。
验证链
openssl x509 -in /root/cert/node.crt -noout -dates
systemctl status x-ui | head -5
# 从外部验证实际握手用的证书
echo | openssl s_client -connect node.example.com:443 -servername node.example.com 2>/dev/null | openssl x509 -noout -dates
第三条是唯一可信的验证——它看到的是真正发给客户端的证书。
一个时间窗口
Let's Encrypt 证书有效期 90 天,acme.sh 默认到期前 30 天续。如果你在续期窗口内改了域名解析,续期会失败,然后进入 7 天重试。改 DNS 前先看 acme.sh --list 的到期日,避开窗口。
一句总结:把"出问题的地方"和"验证的方法"写在一起,比只写配置更有用——配置抄得到,判断顺序抄不到。