@feng3d/ctc

ctc 是 穿透客户端（Chuantou Client）的缩写。

内网穿透转发系统的客户端，运行在内网机器上，将本地服务暴露到公网。

特性

• 极简设计，仅两步：set 配置服务端 → -p <端口> 映射
• 远程端口由服务端自动分配，无需手动指定
• 每个代理端口同时支持 HTTP/WebSocket/TCP/UDP 四种协议
• 三通道架构：WebSocket 控制通道 + TCP 二进制数据通道 + UDP 数据通道
• 自动重连机制

快速开始

推荐使用 npx 直接运行，无需全局安装。两步即可完成映射：

1. 配置服务端访问信息

从服务端启动时打印的命令中复制（服务端 start 会自动给出）：

npx -y @feng3d/ctc set -ip 203.0.113.10 -p 9000 -t a1b2c3d4-e5f6-7890-abcd-ef1234567890

服务端启用 TLS 时追加 --tls。配置保存在 ~/.chuantou/config.json。

2. 映射本地端口

npx -y @feng3d/ctc -p 3000

服务端自动分配远程端口，映射成功后打印访问地址：

  端口映射成功
  ───────────────────────────────────
  本地端口: 3000
  服务端映射端口: 9123
  访问地址: http://203.0.113.10:9123
  ───────────────────────────────────

访问 http://<服务端IP>:<映射端口> 即可访问本地的 3000 端口服务。

命令说明

set - 配置服务端访问信息

npx -y @feng3d/ctc set [选项]

参数说明：

| 参数 | 说明 | 默认值 | |------|------|--------| | -ip <ip> | 服务端 IP 或域名（简写，标准形式 --ip） | （必填） | | -p, --server-port <port> | 服务端控制端口 | （必填） | | -t, --token <token> | 认证 token（与服务端一致） | （必填） | | --tls | 服务端启用 TLS（使用 wss/https） | false |

示例：

# 标准用法（推荐直接复制服务端打印的命令）
npx -y @feng3d/ctc set -ip 203.0.113.10 -p 9000 -t my-token

# 使用域名 + TLS
npx -y @feng3d/ctc set -ip your.domain.com -p 9000 -t my-token --tls

说明：-ip 是用户习惯的简写（commander 短选项本是单字符，内部会自动重写为 --ip）。set 上下文中的 -p 指服务端控制端口，与映射命令的 -p（本地端口）含义不同。

映射本地端口（默认动作）

npx -y @feng3d/ctc -p <本地端口> [选项]

参数说明：

| 参数 | 说明 | 默认值 | |------|------|--------| | -p, --port <localPort> | 要映射的本地端口 | （必填） | | -d, --detach | 后台运行（终端关闭不停止） | 前台运行 |

示例：

# 前台运行，映射本地 3000 端口
npx -y @feng3d/ctc -p 3000

# 后台运行
npx -y @feng3d/ctc -p 3000 -d

不带任何参数运行会显示帮助。

运行模式

默认前台运行，Ctrl+C 或关闭终端即停止。

追加 -d 后台运行（脱离终端），日志写入 ~/.chuantou/client.log：

npx -y @feng3d/ctc -p 3000 -d

后台进程停止用 kill <pid>（Linux）或 taskkill /F /PID <pid>（Windows），PID 在启动时打印。

配置文件

set 命令将服务端访问信息写入 ~/.chuantou/config.json：

{
  "serverIp": "203.0.113.10",
  "serverPort": 9000,
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tls": false
}

映射命令（-p）启动时读取该配置连接服务端。如需切换服务端，重新执行 set 即可覆盖。

作为库使用

import { Controller, ProxyManager } from '@feng3d/ctc';

const controller = new Controller({
  serverUrl: 'ws://203.0.113.10:9000/control',
  token: 'my-token',
  reconnectInterval: 5000,
  maxReconnectAttempts: Infinity,
});

const proxyManager = new ProxyManager(controller);

await controller.connect();
// 认证成功后注册代理，服务端自动分配远程端口
controller.on('authenticated', async () => {
  await proxyManager.registerProxy({ localPort: 3000 });
});

proxyManager.on('registered', (assignedPort: number) => {
  console.log(`已映射，访问地址: http://203.0.113.10:${assignedPort}`);
});

许可证

ISC