Bobay Stack 波贝自建栈

运维与排障 / 2026-09-30

3x-ui 面板:指定版本、随机凭据、证书自动续期

从一台干净的 Debian 13 装起:为什么不装"最新版"、安装脚本随机生成的端口与路径为什么会丢、以及用 acme.sh 把证书续期交给 cron。

3 MIN READ BY BOBAY.TOP 更新于 2026-10-05 ↖ 全部笔记
3x-ui 面板:指定版本、随机凭据、证书自动续期

面板类工具最容易被当成"一键脚本"用掉,直到某天证书过期、面板路径忘了、端口冲突,才发现当初那行命令打印过什么,谁也没记。

这台机器是 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 续期后虽然更新了文件,但:

  1. 面板缓存了证书内容(Xray 进程没重启)
  2. 续期脚本写到了另一个路径
  3. 文件权限变了(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 的到期日,避开窗口。

一句总结:把"出问题的地方"和"验证的方法"写在一起,比只写配置更有用——配置抄得到,判断顺序抄不到。

3x-uiacme.shTLSDebian运维

参考

3x-ui 官方仓库 ↗ acme.sh 文档 ↗