iluobei
364 lines
13 KiB
Markdown
364 lines
13 KiB
Markdown
# mmw-agent
|
||
|
||
妙妙屋X 远程服务器代理程序。部署在子服务器上，负责与主控（miaomiaowux）通信，上报流量/速度数据，并接受主控的远程管理指令。
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Master (miaomiaowux) │
|
||
│ │
|
||
│ /api/remote/ws WebSocket 双向通信 │
|
||
│ /api/remote/traffic HTTP 流量推送 │
|
||
│ /api/remote/speed HTTP 速度推送 │
|
||
│ /api/remote/heartbeat HTTP 心跳 │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
│
|
||
┌────────────┼────────────┐
|
||
│ WebSocket │ HTTP Push │ Pull (被动)
|
||
└────────────┼────────────┘
|
||
│
|
||
┌──────────────────────▼──────────────────────────────┐
|
||
│ mmw-agent │
|
||
│ │
|
||
│ 内部组件: │
|
||
│ ├── Agent Client 连接管理 + 数据上报 │
|
||
│ ├── Collector Xray 流量采集 (/debug/vars) │
|
||
│ ├── Handler 本地管理 API (/api/child/*) │
|
||
│ └── xRPC Xray gRPC 管理 │
|
||
│ │
|
||
│ 监听端口: :23889 (管理API) │
|
||
│ Xray metrics: :38889 (/debug/vars) │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 构建与运行
|
||
|
||
```bash
|
||
# 构建
|
||
go build -ldflags="-s -w" -o mmw-agent ./cmd/mmw-agent
|
||
|
||
# 运行（配置文件方式）
|
||
./mmw-agent -c config.yaml
|
||
|
||
# 运行（环境变量方式）
|
||
MMWX_MASTER_URL=https://master.example.com \
|
||
MMWX_MASTER_TOKEN=your-token \
|
||
./mmw-agent
|
||
```
|
||
|
||
## 配置
|
||
|
||
### 配置文件 (YAML)
|
||
|
||
```yaml
|
||
master_server: "https://master.example.com"
|
||
remote_token: "your-server-token"
|
||
connection_mode: "auto" # auto | websocket | http | pull
|
||
listen_port: 23889
|
||
child_api_token: "" # 可选，pull模式API认证
|
||
traffic_report_interval: 60 # 秒
|
||
speed_report_interval: 3 # 秒
|
||
heartbeat_interval: 30 # 秒
|
||
xray_servers: # 可选，不配则自动发现
|
||
- config_path: "/usr/local/etc/xray/config.json"
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `MMWX_MASTER_URL` | 主控地址 | — |
|
||
| `MMWX_MASTER_TOKEN` | 服务器令牌 | — |
|
||
| `MMWX_CONNECTION_MODE` | 连接模式 | `auto` |
|
||
| `MMWX_LISTEN_PORT` | 监听端口 | `23889` |
|
||
| `MMWX_CHILD_API_TOKEN` | Pull API 认证令牌 | — |
|
||
| `MMWX_TRAFFIC_INTERVAL` | 流量上报间隔(秒) | `60` |
|
||
| `MMWX_SPEED_INTERVAL` | 速度上报间隔(秒) | `3` |
|
||
| `MMWX_HEARTBEAT_INTERVAL` | 心跳间隔(秒) | `30` |
|
||
|
||
环境变量优先级高于配置文件。
|
||
|
||
### Xray 自动发现
|
||
|
||
未显式配置 `xray_servers` 时，agent 按以下路径搜索 Xray 配置：
|
||
|
||
1. `/usr/local/etc/xray/config.json`
|
||
2. `/etc/xray/config.json`
|
||
3. `/opt/xray/config.json`
|
||
|
||
---
|
||
|
||
## 连接模式
|
||
|
||
### Auto（推荐）
|
||
|
||
自动回退链：WebSocket → HTTP → Pull，带指数退避重连。
|
||
|
||
```
|
||
尝试 WebSocket 连接
|
||
├── 成功 → 保持 WebSocket 双向通信
|
||
│ 断开后退避重连，期间通过 HTTP 发送流量保持在线
|
||
└── 失败 → 尝试 HTTP 推送
|
||
├── 成功 → 定时 HTTP POST 上报
|
||
│ 连续 5 次失败后重试上层
|
||
└── 失败 → 回退 Pull 模式
|
||
等待退避时间后重试上层
|
||
```
|
||
|
||
退避策略：基础 5s，指数增长，上限 5min。
|
||
|
||
### WebSocket
|
||
|
||
全双向通信。支持：
|
||
- Agent → Master：流量、速度、心跳、证书结果、扫描结果、域延迟探测结果
|
||
- Master → Agent：证书请求、证书部署、令牌更新、域延迟探测
|
||
|
||
连续 5 次连接失败后自动切换到 Auto 模式回退。
|
||
|
||
### HTTP
|
||
|
||
单向推送。Agent 定时 POST 数据到 Master：
|
||
- `/api/remote/traffic` — 流量数据
|
||
- `/api/remote/speed` — 速度数据
|
||
- `/api/remote/heartbeat` — 心跳
|
||
|
||
### Pull
|
||
|
||
被动模式。Agent 仅暴露本地 API，等待 Master 主动拉取：
|
||
- `GET /api/child/traffic`
|
||
- `GET /api/child/speed`
|
||
|
||
---
|
||
|
||
## 认证机制
|
||
|
||
所有请求必须同时满足：
|
||
|
||
1. **User-Agent**: `miaomiaowux/0.1`
|
||
2. **Authorization**: `Bearer <token>`（或 `X-Remote-Token` header）
|
||
|
||
未通过认证的连接被**静默丢弃**（TCP hijack 后直接关闭，不返回 HTTP 响应）。
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
### 健康检查（无需认证）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/health` | 健康检查 |
|
||
|
||
### 本地管理 API (`/api/child/*`)
|
||
|
||
以下所有端点均需通过 Silent Auth 中间件认证。
|
||
|
||
#### 服务管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/child/services/status` | 获取 Xray/Nginx 服务运行状态 |
|
||
| POST | `/api/child/services/control` | 控制服务启停 |
|
||
|
||
```json
|
||
// POST /api/child/services/control
|
||
{ "service": "xray", "action": "restart" }
|
||
// service: xray | nginx
|
||
// action: start | stop | restart
|
||
```
|
||
|
||
#### Xray 管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/child/xray/install` | 安装 Xray（SSE 流式输出） |
|
||
| POST | `/api/child/xray/remove` | 卸载 Xray（SSE 流式输出） |
|
||
| GET | `/api/child/xray/config` | 获取 Xray 完整配置 |
|
||
| PUT | `/api/child/xray/config` | 写入 Xray 完整配置 |
|
||
| GET | `/api/child/xray/config/files` | 列出 Xray 配置文件 |
|
||
| GET | `/api/child/xray/system-config` | 获取 Xray 系统配置路径信息 |
|
||
|
||
#### Nginx 管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/child/nginx/install` | 安装 Nginx（SSE 流式输出） |
|
||
| POST | `/api/child/nginx/remove` | 卸载 Nginx（SSE 流式输出） |
|
||
| GET | `/api/child/nginx/config` | 获取 Nginx 配置 |
|
||
| PUT | `/api/child/nginx/config` | 写入 Nginx 配置 |
|
||
| GET | `/api/child/nginx/config/files` | 列出 Nginx 配置文件 |
|
||
|
||
#### Xray 入站/出站/路由 (gRPC)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/child/inbounds` | 列出所有入站 |
|
||
| POST | `/api/child/inbounds` | 添加入站 |
|
||
| PUT | `/api/child/inbounds` | 更新入站 |
|
||
| DELETE | `/api/child/inbounds` | 删除入站（query: `?tag=xxx`） |
|
||
| GET | `/api/child/outbounds` | 列出所有出站 |
|
||
| POST | `/api/child/outbounds` | 添加出站 |
|
||
| PUT | `/api/child/outbounds` | 更新出站 |
|
||
| DELETE | `/api/child/outbounds` | 删除出站（query: `?tag=xxx`） |
|
||
| GET | `/api/child/routing` | 获取路由规则 |
|
||
| PUT | `/api/child/routing` | 更新路由规则 |
|
||
|
||
请求体为标准 Xray JSON 配置对象。
|
||
|
||
#### 扫描与探测
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/child/scan` | 扫描 Xray 运行状态与入站配置 |
|
||
| POST | `/api/child/domains/latency` | 域名延迟探测（TCP） |
|
||
|
||
```json
|
||
// POST /api/child/domains/latency
|
||
{
|
||
"domains": ["example.com", "test.org"],
|
||
"timeout_ms": 5000
|
||
}
|
||
// 并发 TCP 探测，自动去重，最多 200 个域名
|
||
```
|
||
|
||
**扫描自动补全**：`/api/child/scan` 会检查 Xray 配置完整性，自动补全缺失的 `api`、`stats`、`policy` 段及 API 入站和路由规则，补全后自动重启 Xray。
|
||
|
||
#### 系统信息
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/child/system/info` | 获取系统信息（OS、CPU、内存、磁盘） |
|
||
|
||
#### Pull 模式数据接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/child/traffic` | 获取当前 Xray 流量统计 |
|
||
| GET | `/api/child/speed` | 获取当前系统网络速度 |
|
||
|
||
```json
|
||
// GET /api/child/traffic 响应
|
||
{
|
||
"stats": {
|
||
"inbound": { "tag": { "uplink": 1024, "downlink": 2048 } },
|
||
"outbound": { "tag": { "uplink": 512, "downlink": 1024 } },
|
||
"user": { "email": { "uplink": 256, "downlink": 512 } }
|
||
}
|
||
}
|
||
|
||
// GET /api/child/speed 响应
|
||
{
|
||
"upload_speed": 102400,
|
||
"download_speed": 204800
|
||
}
|
||
// 单位：字节/秒 (B/s)，来源：/proc/net/dev 物理网卡聚合
|
||
```
|
||
|
||
---
|
||
|
||
## WebSocket 交互协议
|
||
|
||
连接地址：`ws(s)://<master>/api/remote/ws`
|
||
|
||
### 消息格式
|
||
|
||
所有消息为 JSON，统一结构：
|
||
|
||
```json
|
||
{
|
||
"type": "<message_type>",
|
||
"payload": { ... }
|
||
}
|
||
```
|
||
|
||
### 连接流程
|
||
|
||
```
|
||
Agent Master
|
||
│ │
|
||
│──── WebSocket Connect ────────────────>│
|
||
│ Header: User-Agent: miaomiaowux/0.1
|
||
│ │
|
||
│──── auth ─────────────────────────────>│
|
||
│ { "token": "server-token" } │
|
||
│ │
|
||
│<─── auth_result ──────────────────────│
|
||
│ { "success": true } │
|
||
│ │
|
||
│──── traffic (定时) ───────────────────>│
|
||
│──── speed (定时) ─────────────────────>│
|
||
│──── heartbeat (定时) ─────────────────>│
|
||
│ │
|
||
│<─── cert_request ─────────────────────│
|
||
│──── cert_update ──────────────────────>│
|
||
│ │
|
||
│<─── cert_deploy ──────────────────────│
|
||
│<─── token_update ─────────────────────│
|
||
│<─── domain_latency_probe ─────────────│
|
||
│──── domain_latency_result ────────────>│
|
||
│ │
|
||
│──── scan_result (首次连接) ───────────>│
|
||
```
|
||
|
||
### 消息类型
|
||
|
||
#### Agent → Master
|
||
|
||
| type | 说明 | payload |
|
||
|------|------|---------|
|
||
| `auth` | 认证 | `{ "token": "string" }` |
|
||
| `traffic` | 流量数据 | `{ "stats": { "inbound": {}, "outbound": {}, "user": {} } }` |
|
||
| `speed` | 实时速度 | `{ "upload_speed": int64, "download_speed": int64 }` |
|
||
| `heartbeat` | 心跳 | `{ "boot_time": "RFC3339" }` |
|
||
| `cert_update` | 证书申请结果 | `{ "cert_id": int, "domain": "string", "success": bool, "cert_pem": "string", "key_pem": "string", "issue_date": "time", "expiry_date": "time", "error": "string" }` |
|
||
| `scan_result` | Xray 扫描结果 | `{ "xray_running": bool, "xray_version": "string", "inbounds": [...] }` |
|
||
| `domain_latency_result` | 域延迟探测结果 | `{ "request_id": "string", "success": bool, "results": [{ "domain": "string", "latency_ms": int64, "success": bool }] }` |
|
||
|
||
#### Master → Agent
|
||
|
||
| type | 说明 | payload |
|
||
|------|------|---------|
|
||
| `auth_result` | 认证结果 | `{ "success": bool, "message": "string" }` |
|
||
| `cert_request` | 请求申请证书 | `{ "cert_id": int, "domain": "string", "email": "string", "provider": "string", "challenge_mode": "string", ... }` |
|
||
| `cert_deploy` | 部署证书文件 | `{ "domain": "string", "cert_pem": "string", "key_pem": "string", "cert_path": "string", "key_path": "string", "reload": "nginx\|xray\|both\|none" }` |
|
||
| `token_update` | 推送新令牌 | `{ "server_token": "string", "expires_at": "RFC3339" }` |
|
||
| `domain_latency_probe` | 域延迟探测请求 | `{ "request_id": "string", "domains": ["string"], "timeout_ms": int }` |
|
||
|
||
### 认证流程
|
||
|
||
1. Agent 建立 WebSocket 连接（必须携带 `User-Agent: miaomiaowux/0.1`）
|
||
2. Agent 发送 `auth` 消息，携带服务器令牌
|
||
3. Master 验证令牌，返回 `auth_result`
|
||
4. 认证成功后进入消息循环；未认证的消息会收到 `auth_result { success: false, message: "Authentication required" }`
|
||
|
||
### 令牌轮换
|
||
|
||
Master 可通过 `token_update` 推送新令牌。Agent 收到后：
|
||
1. 将新令牌持久化到本地配置
|
||
2. 后续所有请求使用新令牌
|
||
3. Master 端同步更新连接映射
|
||
|
||
### 首次连接自动扫描
|
||
|
||
Agent 认证成功后自动执行 Xray 扫描，将结果通过 `scan_result` 发送给 Master。如果服务器处于 `pending` 状态且配置了域名和 443 端口，Master 会自动触发 steal-self 配置部署。
|
||
|
||
---
|
||
|
||
## 数据采集
|
||
|
||
### 流量采集
|
||
|
||
从 Xray 的 `/debug/vars` HTTP 端点采集，解析 `stats` 对象中的 inbound/outbound/user 流量数据。
|
||
|
||
metrics 地址从 Xray 配置文件的 `api` 段中的 `listen` 字段获取，默认 `127.0.0.1:38889`。
|
||
|
||
### 速度采集
|
||
|
||
读取 `/proc/net/dev`，聚合所有物理网卡（排除 `lo`）的收发字节数，计算两次采样间的速率差值。
|
||
|
||
```
|
||
上传速度 = (当前 TX - 上次 TX) / 采样间隔
|
||
下载速度 = (当前 RX - 上次 RX) / 采样间隔
|
||
```
|