# 安装与更新（主控 / 被控 / L2）

> 文档更新：2026-09-28 ｜ 适用版本：v3 ｜ 功能位置：官网下载页（/download，主控）、节点列表页「安装」抽屉（被控）、「集群控制 → 辅助主控」页「安装」抽屉（L2）

## 星梦面板由哪几部分组成

- **主控**：用户日常操作的桌面端面板程序，装在自己的电脑上（Windows / macOS / Linux）；
- **被控**：安装在各台服务器上的代理程序，按节点类型分为通用被控、监控节点、xcc套件、虚拟化节点四套程序（类型区别见节点类型文档）；
- **L2 辅助主控**（可选）：需要集群监控、监控告警、DNS 自动切换（自动容灾）或自建 CDN 时才需要，装在某台服务器上的"集群大脑"（见集群控制文档）。

三者的安装、更新、卸载方式各不相同，指导用户前先分清对方说的是哪一个。

## 主控：下载安装与升级

入口：官网下载页 https://www.xmpanel.cn/download （每次下载前需勾选同意《使用协议与隐私政策》）。

| 平台 | 安装方式 |
|---|---|
| Windows 10 / 11（x86_64） | 下载 zip 压缩包，解压后运行其中的安装包 |
| macOS（测试版） | 按芯片下载 dmg：M 系列（Apple Silicon）选 arm64，Intel 选 x64。应用未签名，首次打开前需在终端执行 `sudo xattr -rd com.apple.quarantine /Applications/星梦面板.app` 放行（仅需一次） |
| Linux（x86_64） | 终端以 root 执行 `curl -sSL https://node.xmpanel.cn/v3/install-desktop.sh | sudo bash`，自动识别 deb / rpm |

主控升级：**直接覆盖安装，不需要先卸载，数据会保留**。Windows / macOS 重新下载安装包覆盖安装即可；Linux 重新执行同一条脚本（该脚本同时负责安装与升级）。

直连下载慢或无法访问时，可用官网提供的夸克网盘备用下载，内容与官方一致。

## 被控：添加节点

入口：节点列表页 →「添加节点」，填写：

- **节点 ID**：正整数（面板会随机生成一个，可修改）；
- **被控地址**：目标服务器的 IP 或域名 + 端口（端口随机生成，可自行指定）；
- **备注**：可选，方便识别；
- **节点类型**：通用被控 / 监控节点 / xcc套件 / 虚拟化节点，类型决定安装哪套被控程序。

添加成功后，还需要在目标服务器上执行安装命令完成被控安装（见下节）。

## 被控：安装 / 升级（脚本方式）

入口：节点列表 → 对应节点「安装」→「安装/升级」标签页：

1. 按需调整安装选项：**开放防火墙端口**（默认开启，自动放行节点端口）、**自定义安装目录**（默认 `/opt/xmp`，虚拟化节点默认 `/opt/xmp-vm`）；
2. 点「生成证书」；
3. 点「复制命令」到目标服务器终端执行（root），或点「SSH 执行」由主控后台远程执行（只需输入 SSH 连接信息，无需手动粘贴）。

命令格式为「环境变量前缀 + 一键脚本」，脚本地址按节点类型区分：`https://node.xmpanel.cn/v3/{node|monitor|xcc|vmnode}/install.sh`。**命令非常长（包含 mTLS 证书内容）属正常现象**，请完整复制执行。

同一套脚本适用三种场景，脚本自动识别、无需选择：v3 全新安装、v2 升级 v3、v3 更新（兜底更新，在线更新不可用时的补救手段）。虚拟化节点：命令适用于全新安装与覆盖更新，Incus 虚拟化栈在安装完成后由面板引导安装。

节点的被控端口以添加节点时填写的为准；如修改过端口，重新走一遍安装命令即可。

## 被控：在线更新

入口：节点列表 →「安装」→「在线更新」标签页：生成证书 → 点「开始更新」。主控直接调用被控的更新接口，无需 SSH、无需复制命令；被控自动下载新版本并替换重启，进度可在任务监控中查看。

在线更新有版本门槛：

| 类型 | 在线更新条件 |
|---|---|
| 通用被控 | v3 均支持 |
| 虚拟化节点 | v3 均支持 |
| 监控节点 / xcc套件 | 被控版本需 **3.3.0 及以上** |
| L2 辅助主控 | 需 **3.2.0 及以上**（操作入口在集群控制 → 辅助主控的安装抽屉） |

