@mtop-devtools/cloud-server

@mtop-devtools/cloud-server

云端 WebSocket Server，用于中转云端 Agent 请求到本地连接器。

安装

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

使用

命令行方式

mtop-devtools-cloud-server [options]

选项：

• --port <port> - 服务器端口（默认 8080）
• --path <path> - WebSocket 路径（默认 /ws）
• --token <token> - 鉴权密钥（未指定时自动生成）
• --heartbeat <seconds> - 心跳超时时间（默认 90 秒）
• --max-connections <n> - 最大连接数（默认 100）

示例：

# 默认配置启动（自动生成 token）
mtop-devtools-cloud-server

# 自定义端口和鉴权
mtop-devtools-cloud-server --port 9000 --token your-secret-token

# 限制连接数和心跳超时
mtop-devtools-cloud-server --max-connections 50 --heartbeat 120

启动后会在控制台输出 WebSocket URL，例如：

[CloudServer] Public URL (for cloud client): ws://10.0.1.100:8080/ws?token=xxx
[CloudServer] Local URL (for connector): ws://localhost:8080/ws?token=xxx
[CloudServer] Config written to: ~/.mtop-devtools/cloud-server.json

环境变量：

• MTOP_DEVTOOLS_TOKEN - 鉴权密钥（覆盖 --token 选项）
• CLOUD_SERVER_HOST - 公网主机名（默认自动获取）

编程方式

import { CloudServer } from '@mtop-devtools/cloud-server';

const server = new CloudServer({
  port: 8080,
  path: '/ws',
  token: 'your-secret-token',
  heartbeatTimeout: 90,
  maxConnections: 100,
  maxMessageSize: 10 * 1024 * 1024,
});

await server.start();

// 获取统计信息
const stats = server.getStats();
console.log(stats);
// { connections: 2, agents: 1, connectors: 1, pendingRequests: 0 }

// 优雅关闭
await server.stop();

架构

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

连接类型

Server 接受两种类型的连接：

• Agent 连接 - 发起请求的云端客户端
• Connector 连接 - 转发请求到 native-host 的本地连接器

Server 会自动识别连接类型，并将 Agent 的请求转发到可用的 Connector。

消息协议

请求格式（Agent → Server）

{
  "id": "unique-id",
  "action": "get_requests",
  "data": { "count": 5 },
  "version": "1.30.0"
}

响应格式（Server → Agent）

{
  "id": "unique-id",
  "success": true,
  "data": { ... },
  "versionWarning": "..."
}

心跳格式

{ "type": "ping", "timestamp": 1234567890 }
{ "type": "pong", "timestamp": 1234567890 }

鉴权

设置 token 后，所有连接必须携带正确的 token：

# Agent 连接
ws://server.com/ws?token=your-secret-token

# Connector 连接
ws://server.com/ws?token=your-secret-token

部署建议

使用 systemd（Linux）

[Unit]
Description=Mtop DevTools Cloud Server
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/usr/bin/mtop-devtools-cloud-server --port 8080 --token your-token
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

使用 Docker

FROM node:20-alpine
RUN npm install -g @mtop-devtools/cloud-server
EXPOSE 8080
CMD ["mtop-devtools-cloud-server", "--token", "your-token"]

使用 PM2

pm2 start mtop-devtools-cloud-server --name mtop-cloud-server -- --port 8080 --token your-token

注意事项

• 建议在生产环境使用 WSS（WebSocket Secure）加密传输
• 使用反向代理（如 Nginx）处理 WSS 升级
• 设置合理的 maxConnections 限制资源占用
• 启用 token 鉴权保护服务安全
• 在沙箱环境中启动时，会自动检测并使用平台分配的公网地址
• 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址