feat: 引入 vmauth 鉴权与严格多租户

- 对外端口统一为 18428（vmauth 入口），VM 不再直接暴露宿主机端口 - 边缘 vmagent 与中央 Prometheus remote_write 增加 basic auth - 支持 tenants.csv 驱动的 per-tenant 写入/查询隔离，并提供管理员跨租户只读查询 - 更新 Grafana provisioning 与部署/文档 Made-with: Cursor
2026-04-22 11:41:13 +00:00
parent ab1515dffb
commit c4825c2d27
21 changed files with 278 additions and 37 deletions
--- a/doc/ARCHITECTURE.md
+++ b/doc/ARCHITECTURE.md
@@ -9,7 +9,7 @@
                   │ remote_write (HTTP POST)
                   ▼
 ┌─ 中央服务器 ───────────────────────────────────┐
-│  VictoriaMetrics (8428)  接收边缘推送、存储    │
+│  vmauth (18428) 鉴权入口；后端 VictoriaMetrics 存储 │
 │           │ 数据查询                           │
 │           ▼                                    │
 │  Prometheus (9091)  抓取本地、告警评估          │
@@ -38,7 +38,7 @@
            │
            │ remote_write (HTTP POST)
            ▼
-    VictoriaMetrics (8428)
+    vmauth (18428)  ->  VictoriaMetrics (container:8428)
            │
            │ 数据存储
            ▼
@@ -79,9 +79,9 @@ Alertmanager 处理告警

 ## 容器详细说明

-### 1. VictoriaMetrics (8428)
- **作用**：远程写入接收器，存储时序数据
- **接收**：边缘节点通过 `remote_write` 推送的数据
+### 1. vmauth (18428)
+- **作用**：鉴权/路由入口，给 remote_write 与查询接口加访问控制
+- **接收**：边缘节点通过 `remote_write` 推送的数据（带 basic auth）
 - **提供**：数据查询接口
 - **数据路径**：`/storage/victoria-metrics-data`

@@ -121,7 +121,8 @@ monitoring_net (Docker Bridge)
 ├─ prometheus-central:9090  -> 宿主机 9091
 ├─ grafana:3000             -> 宿主机 3000
 ├─ alertmanager:9093        -> 宿主机 9093
-└─ victoria-metrics:8428    -> 宿主机 8428
+├─ vmauth:8427              -> 宿主机 18428
+└─ victoria-metrics:8428     -> （不对外暴露，仅容器网络可达）
 ```

 ## 端口映射
@@ -131,7 +132,7 @@ monitoring_net (Docker Bridge)
 | Prometheus | 9090 | 9091 | PromQL 查询和 Web UI |
 | Grafana | 3000 | 3000 | 可视化仪表板 |
 | Alertmanager | 9093 | 9093 | 告警管理界面 |
-| VictoriaMetrics | 8428 | 8428 | 远程写入和查询接口 |
+| vmauth | 18428 | 8427 | 远程写入与查询入口（鉴权） |

 ## 数据存储

--- a/doc/BEST_PRACTICES.md
+++ b/doc/BEST_PRACTICES.md
@@ -40,14 +40,14 @@
 # 开放端口
 firewall-cmd --permanent --add-port=3000/tcp   # Grafana
 firewall-cmd --permanent --add-port=9091/tcp   # Prometheus
-firewall-cmd --permanent --add-port=8428/tcp   # VictoriaMetrics
+firewall-cmd --permanent --add-port=18428/tcp  # VictoriaMetrics
 firewall-cmd --permanent --add-port=9093/tcp   # Alertmanager
 firewall-cmd --reload
 ```

 **边缘节点**：
 - 不需要开放端口（只做数据推送）
- 确保可以访问中央服务器 8428 端口
+- 确保可以访问中央服务器 18428 端口

 #### 网络优化

--- a/doc/CENTRAL_SERVER_CONFIG.md
+++ b/doc/CENTRAL_SERVER_CONFIG.md
@@ -22,7 +22,7 @@ central-server/
 |------|------|------|
 | prometheus-central | 9091 | 自抓 + 告警评估；边缘数据由 Grafana 从 VictoriaMetrics 查询 |
 | grafana | 3000 | 数据源：Prometheus（中央自抓）、VictoriaMetrics（边缘数据） |
-| victoria-metrics | 8428 | 接收边缘 remote_write |
+| vmauth | 18428 | 边缘 remote_write 与 Grafana 查询入口（鉴权） |
 | alertmanager | 9093 | 告警路由与通知 |

 ## 关键配置摘要
--- a/doc/DEPLOYMENT_GUIDE.md
+++ b/doc/DEPLOYMENT_GUIDE.md
@@ -6,7 +6,7 @@

 ## 第一步：部署中央服务器

-**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093 未被占用；磁盘充足。
+**前置**：Docker、Docker Compose；端口 3000、9091、18428、9093 未被占用；磁盘充足。

 ```bash
 cd central-server
@@ -14,7 +14,7 @@ cp env.example .env   # 可选，按需改端口、Traefik 等
 bash deploy.sh
 ```

-**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、VictoriaMetrics http://localhost:8428。
+**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、vmauth（VictoriaMetrics 入口）http://localhost:18428。

 **详细**：[CENTRAL_SERVER_CONFIG](CENTRAL_SERVER_CONFIG.md)、[central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)。

@@ -22,9 +22,9 @@ bash deploy.sh

 ## 第二步：部署边缘节点

-**前提**：中央已运行，VictoriaMetrics 8428 可访问。
+**前提**：中央已运行，vmauth（VictoriaMetrics 入口）18428 可访问。

- **本机同机**：`cd edge-agent && bash deploy.sh --local`（中央地址设为 host.docker.internal:8428）。
+- **本机同机**：`cd edge-agent && bash deploy.sh --local`（中央地址设为 host.docker.internal:18428）。
 - **边缘跨机**：`cd edge-agent` → 编辑 `.env` 中 `CENTRAL_SERVER_HOST=中央IP` → `bash deploy.sh`。

 **验证**：边缘 http://localhost:9092；中央 Grafana 选数据源 **VictoriaMetrics**，查询 `probe_success{job="network-ping"}` 可见边缘数据。
@@ -32,7 +32,7 @@ bash deploy.sh
 **targets.csv**：部署时自动生成 target-*.json；修改 targets.csv 后需手动 `cd config && ./update-configs.sh`，vmagent 每 5 分钟自动重载。

 **常见问题**：  
- 看不到边缘数据：确认 `.env` 中为中央 IP（跨机不能用 host.docker.internal）；`curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health` 应为 200。  
+- 看不到边缘数据：确认 `.env` 中为中央 IP（跨机不能用 host.docker.internal）；`curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:18428/health` 应为 200（需要带鉴权时用 `-u user:pass`）。  
 - 端口冲突：边缘已映射 9092，与中央 9091 区分。

 **详细**：[EDGE_AGENT_CONFIG](EDGE_AGENT_CONFIG.md)、[TARGETS_AND_MONITORING](TARGETS_AND_MONITORING.md)。
--- a/doc/EDGE_AGENT_CONFIG.md
+++ b/doc/EDGE_AGENT_CONFIG.md
@@ -27,7 +27,11 @@
 - **config/targets.csv**：统一监控目标（ping/onvif/topology），格式与脚本见 [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
 - **config/update-configs.sh**：从 targets.csv 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`。
 - **prometheus-edge (vmagent)**：使用 `config/vmagent/vmagent-scrape.yml.template` 抓取；`CENTRAL_SERVER_HOST`/`PORT` 来自 `.env`；磁盘缓存卷 `vmagent-cache-data`。
- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`、`EDGE_NODE_ID`。本机同机用 `./deploy.sh --local`；跨机配 `.env` 后 `./deploy.sh`。
+- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=18428`、`VMAUTH_WRITE_USER`、`VMAUTH_WRITE_PASSWORD`、`EDGE_NODE_ID`。本机同机用 `./deploy.sh --local`；跨机配 `.env` 后 `./deploy.sh`。
+
+## 严格多租户（推荐）
+
+中央启用 `central-server/config/vmauth/tenants.csv` 后，每个边缘节点建议配置独立的 `VMAUTH_WRITE_USER/VMAUTH_WRITE_PASSWORD`，与中央 tenants.csv 中对应的 write 账号一致；这样每个边缘写入各自 tenant，Grafana 也能按 tenant 独立查询。

 ## 常用操作

--- a/doc/TROUBLESHOOTING.md
+++ b/doc/TROUBLESHOOTING.md
@@ -64,7 +64,7 @@ netstat -tulpn | grep <端口>
 2. **在中央直接查 VictoriaMetrics**  
   在**中央服务器**上执行（或浏览器访问）：
   ```bash
-   curl -sG 'http://localhost:8428/api/v1/series' --data-urlencode 'match[]=probe_success{job="network-ping"}'
+   curl -u 'vm_read:change-me-strong-read' -sG 'http://localhost:18428/api/v1/series' --data-urlencode 'match[]=probe_success{job="network-ping"}'
   ```
   - 若返回 `"data":[]` 表示还没有收到边缘数据（可能是网络不通、刚启动未到抓取周期、或 remote_write 失败）。
   - 若 `data` 里有元素（带 `__name__`、`job`、`region` 等），说明边缘数据已写入中央。
@@ -81,7 +81,7 @@ curl http://localhost:9092/api/v1/query?query=up

 # 2. 检查网络连通性
 ping <中央服务器IP>
-telnet <中央服务器IP> 8428
+telnet <中央服务器IP> 18428

 # 3. 检查环境变量
 cat edge-agent/.env