wimotek-edge-agent 1.0.0 → 1.0.4

package/agent.py

@@ -1,14 +1,11 @@
 #!/usr/bin/env python3
 """
 Wimotek Universal Edge Agent
-A robust, decoupled, cross-platform reverse tunnel & service bridge client.
-Works on Linux, macOS, Windows, inside containers, or on bare metal without root permissions.
-
-State File Resolution Chain:
-1. Environment Variable / Explicit Param Override (UUID_FILE / STATE_FILE)
-2. Standard Designated Container Path (/data, default)
-3. User Home Directory Fallback (~/.wimotek/)
-4. System Temp Directory Extreme Fallback (/tmp/wimotek/)
+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
@@ -19,63 +16,29 @@ import uuid
 import socket
 import asyncio
 import argparse
-import tempfile
 import urllib.parse
 from pathlib import Path
-from typing import Dict, Optional, Callable, Any
+from typing import Dict, Optional, Callable
 import httpx
 
 
-def resolve_persistent_state_file(filename: str = "node_machine.id", custom_path: Optional[str] = None) -> Path:
+def resolve_state_file(filename: str = "node_machine.id", custom_path: Optional[str] = None) -> Path:
     """
-    持久化状态指纹文件解析链：
-    1. 环境变量 / 显式参数覆盖 (UUID_FILE / STATE_FILE)
-    2. 制定标准路径 /data 默认 (容器环境标准约定，存在且可写即用)
-    3. 用户目录兜底 (~/.wimotek/，跨平台桌面与普通用户环境)
-    4. 临时目录保底 (/tmp/wimotek/，极端无权限环境兜底)
+    极简文件路径解析：
+    1. 显式入参 / 环境变量 UUID_FILE
+    2. 默认 /data/<filename>
     """
-    # 1. 显式指定入参 或 环境变量覆盖
     if custom_path:
         return Path(custom_path).expanduser().resolve()
-
-    env_path = os.getenv("UUID_FILE") or os.getenv("STATE_FILE")
-    if env_path:
-        return Path(env_path).expanduser().resolve()
-
-    # 2. 制定标准路径 /data 默认 (容器内通过 -v 挂载到 /data 时自动命中)
-    container_data = Path("/data")
-    try:
-        if container_data.is_dir() and os.access(container_data, os.W_OK):
-            return container_data / filename
-    except Exception:
-        pass
-
-    # 3. 用户目录兜底 (~/.wimotek/，兼容 Linux / macOS / Windows 普通用户环境)
-    try:
-        home_dir = Path.home()
-        if home_dir and os.access(home_dir, os.W_OK):
-            state_dir = home_dir / ".wimotek"
-            state_dir.mkdir(parents=True, exist_ok=True)
-            if os.access(state_dir, os.W_OK):
-                return state_dir / filename
-    except Exception:
-        pass
-
-    # 4. 极端只读系统保底：操作系统标准临时目录 (/tmp/wimotek/)
-    tmp_dir = Path(tempfile.gettempdir()) / "wimotek"
-    try:
-        tmp_dir.mkdir(parents=True, exist_ok=True)
-        return tmp_dir / filename
-    except Exception:
-        return Path(tempfile.gettempdir()) / f"wimotek_{filename}"
+    
+    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:
-    """
-    通用边缘节点代理客户端
-    提供设备身份指纹绑定、NAT4 出站长连接穿透、以及本地任意端口服务的透明反向代理
-    """
-
     def __init__(
         self,
         hub_url: Optional[str] = None,
@@ -91,49 +54,33 @@ class EdgeAgent:
         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()
 
-        # 通用绑定主机 (优先读取通用的 TARGET_HOST/LOCAL_HOST，兼容 CDP 历史命名)
-        self.target_host = (
-            target_host
-            or os.getenv("TARGET_HOST")
-            or os.getenv("LOCAL_HOST")
-            or os.getenv("LOCAL_CDP_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("PORT")
-            or os.getenv("CDP_PORT")
-            or "9222"
-        )
+        # 端口默认 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 则开启出站反向长连接隧道
+        # 默认 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 / 主机名
+        # 节点名默认按出口 IP 或主机名拼接
         env_name = (node_name or os.getenv("NODE_NAME", "")).strip()
         self.node_name = env_name if env_name else self._auto_detect_name()
 
-        # 核心：执行三级文件解析链定位指纹文件
-        self.uuid_path = resolve_persistent_state_file("node_machine.id", custom_path=uuid_file)
+        # 极简指纹路径定位：显式指定 > /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:
@@ -142,11 +89,10 @@ class EdgeAgent:
             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):
-        """向 Agent 注册自定义业务动作回调"""
+        """注册自定义业务动作"""
         self._action_handlers[action_name] = handler
 
     def _parse_services(self) -> Dict[str, int]:
@@ -163,7 +109,6 @@ class EdgeAgent:
         return services
 
     def _auto_detect_name(self) -> str:
-        # A. 嗅探公网出口 IP
         try:
             with httpx.Client(timeout=1.5) as client:
                 res = client.get("https://api.ipify.org")
@@ -172,7 +117,6 @@ class EdgeAgent:
         except Exception:
             pass
 
-        # B. 嗅探网卡出口 IP
         try:
             s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
             s.connect(("8.8.8.8", 80))
@@ -186,20 +130,34 @@ class EdgeAgent:
         return f"Node-{socket.gethostname()[:12]}"
 
     def _load_or_create_uuid(self) -> str:
-        try:
-            if self.uuid_path.is_file():
+        """读取或创建指纹，遇无权限/目录不存在直接清晰报错输出指导"""
+        # 1. 尝试读取已有文件
+        if self.uuid_path.is_file():
+            try:
                 content = self.uuid_path.read_text().strip()
                 if content:
                     return content
-            new_id = str(uuid.uuid4())
+            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}，使用内存临时指纹。")
-            return str(uuid.uuid4())
+            print(f"❌ [目录错误] 无法保存指纹文件 ({self.uuid_path}): {e}")
+            print(f"👉 解决方案：请确认目录是否存在并具备写权限，或通过环境变量 UUID_FILE 指定有效路径。")
+
+        # 仅在严重报错时使用内存 UUID，避免脚本崩溃打断主业务
+        return new_id
 
     def run_direct_report(self):
-        """直连上报模式：轻量 HTTP 登记 + 60s 心跳"""
+        """直连上报模式：轻量 HTTP 登记 + 心跳"""
         print(f"📡 [Direct-Mode] 正在向主控中心登记: {self.http_base} ...")
         headers = {"Content-Type": "application/json"}
         if self.join_token:
@@ -253,7 +211,7 @@ class EdgeAgent:
                         if action in self._action_handlers:
                             try:
                                 handler = self._action_handlers[action]
-                                if inspect.iscoroutinefunction(handler):
+                                if asyncio.iscoroutinefunction(handler):
                                     resp_data = await handler(payload)
                                 else:
                                     resp_data = handler(payload)
@@ -261,7 +219,7 @@ class EdgeAgent:
                             except Exception as ex:
                                 await ws.send(json.dumps({"req_id": req_id, "error": str(ex)}))
 
-                        # 2. 通用透明 HTTP 服务反向中继
+                        # 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", "/")
@@ -290,7 +248,7 @@ class EdgeAgent:
                                     "error": str(ex),
                                 }))
 
-                        # 3. 通用透明 WebSocket 管道转发 (如 CDP / VNC 握手)
+                        # 3. 通用透明 WebSocket 管道转发
                         elif action == "ws_proxy":
                             port = payload.get("port") or self.services.get("default", self.target_port)
                             ws_path = payload.get("path", "")
@@ -323,12 +281,12 @@ class EdgeAgent:
                 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 '直接HTTP登记'} | 主端口: {self.target_port} | 指纹位置: {self.uuid_path}")
+        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:
@@ -344,7 +302,7 @@ def main():
     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="指纹文件存储路径 (默认按优先级推导)")
+    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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wimotek-edge-agent",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Universal Edge Tunnel Agent CLI Runner",
   "main": "index.js",
   "bin": {

package/pyproject.toml

@@ -1,18 +1,20 @@
-[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "wimotek-edge-agent"
-version = "1.0.0"
-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"
+[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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wimotek-edge-agent
-Version: 1.0.0
+Version: 1.0.4
 Summary: Universal Edge Reverse Proxy & Service Bridge Agent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown