Chuantou / Tunneling

Quick Start

npx @feng3d/chuantou-server -p 9000 -t "my-token"

npx @feng3d/chuantou-client -s ws://server:9000 -t "my-token" -p "8080:http:3000:localhost"

System Architecture

• Server: Listens on the control port, accepts client connections, and assigns public network ports
• Client: Connects to the server, establishes tunnels, and forwards local service traffic

Commands

Start Server

npx @feng3d/chuantou-server [options]

• -p, --port <port>

  - Control port (default: 9000)

• -a, --host <address>

  - Listening address (default: 0.0.0.0)

• -t, --tokens <tokens>

  - Authentication tokens (comma-separated)

• --tls-key <path>

  - TLS private key file (enables HTTPS/WSS)

• --tls-cert <path>

  - TLS certificate file

Start Client

npx @feng3d/chuantou-client [options]

• -s, --server <URL>

  - Server address (default:

  ws://li.feng3d.com:9000

  )

• -t, --token <token>

  - Authentication token

• -p, --proxies <config>

  - Proxy configuration (format:

  remote-port:protocol:local-port:local-address

  )

Proxy Configuration Format

remote-port:protocol:local-port:local-address

• remote-port

  : Public access port

• protocol

  :

  http

  or

  ws

  (WebSocket)

• local-port

  : Local service port

• local-address

  : Local service address (default: localhost)

TLS Support

npx @feng3d/chuantou-server --tls-key /path/to/key.pem --tls-cert /path/to/cert.pem

wss://

npx @feng3d/chuantou-client -s wss://server:9000 ...

Configuration Files

~/.chuantou/

• server.json

  - Server configuration (port, tokens)

• client.json

  - Client configuration (server address, token, proxies)

npx @feng3d/chuantou-server -c ~/.chuantou/server.json

Usage Examples

Scenario 1: Local Development Debugging

# Server (machine with public IP)
npx @feng3d/chuantou-server -p 9000 -t "dev-token"

# Client (local development machine)
npx @feng3d/chuantou-client -s ws://server-ip:9000 -t "dev-token" -p "8080:http:5173:localhost"

http://server-ip:8080

Scenario 2: WeChat Official Account Development

npx @feng3d/chuantou-client -s ws://server-ip:9000 -t "my-token" -p "8080:http:3000:localhost"

http://server-ip:8080

Scenario 3: Forward Multiple Ports Simultaneously

npx @feng3d/chuantou-client \
  -s ws://server-ip:9000 \
  -t "my-token" \
  -p "8080:http:3000:localhost,8081:ws:3001:localhost,8082:http:8000:localhost"

Scenario 4: Enable TLS Encryption

# Server (requires domain name and certificate)
npx @feng3d/chuantou-server \
  --tls-key /etc/ssl/private/key.pem \
  --tls-cert /etc/ssl/certs/cert.pem \
  -t "prod-token"

# Client
npx @feng3d/chuantou-client \
  -s wss://your-domain.com:9000 \
  -t "prod-token" \
  -p "8443:http:3000:localhost"

First-Time Usage Process

1. Prepare a Server: You need a machine with a public IP address
2. Start the Server:

npx @feng3d/chuantou-server -p 9000 -t "my-secret-token"
# The output will display the generated token (if not specified)

1. Start the Client (on your local machine):

npx @feng3d/chuantou-client \
  -s ws://server-ip:9000 \
  -t "my-secret-token" \
  -p "8080:http:3000:localhost"

1. Access the Service: Open a browser and visit

   http://server-ip:8080

Troubleshooting

-p

wss://