5 分钟快速安装

本页给出最短且完整的上线路径。它适合首次体验或新建环境。生产环境完成后，还应继续阅读部署与运维和生产审计与使用检查。

你将部署什么

总控服务器使用 Docker Compose 运行 Web、服务端、安装服务、PostgreSQL、Redis 和可选的总控 Agent。被监控服务器只需安装轻量 Agent，并由 Agent 主动连接总控。

角色	最低准备	对外端口
总控服务器	64 位 Linux 与 root/sudo；public 可自动安装 curl、Docker Engine 24+、Compose v2	80/443，初始化时可临时使用 18080
被监控服务器	Linux 或 Windows，具备安装服务的管理员权限	通常无需开放入站端口

生产环境要求

请准备域名和有效 HTTPS 证书。PostgreSQL、Redis 与 Spring Boot 端口不应直接暴露到公网。

安装总控

Linux

能够访问 GitHub 和 GHCR 时，下载固定版本的统一管理脚本并安装：

curl -fsSL --proto '=https' --tlsv1.2 'https://raw.githubusercontent.com/Pstarchen/monitor-for-server/v1.20.22/deploy/xingchen.sh' -o xingchen.sh && chmod +x xingchen.sh && sudo ./xingchen.sh install --version v1.20.22

中国大陆服务器或无法访问 GitHub/GHCR 时，使用 Gitee 入口：

curl -fsSL --proto '=https' --tlsv1.2 'https://gitee.com/starchen520/monitor-for-server/raw/v1.20.22/deploy/xingchen.sh' -o xingchen.sh && chmod +x xingchen.sh && sudo CN=true ./xingchen.sh install --version v1.20.22

xingchen.sh 提供 install、update、status、logs 和 restart 五个直接动作；不带动作运行时会打开交互菜单。安装器在 public 模式会通过受支持的系统包管理器补齐 curl、Git、Docker Engine 和 Compose v2，然后生成数据库凭据、准备固定版本镜像并等待 Web 健康检查通过。安装器不会把数据库密码打印到日志。

CN=true 会从 Gitee 取得固定版本编排文件，并直接拉取腾讯云 TCR 中的六个预构建镜像；目标机不访问 GitHub、GitHub API、GHCR、Docker Hub，也不需要 Go、Maven 或 Node.js 构建环境。它仍需访问 Gitee、腾讯云 TCR 和系统包源，因此不适用于完全断网环境。完全断网时使用 Release 提供的架构对应离线 bundle，校验 .sha256 后执行包内 install-offline.sh。

默认安装目录是 /opt/guanlan-monitor；需要其他位置时，在 install 后添加 --install-dir <绝对路径>。安装成功后会创建系统命令 xingchen，常用管理命令如下：

sudo xingchen status
sudo xingchen logs
sudo xingchen restart
sudo xingchen update

普通更新沿用现有 .env 中的来源、镜像和网络策略，优先按 XINGCHEN_SOURCE_REPOSITORIES 判断发布来源，未配置时才参考 Git origin；部署目录不需要保留 .git。使用 sudo xingchen update --version v1.20.22 可固定目标版本。确需切换公共来源时，使用 --source gitee 或 --source github，这也会切换六个镜像及相关发布策略；内部或离线部署不能直接运行普通在线更新。

在线更新会先从目标版本 Setup 镜像提取并校验更新包，再备份数据库、切换服务和检查健康状态。v1.20.18 及更早版本首次迁移时，须先按部署与运维使用已验证的发布包补齐新版管理器和 bootstrap。不要把下载 URL 改成可变的 main 分支；入口和安装目标都应固定稳定 vX.Y.Z。内部 manifest、固定 digest、源码构建和存量离线升级也见该文档。

Windows

Windows 更适合本机体验或测试。先启动 Docker Desktop，并切换到 Linux containers，然后在项目目录运行：

powershell -ExecutionPolicy Bypass -File .\deploy\install-controller.ps1

若 Docker Desktop 未运行，安装器会在前置检查阶段停止，不会写入半成品配置。

完成首次配置

安装完成后打开：

http://<总控服务器IP>:18080/setup

向导只需要以下信息：

字段	填写建议
站点名称	浏览器、控制台和通知中显示的名称
公网入口	用户与 Agent 实际访问的完整 URL
允许的 Web 来源	至少包含公网入口，多个来源用逗号分隔
服务时区	使用 IANA 名称，例如 Asia/Shanghai
管理员账号	使用独立用户名和高强度密码

提交向导后，安装服务会重建 Web 与服务端。短暂出现连接中断属于正常重启过程，健康检查通过后会进入公开状态页。

先用 IP，稍后切换域名

初始化时可以使用 http://<IP>:18080。正式域名与 TLS 生效后，在系统设置同步修改公网入口，再让 PUBLIC_BASE_URL、ALLOWED_ORIGINS 使用同一个 HTTPS 来源。

完成首次安全检查

登录控制台后，按以下顺序操作：

1. 打开“备份与恢复”，创建第一个 PostgreSQL 备份。
2. 打开“系统设置”，配置并测试至少一种通知渠道。
3. 在个人资料中启用 TOTP 双因素认证。
4. 检查公开状态页是否只展示允许公开的设备与服务。

接入第一台服务器

1. 打开“设备管理”，点击“添加设备”。
2. 填写设备名称、分组和资产信息。
3. 保存后取得只显示一次的一次性接入令牌，并复制控制台生成的一条 Controller 同域短命令；命令本身不包含任何凭据。
4. 在目标服务器运行短命令。bootstrap 会分别下载完整安装器与 SHA256，校验匹配后才执行；安装器取得权限后隐藏读取令牌，准备并校验 Agent 制品，最后交换令牌并写入受限配置文件。
5. 等待设备状态从“待接入”变为“在线”。需要内部源、离线二进制或额外采集参数时，继续使用受监控服务器搭建材料中的高级入口。

接入令牌 15 分钟后过期且只能消费一次；过期时可在设备列表或详情重新签发。不要把令牌发送到聊天群、工单或截图中。

Linux Agent 安装完成后可检查：

/opt/xingchen/agent/agent.sh status
/opt/xingchen/agent/agent.sh logs

Windows Agent 安装完成后可检查：

Get-Service XingchenAgent

配置第一组监控

确认设备已有 CPU、内存和磁盘数据后，再继续：

1. 创建 CPU、内存、磁盘和离线告警规则。
2. 创建一个 HTTP 或 Ping 服务探测并执行“立即探测”。
3. 用可控的阈值变化验证告警打开、通知发送和恢复流程。
4. 为发布与维护创建静默窗口，确认静默期间仍记录事件。

上线完成标准

• 总控页面通过 HTTPS 访问，WebSocket 保持连接。
• 总控宿主机和至少一台被监控服务器持续在线。
• 资源趋势包含多个采集点，数据时间持续更新。
• 服务探测可以成功执行，也能展示失败原因。
• 测试告警完成打开、通知、确认与恢复闭环。
• 已创建可恢复的数据库备份，并妥善保存 .env 与 SETTINGS_ENCRYPTION_KEY。

遇到问题时，从常见问题按现象定位；需要完整参数与升级策略时，继续阅读部署与运维。