版本不满足时标签页会提示"当前版本不支持在线更新"：先用「安装/升级」标签页的脚本方式手动更新一次，之后即可一直走在线更新。v2 通用被控同理，先脚本迁移到 v3。

节点离线时无法在线更新（检测不到版本），需先恢复节点在线。

## 被控：卸载

入口：节点列表 →「安装」→「卸载」标签页：复制卸载命令到目标服务器执行，或点「SSH 远程执行」；「静默卸载」开启后命令直接执行、跳过二次确认。

命令格式：`bash <(curl -sSL https://node.xmpanel.cn/v3/{类型}/uninstall.sh)`（静默卸载时前缀加 `SILENT=y `）。

卸载会删除被控程序文件与数据目录（证书、日志、数据库等），但保留：

- 用户数据目录 `data/www`（网站文件等）；
- Docker 本身（不会卸载）与正在运行的容器（不会停止）；
- `xmpanel` 用户与 `xmp-network` 网桥。

虚拟化节点额外说明：不触碰 Incus 与虚拟化数据——全部实例、镜像、存储池均保留（同样保留 `data/www` 与 `xmpanel` 用户）。

**「删除节点」≠「卸载被控」**：节点列表的「删除」只移除主控侧的管理记录，服务器上的被控程序仍在运行；彻底移除程序需走上述卸载流程。

## L2 辅助主控：配置、安装、更新、卸载

前提：只有需要集群监控、监控告警、DNS 自动切换或自建 CDN 时才需要 L2；全部操作在「集群控制 → 辅助主控」页完成。

- **配置**：首次使用先点「设置」，填写 L2 服务器地址与两个端口（主控连接端口、节点接入端口）；
- **安装**：点「安装」打开 L2 安装管理抽屉 → 生成证书（每次安装或更新，包括在线更新，都会使用新生成的证书）→ 复制安装命令到 L2 服务器执行，或用「SSH 执行」；「开放防火墙」开启时自动放行两个端口；安装完成后页面状态变「在线」；
- **更新**：优先用抽屉里的「在线更新」（需 L2 **3.2.0 及以上**）：生成证书 → 开始更新，程序自动替换并重启，双端口配置保持不变，期间下游证书同步会短暂中断、之后自动恢复；旧版 L2 会提示不支持在线更新，用与安装相同的安装命令手动更新一次即可；
- **卸载**：抽屉底部「卸载」区复制命令或 SSH 执行，支持静默卸载；卸载将删除程序文件、数据目录（证书、日志、数据库）与配置文件，**不可恢复**。

L2 的脚本地址为 `https://node.xmpanel.cn/v3/l2/install.sh` 与 `uninstall.sh`，同样由面板生成完整命令，无需手写。

## 常见疑问

**问：安装命令为什么那么长？**
命令里包含 mTLS 证书内容（Base64 编码），用于主控与被控 / L2 之间的加密认证，长度正常，完整复制执行即可。

**问：v2 被控怎么升级到 v3？**
直接执行 v3 安装命令，脚本自动识别 v2 环境并迁移，无需先卸载。

**问：在线更新提示"当前版本不支持"？**
该类型有版本门槛（监控 / xcc需 3.3.0+，L2 需 3.2.0+）。用脚本方式手动更新一次后即可在线更新。

**问：主控升级会丢数据吗？**
不会。覆盖安装即可，无需先卸载，数据保留。

**问：安装 / 更新后怎么确认成功？**
节点列表 →「版本详情」对比当前版本与最新版本；L2 看辅助主控页状态与安装抽屉里的「当前运行」版本。

**问：删掉节点记录后，服务器上的被控还在吗？**
在。删除节点只影响主控侧记录，彻底移除被控程序需执行卸载命令。

## 指导用户时的注意点

- 先分清对象：主控（自己电脑）、被控（业务服务器）、L2（集群服务器），三者流程完全不同，不要混着指导；
- 安装 / 卸载命令一律让用户从面板里复制，不要手抄或自行拼接；
- 在线更新失败或提示不支持时，出路都是「脚本方式手动更新一次」，之后恢复在线更新；
- 更新会使被控短暂重启，建议空闲时段操作；L2 更新期间下游证书同步会短暂中断；
- 卸载前提醒：程序文件与数据目录删除后不可恢复（被控保留 data/www 与容器；L2 全部删除）。