@feng3d/cts

cts 是 穿透服务端（Chuantou Server）的缩写。

内网穿透转发系统的服务端，运行在有公网 IP 的机器上，接收公网请求并转发给内网客户端。

特性

• 极简设计，仅一条命令 start
• 启动时随机生成认证 Token，无需手动指定
• 代理端口由服务端自动分配，默认范围 [控制端口, 9999]
• 三通道架构：WebSocket 控制通道 + TCP 二进制数据通道 + UDP 数据通道
• 每个代理端口同时支持 HTTP / WebSocket / TCP / UDP 四种协议，自动识别协议类型
• 控制端口复用：同一端口同时处理 WebSocket 控制连接、TCP 数据通道和 UDP 数据通道
• 客户端连接教程页：浏览器访问控制端口即可查看图文教程与可复制的配置命令
• Token 认证
• 代理端口自动启用 TLS（自签证书，支持相机/WebRTC/WebGPU 安全上下文）

快速开始

推荐使用 npx 直接运行，无需全局安装：

npx -y @feng3d/cts start

启动后会打印控制端口、随机生成的 Token、外网/内网 IP、PID，以及可直接复制的客户端配置命令：

  穿透服务端已启动
  ───────────────────────────────────
  控制端口: 9000
  Token:    a1b2c3d4-e5f6-7890-abcd-ef1234567890
  TLS:      未启用
  代理端口范围: 9000-9999
  PID:      12345
  外网 IP:  203.0.113.10
  内网 IP:  192.168.1.10
  ───────────────────────────────────
  外网配置
  npx -y @feng3d/ctc set -ip 203.0.113.10 -p 9000 -t a1b2c3d4-e5f6-7890-abcd-ef1234567890
  内网配置
  npx -y @feng3d/ctc set -ip 192.168.1.10 -p 9000 -t a1b2c3d4-e5f6-7890-abcd-ef1234567890
  提示: 选择与客户端网络可达的地址，复制对应命令执行
  映射示例: npx -y @feng3d/ctc -p 3000

命令说明

start - 启动服务端

npx -y @feng3d/cts start [选项]

常用示例：

# 默认配置启动（控制端口 9000，随机 token，代理范围 9000-9999）
npx -y @feng3d/cts start

# 指定控制端口（代理范围自动变为 9100-9999）
npx -y @feng3d/cts start -p 9100

# 指定认证 token
npx -y @feng3d/cts start --token my-secret-token

# 限定代理端口范围
npx -y @feng3d/cts start --port-range 30000-40000

# 后台运行
npx -y @feng3d/cts start -d

代理端口自动启用 TLS（自签证书启动时自动生成），无需手动配置。

参数说明：

| 参数 | 说明 | 默认值 | |------|------|--------| | -p, --port <port> | 控制端口 | 9000 | | -a, --host <address> | 监听地址 | 0.0.0.0 | | --token <token> | 客户端连接 token（用户映射端口用，不指定则随机生成） | 随机生成 | | --page-token <token> | 教程页访问 token（管理员用，不指定则随机生成） | 随机生成 | | --port-range <min-max> | 代理端口分配范围 | 控制端口-9999 | | -d, --detach | 后台运行（终端关闭不停止） | 前台运行 |

代理端口范围

服务端为每个新映射在 --port-range 指定的闭区间内自动分配空闲端口。

默认规则：未指定 --port-range 时，范围为 [控制端口, 9999]：

| 控制端口 | 默认代理范围 | |----------|--------------| | 9000（默认） | 9000-9999 | | 9100 | 9100-9999 | | 9050 | 9050-9999 |

如需开放固定区间，显式指定即可：

npx -y @feng3d/cts start --port-range 30000-40000

客户端连接教程页

用浏览器访问控制端口，输入 banner 中的「页面Token」登录即可：

http://<服务端IP>:<控制端口>/

浏览器记录 Cookie 后续免登录。页面包含：服务端信息、可一键复制的客户端配置命令、当前映射列表（服务端渲染）。

教程页含敏感信息，已设鉴权；未授权访问只返回登录页，不泄露 Token 与映射信息。Token 通过 POST 提交，不进 URL。

运行模式

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

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

npx -y @feng3d/cts start -d

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

TLS 与安全上下文

• 代理端口（映射端口）自动启用 TLS：启动时自动生成自签证书（~/.chuantou/cert.pem），代理端口用 HTTPS，通过映射端口访问的网页为安全上下文（相机/WebRTC/WebGPU 可用）。
• 控制端口为 HTTP：教程页、证书下载用 HTTP 访问（便于首次下载安装证书）。
• 安装证书：浏览器打开教程页（控制端口），在「证书下载与安装」区块下载 .pem/.cer 并按教程安装。安装后访问映射端口（HTTPS）不再有警告。

架构

控制端口（复用）:
  ├─ WebSocket 控制通道 ── JSON 消息（认证/注册/心跳/连接通知）
  ├─ TCP 数据通道 ─────── 二进制帧（HTTP/WS/TCP 数据转发）
  └─ UDP 数据通道 ─────── UDP 数据帧（UDP 数据转发）

代理端口（每端口同时监听 TCP + UDP）:
  ├─ TCP 服务器 → 自动识别 HTTP/WebSocket/TCP 协议
  └─ UDP 服务器 → 转发 UDP 数据

每个代理端口同时支持 HTTP/WebSocket/TCP/UDP 四种协议，客户端无需指定协议类型。

作为库使用

import { ForwardServer } from '@feng3d/cts';

const server = new ForwardServer({
  host: '0.0.0.0',
  controlPort: 9000,
  authToken: 'my-token',
  // 代理端口分配范围（不指定则默认 [9000, 9999]）
  proxyPortRange: { min: 30000, max: 40000 },
});

await server.start();

许可证

ISC