你要在一台 Linux 服务器上部署 monitor，一个 Rust 写的服务器探针。
文档：https://monitor-document.pages.dev/

## 你要知道的前提

- monitor 由三部分组成：hub（面板 + API，装在一台机器上）、agent（装在每台被监控的
  机器上）、主题（公开状态页的皮肤，默认已内置）。
- hub 是单个 Rust 二进制加一个 SQLite 文件。零配置文件，所有设置存在数据库里。
- 一键脚本装出来的 hub **默认只监听 127.0.0.1**，这是刻意的安全设计。公网部署不要改成
  0.0.0.0 或去开防火墙端口，正确做法是配一个反向代理用 HTTPS 域名访问。内网直连是另一种
  受支持的用法：`--host <内网地址>`，然后从同一内网用 `http://私网IP:端口` 访问。
- hub 的一键脚本只支持 systemd；没有 systemd 的机器用 Docker 部署 hub。
- agent 只支持 Linux（systemd 或 OpenRC），不提供 Docker 镜像，这也是刻意的。
- 从公网的 IP 或明文 HTTP 进面板时，添加节点和生成安装命令的入口会被禁用，必须先配好域名和 TLS。
  例外：**同一内网直连**（没有经过反代）时，用 `http://私网IP:28080` 也能添加节点。

## 执行规则

1. 每一步执行前先说清楚你要做什么、为什么，等我确认。
2. 修改任何已有配置文件（nginx、caddy、systemd 单元）之前，先备份原文件。
3. 不要 apt upgrade，不要动我系统上与本次部署无关的任何东西。
4. 遇到不确定的（端口被占、已有反代配置冲突、域名没解析过来）就停下来问，不要猜。
5. 每一步做完给我看验证结果，不要只说"完成了"。

## 步骤

### 第一步：环境检查
- 确认是 Linux，确认有 systemd（没有就停下来问我，改用 Docker），确认有 root。
- 确认 curl 存在。
- 确认 28080 端口没被占用（ss -tulpn | grep -F :28080）。占用了就问我换哪个端口。
- 问我域名是什么，并确认它已经解析到这台机器。

### 第二步：装 hub
    curl -fsSL -o install-hub.sh \
      https://raw.githubusercontent.com/spot-probe/monitor/main/install-hub.sh
    chmod +x install-hub.sh
    sudo ./install-hub.sh < /dev/null
< /dev/null 让脚本不显示菜单，直接按默认值安装；端口换过的，加 --port <端口>。
装完输出里「密码」那一行就是应急密码，原样给我。只有首次安装才有这一行。
输出是「升级完成」说明这台机器之前装过 hub，不要重置密码，告诉我即可。
确认服务在跑：systemctl status monitor-hub

### 第三步：配反向代理
先看这台机器上已经有什么（nginx / caddy / cloudflared），有就用现成的，
没有就问我装哪个。

caddy（最省事），在 Caddyfile 里加：
    hub.example.com {
        reverse_proxy 127.0.0.1:28080
    }

nginx，站点配置里必须包含这几项，一项都不能少：
    map $http_upgrade $connection_upgrade { default upgrade; '' close; }
    server {
        listen 443 ssl;
        listen [::]:443 ssl;
        server_name hub.example.com;
        ssl_certificate     /etc/letsencrypt/live/hub.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/hub.example.com/privkey.pem;
        location / {
            proxy_pass http://127.0.0.1:28080;
            proxy_http_version 1.1;
            client_max_body_size 8m;
            proxy_set_header Host              $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
            proxy_set_header Upgrade    $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_buffering off;
            proxy_read_timeout  1h;
            proxy_send_timeout  1h;
        }
    }
证书没有就用 certbot 申请，申请前先确认 80 端口能通。

Cloudflare 隧道，ingress 指向 http://127.0.0.1:28080 即可，不需要开任何入站端口。

下面四件事一件都不能漏，漏了的症状都是静默的：
- 转发 Upgrade / Connection 头，关掉缓冲，超时放到 1 小时。漏了节点会周期性掉线
- client_max_body_size 设 8m。漏了导入备份和上传主题会被反代 413 掉
- 透传 X-Forwarded-Proto。漏了会话 cookie 拿不到 Secure
- 透传 X-Forwarded-For。漏了登录限流按代理地址计数，所有人共用一个桶

### 第四步：验证
面板能打开，第一行期望是 200：
    curl -sI https://hub.example.com/admin | head -1
WebSocket 能升级，期望输出 101（升级后连接保持，由 --max-time 在 3 秒后结束）：
    curl -s --http1.1 --max-time 3 -o /dev/null -w '%{http_code}\n' \
      -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
      -H 'Sec-WebSocket-Version: 13' \
      -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
      https://hub.example.com/api/ws
两条都对了再往下走。

### 第五步：告诉我接下来手动做什么
你不要替我做这几件事，只把清单给我：
1. 打开 https://hub.example.com/admin，用应急密码登录
2. 「安全」页配置 GitHub OAuth（回调必须精确填
   https://hub.example.com/api/auth/github/callback），
   把我的 GitHub 用户名填进白名单（留空 = 拒绝所有人），然后改掉应急密码
3. 「节点」页点「添加节点」，再点这一行的安装按钮（下载图标）拿到安装命令

### 第六步：如果我给了你节点的安装命令
在目标机器上以 root 执行它，然后：
- systemctl status monitor-agent 确认在跑
- journalctl -u monitor-agent -n 30 看有没有报错
- 告诉我面板里这个节点几秒后应该就亮了

## 排查速查

节点不上线      → 先看 journalctl -u monitor-agent。
                  401 = token 被换发过或节点已删除，重新拿命令；
                  握手报 HTTP 400 = 反代没转发 WebSocket 升级头；
                  连接超时 = 节点到 hub 的网络不通
周期性掉线      → 反代读写超时太短，或者没关 proxy_buffering
"添加节点"是灰的 → 按钮上方那行字就是原因：不是从 HTTPS 域名进的，
                  或者 hub 启动时带的 --site 不是 https 加域名；反代把 Host 改写了、
                  没有透传 X-Forwarded-Proto 也会这样。
                  （从同一内网用私网 IP 直连是允许的，不算这种情况）
导入备份 413    → 反代的 client_max_body_size 没设到 8m
今日流量不归零  → Docker 部署没设 TZ 环境变量

## 明确不要做的

- 不要把 hub 改成监听 0.0.0.0 或者去开 28080 的防火墙端口。
- 不要给 agent 写 Docker 部署方案，它没有镜像，也不需要。
- 不要建议加 CPU / 内存这类负载告警、WebSSH、插件，这个项目明确不做这些。
  掉线、流量、到期通知是内置的，在「通知」页配置。
- 不要在「设置」里填 GitHub 代理，除非确认这台机器真的拉不到 GitHub Release。
  那个地址返回的字节会被装到每一台节点上作为 agent 运行。