wimotek-edge-agent 0.0.0-stage → 1.0.4

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
-
-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.
+# Wimotek Edge Agent (wimotek-edge-agent)
+
+[![PyPI version](https://img.shields.io/pypi/v/wimotek-edge-agent.svg?color=blue)](https://pypi.org/project/wimotek-edge-agent/)
+[![npm version](https://img.shields.io/npm/v/wimotek-edge-agent.svg?color=red)](https://www.npmjs.com/package/wimotek-edge-agent)
+[![Python Version](https://img.shields.io/pypi/pyversions/wimotek-edge-agent.svg)](https://pypi.org/project/wimotek-edge-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+轻量、通用、零侵入的边缘节点出站反向代理与服务中继客户端（Universal Edge Reverse Tunnel & Service Bridge Agent）。
+
+专为处于 **无公网 IP、NAT4、移动宽带、家用路由器或严格云防火墙** 环境下的容器（noVNC、Kasm Workspaces、Headless Chromium、自动化爬虫等）与边缘服务器设计，提供全自动设备确权、双模身份认证与本地端口透明反向穿透能力。
+
+---
+
+## 🌟 核心特性
+
+- **⚡ 出站长连接 NAT4 极速穿透**：通过单向发起 Outbound WebSocket (WSS/TLS) 长连接直达中心管理端，彻底突破多层 NAT 与企业内网防火墙，**节点无需公网 IP、无需路由器端口映射**。
+- **🛡️ 生产级双模身份认证与防伪造（TOFU + Edge Agent）**：
+  - **默认 TOFU 模式（Trust On First Use）**：零配置启动，节点自动生成硬件指纹 UUID，管理端后台实时弹出审核认领，管理员「一键信任锁定」后完成公钥防篡改绑定。
+  - **Edge Agent 模式**：批量注入 `JOIN_TOKEN`，节点开机秒级自验证入网，支持 CI/CD 与大规模集群全自动挂靠。
+- **🤖 智能命名与设备自协商**：自动探测出口公网 IP 或物理网卡 IP 智能拼接命名（如 `Node-123.45.67.89`），嗅探失败平滑降级为容器主机名。
+- **🔌 通用本地服务透明桥接（Decoupled & Multi-Service）**：业务完全解耦，不仅支持 Chromium CDP（9222），亦可同时中继 VNC 桌面（6080）、Web 业务 API（8080）等任意本地端口。
+- **🌐 跨语言分发与 CLI 驱动**：同时发布至 PyPI 与 npm，支持系统级全局命令 `edge-agent` 与 `npx wimotek-edge-agent`。
+
+---
+
+## 🏗️ 架构原理
+
+```text
+ ┌────────────────────────────────────────────────────────┐
+ │ 边缘内网节点 (家用宽带 / NAT4 / 容器无公网IP)           │
+ │                                                        │
+ │   - Chromium CDP (:9222)                               │
+ │   - noVNC 桌面 (:6080)                                 │
+ │   - 自定义业务服务 (:8080)                             │
+ └──────────────────────────┬─────────────────────────────┘
+                            ▲ 本地 127.0.0.1 访问
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │               wimotek-edge-agent 客户端                │
+ │                                                        │
+ │   职责: 硬件指纹生成 + TOFU/Token协商 + 本地服务透明中继 │
+ └──────────────────────────┬─────────────────────────────┘
+                            │
+                            │ 主动发起出站反向长连接 (Outbound TLS/WSS)
+                            │ 仅需中心管理端暴露 8443 端口，无视客户端网络环境
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │              中心控制端 (Central Hub)                  │
+ │                                                        │
+ │   - 管理员在线认领锁定 (TOFU) / Token 自动化放行       │
+ │   - 借由反向长连接随时下发指令、Cookie同步、采集探针   │
+ └────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📦 安装与调用
+
+### 1. Python / PyPI 安装（推荐）
+```bash
+pip install wimotek-edge-agent
+```
+安装后直接获得系统全局命令 **`edge-agent`**。
+
+### 2. Node.js / npm 免安装执行
+```bash
+npx wimotek-edge-agent --hub-url https://hub.yourdomain.com:8443
+```
+或全局安装：
+```bash
+npm install -g wimotek-edge-agent
+```
+
+---
+
+## 🚀 快速上手
+
+### 1. 命令行直接启动 (CLI)
+```bash
+# 最简启动 (直连模式，自动嗅探 IP 命名)
+edge-agent --hub-url https://hub.yourdomain.com:8443
+
+# NAT4 穿透模式 (无公网 IP 环境)
+edge-agent --hub-url https://hub.yourdomain.com:8443 --reverse
+
+# 批量免审批模式 (携带集群入网通行码)
+edge-agent --hub-url https://hub.yourdomain.com:8443 --join-token hub_join_xxxxxx --reverse
+```
+
+### 2. 环境变量一键启动（容器化最佳实践）
+无需修改命令，直接传入环境变量：
+```bash
+export HUB_URL="https://hub.yourdomain.com:8443"
+export JOIN_TOKEN="hub_join_xxxxxx" # 可选，不填走 TOFU 待认领模式
+export REVERSE_TUNNEL="true"        # 可选，默认 false；NAT4 无公网环境设为 true
+edge-agent
+```
+
+### 3. Python 脚本编程式集成
+```python
+from wimotek_edge_agent import EdgeAgent
+
+agent = EdgeAgent(
+    hub_url="https://hub.yourdomain.com:8443",
+    join_token="hub_join_xxxxxx",     # 可选
+    node_name="Seoul-Worker-01",      # 可选，留空自动按 IP 拼接
+    node_group="爬虫矩阵组",           # 默认: 默认分组
+    cdp_port=9222,                    # 默认: 9222
+    reverse_tunnel=True               # 开启 NAT4 反向长连接
+)
+
+# 启动后台代理 (阻塞运行)
+agent.run()
+```
+
+---
+
+## ⚙️ 环境变量与参数字典
+
+| 环境变量名 | CLI 参数 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `HUB_URL` | `--hub-url` | *无 (必填)* | 中心管理端 HTTPS/WSS 地址，如 `https://hub.domain.com:8443` |
+| `JOIN_TOKEN` | `--join-token` | `""` (空) | 集群入网通行码。**留空走 TOFU 后台审核认领**；填入则走 Edge Agent 自动放行入网 |
+| `REVERSE_TUNNEL`| `--reverse` / `--direct` | `false` | 是否开启出站反向长连接隧道。**无公网 IP/NAT4 环境设为 `true`**；有公网/局域网设为 `false` |
+| `NODE_NAME` | `--node-name` | 自动嗅探 | 节点名称。未设置时自动以出口 IP 命名（如 `Node-123.45.67.89`），兜底为主机名 |
+| `NODE_GROUP` | `--group` | `默认分组` | 节点所属集群分组，便于多策略调度分类 |
+| `CDP_PORT` | `--port` | `9222` | 容器本地需要中继的主服务端口（如 Chromium 调试端口） |
+| `LOCAL_CDP_HOST`| `--cdp-host` | `127.0.0.1` | 节点本地被中继服务的绑定地址 |
+| `SERVICES` | `--services` | *无* | 多服务端口定义，格式：`cdp:9222,vnc:6080,api:8080` |
+| `UUID_FILE` | `--uuid-file` | `/data/node_machine.id` | 硬件指纹持久化文件路径，保障重启后身份不漂移 |
+
+---
+
+## 🐳 Docker 生产环境集成示例
+
+### 场景 1：noVNC / Kasm 节点 Dockerfile 集成
+在现有的浏览器镜像中，只需增加 `pip install` 即可：
+
+```dockerfile
+FROM debian:bookworm-slim
+
+# 安装 Chromium、noVNC 及基础环境
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    chromium xvfb x11vnc novnc websockify python3 python3-pip curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 一行安装通用边缘 Agent
+RUN pip3 install --no-cache-dir --break-system-packages wimotek-edge-agent
+
+COPY entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+ENTRYPOINT ["/app/entrypoint.sh"]
+```
+
+在 `entrypoint.sh` 中只需一行后台唤起：
+```bash
+#!/bin/bash
+# 启动本地服务 (如 Chromium 9222)
+chromium --remote-debugging-port=9222 --remote-allow-origins=* &
+
+# 只要注入了 HUB_URL，自动在后台拉起边缘代理
+if [ -n "$HUB_URL" ]; then
+    echo "🚀 启动 wimotek-edge-agent ..."
+    edge-agent &
+fi
+
+wait -n
+```
+
+### 场景 2：`docker-compose.yml` 极简部署
+
+#### 无公网 IP / 家用宽带 / NAT4（开启反向长连接）：
+```yaml
+version: '3.8'
+
+services:
+  browser-node:
+    image: your-browser-image:latest
+    restart: unless-stopped
+    ports:
+      - "6080:6080"  # 仅供内网访问桌面，公网无需暴露 9222
+    environment:
+      - HUB_URL=https://hub.yourdomain.com:8443
+      - JOIN_TOKEN=hub_join_abcdef1234567890   # 可选：留空在控制台一键点击认领
+      - REVERSE_TUNNEL=true                    # NAT4 穿透开关
+      - NODE_GROUP=北美爬虫矩阵组
+    volumes:
+      - ./data:/data
+```
+
+#### 拥有独立公网 IP 的云服务器（直连心跳上报）：
+```yaml
+version: '3.8'
+
+services:
+  browser-node:
+    image: your-browser-image:latest
+    restart: unless-stopped
+    ports:
+      - "9222:9222"  # 防火墙已开放端口
+    environment:
+      - HUB_URL=https://hub.yourdomain.com:8443
+      - REVERSE_TUNNEL=false  # 默认即为 false，仅发起轻量 HTTP 登记，零长连接开销
+```
+
+---
+
+## 🔒 安全性考量
+
+1. **防恶意伪造（SSRF 防御）**：在直连上报模式下，管理端强制从底层 TCP 握手来源直接锁定节点的真实来源 IP，杜绝假冒内网私网地址。
+2. **防公网扫描冒充**：未携带 `JOIN_TOKEN` 的未知连接一律进入隔离待审核队列（TOFU），未经管理端管理员后台显式认领的节点，绝不参与任何数据交互。
+3. **安全通信**：长连接反向通道强制基于 TLS (WSS) 传输，天然防御中间人窃听与数据篡改。
+
+---
+
+## 📄 License
+
+MIT License © 2026 [Wimotek](https://github.com/wimotek)
+```

package/agent.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""
+Wimotek Universal Edge Agent
+A lightweight, clean reverse tunnel & service bridge client.
+
+State File Logic:
+- User specified path (param / UUID_FILE env) > Default (/data/node_machine.id)
+- If permission denied, logs clear error instructions for the user to resolve.
+"""
+
+import os
+import sys
+import time
+import json
+import uuid
+import socket
+import asyncio
+import argparse
+import urllib.parse
+from pathlib import Path
+from typing import Dict, Optional, Callable
+import httpx
+
+
+def resolve_state_file(filename: str = "node_machine.id", custom_path: Optional[str] = None) -> Path:
+    """
+    极简文件路径解析：
+    1. 显式入参 / 环境变量 UUID_FILE
+    2. 默认 /data/<filename>
+    """
+    if custom_path:
+        return Path(custom_path).expanduser().resolve()
+    
+    env_override = os.getenv("UUID_FILE") or os.getenv("STATE_FILE")
+    if env_override:
+        return Path(env_override).expanduser().resolve()
+    
+    return Path("/data") / filename
+
+
+class EdgeAgent:
+    def __init__(
+        self,
+        hub_url: Optional[str] = None,
+        join_token: Optional[str] = None,
+        node_name: Optional[str] = None,
+        node_group: Optional[str] = None,
+        target_port: Optional[int] = None,
+        target_host: Optional[str] = None,
+        services: Optional[Dict[str, int]] = None,
+        reverse_tunnel: Optional[bool] = None,
+        uuid_file: Optional[str] = None,
+    ):
+        self.hub_url = (hub_url or os.getenv("HUB_URL", "")).rstrip("/")
+        self.join_token = (join_token or os.getenv("JOIN_TOKEN", "")).strip()
+        self.node_group = (node_group or os.getenv("NODE_GROUP", "默认分组")).strip()
+        self.target_host = (target_host or os.getenv("TARGET_HOST") or os.getenv("LOCAL_HOST") or "127.0.0.1").strip()
+
+        # 端口默认 9222
+        raw_port = target_port if target_port is not None else (os.getenv("TARGET_PORT") or os.getenv("CDP_PORT") or "9222")
+        try:
+            self.target_port = int(raw_port)
+        except ValueError:
+            self.target_port = 9222
+
+        self.services: Dict[str, int] = services or self._parse_services()
+        self.services["default"] = self.target_port
+
+        # 默认 false (直连上报)，显式为 true 时走反向隧道
+        if reverse_tunnel is not None:
+            self.reverse_tunnel = bool(reverse_tunnel)
+        else:
+            self.reverse_tunnel = os.getenv("REVERSE_TUNNEL", "false").lower() in ["true", "1", "yes"]
+
+        # 节点名默认按出口 IP 或主机名拼接
+        env_name = (node_name or os.getenv("NODE_NAME", "")).strip()
+        self.node_name = env_name if env_name else self._auto_detect_name()
+
+        # 极简指纹路径定位：显式指定 > /data/node_machine.id
+        self.uuid_path = resolve_state_file("node_machine.id", custom_path=uuid_file)
+        self.node_uuid = self._load_or_create_uuid()
+
+        # 通信协议端点解析
+        self.http_base = ""
+        self.ws_base = ""
+        if self.hub_url:
+            parsed = urllib.parse.urlparse(self.hub_url)
+            self.http_base = f"{parsed.scheme}://{parsed.netloc}"
+            ws_scheme = "wss" if parsed.scheme == "https" else "ws"
+            self.ws_base = f"{ws_scheme}://{parsed.netloc}"
+
+        self._action_handlers: Dict[str, Callable] = {}
+
+    def register_action(self, action_name: str, handler: Callable):
+        """注册自定义业务动作"""
+        self._action_handlers[action_name] = handler
+
+    def _parse_services(self) -> Dict[str, int]:
+        services = {}
+        raw = os.getenv("SERVICES", "").strip()
+        if raw:
+            for item in raw.split(","):
+                if ":" in item:
+                    name, p = item.split(":", 1)
+                    try:
+                        services[name.strip()] = int(p.strip())
+                    except ValueError:
+                        pass
+        return services
+
+    def _auto_detect_name(self) -> str:
+        try:
+            with httpx.Client(timeout=1.5) as client:
+                res = client.get("https://api.ipify.org")
+                if res.status_code == 200 and res.text.strip():
+                    return f"Node-{res.text.strip()}"
+        except Exception:
+            pass
+
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            s.connect(("8.8.8.8", 80))
+            ip = s.getsockname()[0]
+            s.close()
+            if ip and ip != "127.0.0.1":
+                return f"Node-{ip}"
+        except Exception:
+            pass
+
+        return f"Node-{socket.gethostname()[:12]}"
+
+    def _load_or_create_uuid(self) -> str:
+        """读取或创建指纹，遇无权限/目录不存在直接清晰报错输出指导"""
+        # 1. 尝试读取已有文件
+        if self.uuid_path.is_file():
+            try:
+                content = self.uuid_path.read_text().strip()
+                if content:
+                    return content
+            except Exception as e:
+                print(f"⚠️ [指纹读取失败] 无法读取已有指纹文件 ({self.uuid_path}): {e}")
+
+        # 2. 首次写入持久化
+        new_id = str(uuid.uuid4())
+        try:
+            self.uuid_path.parent.mkdir(parents=True, exist_ok=True)
+            self.uuid_path.write_text(new_id)
+            return new_id
+        except PermissionError:
+            print(f"❌ [权限错误] 无权限写入指纹文件: {self.uuid_path}")
+            print(f"👉 解决方案：请检查容器挂载目录写权限，或指定环境变量 UUID_FILE 改为可写路径，例如: -e UUID_FILE=/my_path/{self.uuid_path.name}")
+        except Exception as e:
+            print(f"❌ [目录错误] 无法保存指纹文件 ({self.uuid_path}): {e}")
+            print(f"👉 解决方案：请确认目录是否存在并具备写权限，或通过环境变量 UUID_FILE 指定有效路径。")
+
+        # 仅在严重报错时使用内存 UUID，避免脚本崩溃打断主业务
+        return new_id
+
+    def run_direct_report(self):
+        """直连上报模式：轻量 HTTP 登记 + 心跳"""
+        print(f"📡 [Direct-Mode] 正在向主控中心登记: {self.http_base} ...")
+        headers = {"Content-Type": "application/json"}
+        if self.join_token:
+            headers["X-Join-Token"] = self.join_token
+
+        payload = {
+            "node_uuid": self.node_uuid,
+            "name": self.node_name,
+            "group_name": self.node_group,
+            "cdp_port": self.target_port,
+            "services": self.services,
+        }
+
+        while True:
+            try:
+                with httpx.Client(timeout=10.0, verify=False) as client:
+                    res = client.post(f"{self.http_base}/api/nodes/auto-register", json=payload, headers=headers)
+                    print(f"✅ [{time.strftime('%X')}] 节点上报/心跳成功: {res.text}")
+            except Exception as e:
+                print(f"⚠️ [{time.strftime('%X')}] 上报失败，60秒后重试: {e}")
+            time.sleep(60)
+
+    async def run_reverse_tunnel(self):
+        """反向长连接隧道模式：全双工出站连接穿透 NAT4"""
+        import websockets
+
+        params = urllib.parse.urlencode({
+            "uuid": self.node_uuid,
+            "name": self.node_name,
+            "group": self.node_group,
+            "token": self.join_token,
+            "port": self.target_port,
+        })
+        ws_endpoint = f"{self.ws_base}/api/nodes/reverse-tunnel?{params}"
+        is_ssl = self.ws_base.startswith("wss://")
+
+        while True:
+            try:
+                print(f"📡 [Tunnel-Mode] 正在建立反向长连接 -> {self.hub_url} ...")
+                async with websockets.connect(ws_endpoint, timeout=10.0, ssl=False if not is_ssl else None) as ws:
+                    print(f"✅ [Tunnel-Connected] 隧道就绪！指纹存储于: {self.uuid_path}")
+
+                    while True:
+                        msg_text = await ws.recv()
+                        req = json.loads(msg_text)
+                        req_id = req.get("req_id")
+                        action = req.get("action", "http_proxy")
+                        payload = req.get("payload", {})
+
+                        # 1. 自定义扩展指令
+                        if action in self._action_handlers:
+                            try:
+                                handler = self._action_handlers[action]
+                                if asyncio.iscoroutinefunction(handler):
+                                    resp_data = await handler(payload)
+                                else:
+                                    resp_data = handler(payload)
+                                await ws.send(json.dumps({"req_id": req_id, "data": resp_data}))
+                            except Exception as ex:
+                                await ws.send(json.dumps({"req_id": req_id, "error": str(ex)}))
+
+                        # 2. 通用透明 HTTP 反向中继
+                        elif action in ["http_proxy", "service_proxy"]:
+                            port = payload.get("port") or self.services.get(payload.get("service", "default"), self.target_port)
+                            path = payload.get("path", "/")
+                            method = payload.get("method", "GET")
+                            body = payload.get("body")
+                            headers = payload.get("headers", {})
+
+                            try:
+                                async with httpx.AsyncClient(timeout=15.0) as client:
+                                    resp = await client.request(
+                                        method=method,
+                                        url=f"http://{self.target_host}:{port}{path}",
+                                        headers=headers,
+                                        content=body,
+                                    )
+                                await ws.send(json.dumps({
+                                    "req_id": req_id,
+                                    "status_code": resp.status_code,
+                                    "headers": dict(resp.headers),
+                                    "body": resp.text,
+                                }))
+                            except Exception as ex:
+                                await ws.send(json.dumps({
+                                    "req_id": req_id,
+                                    "status_code": 502,
+                                    "error": str(ex),
+                                }))
+
+                        # 3. 通用透明 WebSocket 管道转发
+                        elif action == "ws_proxy":
+                            port = payload.get("port") or self.services.get("default", self.target_port)
+                            ws_path = payload.get("path", "")
+                            local_ws_url = f"ws://{self.target_host}:{port}{ws_path}"
+                            send_data = payload.get("data")
+
+                            try:
+                                async with websockets.connect(local_ws_url, timeout=5.0) as local_ws:
+                                    if send_data:
+                                        await local_ws.send(send_data)
+                                    reply = await local_ws.recv()
+                                await ws.send(json.dumps({
+                                    "req_id": req_id,
+                                    "success": True,
+                                    "data": reply,
+                                }))
+                            except Exception as ex:
+                                await ws.send(json.dumps({
+                                    "req_id": req_id,
+                                    "success": False,
+                                    "error": str(ex),
+                                }))
+
+                        # 4. 心跳响应
+                        elif action == "ping":
+                            await ws.send(json.dumps({"req_id": req_id, "action": "pong", "time": time.time()}))
+
+            except (websockets.ConnectionClosed, Exception) as e:
+                print(f"⚠️ 反向连接断开，5秒后自动重连: {e}")
+                await asyncio.sleep(5)
+
+    def run(self):
+        """运行入口"""
+        if not self.hub_url:
+            print("ℹ️ 未配置 HUB_URL，Agent 停止运行。")
+            return
+
+        print(f"🚀 [Edge-Agent] 启动节点: {self.node_name} | 模式: {'反向穿透(NAT4)' if self.reverse_tunnel else '直连上报'} | 主端口: {self.target_port} | 指纹位置: {self.uuid_path}")
+        if self.reverse_tunnel:
+            asyncio.run(self.run_reverse_tunnel())
+        else:
+            self.run_direct_report()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Wimotek Universal Edge Agent")
+    parser.add_argument("--hub-url", type=str, help="中心管理端 URL (如 https://hub.domain.com:8443)")
+    parser.add_argument("--join-token", type=str, help="入网认证 Token (可选)")
+    parser.add_argument("--node-name", type=str, help="节点名称 (默认自动嗅探 IP)")
+    parser.add_argument("--group", type=str, help="所属集群分组")
+    parser.add_argument("--port", type=int, help="要代理的主端口 (默认: 9222)")
+    parser.add_argument("--host", type=str, help="本地服务绑定地址 (默认: 127.0.0.1)")
+    parser.add_argument("--services", type=str, help="多端口代理定义, 如: cdp:9222,vnc:6080")
+    parser.add_argument("--state-file", type=str, help="指纹文件存储路径 (默认: /data/node_machine.id)")
+    parser.add_argument("--reverse", action="store_true", help="强制开启出站反向长连接隧道")
+    parser.add_argument("--direct", action="store_true", help="强制开启直连上报心跳模式")
+    args = parser.parse_args()
+
+    rev_mode = None
+    if args.reverse:
+        rev_mode = True
+    elif args.direct:
+        rev_mode = False
+
+    agent = EdgeAgent(
+        hub_url=args.hub_url,
+        join_token=args.join_token,
+        node_name=args.node_name,
+        node_group=args.group,
+        target_port=args.port,
+        target_host=args.host,
+        reverse_tunnel=rev_mode,
+        uuid_file=args.state_file,
+    )
+    agent.run()
+
+
+if __name__ == "__main__":
+    main()

package/bin/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+
+const args = ['-m', 'wimotek_edge_agent.agent', ...process.argv.slice(2)];
+const py = spawn('python3', args, { stdio: 'inherit', env: process.env });
+
+py.on('error', () => {
+  console.error('❌ 请确保宿主机已安装 Python 3 和 wimotek-edge-agent: pip install wimotek-edge-agent');
+  process.exit(1);
+});
+
+py.on('close', (code) => {
+  process.exit(code);
+});

package/package.json

@@ -1,6 +1,19 @@
-{
-  "name": "wimotek-edge-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "wimotek-edge-agent",
+  "version": "1.0.4",
+  "description": "Universal Edge Tunnel Agent CLI Runner",
+  "main": "index.js",
+  "bin": {
+    "edge-agent": "./bin/cli.js"
+  },
+  "keywords": [
+    "edge",
+    "agent",
+    "tunnel",
+    "reverse-proxy",
+    "cdp",
+    "vnc"
+  ],
+  "author": "wimotek",
+  "license": "MIT"
+}

package/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = [
+    "setuptools>=61.0",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wimotek-edge-agent"
+version = "1.0.4"
+description = "Universal Edge Reverse Proxy & Service Bridge Agent"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.24.0",
+    "websockets>=11.0",
+]
+
+[project.scripts]
+edge-agent = "wimotek_edge_agent.agent:main"
+wimotek-agent = "wimotek_edge_agent.agent:main"

package/wimotek_edge_agent.egg-info/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: wimotek-edge-agent
+Version: 1.0.4
+Summary: Universal Edge Reverse Proxy & Service Bridge Agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: websockets>=11.0
+
+# Wimotek Edge Agent (wimotek-edge-agent)
+
+[![PyPI version](https://img.shields.io/pypi/v/wimotek-edge-agent.svg?color=blue)](https://pypi.org/project/wimotek-edge-agent/)
+[![npm version](https://img.shields.io/npm/v/wimotek-edge-agent.svg?color=red)](https://www.npmjs.com/package/wimotek-edge-agent)
+[![Python Version](https://img.shields.io/pypi/pyversions/wimotek-edge-agent.svg)](https://pypi.org/project/wimotek-edge-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+轻量、通用、零侵入的边缘节点出站反向代理与服务中继客户端（Universal Edge Reverse Tunnel & Service Bridge Agent）。
+
+专为处于 **无公网 IP、NAT4、移动宽带、家用路由器或严格云防火墙** 环境下的容器（noVNC、Kasm Workspaces、Headless Chromium、自动化爬虫等）与边缘服务器设计，提供全自动设备确权、双模身份认证与本地端口透明反向穿透能力。
+
+---
+
+## 🌟 核心特性
+
+- **⚡ 出站长连接 NAT4 极速穿透**：通过单向发起 Outbound WebSocket (WSS/TLS) 长连接直达中心管理端，彻底突破多层 NAT 与企业内网防火墙，**节点无需公网 IP、无需路由器端口映射**。
+- **🛡️ 生产级双模身份认证与防伪造（TOFU + Edge Agent）**：
+  - **默认 TOFU 模式（Trust On First Use）**：零配置启动，节点自动生成硬件指纹 UUID，管理端后台实时弹出审核认领，管理员「一键信任锁定」后完成公钥防篡改绑定。
+  - **Edge Agent 模式**：批量注入 `JOIN_TOKEN`，节点开机秒级自验证入网，支持 CI/CD 与大规模集群全自动挂靠。
+- **🤖 智能命名与设备自协商**：自动探测出口公网 IP 或物理网卡 IP 智能拼接命名（如 `Node-123.45.67.89`），嗅探失败平滑降级为容器主机名。
+- **🔌 通用本地服务透明桥接（Decoupled & Multi-Service）**：业务完全解耦，不仅支持 Chromium CDP（9222），亦可同时中继 VNC 桌面（6080）、Web 业务 API（8080）等任意本地端口。
+- **🌐 跨语言分发与 CLI 驱动**：同时发布至 PyPI 与 npm，支持系统级全局命令 `edge-agent` 与 `npx wimotek-edge-agent`。
+
+---
+
+## 🏗️ 架构原理
+
+```text
+ ┌────────────────────────────────────────────────────────┐
+ │ 边缘内网节点 (家用宽带 / NAT4 / 容器无公网IP)           │
+ │                                                        │
+ │   - Chromium CDP (:9222)                               │
+ │   - noVNC 桌面 (:6080)                                 │
+ │   - 自定义业务服务 (:8080)                             │
+ └──────────────────────────┬─────────────────────────────┘
+                            ▲ 本地 127.0.0.1 访问
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │               wimotek-edge-agent 客户端                │
+ │                                                        │
+ │   职责: 硬件指纹生成 + TOFU/Token协商 + 本地服务透明中继 │
+ └──────────────────────────┬─────────────────────────────┘
+                            │
+                            │ 主动发起出站反向长连接 (Outbound TLS/WSS)
+                            │ 仅需中心管理端暴露 8443 端口，无视客户端网络环境
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │              中心控制端 (Central Hub)                  │
+ │                                                        │
+ │   - 管理员在线认领锁定 (TOFU) / Token 自动化放行       │
+ │   - 借由反向长连接随时下发指令、Cookie同步、采集探针   │
+ └────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📦 安装与调用
+
+### 1. Python / PyPI 安装（推荐）
+```bash
+pip install wimotek-edge-agent
+```
+安装后直接获得系统全局命令 **`edge-agent`**。
+
+### 2. Node.js / npm 免安装执行
+```bash
+npx wimotek-edge-agent --hub-url https://hub.yourdomain.com:8443
+```
+或全局安装：
+```bash
+npm install -g wimotek-edge-agent
+```
+
+---
+
+## 🚀 快速上手
+
+### 1. 命令行直接启动 (CLI)
+```bash
+# 最简启动 (直连模式，自动嗅探 IP 命名)
+edge-agent --hub-url https://hub.yourdomain.com:8443
+
+# NAT4 穿透模式 (无公网 IP 环境)
+edge-agent --hub-url https://hub.yourdomain.com:8443 --reverse
+
+# 批量免审批模式 (携带集群入网通行码)
+edge-agent --hub-url https://hub.yourdomain.com:8443 --join-token hub_join_xxxxxx --reverse
+```
+
+### 2. 环境变量一键启动（容器化最佳实践）
+无需修改命令，直接传入环境变量：
+```bash
+export HUB_URL="https://hub.yourdomain.com:8443"
+export JOIN_TOKEN="hub_join_xxxxxx" # 可选，不填走 TOFU 待认领模式
+export REVERSE_TUNNEL="true"        # 可选，默认 false；NAT4 无公网环境设为 true
+edge-agent
+```
+
+### 3. Python 脚本编程式集成
+```python
+from wimotek_edge_agent import EdgeAgent
+
+agent = EdgeAgent(
+    hub_url="https://hub.yourdomain.com:8443",
+    join_token="hub_join_xxxxxx",     # 可选
+    node_name="Seoul-Worker-01",      # 可选，留空自动按 IP 拼接
+    node_group="爬虫矩阵组",           # 默认: 默认分组
+    cdp_port=9222,                    # 默认: 9222
+    reverse_tunnel=True               # 开启 NAT4 反向长连接
+)
+
+# 启动后台代理 (阻塞运行)
+agent.run()
+```
+
+---
+
+## ⚙️ 环境变量与参数字典
+
+| 环境变量名 | CLI 参数 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `HUB_URL` | `--hub-url` | *无 (必填)* | 中心管理端 HTTPS/WSS 地址，如 `https://hub.domain.com:8443` |
+| `JOIN_TOKEN` | `--join-token` | `""` (空) | 集群入网通行码。**留空走 TOFU 后台审核认领**；填入则走 Edge Agent 自动放行入网 |
+| `REVERSE_TUNNEL`| `--reverse` / `--direct` | `false` | 是否开启出站反向长连接隧道。**无公网 IP/NAT4 环境设为 `true`**；有公网/局域网设为 `false` |
+| `NODE_NAME` | `--node-name` | 自动嗅探 | 节点名称。未设置时自动以出口 IP 命名（如 `Node-123.45.67.89`），兜底为主机名 |
+| `NODE_GROUP` | `--group` | `默认分组` | 节点所属集群分组，便于多策略调度分类 |
+| `CDP_PORT` | `--port` | `9222` | 容器本地需要中继的主服务端口（如 Chromium 调试端口） |
+| `LOCAL_CDP_HOST`| `--cdp-host` | `127.0.0.1` | 节点本地被中继服务的绑定地址 |
+| `SERVICES` | `--services` | *无* | 多服务端口定义，格式：`cdp:9222,vnc:6080,api:8080` |
+| `UUID_FILE` | `--uuid-file` | `/data/node_machine.id` | 硬件指纹持久化文件路径，保障重启后身份不漂移 |
+
+---
+
+## 🐳 Docker 生产环境集成示例
+
+### 场景 1：noVNC / Kasm 节点 Dockerfile 集成
+在现有的浏览器镜像中，只需增加 `pip install` 即可：
+
+```dockerfile
+FROM debian:bookworm-slim
+
+# 安装 Chromium、noVNC 及基础环境
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    chromium xvfb x11vnc novnc websockify python3 python3-pip curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 一行安装通用边缘 Agent
+RUN pip3 install --no-cache-dir --break-system-packages wimotek-edge-agent
+
+COPY entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+ENTRYPOINT ["/app/entrypoint.sh"]
+```
+
+在 `entrypoint.sh` 中只需一行后台唤起：
+```bash
+#!/bin/bash
+# 启动本地服务 (如 Chromium 9222)
+chromium --remote-debugging-port=9222 --remote-allow-origins=* &
+
+# 只要注入了 HUB_URL，自动在后台拉起边缘代理
+if [ -n "$HUB_URL" ]; then
+    echo "🚀 启动 wimotek-edge-agent ..."
+    edge-agent &
+fi
+
+wait -n
+```
+
+### 场景 2：`docker-compose.yml` 极简部署
+
+#### 无公网 IP / 家用宽带 / NAT4（开启反向长连接）：
+```yaml
+version: '3.8'
+
+services:
+  browser-node:
+    image: your-browser-image:latest
+    restart: unless-stopped
+    ports:
+      - "6080:6080"  # 仅供内网访问桌面，公网无需暴露 9222
+    environment:
+      - HUB_URL=https://hub.yourdomain.com:8443
+      - JOIN_TOKEN=hub_join_abcdef1234567890   # 可选：留空在控制台一键点击认领
+      - REVERSE_TUNNEL=true                    # NAT4 穿透开关
+      - NODE_GROUP=北美爬虫矩阵组
+    volumes:
+      - ./data:/data
+```
+
+#### 拥有独立公网 IP 的云服务器（直连心跳上报）：
+```yaml
+version: '3.8'
+
+services:
+  browser-node:
+    image: your-browser-image:latest
+    restart: unless-stopped
+    ports:
+      - "9222:9222"  # 防火墙已开放端口
+    environment:
+      - HUB_URL=https://hub.yourdomain.com:8443
+      - REVERSE_TUNNEL=false  # 默认即为 false，仅发起轻量 HTTP 登记，零长连接开销
+```
+
+---
+
+## 🔒 安全性考量
+
+1. **防恶意伪造（SSRF 防御）**：在直连上报模式下，管理端强制从底层 TCP 握手来源直接锁定节点的真实来源 IP，杜绝假冒内网私网地址。
+2. **防公网扫描冒充**：未携带 `JOIN_TOKEN` 的未知连接一律进入隔离待审核队列（TOFU），未经管理端管理员后台显式认领的节点，绝不参与任何数据交互。
+3. **安全通信**：长连接反向通道强制基于 TLS (WSS) 传输，天然防御中间人窃听与数据篡改。
+
+---
+
+## 📄 License
+
+MIT License © 2026 [Wimotek](https://github.com/wimotek)
+```

package/wimotek_edge_agent.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+agent.py
+pyproject.toml
+wimotek_edge_agent.egg-info/PKG-INFO
+wimotek_edge_agent.egg-info/SOURCES.txt
+wimotek_edge_agent.egg-info/dependency_links.txt
+wimotek_edge_agent.egg-info/entry_points.txt
+wimotek_edge_agent.egg-info/requires.txt
+wimotek_edge_agent.egg-info/top_level.txt

package/wimotek_edge_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

package/wimotek_edge_agent.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+edge-agent = wimotek_edge_agent.agent:main
+wimotek-agent = wimotek_edge_agent.agent:main

package/wimotek_edge_agent.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.24.0
+websockets>=11.0

package/wimotek_edge_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent