@mtop-devtools/cloud-connector

@mtop-devtools/cloud-connector

本地连接器，用于将本地的 native-host 通过 WebSocket 连接到云端 Server。

安装

npm install -g @mtop-devtools/cloud-connector
# 或
pnpm add -g @mtop-devtools/cloud-connector

两种管理模式

连接器同时支持两种生命周期管理方式，二者通过同一份共享注册表互通（见运行时文件），不会对同一个 server-url 重复建连：

1. 被 native-host 托管 —— 在浏览器插件面板里点击连接时，native-host 会自动以前台进程方式拉起连接器并监听其状态。无需手动操作。
2. 自管理（守护进程） —— 在终端用 start / stop 等子命令把连接器作为后台守护进程管理，拥有独立日志文件，便于在无插件面板的场景（如远程机器、排查问题）下使用。

使用

mtop-devtools-cloud-connector <server-url> [options]            # 前台运行
mtop-devtools-cloud-connector <command> [server-url] [options]  # 管理后台守护进程

参数：

• server-url —— 云端 WebSocket Server 地址（包含 token，如 ws://host:port/ws?token=xxx）

子命令：

• start <server-url> —— 后台启动守护进程（幂等：已有存活连接器则复用）
• stop <server-url> —— 停止指定 server-url 的后台连接器
• stop --all —— 停止所有后台连接器
• restart <server-url> —— 重启指定连接器
• status [server-url] —— 查看某连接器状态；省略 server-url 时列出全部
• list —— 列出所有正在运行的连接器
• logs <server-url> —— 打印某连接器日志末尾

选项：

• --foreground / -f —— 前台运行（不守护化）
• --heartbeat <seconds> —— 心跳间隔（默认 30 秒）
• --reconnect <ms> —— 重连间隔（默认 5000 毫秒）
• --max-reconnect <n> —— 最大重连次数，-1 表示无限（默认 -1）
• --fail-fast —— 首次连接失败即退出（供 native-host 探测启动结果）

示例：

# 前台运行（Ctrl+C 停止）—— 也是 native-host 拉起连接器的方式
mtop-devtools-cloud-connector "ws://localhost:8080/ws?token=xxx"

# 后台启动一个自管理连接器，拥有独立日志文件
mtop-devtools-cloud-connector start "wss://cloud.example.com/ws?token=xxx"

# 查看状态 / 列表 / 日志
mtop-devtools-cloud-connector status
mtop-devtools-cloud-connector list
mtop-devtools-cloud-connector logs "wss://cloud.example.com/ws?token=xxx"

# 停止
mtop-devtools-cloud-connector stop "wss://cloud.example.com/ws?token=xxx"
mtop-devtools-cloud-connector stop --all

# 自定义心跳和重连配置
mtop-devtools-cloud-connector "ws://localhost:8080/ws?token=xxx" --heartbeat 60 --max-reconnect 10

编程方式

import { CloudConnector } from '@mtop-devtools/cloud-connector';

const connector = new CloudConnector({
  serverUrl: 'wss://cloud.example.com/ws?token=xxx',
  heartbeatInterval: 30,
  reconnectInterval: 5000,
  maxReconnectAttempts: -1,
  onConnected: url => console.log('connected to', url),
});

connector.connect();

// 优雅关闭
process.on('SIGINT', () => {
  connector.disconnect();
  process.exit(0);
});

运行时文件

每个连接器实例在 ~/.mtop-devtools/connectors/ 下按 server-url 哈希生成一对文件：

• <hash>.json —— 连接记录（含 serverUrl、pid、startedAt）。连接器进程是该记录的唯一写入方：连上时写入、优雅退出时删除（崩溃残留的记录会被读取方按 pid 存活性自动清理）。
• <hash>.log —— 守护进程日志（logs 子命令读取，或 tail -f 跟踪）；超过 5MB 会在下次启动时滚动为 <hash>.log.1。

native-host 与守护进程 CLI 都通过这套共享路径（由 @mtop-devtools/daemon-core 派生）读取注册表，因此一方启动的连接器另一方也能发现、复用或停止。

前台运行（含 native-host 托管）时日志输出到 stdout/stderr，不写独立日志文件；只有守护进程模式才落盘到 <hash>.log。

前置条件

1. 安装 @mtop-devtools/native-host

   npm install -g @mtop-devtools/native-host

   或使用本项目的 monorepo 构建产物。

2. 确保 native-host 已初始化

   mtop-devtools-native-host --init

3. 确保 Chrome 浏览器正在运行，且：

   • 已安装 Mtop DevTools 浏览器插件，或
   • 已在 chrome://inspect/#remote-debugging 启用远程调试（Chrome 145+）

架构

云端 Agent
  ↓
@mtop-devtools/cloud-client
  ↓
@mtop-devtools/cloud-server
  ↓ (WebSocket)
@mtop-devtools/cloud-connector (本进程)
  ↓ (Unix Socket)
@mtop-devtools/native-host
  ↓
Chrome Extension / CDP

注意事项

• 连接器需要保持运行才能转发云端请求。被 native-host 托管时，连接器以 detached 方式启动，会在插件重载/更新后继续存活；自管理时由 start/stop 子命令掌控生命周期。
• 前台模式若想交给外部进程管理器（systemd / PM2）托管，加 --foreground 让其在前台运行并由管理器负责守护重启。
• 支持断线自动重连（可在配置中调整）；瞬时断连期间连接记录会保留，仅在进程退出时清除。