Socket Tunnel Client

一个简单易用的 Socket 隧道客户端，可以将本地服务暴露到公网。支持在普通环境和 WebContainer 环境中使用。

系统架构

整个隧道系统由三个主要组件构成：

1. 隧道服务器 (Tunnel Server)

   • 负责管理所有隧道连接
   • 生成唯一的隧道标识和URL
   • 转发请求到对应的隧道客户端

2. 隧道代理 (Tunnel Proxy)

   • 接收来自公网的 HTTP 请求
   • 将请求转发到隧道服务器
   • 等待并返回响应

3. 隧道客户端 (Tunnel Client)

   • 连接到隧道服务器
   • 将请求转发到本地服务
   • 将响应返回给隧道服务器

[公网请求] -> [Tunnel Proxy] -> [Tunnel Server] -> [Tunnel Client] -> [本地服务]

安装

客户端安装

npm install @d8d-socket-tunnel/client

服务端安装

npm install @d8d-socket-tunnel/server

代理安装

npm install @d8d-socket-tunnel/proxy

完整部署示例

1. 启动隧道服务器

# 设置环境变量
export TUNNEL_DOMAIN=your-domain.com
export PORT=23909

# 启动服务器
DEBUG=tunnel:server npx @d8d-socket-tunnel/server

2. 启动隧道代理

# 设置环境变量
export TUNNEL_SERVER=http://localhost:23909

# 启动代理
DEBUG=tunnel:proxy npx @d8d-socket-tunnel/proxy

3. 启动本地服务

# 示例：启动一个本地服务在 8080 端口
node your-local-server.js

4. 启动隧道客户端

# 基础用法
npx @d8d-socket-tunnel/client -p 8080

# 完整配置
npx @d8d-socket-tunnel/client -s http://your-tunnel-server.com -p 8080 -r 5

使用方式

1. 基础使用

const { SocketTunnel } = require('@d8d-socket-tunnel/client');

// 创建隧道实例
const tunnel = new SocketTunnel({
  serverUrl: process.env.TUNNEL_SERVER,  // 如果未设置，将使用默认值
  localPort: process.env.LOCAL_PORT      // 如果未设置，将使用默认值
});

// 连接到隧道服务器
tunnel.connect();

// 处理进程退出
process.on('SIGINT', () => {
  console.log('正在关闭隧道...');
  tunnel.close();
  process.exit(0);
});

2. 命令行使用

# 使用 npx
npx @d8d-socket-tunnel/client -p 8080

# 指定服务器
npx @d8d-socket-tunnel/client -s https://your-tunnel-server.com -p 8080

# 完整参数
npx @d8d-socket-tunnel/client -s https://your-tunnel-server.com -p 8080 -r 5

3. 在 WebContainer 中使用

async function startTunnel(webcontainerInstance) {
  return new Promise((resolve, reject) => {
    let tunnelUrl = null;
    
    const process = await webcontainerInstance.spawn('npx', [
      '@d8d-socket-tunnel/client',
      '-s', 'https://your-tunnel-server.com',
      '-p', '8080',
      '--webcontainer'  // 启用 WebContainer 模式
    ]);

    // 监听输出获取隧道 URL
    process.output.on('data', (data) => {
      const output = data.toString();
      const match = output.match(/TUNNEL_URL=(.+)/);
      if (match) {
        tunnelUrl = match[1];
        resolve({
          tunnelUrl,
          process,
          close: async () => {
            await process.kill();
          }
        });
      }
    });

    // 错误处理
    process.output.on('error', reject);

    // 超时处理
    setTimeout(() => {
      if (!tunnelUrl) {
        reject(new Error('获取隧道URL超时'));
      }
    }, 10000);
  });
}

// 使用示例
try {
  const { tunnelUrl, close } = await startTunnel(webcontainerInstance);
  console.log('隧道URL:', tunnelUrl);
  
  // 在需要时关闭隧道
  // await close();
} catch (error) {
  console.error('启动隧道失败:', error);
}

命令行参数

| 参数 | 说明 | 默认值 | |------|------|--------| | -s, --server | 隧道服务器地址 | http://localhost:23909 | | -p, --port | 本地服务端口 | 1081 | | -r, --retries | 最大重试次数 | 10 | | --webcontainer | 在 WebContainer 中运行 | false | | -h, --help | 显示帮助信息 | - | | -V, --version | 显示版本号 | - |

环境变量

也可以通过环境变量来配置：

• TUNNEL_SERVER: 隧道服务器地址
• LOCAL_PORT: 本地服务端口
• MAX_RETRIES: 最大重试次数
• DEBUG=tunnel:client: 启用调试日志

WebContainer 模式特性

在 WebContainer 中运行时（使用 --webcontainer 参数）：

1. 输出格式优化：

   • 使用特定格式输出隧道 URL: TUNNEL_URL=xxx
   • 简化日志输出，便于解析

2. 错误处理：

   • 自动重试连接
   • 超时保护
   • 优雅退出

3. 资源清理：

   • 提供 close 方法关闭隧道
   • 自动处理进程退出

注意事项

1. 确保本地服务已经启动
2. 需要可用的隧道服务器
3. 在 WebContainer 中使用时，建议设置合理的超时时间
4. 记得在不需要时关闭隧道释放资源

许可证

MIT