安装 Master

读者：准备在生产环境部署控制平台的运维人员。

生产环境请使用官方安装脚本部署 Master，并妥善保管 MWAAS_MASTER_KEY、XCTL_LICENSE_KEY 等密钥（勿泄露给他人）。

1. 前置条件

• 一台满足 环境要求 的 Linux 服务器
• 已安装数据库并创建好库与用户（推荐 MariaDB 10.6+ 或 MySQL 8.0+；MySQL 5.7 / MariaDB 10.3+ 见 环境要求 · 数据库版本）
• 已在官网完成试用或购买，持有 License Key（见 授权激活）

2. 一键安装（推荐）

在服务器上以 root 执行（勿使用 sudo bash <(curl …) 形式）：

curl -fsSL https://raw.githubusercontent.com/catxtom/xctl-publication/main/scripts/install.sh | sudo bash -s -- -install

安装脚本会：

1. 下载当前 master-latest 安装包并解压到 /etc/xctl/master
2. 生成 configs/master.yaml（数据库 DSN、端口等）
3. 首次生成 MWAAS_MASTER_KEY → /etc/xctl/master.env（升级不覆盖）
4. 交互或写入 XCTL_LICENSE_KEY
5. 随机创建 super_admin 账号 → 凭据保存在 /etc/xctl/admin.credentials（权限 600）
6. 注册 xctl-master.service 并启动

安装完成后执行：

sudo xctl master creds   # 查看控制台 URL、管理员用户名与密码
sudo xctl master         # 运维菜单（状态、日志、升级等）

3. 手动调整配置

主要文件：

路径	说明
/etc/xctl/master/configs/master.yaml	服务端口、数据库 DSN、功能开关
/etc/xctl/master.env	MWAAS_MASTER_KEY、XCTL_LICENSE_KEY 等敏感项
/etc/xctl/admin.credentials	初始管理员账号（可改密后删除备份）

数据库 DSN 示例（安装脚本会提示修改）：

database:
  driver: "mysql"
  dsn: "xuictl:YOUR_PASSWORD@tcp(127.0.0.1:3306)/xuictl?charset=utf8mb4&parseTime=True&loc=UTC"

修改配置后重启：

sudo systemctl restart xctl-master

4. HTTPS 与反代（建议）

生产环境建议在 Master 前放置 Nginx / Caddy：

• 终止 TLS，反代到 127.0.0.1:80（或 master.yaml 中的端口）
• 控制台与装机向导使用浏览器访问的 origin 作为 Master 对外 URL，无需写入 yaml

5. 验证安装

1. 浏览器打开 xctl master creds 输出的地址，使用管理员登录
2. 控制台首页应显示授权状态与版本信息
3. 访问 https://你的域名/dl/xctl-client-linux-amd64 应能下载 Client 二进制（用于节点装机）

6. 注意事项

• MWAAS_MASTER_KEY 丢失会导致已加密数据无法解密，请离线备份 master.env
• 升级使用 sudo xctl master 菜单或重新运行安装脚本；不要手动覆盖 master.env
• Client 优先从 Master /dl/ 拉取；缺失时会回退到 GitHub client-latest Release

7. 常见问题

Q：安装时数据库连接失败？
A：确认 MariaDB 监听地址、用户权限与防火墙；DSN 中主机名用 127.0.0.1 而非 localhost 可避免部分 socket 问题。

Q：忘记管理员密码？
A：使用 root 在服务器上执行 xctl-master -u 新用户 -p '新密码'（具体以安装包内 CLI 帮助为准），或通过运维菜单重置。

Q：License 填错了怎么办？
A：编辑 /etc/xctl/master.env 中的 XCTL_LICENSE_KEY 后重启服务，或在控制台授权页更新。

下一步

• 授权激活
• 安装 Client
• 控制台入门