环境要求

读者：部署前的运维人员。概念说明见 核心概念。

1. Master 服务器

项目	要求
操作系统	Linux（x86_64 或 arm64），推荐 Debian 12 / Ubuntu 22.04+
CPU / 内存	2 核 / 2 GB 起；Host 与租户较多时建议 4 核 / 4 GB+
磁盘	20 GB+（含 MariaDB 与日志）
网络	可被运维浏览器访问；各 Host 上的 Client 能主动连上 Master（出站 HTTPS）
数据库	推荐 MariaDB 10.6+ 或 MySQL 8.0+（可与 Master 同机或独立实例）；旧版见下表

Master 默认监听 80（可在 master.yaml 中改为 443 并配置 TLS，或由 Nginx / Caddy 反代）。

数据库版本

Schema 与安装包以 MariaDB 10.6 为基线设计；生产环境请优先使用该版本或 MySQL 8.0+。

档位	版本	说明
推荐（生产）	MariaDB 10.6+、MySQL 8.0+	官方测试目标；流量事件 worker 可使用 FOR UPDATE SKIP LOCKED
最低兼容	MySQL 5.7+、MariaDB 10.3+	与安装模板 master.example.yaml 一致；控制台、用户同步、配置下发可运行
不支持	MySQL 5.6 及以下	缺少完整 JSON / utf8mb4 等能力，不保证 migration 通过

MySQL 5.7 / MariaDB 10.3～10.5 与推荐版的差异（单 Master 部署通常无感）：

• 流量事件 outbound worker 检测版本后自动降级：不用 SKIP LOCKED，改用普通 FOR UPDATE（日志会提示 SKIP LOCKED not available）
• 仅跑一个 xctl-master 进程时，上述降级可正常工作
• 若计划 多 Master 实例 HA（水平扩展、多副本抢同一批事件），必须使用 MariaDB 10.6+ 或 MySQL 8.0.1+

新部署不建议再选 MySQL 5.7；存量 5.7 环境可先跑通再规划升级到 8.0。

2. Host 与 Client

项目	要求
操作系统	Linux x86_64 或 arm64
面板	3x-ui（可由 Master SSH 装机向导非交互安装，或自行预装）
权限	root 或具备 systemd、写 /usr/local/bin 的 sudo
网络	能访问 Master 的 /dl/ 与 WebSocket；对外提供代理业务端口

单台 Host 可承载多个逻辑节点；同一逻辑节点也可绑定多台 Host（多 IP 靠 DNS 解析，Master 保证池内配置一致）。

3. 端口与连通性

方向	说明
运维 → Master	控制台 HTTPS（安装后 xctl master creds 查看地址与账号）
Host → Master	Client 长连接与配置同步；/dl/xctl-client-linux-{arch} 下载
Master → Host	SSH 装机向导（22 或自定义端口）
业务流量	由逻辑节点协议与面板订阅决定，与 Master 管理端口无关

防火墙需放行：节点能出站访问 Master；若使用 SSH 装机，Master 需能入站 SSH 到节点。

4. 授权（License）

• 试用或付费后获得 License Key（见 购买与支付）
• 安装 Master 时写入 /etc/xctl/master.env 的 XCTL_LICENSE_KEY
• 配额按 套餐说明：租户数、Host 数、有效期

未激活或过期时，控制台会提示授权状态；已部署的节点不会自动删除，但部分管理能力可能受限。

5. 集成侧（可选）

若对接 WHMCS、Xboard 等面板：

• 面板服务器需能访问 Master 的 Adapter / UniProxy 路径
• 各面板插件版本与 Master 版本匹配（见 主流面板对接）

6. 常见问题

Q：Master 和 MariaDB 必须分开部署吗？
A：不必须。小规模可同机；生产建议独立数据库实例并做好备份。

Q：还能用 MySQL 5.7 吗？
A：属最低兼容档位，可安装运行，但不在推荐列表；事件 worker 会降级锁策略。新环境请用 MariaDB 10.6+ 或 MySQL 8.0+。MySQL 5.6 及以下不支持。

Q：MariaDB 10.4 和 10.6 差别大吗？
A：10.4 落在最低兼容区，单 Master 一般可用；10.6 起才有 SKIP LOCKED，且与官方 schema 基线一致，生产请选 10.6+。

Q：节点没有公网 IP 可以吗？
A：可以，只要节点能主动连接 Master。SSH 装机仍需 Master 能连到节点管理口。

Q：支持 Windows 节点吗？
A：当前仅支持 Linux + 3x-ui 体系。

下一步

• 安装 Master
• 术语表