wimotek-edge-agent 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +219 -3
- package/agent.py +372 -0
- package/bin/cli.js +14 -0
- package/dist/wimotek_edge_agent-1.0.0-py3-none-any.whl +0 -0
- package/dist/wimotek_edge_agent-1.0.0.tar.gz +0 -0
- package/package.json +19 -6
- package/pyproject.toml +18 -0
- package/wimotek_edge_agent.egg-info/PKG-INFO +228 -0
- package/wimotek_edge_agent.egg-info/SOURCES.txt +9 -0
- package/wimotek_edge_agent.egg-info/dependency_links.txt +1 -0
- package/wimotek_edge_agent.egg-info/entry_points.txt +3 -0
- package/wimotek_edge_agent.egg-info/requires.txt +2 -0
- package/wimotek_edge_agent.egg-info/top_level.txt +1 -0
package/README.md
CHANGED
|
@@ -1,3 +1,219 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# Wimotek Edge Agent (wimotek-edge-agent)
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/wimotek-edge-agent/)
|
|
4
|
+
[](https://www.npmjs.com/package/wimotek-edge-agent)
|
|
5
|
+
[](https://pypi.org/project/wimotek-edge-agent/)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
轻量、通用、零侵入的边缘节点出站反向代理与服务中继客户端(Universal Edge Reverse Tunnel & Service Bridge Agent)。
|
|
9
|
+
|
|
10
|
+
专为处于 **无公网 IP、NAT4、移动宽带、家用路由器或严格云防火墙** 环境下的容器(noVNC、Kasm Workspaces、Headless Chromium、自动化爬虫等)与边缘服务器设计,提供全自动设备确权、双模身份认证与本地端口透明反向穿透能力。
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 🌟 核心特性
|
|
15
|
+
|
|
16
|
+
- **⚡ 出站长连接 NAT4 极速穿透**:通过单向发起 Outbound WebSocket (WSS/TLS) 长连接直达中心管理端,彻底突破多层 NAT 与企业内网防火墙,**节点无需公网 IP、无需路由器端口映射**。
|
|
17
|
+
- **🛡️ 生产级双模身份认证与防伪造(TOFU + Edge Agent)**:
|
|
18
|
+
- **默认 TOFU 模式(Trust On First Use)**:零配置启动,节点自动生成硬件指纹 UUID,管理端后台实时弹出审核认领,管理员「一键信任锁定」后完成公钥防篡改绑定。
|
|
19
|
+
- **Edge Agent 模式**:批量注入 `JOIN_TOKEN`,节点开机秒级自验证入网,支持 CI/CD 与大规模集群全自动挂靠。
|
|
20
|
+
- **🤖 智能命名与设备自协商**:自动探测出口公网 IP 或物理网卡 IP 智能拼接命名(如 `Node-123.45.67.89`),嗅探失败平滑降级为容器主机名。
|
|
21
|
+
- **🔌 通用本地服务透明桥接(Decoupled & Multi-Service)**:业务完全解耦,不仅支持 Chromium CDP(9222),亦可同时中继 VNC 桌面(6080)、Web 业务 API(8080)等任意本地端口。
|
|
22
|
+
- **🌐 跨语言分发与 CLI 驱动**:同时发布至 PyPI 与 npm,支持系统级全局命令 `edge-agent` 与 `npx wimotek-edge-agent`。
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 🏗️ 架构原理
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
┌────────────────────────────────────────────────────────┐
|
|
30
|
+
│ 边缘内网节点 (家用宽带 / NAT4 / 容器无公网IP) │
|
|
31
|
+
│ │
|
|
32
|
+
│ - Chromium CDP (:9222) │
|
|
33
|
+
│ - noVNC 桌面 (:6080) │
|
|
34
|
+
│ - 自定义业务服务 (:8080) │
|
|
35
|
+
└──────────────────────────┬─────────────────────────────┘
|
|
36
|
+
▲ 本地 127.0.0.1 访问
|
|
37
|
+
▼
|
|
38
|
+
┌────────────────────────────────────────────────────────┐
|
|
39
|
+
│ wimotek-edge-agent 客户端 │
|
|
40
|
+
│ │
|
|
41
|
+
│ 职责: 硬件指纹生成 + TOFU/Token协商 + 本地服务透明中继 │
|
|
42
|
+
└──────────────────────────┬─────────────────────────────┘
|
|
43
|
+
│
|
|
44
|
+
│ 主动发起出站反向长连接 (Outbound TLS/WSS)
|
|
45
|
+
│ 仅需中心管理端暴露 8443 端口,无视客户端网络环境
|
|
46
|
+
▼
|
|
47
|
+
┌────────────────────────────────────────────────────────┐
|
|
48
|
+
│ 中心控制端 (Central Hub) │
|
|
49
|
+
│ │
|
|
50
|
+
│ - 管理员在线认领锁定 (TOFU) / Token 自动化放行 │
|
|
51
|
+
│ - 借由反向长连接随时下发指令、Cookie同步、采集探针 │
|
|
52
|
+
└────────────────────────────────────────────────────────┘
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 📦 安装与调用
|
|
58
|
+
|
|
59
|
+
### 1. Python / PyPI 安装(推荐)
|
|
60
|
+
```bash
|
|
61
|
+
pip install wimotek-edge-agent
|
|
62
|
+
```
|
|
63
|
+
安装后直接获得系统全局命令 **`edge-agent`**。
|
|
64
|
+
|
|
65
|
+
### 2. Node.js / npm 免安装执行
|
|
66
|
+
```bash
|
|
67
|
+
npx wimotek-edge-agent --hub-url https://hub.yourdomain.com:8443
|
|
68
|
+
```
|
|
69
|
+
或全局安装:
|
|
70
|
+
```bash
|
|
71
|
+
npm install -g wimotek-edge-agent
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 🚀 快速上手
|
|
77
|
+
|
|
78
|
+
### 1. 命令行直接启动 (CLI)
|
|
79
|
+
```bash
|
|
80
|
+
# 最简启动 (直连模式,自动嗅探 IP 命名)
|
|
81
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443
|
|
82
|
+
|
|
83
|
+
# NAT4 穿透模式 (无公网 IP 环境)
|
|
84
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443 --reverse
|
|
85
|
+
|
|
86
|
+
# 批量免审批模式 (携带集群入网通行码)
|
|
87
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443 --join-token hub_join_xxxxxx --reverse
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 2. 环境变量一键启动(容器化最佳实践)
|
|
91
|
+
无需修改命令,直接传入环境变量:
|
|
92
|
+
```bash
|
|
93
|
+
export HUB_URL="https://hub.yourdomain.com:8443"
|
|
94
|
+
export JOIN_TOKEN="hub_join_xxxxxx" # 可选,不填走 TOFU 待认领模式
|
|
95
|
+
export REVERSE_TUNNEL="true" # 可选,默认 false;NAT4 无公网环境设为 true
|
|
96
|
+
edge-agent
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### 3. Python 脚本编程式集成
|
|
100
|
+
```python
|
|
101
|
+
from wimotek_edge_agent import EdgeAgent
|
|
102
|
+
|
|
103
|
+
agent = EdgeAgent(
|
|
104
|
+
hub_url="https://hub.yourdomain.com:8443",
|
|
105
|
+
join_token="hub_join_xxxxxx", # 可选
|
|
106
|
+
node_name="Seoul-Worker-01", # 可选,留空自动按 IP 拼接
|
|
107
|
+
node_group="爬虫矩阵组", # 默认: 默认分组
|
|
108
|
+
cdp_port=9222, # 默认: 9222
|
|
109
|
+
reverse_tunnel=True # 开启 NAT4 反向长连接
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
# 启动后台代理 (阻塞运行)
|
|
113
|
+
agent.run()
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## ⚙️ 环境变量与参数字典
|
|
119
|
+
|
|
120
|
+
| 环境变量名 | CLI 参数 | 默认值 | 描述 |
|
|
121
|
+
| :--- | :--- | :--- | :--- |
|
|
122
|
+
| `HUB_URL` | `--hub-url` | *无 (必填)* | 中心管理端 HTTPS/WSS 地址,如 `https://hub.domain.com:8443` |
|
|
123
|
+
| `JOIN_TOKEN` | `--join-token` | `""` (空) | 集群入网通行码。**留空走 TOFU 后台审核认领**;填入则走 Edge Agent 自动放行入网 |
|
|
124
|
+
| `REVERSE_TUNNEL`| `--reverse` / `--direct` | `false` | 是否开启出站反向长连接隧道。**无公网 IP/NAT4 环境设为 `true`**;有公网/局域网设为 `false` |
|
|
125
|
+
| `NODE_NAME` | `--node-name` | 自动嗅探 | 节点名称。未设置时自动以出口 IP 命名(如 `Node-123.45.67.89`),兜底为主机名 |
|
|
126
|
+
| `NODE_GROUP` | `--group` | `默认分组` | 节点所属集群分组,便于多策略调度分类 |
|
|
127
|
+
| `CDP_PORT` | `--port` | `9222` | 容器本地需要中继的主服务端口(如 Chromium 调试端口) |
|
|
128
|
+
| `LOCAL_CDP_HOST`| `--cdp-host` | `127.0.0.1` | 节点本地被中继服务的绑定地址 |
|
|
129
|
+
| `SERVICES` | `--services` | *无* | 多服务端口定义,格式:`cdp:9222,vnc:6080,api:8080` |
|
|
130
|
+
| `UUID_FILE` | `--uuid-file` | `/data/node_machine.id` | 硬件指纹持久化文件路径,保障重启后身份不漂移 |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 🐳 Docker 生产环境集成示例
|
|
135
|
+
|
|
136
|
+
### 场景 1:noVNC / Kasm 节点 Dockerfile 集成
|
|
137
|
+
在现有的浏览器镜像中,只需增加 `pip install` 即可:
|
|
138
|
+
|
|
139
|
+
```dockerfile
|
|
140
|
+
FROM debian:bookworm-slim
|
|
141
|
+
|
|
142
|
+
# 安装 Chromium、noVNC 及基础环境
|
|
143
|
+
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
144
|
+
chromium xvfb x11vnc novnc websockify python3 python3-pip curl \
|
|
145
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
146
|
+
|
|
147
|
+
# 一行安装通用边缘 Agent
|
|
148
|
+
RUN pip3 install --no-cache-dir --break-system-packages wimotek-edge-agent
|
|
149
|
+
|
|
150
|
+
COPY entrypoint.sh /app/entrypoint.sh
|
|
151
|
+
RUN chmod +x /app/entrypoint.sh
|
|
152
|
+
ENTRYPOINT ["/app/entrypoint.sh"]
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
在 `entrypoint.sh` 中只需一行后台唤起:
|
|
156
|
+
```bash
|
|
157
|
+
#!/bin/bash
|
|
158
|
+
# 启动本地服务 (如 Chromium 9222)
|
|
159
|
+
chromium --remote-debugging-port=9222 --remote-allow-origins=* &
|
|
160
|
+
|
|
161
|
+
# 只要注入了 HUB_URL,自动在后台拉起边缘代理
|
|
162
|
+
if [ -n "$HUB_URL" ]; then
|
|
163
|
+
echo "🚀 启动 wimotek-edge-agent ..."
|
|
164
|
+
edge-agent &
|
|
165
|
+
fi
|
|
166
|
+
|
|
167
|
+
wait -n
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### 场景 2:`docker-compose.yml` 极简部署
|
|
171
|
+
|
|
172
|
+
#### 无公网 IP / 家用宽带 / NAT4(开启反向长连接):
|
|
173
|
+
```yaml
|
|
174
|
+
version: '3.8'
|
|
175
|
+
|
|
176
|
+
services:
|
|
177
|
+
browser-node:
|
|
178
|
+
image: your-browser-image:latest
|
|
179
|
+
restart: unless-stopped
|
|
180
|
+
ports:
|
|
181
|
+
- "6080:6080" # 仅供内网访问桌面,公网无需暴露 9222
|
|
182
|
+
environment:
|
|
183
|
+
- HUB_URL=https://hub.yourdomain.com:8443
|
|
184
|
+
- JOIN_TOKEN=hub_join_abcdef1234567890 # 可选:留空在控制台一键点击认领
|
|
185
|
+
- REVERSE_TUNNEL=true # NAT4 穿透开关
|
|
186
|
+
- NODE_GROUP=北美爬虫矩阵组
|
|
187
|
+
volumes:
|
|
188
|
+
- ./data:/data
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
#### 拥有独立公网 IP 的云服务器(直连心跳上报):
|
|
192
|
+
```yaml
|
|
193
|
+
version: '3.8'
|
|
194
|
+
|
|
195
|
+
services:
|
|
196
|
+
browser-node:
|
|
197
|
+
image: your-browser-image:latest
|
|
198
|
+
restart: unless-stopped
|
|
199
|
+
ports:
|
|
200
|
+
- "9222:9222" # 防火墙已开放端口
|
|
201
|
+
environment:
|
|
202
|
+
- HUB_URL=https://hub.yourdomain.com:8443
|
|
203
|
+
- REVERSE_TUNNEL=false # 默认即为 false,仅发起轻量 HTTP 登记,零长连接开销
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 🔒 安全性考量
|
|
209
|
+
|
|
210
|
+
1. **防恶意伪造(SSRF 防御)**:在直连上报模式下,管理端强制从底层 TCP 握手来源直接锁定节点的真实来源 IP,杜绝假冒内网私网地址。
|
|
211
|
+
2. **防公网扫描冒充**:未携带 `JOIN_TOKEN` 的未知连接一律进入隔离待审核队列(TOFU),未经管理端管理员后台显式认领的节点,绝不参与任何数据交互。
|
|
212
|
+
3. **安全通信**:长连接反向通道强制基于 TLS (WSS) 传输,天然防御中间人窃听与数据篡改。
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## 📄 License
|
|
217
|
+
|
|
218
|
+
MIT License © 2026 [Wimotek](https://github.com/wimotek)
|
|
219
|
+
```
|
package/agent.py
ADDED
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Wimotek Universal Edge Agent
|
|
4
|
+
A robust, decoupled, cross-platform reverse tunnel & service bridge client.
|
|
5
|
+
Works on Linux, macOS, Windows, inside containers, or on bare metal without root permissions.
|
|
6
|
+
|
|
7
|
+
State File Resolution Chain:
|
|
8
|
+
1. Environment Variable / Explicit Param Override (UUID_FILE / STATE_FILE)
|
|
9
|
+
2. Standard Designated Container Path (/data, default)
|
|
10
|
+
3. User Home Directory Fallback (~/.wimotek/)
|
|
11
|
+
4. System Temp Directory Extreme Fallback (/tmp/wimotek/)
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import os
|
|
15
|
+
import sys
|
|
16
|
+
import time
|
|
17
|
+
import json
|
|
18
|
+
import uuid
|
|
19
|
+
import socket
|
|
20
|
+
import asyncio
|
|
21
|
+
import argparse
|
|
22
|
+
import tempfile
|
|
23
|
+
import urllib.parse
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Dict, Optional, Callable, Any
|
|
26
|
+
import httpx
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def resolve_persistent_state_file(filename: str = "node_machine.id", custom_path: Optional[str] = None) -> Path:
|
|
30
|
+
"""
|
|
31
|
+
持久化状态指纹文件解析链:
|
|
32
|
+
1. 环境变量 / 显式参数覆盖 (UUID_FILE / STATE_FILE)
|
|
33
|
+
2. 制定标准路径 /data 默认 (容器环境标准约定,存在且可写即用)
|
|
34
|
+
3. 用户目录兜底 (~/.wimotek/,跨平台桌面与普通用户环境)
|
|
35
|
+
4. 临时目录保底 (/tmp/wimotek/,极端无权限环境兜底)
|
|
36
|
+
"""
|
|
37
|
+
# 1. 显式指定入参 或 环境变量覆盖
|
|
38
|
+
if custom_path:
|
|
39
|
+
return Path(custom_path).expanduser().resolve()
|
|
40
|
+
|
|
41
|
+
env_path = os.getenv("UUID_FILE") or os.getenv("STATE_FILE")
|
|
42
|
+
if env_path:
|
|
43
|
+
return Path(env_path).expanduser().resolve()
|
|
44
|
+
|
|
45
|
+
# 2. 制定标准路径 /data 默认 (容器内通过 -v 挂载到 /data 时自动命中)
|
|
46
|
+
container_data = Path("/data")
|
|
47
|
+
try:
|
|
48
|
+
if container_data.is_dir() and os.access(container_data, os.W_OK):
|
|
49
|
+
return container_data / filename
|
|
50
|
+
except Exception:
|
|
51
|
+
pass
|
|
52
|
+
|
|
53
|
+
# 3. 用户目录兜底 (~/.wimotek/,兼容 Linux / macOS / Windows 普通用户环境)
|
|
54
|
+
try:
|
|
55
|
+
home_dir = Path.home()
|
|
56
|
+
if home_dir and os.access(home_dir, os.W_OK):
|
|
57
|
+
state_dir = home_dir / ".wimotek"
|
|
58
|
+
state_dir.mkdir(parents=True, exist_ok=True)
|
|
59
|
+
if os.access(state_dir, os.W_OK):
|
|
60
|
+
return state_dir / filename
|
|
61
|
+
except Exception:
|
|
62
|
+
pass
|
|
63
|
+
|
|
64
|
+
# 4. 极端只读系统保底:操作系统标准临时目录 (/tmp/wimotek/)
|
|
65
|
+
tmp_dir = Path(tempfile.gettempdir()) / "wimotek"
|
|
66
|
+
try:
|
|
67
|
+
tmp_dir.mkdir(parents=True, exist_ok=True)
|
|
68
|
+
return tmp_dir / filename
|
|
69
|
+
except Exception:
|
|
70
|
+
return Path(tempfile.gettempdir()) / f"wimotek_{filename}"
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class EdgeAgent:
|
|
74
|
+
"""
|
|
75
|
+
通用边缘节点代理客户端
|
|
76
|
+
提供设备身份指纹绑定、NAT4 出站长连接穿透、以及本地任意端口服务的透明反向代理
|
|
77
|
+
"""
|
|
78
|
+
|
|
79
|
+
def __init__(
|
|
80
|
+
self,
|
|
81
|
+
hub_url: Optional[str] = None,
|
|
82
|
+
join_token: Optional[str] = None,
|
|
83
|
+
node_name: Optional[str] = None,
|
|
84
|
+
node_group: Optional[str] = None,
|
|
85
|
+
target_port: Optional[int] = None,
|
|
86
|
+
target_host: Optional[str] = None,
|
|
87
|
+
services: Optional[Dict[str, int]] = None,
|
|
88
|
+
reverse_tunnel: Optional[bool] = None,
|
|
89
|
+
uuid_file: Optional[str] = None,
|
|
90
|
+
):
|
|
91
|
+
self.hub_url = (hub_url or os.getenv("HUB_URL", "")).rstrip("/")
|
|
92
|
+
self.join_token = (join_token or os.getenv("JOIN_TOKEN", "")).strip()
|
|
93
|
+
self.node_group = (node_group or os.getenv("NODE_GROUP", "默认分组")).strip()
|
|
94
|
+
|
|
95
|
+
# 通用绑定主机 (优先读取通用的 TARGET_HOST/LOCAL_HOST,兼容 CDP 历史命名)
|
|
96
|
+
self.target_host = (
|
|
97
|
+
target_host
|
|
98
|
+
or os.getenv("TARGET_HOST")
|
|
99
|
+
or os.getenv("LOCAL_HOST")
|
|
100
|
+
or os.getenv("LOCAL_CDP_HOST")
|
|
101
|
+
or "127.0.0.1"
|
|
102
|
+
).strip()
|
|
103
|
+
|
|
104
|
+
# 解析主服务端口 (默认 9222)
|
|
105
|
+
raw_port = (
|
|
106
|
+
target_port
|
|
107
|
+
if target_port is not None
|
|
108
|
+
else os.getenv("TARGET_PORT")
|
|
109
|
+
or os.getenv("PORT")
|
|
110
|
+
or os.getenv("CDP_PORT")
|
|
111
|
+
or "9222"
|
|
112
|
+
)
|
|
113
|
+
try:
|
|
114
|
+
self.target_port = int(raw_port)
|
|
115
|
+
except ValueError:
|
|
116
|
+
self.target_port = 9222
|
|
117
|
+
|
|
118
|
+
# 多服务端口映射
|
|
119
|
+
self.services: Dict[str, int] = services or self._parse_services()
|
|
120
|
+
self.services["default"] = self.target_port
|
|
121
|
+
|
|
122
|
+
# 模式判定:默认 false 为直连上报;显式设为 true 则开启出站反向长连接隧道
|
|
123
|
+
if reverse_tunnel is not None:
|
|
124
|
+
self.reverse_tunnel = bool(reverse_tunnel)
|
|
125
|
+
else:
|
|
126
|
+
self.reverse_tunnel = os.getenv("REVERSE_TUNNEL", "false").lower() in ["true", "1", "yes"]
|
|
127
|
+
|
|
128
|
+
# 节点名称:支持显式配置,默认自动嗅探出口 IP / 主机名
|
|
129
|
+
env_name = (node_name or os.getenv("NODE_NAME", "")).strip()
|
|
130
|
+
self.node_name = env_name if env_name else self._auto_detect_name()
|
|
131
|
+
|
|
132
|
+
# 核心:执行三级文件解析链定位指纹文件
|
|
133
|
+
self.uuid_path = resolve_persistent_state_file("node_machine.id", custom_path=uuid_file)
|
|
134
|
+
self.node_uuid = self._load_or_create_uuid()
|
|
135
|
+
|
|
136
|
+
# 解析主控端通信协议
|
|
137
|
+
self.http_base = ""
|
|
138
|
+
self.ws_base = ""
|
|
139
|
+
if self.hub_url:
|
|
140
|
+
parsed = urllib.parse.urlparse(self.hub_url)
|
|
141
|
+
self.http_base = f"{parsed.scheme}://{parsed.netloc}"
|
|
142
|
+
ws_scheme = "wss" if parsed.scheme == "https" else "ws"
|
|
143
|
+
self.ws_base = f"{ws_scheme}://{parsed.netloc}"
|
|
144
|
+
|
|
145
|
+
# 动态自定义业务动作处理器表
|
|
146
|
+
self._action_handlers: Dict[str, Callable] = {}
|
|
147
|
+
|
|
148
|
+
def register_action(self, action_name: str, handler: Callable):
|
|
149
|
+
"""向 Agent 注册自定义业务动作回调"""
|
|
150
|
+
self._action_handlers[action_name] = handler
|
|
151
|
+
|
|
152
|
+
def _parse_services(self) -> Dict[str, int]:
|
|
153
|
+
services = {}
|
|
154
|
+
raw = os.getenv("SERVICES", "").strip()
|
|
155
|
+
if raw:
|
|
156
|
+
for item in raw.split(","):
|
|
157
|
+
if ":" in item:
|
|
158
|
+
name, p = item.split(":", 1)
|
|
159
|
+
try:
|
|
160
|
+
services[name.strip()] = int(p.strip())
|
|
161
|
+
except ValueError:
|
|
162
|
+
pass
|
|
163
|
+
return services
|
|
164
|
+
|
|
165
|
+
def _auto_detect_name(self) -> str:
|
|
166
|
+
# A. 嗅探公网出口 IP
|
|
167
|
+
try:
|
|
168
|
+
with httpx.Client(timeout=1.5) as client:
|
|
169
|
+
res = client.get("https://api.ipify.org")
|
|
170
|
+
if res.status_code == 200 and res.text.strip():
|
|
171
|
+
return f"Node-{res.text.strip()}"
|
|
172
|
+
except Exception:
|
|
173
|
+
pass
|
|
174
|
+
|
|
175
|
+
# B. 嗅探网卡出口 IP
|
|
176
|
+
try:
|
|
177
|
+
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
|
178
|
+
s.connect(("8.8.8.8", 80))
|
|
179
|
+
ip = s.getsockname()[0]
|
|
180
|
+
s.close()
|
|
181
|
+
if ip and ip != "127.0.0.1":
|
|
182
|
+
return f"Node-{ip}"
|
|
183
|
+
except Exception:
|
|
184
|
+
pass
|
|
185
|
+
|
|
186
|
+
return f"Node-{socket.gethostname()[:12]}"
|
|
187
|
+
|
|
188
|
+
def _load_or_create_uuid(self) -> str:
|
|
189
|
+
try:
|
|
190
|
+
if self.uuid_path.is_file():
|
|
191
|
+
content = self.uuid_path.read_text().strip()
|
|
192
|
+
if content:
|
|
193
|
+
return content
|
|
194
|
+
new_id = str(uuid.uuid4())
|
|
195
|
+
self.uuid_path.write_text(new_id)
|
|
196
|
+
return new_id
|
|
197
|
+
except Exception as e:
|
|
198
|
+
print(f"⚠️ 无法持久化指纹文件 ({self.uuid_path}): {e},使用内存临时指纹。")
|
|
199
|
+
return str(uuid.uuid4())
|
|
200
|
+
|
|
201
|
+
def run_direct_report(self):
|
|
202
|
+
"""直连上报模式:轻量 HTTP 登记 + 60s 心跳"""
|
|
203
|
+
print(f"📡 [Direct-Mode] 正在向主控中心登记: {self.http_base} ...")
|
|
204
|
+
headers = {"Content-Type": "application/json"}
|
|
205
|
+
if self.join_token:
|
|
206
|
+
headers["X-Join-Token"] = self.join_token
|
|
207
|
+
|
|
208
|
+
payload = {
|
|
209
|
+
"node_uuid": self.node_uuid,
|
|
210
|
+
"name": self.node_name,
|
|
211
|
+
"group_name": self.node_group,
|
|
212
|
+
"cdp_port": self.target_port,
|
|
213
|
+
"services": self.services,
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
while True:
|
|
217
|
+
try:
|
|
218
|
+
with httpx.Client(timeout=10.0, verify=False) as client:
|
|
219
|
+
res = client.post(f"{self.http_base}/api/nodes/auto-register", json=payload, headers=headers)
|
|
220
|
+
print(f"✅ [{time.strftime('%X')}] 节点上报/心跳成功: {res.text}")
|
|
221
|
+
except Exception as e:
|
|
222
|
+
print(f"⚠️ [{time.strftime('%X')}] 上报失败,60秒后重试: {e}")
|
|
223
|
+
time.sleep(60)
|
|
224
|
+
|
|
225
|
+
async def run_reverse_tunnel(self):
|
|
226
|
+
"""反向长连接隧道模式:全双工出站连接穿透 NAT4"""
|
|
227
|
+
import websockets
|
|
228
|
+
|
|
229
|
+
params = urllib.parse.urlencode({
|
|
230
|
+
"uuid": self.node_uuid,
|
|
231
|
+
"name": self.node_name,
|
|
232
|
+
"group": self.node_group,
|
|
233
|
+
"token": self.join_token,
|
|
234
|
+
"port": self.target_port,
|
|
235
|
+
})
|
|
236
|
+
ws_endpoint = f"{self.ws_base}/api/nodes/reverse-tunnel?{params}"
|
|
237
|
+
is_ssl = self.ws_base.startswith("wss://")
|
|
238
|
+
|
|
239
|
+
while True:
|
|
240
|
+
try:
|
|
241
|
+
print(f"📡 [Tunnel-Mode] 正在建立反向长连接 -> {self.hub_url} ...")
|
|
242
|
+
async with websockets.connect(ws_endpoint, timeout=10.0, ssl=False if not is_ssl else None) as ws:
|
|
243
|
+
print(f"✅ [Tunnel-Connected] 隧道就绪!指纹存储于: {self.uuid_path}")
|
|
244
|
+
|
|
245
|
+
while True:
|
|
246
|
+
msg_text = await ws.recv()
|
|
247
|
+
req = json.loads(msg_text)
|
|
248
|
+
req_id = req.get("req_id")
|
|
249
|
+
action = req.get("action", "http_proxy")
|
|
250
|
+
payload = req.get("payload", {})
|
|
251
|
+
|
|
252
|
+
# 1. 自定义扩展指令
|
|
253
|
+
if action in self._action_handlers:
|
|
254
|
+
try:
|
|
255
|
+
handler = self._action_handlers[action]
|
|
256
|
+
if inspect.iscoroutinefunction(handler):
|
|
257
|
+
resp_data = await handler(payload)
|
|
258
|
+
else:
|
|
259
|
+
resp_data = handler(payload)
|
|
260
|
+
await ws.send(json.dumps({"req_id": req_id, "data": resp_data}))
|
|
261
|
+
except Exception as ex:
|
|
262
|
+
await ws.send(json.dumps({"req_id": req_id, "error": str(ex)}))
|
|
263
|
+
|
|
264
|
+
# 2. 通用透明 HTTP 服务反向中继
|
|
265
|
+
elif action in ["http_proxy", "service_proxy"]:
|
|
266
|
+
port = payload.get("port") or self.services.get(payload.get("service", "default"), self.target_port)
|
|
267
|
+
path = payload.get("path", "/")
|
|
268
|
+
method = payload.get("method", "GET")
|
|
269
|
+
body = payload.get("body")
|
|
270
|
+
headers = payload.get("headers", {})
|
|
271
|
+
|
|
272
|
+
try:
|
|
273
|
+
async with httpx.AsyncClient(timeout=15.0) as client:
|
|
274
|
+
resp = await client.request(
|
|
275
|
+
method=method,
|
|
276
|
+
url=f"http://{self.target_host}:{port}{path}",
|
|
277
|
+
headers=headers,
|
|
278
|
+
content=body,
|
|
279
|
+
)
|
|
280
|
+
await ws.send(json.dumps({
|
|
281
|
+
"req_id": req_id,
|
|
282
|
+
"status_code": resp.status_code,
|
|
283
|
+
"headers": dict(resp.headers),
|
|
284
|
+
"body": resp.text,
|
|
285
|
+
}))
|
|
286
|
+
except Exception as ex:
|
|
287
|
+
await ws.send(json.dumps({
|
|
288
|
+
"req_id": req_id,
|
|
289
|
+
"status_code": 502,
|
|
290
|
+
"error": str(ex),
|
|
291
|
+
}))
|
|
292
|
+
|
|
293
|
+
# 3. 通用透明 WebSocket 管道转发 (如 CDP / VNC 握手)
|
|
294
|
+
elif action == "ws_proxy":
|
|
295
|
+
port = payload.get("port") or self.services.get("default", self.target_port)
|
|
296
|
+
ws_path = payload.get("path", "")
|
|
297
|
+
local_ws_url = f"ws://{self.target_host}:{port}{ws_path}"
|
|
298
|
+
send_data = payload.get("data")
|
|
299
|
+
|
|
300
|
+
try:
|
|
301
|
+
async with websockets.connect(local_ws_url, timeout=5.0) as local_ws:
|
|
302
|
+
if send_data:
|
|
303
|
+
await local_ws.send(send_data)
|
|
304
|
+
reply = await local_ws.recv()
|
|
305
|
+
await ws.send(json.dumps({
|
|
306
|
+
"req_id": req_id,
|
|
307
|
+
"success": True,
|
|
308
|
+
"data": reply,
|
|
309
|
+
}))
|
|
310
|
+
except Exception as ex:
|
|
311
|
+
await ws.send(json.dumps({
|
|
312
|
+
"req_id": req_id,
|
|
313
|
+
"success": False,
|
|
314
|
+
"error": str(ex),
|
|
315
|
+
}))
|
|
316
|
+
|
|
317
|
+
# 4. 心跳响应
|
|
318
|
+
elif action == "ping":
|
|
319
|
+
await ws.send(json.dumps({"req_id": req_id, "action": "pong", "time": time.time()}))
|
|
320
|
+
|
|
321
|
+
except (websockets.ConnectionClosed, Exception) as e:
|
|
322
|
+
print(f"⚠️ 反向连接断开,5秒后自动重连: {e}")
|
|
323
|
+
await asyncio.sleep(5)
|
|
324
|
+
|
|
325
|
+
def run(self):
|
|
326
|
+
"""执行入口"""
|
|
327
|
+
if not self.hub_url:
|
|
328
|
+
print("ℹ️ 未配置 HUB_URL,Agent 停止运行。")
|
|
329
|
+
return
|
|
330
|
+
|
|
331
|
+
print(f"🚀 [Edge-Agent] 启动节点: {self.node_name} | 模式: {'反向穿透(NAT4)' if self.reverse_tunnel else '直接HTTP登记'} | 主端口: {self.target_port} | 指纹位置: {self.uuid_path}")
|
|
332
|
+
if self.reverse_tunnel:
|
|
333
|
+
asyncio.run(self.run_reverse_tunnel())
|
|
334
|
+
else:
|
|
335
|
+
self.run_direct_report()
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
def main():
|
|
339
|
+
parser = argparse.ArgumentParser(description="Wimotek Universal Edge Agent")
|
|
340
|
+
parser.add_argument("--hub-url", type=str, help="中心管理端 URL (如 https://hub.domain.com:8443)")
|
|
341
|
+
parser.add_argument("--join-token", type=str, help="入网认证 Token (可选)")
|
|
342
|
+
parser.add_argument("--node-name", type=str, help="节点名称 (默认自动嗅探 IP)")
|
|
343
|
+
parser.add_argument("--group", type=str, help="所属集群分组")
|
|
344
|
+
parser.add_argument("--port", type=int, help="要代理的主端口 (默认: 9222)")
|
|
345
|
+
parser.add_argument("--host", type=str, help="本地服务绑定地址 (默认: 127.0.0.1)")
|
|
346
|
+
parser.add_argument("--services", type=str, help="多端口代理定义, 如: cdp:9222,vnc:6080")
|
|
347
|
+
parser.add_argument("--state-file", type=str, help="指纹文件存储路径 (默认按优先级推导)")
|
|
348
|
+
parser.add_argument("--reverse", action="store_true", help="强制开启出站反向长连接隧道")
|
|
349
|
+
parser.add_argument("--direct", action="store_true", help="强制开启直连上报心跳模式")
|
|
350
|
+
args = parser.parse_args()
|
|
351
|
+
|
|
352
|
+
rev_mode = None
|
|
353
|
+
if args.reverse:
|
|
354
|
+
rev_mode = True
|
|
355
|
+
elif args.direct:
|
|
356
|
+
rev_mode = False
|
|
357
|
+
|
|
358
|
+
agent = EdgeAgent(
|
|
359
|
+
hub_url=args.hub_url,
|
|
360
|
+
join_token=args.join_token,
|
|
361
|
+
node_name=args.node_name,
|
|
362
|
+
node_group=args.group,
|
|
363
|
+
target_port=args.port,
|
|
364
|
+
target_host=args.host,
|
|
365
|
+
reverse_tunnel=rev_mode,
|
|
366
|
+
uuid_file=args.state_file,
|
|
367
|
+
)
|
|
368
|
+
agent.run()
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
if __name__ == "__main__":
|
|
372
|
+
main()
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
const { spawn } = require('child_process');
|
|
3
|
+
|
|
4
|
+
const args = ['-m', 'wimotek_edge_agent.agent', ...process.argv.slice(2)];
|
|
5
|
+
const py = spawn('python3', args, { stdio: 'inherit', env: process.env });
|
|
6
|
+
|
|
7
|
+
py.on('error', () => {
|
|
8
|
+
console.error('❌ 请确保宿主机已安装 Python 3 和 wimotek-edge-agent: pip install wimotek-edge-agent');
|
|
9
|
+
process.exit(1);
|
|
10
|
+
});
|
|
11
|
+
|
|
12
|
+
py.on('close', (code) => {
|
|
13
|
+
process.exit(code);
|
|
14
|
+
});
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,19 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "wimotek-edge-agent",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "wimotek-edge-agent",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Universal Edge Tunnel Agent CLI Runner",
|
|
5
|
+
"main": "index.js",
|
|
6
|
+
"bin": {
|
|
7
|
+
"edge-agent": "./bin/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"keywords": [
|
|
10
|
+
"edge",
|
|
11
|
+
"agent",
|
|
12
|
+
"tunnel",
|
|
13
|
+
"reverse-proxy",
|
|
14
|
+
"cdp",
|
|
15
|
+
"vnc"
|
|
16
|
+
],
|
|
17
|
+
"author": "wimotek",
|
|
18
|
+
"license": "MIT"
|
|
19
|
+
}
|
package/pyproject.toml
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wimotek-edge-agent"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Universal Edge Reverse Proxy & Service Bridge Agent"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"httpx>=0.24.0",
|
|
13
|
+
"websockets>=11.0",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.scripts]
|
|
17
|
+
edge-agent = "wimotek_edge_agent.agent:main"
|
|
18
|
+
wimotek-agent = "wimotek_edge_agent.agent:main"
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wimotek-edge-agent
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Universal Edge Reverse Proxy & Service Bridge Agent
|
|
5
|
+
Requires-Python: >=3.9
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: httpx>=0.24.0
|
|
8
|
+
Requires-Dist: websockets>=11.0
|
|
9
|
+
|
|
10
|
+
# Wimotek Edge Agent (wimotek-edge-agent)
|
|
11
|
+
|
|
12
|
+
[](https://pypi.org/project/wimotek-edge-agent/)
|
|
13
|
+
[](https://www.npmjs.com/package/wimotek-edge-agent)
|
|
14
|
+
[](https://pypi.org/project/wimotek-edge-agent/)
|
|
15
|
+
[](https://opensource.org/licenses/MIT)
|
|
16
|
+
|
|
17
|
+
轻量、通用、零侵入的边缘节点出站反向代理与服务中继客户端(Universal Edge Reverse Tunnel & Service Bridge Agent)。
|
|
18
|
+
|
|
19
|
+
专为处于 **无公网 IP、NAT4、移动宽带、家用路由器或严格云防火墙** 环境下的容器(noVNC、Kasm Workspaces、Headless Chromium、自动化爬虫等)与边缘服务器设计,提供全自动设备确权、双模身份认证与本地端口透明反向穿透能力。
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🌟 核心特性
|
|
24
|
+
|
|
25
|
+
- **⚡ 出站长连接 NAT4 极速穿透**:通过单向发起 Outbound WebSocket (WSS/TLS) 长连接直达中心管理端,彻底突破多层 NAT 与企业内网防火墙,**节点无需公网 IP、无需路由器端口映射**。
|
|
26
|
+
- **🛡️ 生产级双模身份认证与防伪造(TOFU + Edge Agent)**:
|
|
27
|
+
- **默认 TOFU 模式(Trust On First Use)**:零配置启动,节点自动生成硬件指纹 UUID,管理端后台实时弹出审核认领,管理员「一键信任锁定」后完成公钥防篡改绑定。
|
|
28
|
+
- **Edge Agent 模式**:批量注入 `JOIN_TOKEN`,节点开机秒级自验证入网,支持 CI/CD 与大规模集群全自动挂靠。
|
|
29
|
+
- **🤖 智能命名与设备自协商**:自动探测出口公网 IP 或物理网卡 IP 智能拼接命名(如 `Node-123.45.67.89`),嗅探失败平滑降级为容器主机名。
|
|
30
|
+
- **🔌 通用本地服务透明桥接(Decoupled & Multi-Service)**:业务完全解耦,不仅支持 Chromium CDP(9222),亦可同时中继 VNC 桌面(6080)、Web 业务 API(8080)等任意本地端口。
|
|
31
|
+
- **🌐 跨语言分发与 CLI 驱动**:同时发布至 PyPI 与 npm,支持系统级全局命令 `edge-agent` 与 `npx wimotek-edge-agent`。
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 🏗️ 架构原理
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
┌────────────────────────────────────────────────────────┐
|
|
39
|
+
│ 边缘内网节点 (家用宽带 / NAT4 / 容器无公网IP) │
|
|
40
|
+
│ │
|
|
41
|
+
│ - Chromium CDP (:9222) │
|
|
42
|
+
│ - noVNC 桌面 (:6080) │
|
|
43
|
+
│ - 自定义业务服务 (:8080) │
|
|
44
|
+
└──────────────────────────┬─────────────────────────────┘
|
|
45
|
+
▲ 本地 127.0.0.1 访问
|
|
46
|
+
▼
|
|
47
|
+
┌────────────────────────────────────────────────────────┐
|
|
48
|
+
│ wimotek-edge-agent 客户端 │
|
|
49
|
+
│ │
|
|
50
|
+
│ 职责: 硬件指纹生成 + TOFU/Token协商 + 本地服务透明中继 │
|
|
51
|
+
└──────────────────────────┬─────────────────────────────┘
|
|
52
|
+
│
|
|
53
|
+
│ 主动发起出站反向长连接 (Outbound TLS/WSS)
|
|
54
|
+
│ 仅需中心管理端暴露 8443 端口,无视客户端网络环境
|
|
55
|
+
▼
|
|
56
|
+
┌────────────────────────────────────────────────────────┐
|
|
57
|
+
│ 中心控制端 (Central Hub) │
|
|
58
|
+
│ │
|
|
59
|
+
│ - 管理员在线认领锁定 (TOFU) / Token 自动化放行 │
|
|
60
|
+
│ - 借由反向长连接随时下发指令、Cookie同步、采集探针 │
|
|
61
|
+
└────────────────────────────────────────────────────────┘
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 📦 安装与调用
|
|
67
|
+
|
|
68
|
+
### 1. Python / PyPI 安装(推荐)
|
|
69
|
+
```bash
|
|
70
|
+
pip install wimotek-edge-agent
|
|
71
|
+
```
|
|
72
|
+
安装后直接获得系统全局命令 **`edge-agent`**。
|
|
73
|
+
|
|
74
|
+
### 2. Node.js / npm 免安装执行
|
|
75
|
+
```bash
|
|
76
|
+
npx wimotek-edge-agent --hub-url https://hub.yourdomain.com:8443
|
|
77
|
+
```
|
|
78
|
+
或全局安装:
|
|
79
|
+
```bash
|
|
80
|
+
npm install -g wimotek-edge-agent
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 🚀 快速上手
|
|
86
|
+
|
|
87
|
+
### 1. 命令行直接启动 (CLI)
|
|
88
|
+
```bash
|
|
89
|
+
# 最简启动 (直连模式,自动嗅探 IP 命名)
|
|
90
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443
|
|
91
|
+
|
|
92
|
+
# NAT4 穿透模式 (无公网 IP 环境)
|
|
93
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443 --reverse
|
|
94
|
+
|
|
95
|
+
# 批量免审批模式 (携带集群入网通行码)
|
|
96
|
+
edge-agent --hub-url https://hub.yourdomain.com:8443 --join-token hub_join_xxxxxx --reverse
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### 2. 环境变量一键启动(容器化最佳实践)
|
|
100
|
+
无需修改命令,直接传入环境变量:
|
|
101
|
+
```bash
|
|
102
|
+
export HUB_URL="https://hub.yourdomain.com:8443"
|
|
103
|
+
export JOIN_TOKEN="hub_join_xxxxxx" # 可选,不填走 TOFU 待认领模式
|
|
104
|
+
export REVERSE_TUNNEL="true" # 可选,默认 false;NAT4 无公网环境设为 true
|
|
105
|
+
edge-agent
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 3. Python 脚本编程式集成
|
|
109
|
+
```python
|
|
110
|
+
from wimotek_edge_agent import EdgeAgent
|
|
111
|
+
|
|
112
|
+
agent = EdgeAgent(
|
|
113
|
+
hub_url="https://hub.yourdomain.com:8443",
|
|
114
|
+
join_token="hub_join_xxxxxx", # 可选
|
|
115
|
+
node_name="Seoul-Worker-01", # 可选,留空自动按 IP 拼接
|
|
116
|
+
node_group="爬虫矩阵组", # 默认: 默认分组
|
|
117
|
+
cdp_port=9222, # 默认: 9222
|
|
118
|
+
reverse_tunnel=True # 开启 NAT4 反向长连接
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
# 启动后台代理 (阻塞运行)
|
|
122
|
+
agent.run()
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## ⚙️ 环境变量与参数字典
|
|
128
|
+
|
|
129
|
+
| 环境变量名 | CLI 参数 | 默认值 | 描述 |
|
|
130
|
+
| :--- | :--- | :--- | :--- |
|
|
131
|
+
| `HUB_URL` | `--hub-url` | *无 (必填)* | 中心管理端 HTTPS/WSS 地址,如 `https://hub.domain.com:8443` |
|
|
132
|
+
| `JOIN_TOKEN` | `--join-token` | `""` (空) | 集群入网通行码。**留空走 TOFU 后台审核认领**;填入则走 Edge Agent 自动放行入网 |
|
|
133
|
+
| `REVERSE_TUNNEL`| `--reverse` / `--direct` | `false` | 是否开启出站反向长连接隧道。**无公网 IP/NAT4 环境设为 `true`**;有公网/局域网设为 `false` |
|
|
134
|
+
| `NODE_NAME` | `--node-name` | 自动嗅探 | 节点名称。未设置时自动以出口 IP 命名(如 `Node-123.45.67.89`),兜底为主机名 |
|
|
135
|
+
| `NODE_GROUP` | `--group` | `默认分组` | 节点所属集群分组,便于多策略调度分类 |
|
|
136
|
+
| `CDP_PORT` | `--port` | `9222` | 容器本地需要中继的主服务端口(如 Chromium 调试端口) |
|
|
137
|
+
| `LOCAL_CDP_HOST`| `--cdp-host` | `127.0.0.1` | 节点本地被中继服务的绑定地址 |
|
|
138
|
+
| `SERVICES` | `--services` | *无* | 多服务端口定义,格式:`cdp:9222,vnc:6080,api:8080` |
|
|
139
|
+
| `UUID_FILE` | `--uuid-file` | `/data/node_machine.id` | 硬件指纹持久化文件路径,保障重启后身份不漂移 |
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 🐳 Docker 生产环境集成示例
|
|
144
|
+
|
|
145
|
+
### 场景 1:noVNC / Kasm 节点 Dockerfile 集成
|
|
146
|
+
在现有的浏览器镜像中,只需增加 `pip install` 即可:
|
|
147
|
+
|
|
148
|
+
```dockerfile
|
|
149
|
+
FROM debian:bookworm-slim
|
|
150
|
+
|
|
151
|
+
# 安装 Chromium、noVNC 及基础环境
|
|
152
|
+
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
153
|
+
chromium xvfb x11vnc novnc websockify python3 python3-pip curl \
|
|
154
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
155
|
+
|
|
156
|
+
# 一行安装通用边缘 Agent
|
|
157
|
+
RUN pip3 install --no-cache-dir --break-system-packages wimotek-edge-agent
|
|
158
|
+
|
|
159
|
+
COPY entrypoint.sh /app/entrypoint.sh
|
|
160
|
+
RUN chmod +x /app/entrypoint.sh
|
|
161
|
+
ENTRYPOINT ["/app/entrypoint.sh"]
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
在 `entrypoint.sh` 中只需一行后台唤起:
|
|
165
|
+
```bash
|
|
166
|
+
#!/bin/bash
|
|
167
|
+
# 启动本地服务 (如 Chromium 9222)
|
|
168
|
+
chromium --remote-debugging-port=9222 --remote-allow-origins=* &
|
|
169
|
+
|
|
170
|
+
# 只要注入了 HUB_URL,自动在后台拉起边缘代理
|
|
171
|
+
if [ -n "$HUB_URL" ]; then
|
|
172
|
+
echo "🚀 启动 wimotek-edge-agent ..."
|
|
173
|
+
edge-agent &
|
|
174
|
+
fi
|
|
175
|
+
|
|
176
|
+
wait -n
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### 场景 2:`docker-compose.yml` 极简部署
|
|
180
|
+
|
|
181
|
+
#### 无公网 IP / 家用宽带 / NAT4(开启反向长连接):
|
|
182
|
+
```yaml
|
|
183
|
+
version: '3.8'
|
|
184
|
+
|
|
185
|
+
services:
|
|
186
|
+
browser-node:
|
|
187
|
+
image: your-browser-image:latest
|
|
188
|
+
restart: unless-stopped
|
|
189
|
+
ports:
|
|
190
|
+
- "6080:6080" # 仅供内网访问桌面,公网无需暴露 9222
|
|
191
|
+
environment:
|
|
192
|
+
- HUB_URL=https://hub.yourdomain.com:8443
|
|
193
|
+
- JOIN_TOKEN=hub_join_abcdef1234567890 # 可选:留空在控制台一键点击认领
|
|
194
|
+
- REVERSE_TUNNEL=true # NAT4 穿透开关
|
|
195
|
+
- NODE_GROUP=北美爬虫矩阵组
|
|
196
|
+
volumes:
|
|
197
|
+
- ./data:/data
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
#### 拥有独立公网 IP 的云服务器(直连心跳上报):
|
|
201
|
+
```yaml
|
|
202
|
+
version: '3.8'
|
|
203
|
+
|
|
204
|
+
services:
|
|
205
|
+
browser-node:
|
|
206
|
+
image: your-browser-image:latest
|
|
207
|
+
restart: unless-stopped
|
|
208
|
+
ports:
|
|
209
|
+
- "9222:9222" # 防火墙已开放端口
|
|
210
|
+
environment:
|
|
211
|
+
- HUB_URL=https://hub.yourdomain.com:8443
|
|
212
|
+
- REVERSE_TUNNEL=false # 默认即为 false,仅发起轻量 HTTP 登记,零长连接开销
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## 🔒 安全性考量
|
|
218
|
+
|
|
219
|
+
1. **防恶意伪造(SSRF 防御)**:在直连上报模式下,管理端强制从底层 TCP 握手来源直接锁定节点的真实来源 IP,杜绝假冒内网私网地址。
|
|
220
|
+
2. **防公网扫描冒充**:未携带 `JOIN_TOKEN` 的未知连接一律进入隔离待审核队列(TOFU),未经管理端管理员后台显式认领的节点,绝不参与任何数据交互。
|
|
221
|
+
3. **安全通信**:长连接反向通道强制基于 TLS (WSS) 传输,天然防御中间人窃听与数据篡改。
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 📄 License
|
|
226
|
+
|
|
227
|
+
MIT License © 2026 [Wimotek](https://github.com/wimotek)
|
|
228
|
+
```
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
agent.py
|
|
3
|
+
pyproject.toml
|
|
4
|
+
wimotek_edge_agent.egg-info/PKG-INFO
|
|
5
|
+
wimotek_edge_agent.egg-info/SOURCES.txt
|
|
6
|
+
wimotek_edge_agent.egg-info/dependency_links.txt
|
|
7
|
+
wimotek_edge_agent.egg-info/entry_points.txt
|
|
8
|
+
wimotek_edge_agent.egg-info/requires.txt
|
|
9
|
+
wimotek_edge_agent.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
agent
|