wimotek-chromium-sync 1.0.7 → 1.0.9

package/README.md

@@ -4,95 +4,197 @@
 [![npm version](https://img.shields.io/npm/v/wimotek-chromium-sync.svg?style=flat-square)](https://www.npmjs.com/package/wimotek-chromium-sync)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
 
-专为 Chromium / Chrome 设计的通用会话与 Cookie 穿透热同步工具。
+专为 Chromium / Chrome 设计的通用会话与 Cookie 集群同步调度工具。支持 1对1 与 1对多集群、本地直连免密、SSH 私钥内容/文件与密码认证、Cookie 有效期智能融合（Merge）以及轻量静态探针。
 
-支持在本地容器与远程服务器容器之间双向热同步登录凭证（Cookie + LocalStorage），全端口可参数化自定义，内置智能流向识别与带心跳保活的 SSH 隧道自愈管理。
 ---
 
-## 🌟 核心特性
+## 🌟 核心工程特性
 
-* 全端口自由定义：本地容器端口、远程实际端口、本地隧道映射端口及 SSH 端口均可自由配置或通过环境变量覆盖。
-* 智能双向流向探测 (auto)：连通后自动探测两端 Cookie 数量与页面状态，支持智能推荐、人工交互确认或全自动执行。
-* 内置心跳保活隧道：内置 ServerAliveInterval=15 与端口占用检测，已存在则自动复用，不存在则自动拉起，绝不产生假死僵尸连接。
-* 无 TTY 环境自适应：在 Linux Crontab 定时任务、无图形后台或 CI 流程中自动回退，不因无键盘输入而崩溃。
-* 双生态支持：同时发布于 PyPI 与 npm，支持 Python 代码导入与命令行跨语言一键执行。
+1. **统一现代节点模型 (1对1 / 1对多集群)**：
+   * 原生支持任意规模的节点集群管理与多隧道并发映射。
+   * **本地节点免密直连**：配置本地端口即可直接直连 CDP 探针，跳过 SSH 隧道拉起。
 
-## 📦 安装
+2. **原生私钥内容 (PEM String) / 路径与密码认证**：
+   * `ssh_key`: 原生支持**私钥文本内容字符串**（如以 `-----BEGIN` 开头的 PEM 文本）或**私钥文件绝对路径**（如 `~/.ssh/id_rsa`），调用方无需配置繁琐的环境变量中转。
+   * `ssh_password`: 直接支持 SSH 密码认证，支持集群级默认凭证与单节点重载。
+
+3. **结构化执行指标返回 (Structured Return Dict)**：
+   * `syncer.run()` 与 `await syncer.run_async()` 执行后返回标准指标字典，上层 Web 控制台可直接捕获迁移量、源端/目标端存量、耗时及明细，无需额外发送 CDP 探针度量。
+
+4. **双驱动入口：原生异步协程 + 同步阻塞**：
+   * 原生提供 `await syncer.run_async()` 与 `await syncer.inspect_async()`，适配 FastAPI、Tornado、aiohttp 等现代异步服务。
+   * 同步环境直接调用 `syncer.run()`，开箱即用。
 
-Python 环境 (PyPI)
+5. **暴露轻量静态探针工具方法 (无需实例化集群)**：
+   * 提供单点工具函数：`ChromiumSync.get_cookies(port=9222)`、`ChromiumSync.set_cookies(cookies, port=9222)`、`ChromiumSync.probe(port=9222)`，单点探测仅需 1 行代码。
 
+6. **全节点智能 Merge 算法**：
+   * 汇总所有节点 Cookie，针对冲突项**优先保留有效期最新（expires 更长 / 最新持久凭证）的 Cookie**，并写回热刷新。
+
+---
+
+## 📦 安装
+
+### Python (PyPI)
 ```bash
 pip install wimotek-chromium-sync
+playwright install chromium
 ```
 
-Node.js 环境 (npm)
-
+### Node.js (npm)
 ```bash
-npm install wimotek-chromium-sync 
+npm install -g wimotek-chromium-sync
 ```
 
-## 🚀 极简使用示例
+---
 
-### 1. Python 代码调用（仅需 3 行）
+## 🚀 极简开发示例
 
+### 1. 轻量静态探针工具（无需实例化集群）
+单点探测某个节点时，直接 1 行静态调用：
 ```python
 from chromium_sync import ChromiumSync
 
-自由定制两端的所有端口
+# 1. 单点探测节点在线状态与页面信息
+info = ChromiumSync.probe(port=9222)
+print(info)
+# {'online': True, 'cookie_count': 42, 'page_title': 'GitHub', 'page_url': 'https://github.com', ...}
 
-syncer = ChromiumSync( remote_ssh="root@xx.xx.xx", # 远程 SSH 服务器
-remote_ssh_port=22, # SSH 连接端口
-local_cdp_port=16002, # 本地容器的 CDP 端口
-remote_cdp_port=9222, # 远程容器的实际
-CDP 端口 remote_tunnel_port=9222, # 本地用于接收隧道的端口
-direction="auto", # 智能判断: 自动往缺少凭证的一端同步
-timeout=15 # 倒计时等待秒数 (0 为秒执行) )
+# 2. 单点直接提取 Cookie 列表
+cookies = ChromiumSync.get_cookies(port=9222)
 
-syncer.run() 
+# 3. 单点直接批量写入 Cookie 并热刷新页面
+ChromiumSync.set_cookies(cookies, port=9223, reload=True)
 ```
 
-### 2. 命令行使用 (CLI 模式)
+---
 
-无论是通过 pip 安装还是 npm 安装，均可直接在终端中敲命令运行：
+### 2. 现代多节点集群同步与结构化返回
 
-```bash
+#### (1) Python 同步调用 (同步脚本 / Celery 任务)
+```python
+from chromium_sync import ChromiumSync
+
+syncer = ChromiumSync(
+    nodes=[
+        {"id": "local", "name": "本地容器", "cdp_port": 9223},
+        {
+            "id": "kr2",
+            "name": "韩国生产服",
+            "ssh_host": "kr2.wimotek.com",
+            "ssh_user": "root",
+            # 直接支持私钥文本内容 (PEM String) 或文件路径
+            "ssh_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIB...\n-----END RSA PRIVATE KEY-----",
+            "cdp_port": 9222
+        },
+        {
+            "id": "sg1",
+            "name": "新加坡服",
+            "ssh_host": "sg1.wimotek.com",
+            "ssh_user": "ubuntu",
+            # 直接支持密码认证
+            "ssh_password": "YourStrongPassword123",
+            "cdp_port": 9222
+        }
+    ],
+    mode="merge"  # "merge" (合并最新凭据) 或 "sync" (单源广播)
+)
+
+# 执行同步并获取度量指标字典
+result = syncer.run()
+print(result)
+```
+**结构化返回值示例**：
+```python
+{
+    "status": "success",          # "success" | "failed"
+    "mode": "merge",              # 执行模式
+    "transferred_count": 45,      # 实际迁移/融合生成的 Cookie 数量
+    "source_total": 80,           # 源端/融合前凭证总数
+    "target_total": 45,           # 目标端/融合后凭证总数
+    "nodes_synced": ["local", "kr2", "sg1"], # 成功同步的节点列表
+    "duration": 1.25,             # 耗时（秒）
+    "details": "全节点 Merge 成功: 融合 45 条最新凭证至 ['本地容器', '韩国生产服', '新加坡服']",
+    "error": None
+}
+```
 
-查看所有端口与流向选项
+#### (2) FastAPI / aiohttp 异步协程原生驱动
+```python
+from fastapi import FastAPI
+from chromium_sync import ChromiumSync
 
-chromium-sync --help
+app = FastAPI()
+
+@app.post("/api/sync")
+async def trigger_sync():
+    syncer = ChromiumSync(
+        nodes=[
+            {"id": "local", "cdp_port": 9222},
+            {"id": "cloud", "ssh_host": "remote.host.com", "ssh_key": "~/.ssh/id_rsa", "cdp_port": 9222}
+        ],
+        mode="merge"
+    )
+    # 原生 asyncio 协程，零线程切换开销，高并发性能极佳
+    result = await syncer.run_async()
+    return result
+```
 
-自由指定各端口全自动推送 (0 秒等待)
+---
 
-chromium-sync 
---remote-ssh root@xx.xx.xx 
---ssh-port 22 
---local-port 9222 
---tunnel-port 9222 
---direction push 
---timeout 0 
+### 3. 命令行 CLI 执行
+
+#### (1) 内联语法直接启动多节点 Merge
+```bash
+chromium-sync \
+  --node id=local,port=9223 \
+  --node id=kr2,ssh=root@kr2.wimotek.com,port=9222,key=~/.ssh/id_rsa \
+  --node id=sg1,ssh=ubuntu@sg1.wimotek.com,port=9222,pass=SecretPass123 \
+  --mode merge
 ```
 
-## ⚙️ 端口与参数对应说明
-
-| 参数名称                 | 命令行选项          | 对应环境变量                      | 默认值                    | 详细说明                 |
-| :------------------- | :------------- | :-------------------------- | :--------------------- | :------------------- |
-| remote\_ssh          | \--remote-ssh  | CHROMIUM\_REMOTE\_SSH       | <root@xx.xx.xx> | 远程 SSH 连接主机          |
-| remote\_ssh\_port    | \--ssh-port    | CHROMIUM\_SSH\_PORT         | 22                     | 远程服务器的 SSH 端口        |
-| local\_cdp\_port     | \--local-port  | CHROMIUM\_LOCAL\_PORT       | 16002                   | 运行在本机的容器 CDP 端口      |
-| remote\_cdp\_port    | \--remote-port | CHROMIUM\_REMOTE\_CDP\_PORT | 9222                   | 运行在远端服务器上的容器实际端口     |
-| remote\_tunnel\_port | \--tunnel-port | CHROMIUM\_TUNNEL\_PORT      | 9222                   | SSH 隧道映射到本机的监听端口     |
-| direction            | \--direction   | CHROMIUM\_DIRECTION         | push                   | 默认同步流向 (push 或 pull 或 auto) |
-| timeout              | \--timeout     | CHROMIUM\_TIMEOUT           | 15                      | 倒计时交互等待秒数，0 为免打扰秒执行  |
-| auto\_close\_tunnel  | \--auto-close  | \-                          | False                  | 任务完成后是否关闭创建的 SSH 隧道  |
-
-## 🤖 自动化与定时任务配置示例
-配合 Linux Crontab，每天凌晨自动将本地维护好的登录态推送到云端远程容器：
+#### (2) 仅查看节点状态与 Cookie 数量 (ASCII 表格)
 ```bash
-编辑定时任务
-crontab -e
-添加此行：每天凌晨 3:00 自动执行同步且不弹任何提示
-0 3 * * * /usr/local/bin/chromium-sync --direction push --timeout 0 --auto-close >> /tmp/chromium_sync.log 2>&1
+chromium-sync --config cluster.json --status
 ```
+输出样例：
+```text
+==========================================================================================
+节点 ID    | 节点名称       | 类型       | CDP端口/映射 | Cookie数   | 当前页面状态
+------------------------------------------------------------------------------------------
+local      | 本地容器       | 本地直连   | 9223         | 42 条      | [Google] https://google.com
+kr2        | 韩国节点       | SSH远程    | 19222        | 38 条      | [GitHub] https://github.com
+==========================================================================================
+```
+
+#### (3) 导出 Cookie 详情或执行结果为 JSON
+```bash
+# 1. 导出所有节点及 Cookie 列表为 JSON
+chromium-sync --config cluster.json --status --json > /tmp/cluster_data.json
+
+# 2. 执行同步并将结构化指标以 JSON 打印 (方便 CI/CD 或流水线捕获)
+chromium-sync --config cluster.json --mode merge --json
+```
+
+---
+
+## ⚙️ 节点参数配置规范 (NodeConfig)
+
+| 字段 | 类型 | 默认值 | 详细说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | str | 必填 | 节点唯一标识符 (例如 `local`, `kr2`) |
+| `name` | str | `id` | 节点显示名称 |
+| `is_local` | bool | 自动识别 | 是否为本地节点 (不填 `ssh_host` 或填回环地址自动判定为本地，免密直连) |
+| `cdp_host` | str | `127.0.0.1` | 节点 CDP 服务监听的主机地址 |
+| `cdp_port` | int | `9222` | 节点暴露的 CDP 端口 |
+| `ssh_host` | str | `None` | 远程服务器 IP 或主机名 (提供该字段时识别为远程 SSH 节点) |
+| `ssh_port` | int | `22` | 远程服务器 SSH 端口 |
+| `ssh_user` | str | `root` | 远程 SSH 用户名 |
+| `ssh_key` | str | `None` | **SSH 私钥 (同时支持文件绝对路径 或 私钥 PEM 文本字符串)** |
+| `ssh_password` | str | `None` | SSH 登录密码 (自动适配 `sshpass` 与原生 `SSH_ASKPASS`) |
+| `tunnel_port` | int | 自动分配 | 本地用于映射隧道的端口 (多节点自动分配防冲突) |
+
+---
 
 ## 📄 License
 

package/chromium_sync/__init__.py

@@ -1,7 +1,8 @@
 """
-Chromium Sync Package
+wimotek-chromium-sync Package
+Universal Chromium Session & Cookie Synchronizer with SSH Tunnel and Cluster Support
 """
-from .core import ChromiumSync
+from .core import ChromiumSync, NodeConfig, merge_cookies
 
-__version__ = "1.0.0"
-__all__ = ["ChromiumSync"]
+__version__ = "1.2.0"
+__all__ = ["ChromiumSync", "NodeConfig", "merge_cookies"]

package/chromium_sync/cli.py

@@ -1,33 +1,165 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+Chromium Sync CLI (现代多节点调度版)
+"""
 
 import argparse
-from .core import ChromiumSync
+import json
+import os
+import sys
+try:
+    from .core import ChromiumSync, NodeConfig
+except (ImportError, ValueError):
+    from core import ChromiumSync, NodeConfig
+
+
+def parse_node_str(val: str) -> dict:
+    """
+    解析内联节点定义参数:
+    例如:
+      --node id=local,port=9222
+      --node id=kr2,ssh=root@kr2.wimotek.com,port=9222,key=~/.ssh/id_rsa
+      --node id=sg1,ssh=ubuntu@sg1.wimotek.com,port=9222,pass=Secret123
+      --node '{"id": "local", "cdp_port": 9222}'
+    """
+    val = val.strip()
+    if val.startswith("{") and val.endswith("}"):
+        return json.loads(val)
+
+    res = {}
+    for part in val.split(","):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            k = k.strip().lower()
+            v = v.strip()
+            if k in ("port", "cdp_port"):
+                res["cdp_port"] = int(v)
+            elif k in ("ssh_port",):
+                res["ssh_port"] = int(v)
+            elif k in ("tunnel_port",):
+                res["tunnel_port"] = int(v)
+            elif k in ("local", "is_local"):
+                res["is_local"] = v.lower() in ("true", "1", "yes")
+            elif k in ("host", "cdp_host"):
+                res["cdp_host"] = v
+            elif k in ("ssh", "ssh_host"):
+                if "@" in v:
+                    user, host = v.split("@", 1)
+                    res["ssh_user"] = user
+                    res["ssh_host"] = host
+                else:
+                    res["ssh_host"] = v
+            elif k in ("user", "ssh_user"):
+                res["ssh_user"] = v
+            elif k in ("key", "ssh_key", "ssh_key_path"):
+                res["ssh_key"] = v
+            elif k in ("pass", "password", "ssh_pass", "ssh_password"):
+                res["ssh_password"] = v
+            elif k in ("id", "name"):
+                res[k] = v
+            else:
+                res[k] = v
+
+    if "id" not in res:
+        res["id"] = res.get("name") or res.get("ssh_host") or "local"
+    return res
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Chromium 一体化会话热同步工具")
-    parser.add_argument("--remote-ssh", default="root@kr2.wimotek.com", help="远程 SSH 地址")
-    parser.add_argument("--ssh-port", type=int, default=22, help="远程 SSH 端口")
-    parser.add_argument("--local-port", type=int, default=9223, help="本地容器 CDP 端口")
-    parser.add_argument("--remote-port", type=int, default=9222, help="远程容器暴露的端口")
-    parser.add_argument("--tunnel-port", type=int, default=9222, help="本地隧道端口")
-    parser.add_argument("--direction", choices=["push", "pull", "auto"], default=None, help="同步方向")
-    parser.add_argument("--timeout", type=int, default=5, help="倒计时秒数 (设为 0 即秒执行)")
-    parser.add_argument("--auto-close", action="store_true", help="任务完成后关闭 SSH 隧道")
+    parser = argparse.ArgumentParser(
+        description="现代多节点 Chromium 会话同步与 Cookie 集群调度工具",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+使用示例:
+  # 1. 快速查看节点状态与 Cookie 数量 (ASCII 表格)
+  chromium-sync --node id=local,port=9222 --node id=kr2,ssh=root@kr2.wimotek.com,port=9222,key=~/.ssh/id_rsa --status
+
+  # 2. 导出节点状态与 Cookie 详情为 JSON (便于程序直接提取 Cookie 列表)
+  chromium-sync --config cluster.json --status --json
+
+  # 3. 全节点 Cookie 智能 Merge (合并所有节点并保留最新有效期)
+  chromium-sync --config cluster.json --mode merge
+
+  # 4. 指定单源节点广播同步并输出结构化指标 JSON
+  chromium-sync --config cluster.json --mode sync --source local --json
+
+  # 5. 极简命令行多节点直接同步
+  chromium-sync \\
+    --node id=local,port=9223 \\
+    --node id=kr2,ssh=root@kr2.wimotek.com,port=9222,key=~/.ssh/id_rsa \\
+    --mode merge
+        """
+    )
+
+    # 节点输入方式
+    parser.add_argument("--config", help="集群节点配置文件路径 (JSON 格式)")
+    parser.add_argument("--node", action="append", default=[], help="定义节点 (可多次传入，如 id=local,port=9222)")
+    parser.add_argument("--nodes", help="JSON 数组格式的节点配置字符串")
+
+    # 全局默认 SSH 凭据
+    parser.add_argument("--ssh-key", help="集群默认 SSH 私钥 (支持私钥文件绝对路径 或 私钥 PEM 文本内容)")
+    parser.add_argument("--ssh-password", help="集群默认 SSH 连接密码")
+
+    # 同步模式
+    parser.add_argument("--mode", choices=["sync", "merge"], default="sync",
+                        help="同步方式: 'merge'(合并所有节点最新Cookie), 'sync'(单源广播同步，默认)")
+    parser.add_argument("--source", default=None, help="sync 模式下的源节点 ID (默认第一个节点)")
+    parser.add_argument("--targets", nargs="*", default=None, help="sync 模式下的目标节点 ID 列表 (默认其余所有节点)")
+
+    # 探测与数据查询
+    parser.add_argument("--status", action="store_true", help="仅探测并输出各节点的 Cookie 数与详情表格，不执行写入")
+    parser.add_argument("--json", action="store_true", help="以 JSON 格式输出节点数据或执行结果指标")
+
+    # 隧道与连接
+    parser.add_argument("--auto-close", action="store_true", help="任务完成后关闭拉起的 SSH 隧道")
+    parser.add_argument("-v", "--verbose", action="store_true", help="显示详细调试日志")
+
     args = parser.parse_args()
 
+    # 聚合节点配置
+    raw_nodes = []
+    if args.config:
+        if not os.path.exists(args.config):
+            sys.exit(f"[-] 配置文件不存在: {args.config}")
+        with open(args.config, "r", encoding="utf-8") as f:
+            raw_nodes.extend(json.load(f))
+
+    if args.nodes:
+        raw_nodes.extend(json.loads(args.nodes))
+
+    if args.node:
+        for n_str in args.node:
+            raw_nodes.append(parse_node_str(n_str))
+
+    # 默认兜底：若未传入任何节点参数，尝试使用标准默认本地节点
+    if not raw_nodes:
+        raw_nodes = [
+            {"id": "local", "name": "本地容器", "is_local": True, "cdp_port": 9222}
+        ]
+
     syncer = ChromiumSync(
-        remote_ssh=args.remote_ssh,
-        remote_ssh_port=args.ssh_port,
-        local_cdp_port=args.local_port,
-        remote_cdp_port=args.remote_port,
-        remote_tunnel_port=args.tunnel_port,
-        direction=args.direction or "auto",
-        timeout=args.timeout,
-        auto_close_tunnel=args.auto_close
+        nodes=raw_nodes,
+        mode=args.mode,
+        source=args.source,
+        targets=args.targets,
+        ssh_key=args.ssh_key,
+        ssh_password=args.ssh_password,
+        auto_close_tunnel=args.auto_close,
+        verbose=args.verbose
     )
-    syncer.run()
+
+    if args.status:
+        report = syncer.inspect()
+        if args.json:
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+        else:
+            print(syncer.get_summary_table(report))
+        return
+
+    result = syncer.run()
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
 
 
 if __name__ == "__main__":