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 CHANGED
@@ -1,3 +1,219 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # Wimotek Edge Agent (wimotek-edge-agent)
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/wimotek-edge-agent.svg?color=blue)](https://pypi.org/project/wimotek-edge-agent/)
4
+ [![npm version](https://img.shields.io/npm/v/wimotek-edge-agent.svg?color=red)](https://www.npmjs.com/package/wimotek-edge-agent)
5
+ [![Python Version](https://img.shields.io/pypi/pyversions/wimotek-edge-agent.svg)](https://pypi.org/project/wimotek-edge-agent/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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
+ });
package/package.json CHANGED
@@ -1,6 +1,19 @@
1
- {
2
- "name": "wimotek-edge-agent",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ [![PyPI version](https://img.shields.io/pypi/v/wimotek-edge-agent.svg?color=blue)](https://pypi.org/project/wimotek-edge-agent/)
13
+ [![npm version](https://img.shields.io/npm/v/wimotek-edge-agent.svg?color=red)](https://www.npmjs.com/package/wimotek-edge-agent)
14
+ [![Python Version](https://img.shields.io/pypi/pyversions/wimotek-edge-agent.svg)](https://pypi.org/project/wimotek-edge-agent/)
15
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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,3 @@
1
+ [console_scripts]
2
+ edge-agent = wimotek_edge_agent.agent:main
3
+ wimotek-agent = wimotek_edge_agent.agent:main
@@ -0,0 +1,2 @@
1
+ httpx>=0.24.0
2
+ websockets>=11.0
@@ -0,0 +1 @@
1
+ agent