rustunnel

rustunnel

可随你扩展的开源隧道。不必为闲置时间付费。安全、拥有 Rust 般的高速，并按使用量付费。

通过加密的 WebSocket 连接，将本地服务暴露到公共服务器，并支持 TLS 终止、HTTP/TCP 代理、实时仪表板、Prometheus 指标和审计日志。

你可以自行托管，也可以使用我们的托管服务。

正在使用 AI Agent？ rustunnel 提供 MCP 服务——可一键设置 Cursor（然后添加你的 API 令牌）：

关于 Claude Code、Claude Desktop、Windsurf 等，请参阅 Agent 集成指南或 rustunnel.com/agents.md 上的 Agent 手册。

---

目录

• 托管服务
• 架构概览
• 要求
• 本地开发设置
  • 构建
  • 运行测试
  • 在本地运行服务端
  • 在本地运行客户端
  • Git 钩子
• 生产环境部署（Ubuntu / systemd）
  • 1 — 安装依赖项
  • 2 — 构建发布二进制文件
  • 3 — 创建系统用户和目录
  • 4 — 安装服务端二进制文件
  • 5 — 创建服务端配置文件
  • 6 — TLS 证书（Let's Encrypt + Cloudflare）
  • 7 — 设置 systemd 服务
  • 8 — 开放防火墙端口
  • 9 — 验证服务端正在运行
  • 更新服务端
• Docker 部署 · 完整指南
• 客户端配置
  • 安装
  • 设置向导
  • 快速开始（CLI 参数）
  • 机器可读输出（--json）
  • 配置文件
  • 令牌管理
• 端口参考
• 配置文件参考（服务端）
• REST API
• AI Agent 集成（MCP 服务）
  • OpenClaw 技能
• 监控
• 路线图
• 贡献
• 许可证
• 联系方式

---

托管服务

无需运行自己的服务端即可使用 rustunnel。我们运营着一个由公共边缘服务器组成的全球集群，你可以立即连接。

可用区域

区域 ID	服务	位置	控制平面	状态
eu	eu.edge.rustunnel.com	芬兰赫尔辛基	:4040	在线
us	us.edge.rustunnel.com	俄勒冈州希尔斯伯勒	:4040	在线
ap	ap.edge.rustunnel.com	新加坡	:4040	在线

默认情况下，客户端会自动选择最近的区域。使用 --region <id> 可连接到指定区域。旧地址 edge.rustunnel.com 是指向 eu.edge.rustunnel.com 的 CNAME，为保证向后兼容，将继续可用。

获取身份验证令牌

在 rustunnel.com 注册免费账户——无需排队等待，也无需人工审批。

1. 在 rustunnel.com 创建账户
2. 前往 Dashboard → API Keys 并创建令牌
3. 复制令牌——它只会显示一次

套餐：

套餐	价格	隧道	自定义子域名	TLS/HTTPS
免费	$0	最多 3 个	—	✓
按量付费	最低 $3/月 + $0.10/GB	无限	✓	✓
自托管	免费（运行自己的服务）	无限	✓	✓

免费套餐是很好的入门选择。需要自定义子域名或无限隧道时，可随时从控制面板升级为按量付费套餐。

使用托管服务快速开始

获取令牌后，运行设置向导：

rustunnel setup
# Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter)
#   Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
#   Server set to: eu.edge.rustunnel.com:4040
# Auth token: <paste your token>

然后公开一个本地服务：

# HTTP tunnel — auto-selects the nearest region
rustunnel http 3000

# Connect to a specific region
rustunnel http 3000 --region eu

# Custom subdomain
rustunnel http 3000 --subdomain myapp

# TCP tunnel — e.g. expose a local database
rustunnel tcp 5432

# UDP tunnel — e.g. expose a game server
rustunnel udp 27015

# P2P tunnel — expose a service to another rustunnel client
rustunnel p2p 27015 --name my-game --secret "shared-secret"

# P2P tunnel — connect to a peer's service
rustunnel p2p 8000 --target my-game --secret "shared-secret"

隧道建立后，客户端会立即打印公共 URL：

  Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
✓ tunnel open  https://abc123.eu.edge.rustunnel.com

---

架构概览

                        ┌──────────────────────────────────────────┐
                        │           rustunnel-server               │
                        │                                          │
Internet ──── :80 ─────▶│  HTTP edge (301 → HTTPS)                 │
Internet ──── :443 ────▶│  HTTPS edge  ──▶ yamux stream ──▶ client │
Client ───── :4040 ────▶│  Control-plane WebSocket (TLS)           │
Browser ──── :8443 ────▶│  Dashboard UI + REST API                 │
Prometheus ─ :9090 ────▶│  Metrics endpoint                        │
Internet ── :20000+ ───▶│  TCP tunnel ports (one per TCP tunnel)   │
                        └──────────────────────────────────────────┘
                                          │ yamux multiplexed streams
                                          ▼
                              ┌─────────────────────┐
                              │   rustunnel client   │
                              │  (developer laptop)  │
                              └──────────┬──────────┘
                                         │ localhost
                                         ▼
                                ┌────────────────┐
                                │  local service  │
                                │  e.g. :3000    │
                                └────────────────┘

---

要求

构建要求

要求	版本	备注
Rust 工具链	1.76+	通过 rustup 安装
pkg-config	任意	reqwest（TLS）所需
libssl-dev	任意	在 Debian/Ubuntu 上：apt install libssl-dev
Node.js + npm	18+	仅重新构建控制面板 UI 时需要

在生产环境中运行服务的要求

要求	备注
Linux（Ubuntu 22.04+）	附带 systemd 服务
TLS 证书 + 私钥	PEM 格式（推荐 Let's Encrypt）
公网 IP / DNS	HTTP 隧道需要通配符 DNS *.tunnel.yourdomain.com → server IP

---

本地开发环境设置

构建

# Clone the repository
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel

# Compile all workspace crates (debug mode)
cargo build --workspace

# Or use the Makefile shortcut
make build

运行测试

集成测试套件会在随机端口上启动真实服务，并测试身份验证、HTTP 隧道、TCP 隧道和重连逻辑。需要运行中的 PostgreSQL 实例。

# Start the local PostgreSQL container (once per machine, persists across reboots)
make db-start

# Full suite (unit + integration)
make test

# With output visible
TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  cargo test --workspace -- --nocapture

# Stop PostgreSQL when you no longer need it
make db-stop

make db-start 会运行 deploy/docker-compose.dev-deps.yml，在 localhost:5432 上启动 Postgres 16 容器。make test 目标会自动注入 TEST_DATABASE_URL。如果直接运行 cargo test，请先导出该变量：

export TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test

在本地运行服务

生成用于本地测试的自签名证书：

mkdir -p /tmp/rustunnel-dev

openssl req -x509 -newkey rsa:2048 -keyout /tmp/rustunnel-dev/key.pem \
  -out /tmp/rustunnel-dev/cert.pem -days 365 -nodes \
  -subj "/CN=localhost"

仓库中已包含可直接使用的本地配置 deploy/local/server.toml。 它指向上述自签名证书路径，并为方便起见禁用了身份验证。 直接使用该配置启动服务：

cargo run -p rustunnel-server -- --config deploy/local/server.toml

deploy/local/server.toml 中的关键设置：

设置	值
域名	localhost
HTTP 边缘	:8080
HTTPS 边缘	:8443
控制平面	:4040
控制面板	:4041
身份验证令牌	dev-secret-change-me
是否需要身份验证	false
TLS 证书	/tmp/rustunnel-dev/cert.pem
TLS 密钥	/tmp/rustunnel-dev/key.pem
数据库	/tmp/rustunnel-dev/rustunnel.db

在本地运行客户端

服务运行后，公开一个本地服务（例如运行在端口 3000 上的服务）：

# HTTP tunnel
cargo run -p rustunnel-client -- http 3000 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure

# TCP tunnel
cargo run -p rustunnel-client -- tcp 5432 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure

--insecure 会跳过 TLS 证书验证。在本地使用自签名证书时需要此参数。切勿对生产服务使用此参数。

客户端会打印一个公共 URL，例如：

http tunnel  →  http://abc123.localhost:8080
tcp  tunnel  →  tcp://localhost:20000

在本地测试 HTTP 隧道

隧道 URL 使用子域名（例如：http://abc123.localhost:8080）。 浏览器默认无法解析 *.localhost 子域名，因此有两种选择：

选项 A — 使用带 Host 标头的 curl（无需设置）

curl -v -H "Host: abc123.localhost" http://localhost:8080/

选项 B — 通过 dnsmasq 配置通配符 DNS（允许浏览器访问）

# Install and configure dnsmasq to resolve *.localhost → 127.0.0.1
brew install dnsmasq
echo "address=/.localhost/127.0.0.1" | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
sudo brew services start dnsmasq

# Tell macOS to use dnsmasq for .localhost queries
sudo mkdir -p /etc/resolver
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/localhost

然后在浏览器中访问 http://abc123.localhost:8080（请带上 :8080，因为 本地配置使用的是端口 8080，而不是端口 80）。

Git 钩子

.githooks/ 中包含一个 pre-push 钩子，用于执行与 CI 检查步骤相同的检查 （格式检查 + Clippy）。克隆后运行一次即可启用：

make install-hooks

此后，每次运行 git push 都会自动执行：

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

如果任一检查失败，推送就会中止，以确保远程分支保持正常。

---

生产环境部署（Ubuntu / systemd）

以下步骤适用于这样的部署环境：

• 域名：edge.rustunnel.com
• 通配符 DNS：*.edge.rustunnel.com → <server IP>
• TLS 证书：通过 Certbot + Cloudflare DNS 验证获取的 Let's Encrypt 证书

1 — 安装依赖

apt update && apt install -y \
  pkg-config libssl-dev curl git \
  certbot python3-certbot-dns-cloudflare

安装 Rust（以构建用户身份执行，而非 root）：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

2 — 构建发布版二进制文件

git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
cargo build --release -p rustunnel-server -p rustunnel-client

二进制文件位于：

• target/release/rustunnel-server
• target/release/rustunnel

3 — 创建系统用户和目录

useradd --system --no-create-home --shell /usr/sbin/nologin rustunnel

mkdir -p /etc/rustunnel /var/lib/rustunnel
chown rustunnel:rustunnel /var/lib/rustunnel
chmod 750 /var/lib/rustunnel

4 — 安装服务端二进制文件

install -Dm755 target/release/rustunnel-server /usr/local/bin/rustunnel-server

# Optionally install the client system-wide
install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel

也可以使用 Makefile 目标（执行构建、安装和 systemd 设置）：

sudo make deploy

5 — 设置 PostgreSQL

rustunnel 需要使用 PostgreSQL 存储共享状态（令牌、隧道历史记录、审计日志）。

apt install -y postgresql postgresql-contrib

# Start and enable the service
systemctl enable --now postgresql

创建专用数据库和用户：

sudo -u postgres psql <<'SQL'
CREATE USER rustunnel WITH PASSWORD 'CHANGE_ME';
CREATE DATABASE rustunnel OWNER rustunnel;
GRANT ALL PRIVILEGES ON DATABASE rustunnel TO rustunnel;
SQL

提示： 如果使用托管 PostgreSQL（例如 AWS RDS、DigitalOcean Managed Database、Supabase），请跳过上面的 apt install 步骤，并记下连接 URL，以便在下一步配置中使用。

服务端启动时会自动运行架构迁移，无需手动执行 SQL。

6 — 创建服务端配置文件

使用以下内容创建 /etc/rustunnel/server.toml。 将 your-admin-token-here 替换为强随机密钥（例如 openssl rand -hex 32）。

# /etc/rustunnel/server.toml

[server]
# Primary domain — must match your wildcard DNS record.
domain       = "edge.rustunnel.com"

# Ports for incoming tunnel traffic (requires CAP_NET_BIND_SERVICE or root).
http_port    = 80
https_port   = 443

# Control-plane WebSocket port — clients connect here.
control_port = 4040

# Dashboard UI and REST API port.
dashboard_port = 8443

# Allowed CORS origin for the dashboard UI.
# Set to the URL where you serve the dashboard-ui (e.g. http://localhost:3000 for local dev).
dashboard_origin = "http://localhost:3000"

# ── TLS ─────────────────────────────────────────────────────────────────────
[tls]
# Paths written by Certbot (see step 6).
cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
key_path  = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"

# Set acme_enabled = true only if you want rustunnel to manage certs itself
# via the ACME protocol (requires Cloudflare credentials below).
# When using Certbot (recommended), leave this false.
acme_enabled = false

# ── Auth ─────────────────────────────────────────────────────────────────────
[auth]
# Strong random secret — used both as the admin token and for client auth.
# Generate: openssl rand -hex 32
admin_token  = "your-admin-token-here"
require_auth = true
# Failed auth attempts per source IP per minute before rejection (0 = off).
max_failed_auth_per_minute = 10

# ── Database ─────────────────────────────────────────────────────────────────
[database]
# PostgreSQL connection URL — the database and user must exist before starting
# the server (see the PostgreSQL setup step above).  Schema migrations run
# automatically on first start.
url = "postgresql://rustunnel:CHANGE_ME@localhost:5432/rustunnel"

# Per-region SQLite file for captured HTTP request bodies.
# The directory must be writable by the rustunnel user.
captured_path = "/var/lib/rustunnel/captured.db"

# ── Logging ──────────────────────────────────────────────────────────────────
[logging]
level  = "info"
format = "json"

# Optional: write an append-only audit log (JSON-lines) for auth attempts,
# tunnel registrations, token creation/deletion, and admin actions.
# Omit or comment out to disable.
audit_log_path = "/var/lib/rustunnel/audit.log"

# ── Limits ───────────────────────────────────────────────────────────────────
[limits]
# Maximum tunnels a single authenticated session may register.
max_tunnels_per_session = 10

# Maximum simultaneous proxied connections per tunnel (semaphore).
max_connections_per_tunnel = 100

# Per-tunnel request rate limit (requests/second).
rate_limit_rps = 100

# Per-source-IP rate limit (requests/second). Set to 0 to disable.
ip_rate_limit_rps = 100

# Maximum size of a proxied HTTP request body (bytes). Default: 10 MB.
request_body_max_bytes = 10485760

# Inclusive port range reserved for TCP tunnels.
# Each active TCP tunnel consumes one port from this range.
tcp_port_range = [20000, 20099]

# Inclusive port range reserved for UDP tunnels.
# Each active UDP tunnel consumes one port from this range.
# Must not overlap with tcp_port_range. Set to [0, 0] to disable UDP tunnels.
udp_port_range = [20100, 20199]

保护该文件：

chown root:rustunnel /etc/rustunnel/server.toml
chmod 640 /etc/rustunnel/server.toml

7 — TLS 证书（Let's Encrypt + Cloudflare）

创建 Cloudflare 凭据文件：

cat > /etc/letsencrypt/cloudflare.ini <<'EOF'
# Cloudflare API token with DNS:Edit permission for the zone.
dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
EOF

chmod 600 /etc/letsencrypt/cloudflare.ini

申请同时涵盖裸域名和通配符域名的证书（HTTP 子域名隧道需要此证书）：

certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  -d "edge.rustunnel.com" \
  -d "*.edge.rustunnel.com" \
  --agree-tos \
  --email [email protected]

Certbot 会将证书写入：

/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem

上述配置中已设置这些路径。Certbot 会通过 systemd 计时器自动续订证书。

rustunnel 会在启动时从磁盘读取 TLS 证书，因此每次续订后都必须重启服务。 添加 Certbot 部署钩子以自动执行此操作：

cat > /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh <<'EOF'
#!/bin/sh
systemctl restart rustunnel.service
EOF
chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh

允许 rustunnel 服务用户读取证书：

# Grant read access to the live/ and archive/ directories
chmod 755 /etc/letsencrypt/{live,archive}
chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem

8 — 设置 systemd 服务

# Copy the unit file from the repository
install -Dm644 deploy/rustunnel.service /etc/systemd/system/rustunnel.service

systemctl daemon-reload
systemctl enable --now rustunnel.service

# Check it started
systemctl status rustunnel.service
journalctl -u rustunnel.service -f

9 — 开放防火墙端口

ufw allow 80/tcp   comment "rustunnel HTTP edge"
ufw allow 443/tcp  comment "rustunnel HTTPS edge"
ufw allow 4040/tcp comment "rustunnel control plane"
ufw allow 8443/tcp comment "rustunnel dashboard"
ufw allow 9090/tcp comment "rustunnel Prometheus metrics"

# TCP tunnel port range (must match tcp_port_range in server.toml)
ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"

# UDP tunnel port range (must match udp_port_range in server.toml)
ufw allow 20100:20199/udp comment "rustunnel UDP tunnels"

10 — 验证服务端是否正在运行

# Health check — use dashboard_port from server.toml (default 8443 in production)
curl http://localhost:8443/api/status

# Confirm which ports the process is actually bound to
ss -tlnp | grep rustunnel-serve

# Startup banner is visible in the logs
journalctl -u rustunnel.service --no-pager | tail -30

# Prometheus metrics
curl -s http://localhost:9090/metrics

端口提醒：端口 4040 是控制平面的 WebSocket 端口（客户端连接到此处）， 不是仪表板端口。使用普通 HTTP 访问该端口会返回 HTTP/0.9，这是预期行为。 仪表板位于 dashboard_port — 如果不确定，请检查 server.toml。

更新服务端

拉取最新代码、重新构建、安装并重启，只需运行一条命令：

cd ~/rustunnel && sudo make update-server

此命令会依次执行 git pull → cargo build --release → install → systemctl restart → systemctl status。

---

Docker 部署

docs/docker-deployment.md 中提供了完整的 Docker 指南，涵盖本地开发（自签名证书）和 生产 VPS（Let's Encrypt）。

拉取已发布的镜像

每次稳定版本发布时，都会将多架构镜像（linux/amd64 + linux/arm64）发布到 GitHub Container Registry，无需构建：

# Latest stable, or pin a version (e.g. :0.8.1)
docker pull ghcr.io/joaoh82/rustunnel-server:latest

# Run it with your server config mounted at /etc/rustunnel/server.toml
docker run --rm \
  -p 80:80 -p 443:443 -p 4040:4040 -p 8443:8443 \
  -v "$PWD/deploy/server.toml:/etc/rustunnel/server.toml:ro" \
  ghcr.io/joaoh82/rustunnel-server:latest

快速参考（从源代码构建）

# Build the image locally (includes Next.js dashboard + Rust server)
make docker-build

# Build and push a multi-arch image to GHCR (maintainers; needs buildx + ghcr login)
make docker-push

# Local development (self-signed cert, no auth required)
docker compose -f deploy/docker-compose.local.yml up

# Production VPS (requires deploy/server.toml to be configured first)
make docker-run

# Production + Prometheus + Grafana monitoring stack
make docker-run-monitoring

# Tail server logs
make docker-logs

# Stop everything
make docker-stop

文件

文件	用途
deploy/Dockerfile	多阶段构建：Node.js UI → Rust 服务 → 精简运行时
deploy/docker-compose.yml	生产环境 compose 文件
deploy/docker-compose.local.yml	本地开发 compose 文件
deploy/server.toml	生产环境服务配置模板
deploy/server.local.toml	本地开发服务配置
deploy/prometheus.yml	Prometheus 抓取配置

---

客户端配置

安装

选项 1 — Homebrew（macOS 和 Linux，推荐）

brew tap joaoh82/rustunnel
brew install rustunnel

Homebrew 会安装预构建的二进制文件，无需 Rust 工具链。 该 formula 会在每次发布时自动更新。此操作会同时安装 rustunnel（CLI 客户端）和 rustunnel-mcp（用于 AI Agent 集成的 MCP 服务）。

选项 2 — 预构建二进制文件

从最新的 GitHub Release 下载适用于你平台的压缩包，解压后将 rustunnel 二进制文件移至 $PATH 中的目录：

# Example for macOS Apple Silicon
curl -L https://github.com/joaoh82/rustunnel/releases/latest/download/rustunnel-<version>-aarch64-apple-darwin.tar.gz \
  | tar xz
sudo install -Dm755 rustunnel /usr/local/bin/rustunnel

可用目标：

平台	压缩包
macOS Apple Silicon	rustunnel-<version>-aarch64-apple-darwin.tar.gz
macOS Intel	rustunnel-<version>-x86_64-apple-darwin.tar.gz
Linux x86_64（glibc）	rustunnel-<version>-x86_64-unknown-linux-gnu.tar.gz
Linux x86_64（musl，静态）	rustunnel-<version>-x86_64-unknown-linux-musl.tar.gz
Linux arm64	rustunnel-<version>-aarch64-unknown-linux-gnu.tar.gz
Windows x86_64	rustunnel-<version>-x86_64-pc-windows-msvc.zip

选项 3 — 从源代码构建

需要 Rust 1.76+。

git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
cargo build --release -p rustunnel-client
sudo install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel

# Or via make
make deploy-client

设置向导

创建配置文件最简单的方式是使用交互式设置向导：

rustunnel setup

向导会提示你输入区域和身份验证令牌，然后写入 ~/.rustunnel/config.yml，其中包含正确的服务地址和带注释的 tunnels: 示例部分。

rustunnel setup — create ~/.rustunnel/config.yml

Region [auto / eu / us / ap / self-hosted] (default: auto):
  Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
  Server set to: eu.edge.rustunnel.com:4040

Auth token (leave blank to skip): rt_live_abc123...

Created: /Users/you/.rustunnel/config.yml
Run `rustunnel start` to connect using this config.

选择特定区域（eu、us、ap）以直接连接，或选择 auto（默认值），让客户端探测所有区域并选择最近的区域。如果你运行自己的服务，请选择 self-hosted；随后向导会提示你输入服务地址。

完成设置后，使用 rustunnel start 连接配置中定义的所有隧道，或使用 rustunnel http <port> / rustunnel tcp <port> 创建一次性隧道。

快速开始（CLI 标志）

# Expose a local HTTP service on port 3000 (auto-selects nearest region)
rustunnel http 3000 \
  --token YOUR_AUTH_TOKEN

# Connect to a specific region
rustunnel http 3000 --region eu --token YOUR_AUTH_TOKEN

# Use an explicit server address (bypasses region selection)
rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_AUTH_TOKEN

# Expose a local service with a custom subdomain
rustunnel http 3000 \
  --token YOUR_AUTH_TOKEN \
  --subdomain myapp

# Expose a local TCP service (e.g. a PostgreSQL database)
rustunnel tcp 5432 \
  --token YOUR_AUTH_TOKEN

# Disable automatic reconnection
rustunnel http 3000 --no-reconnect

机器可读输出（--json）

所有运行隧道的命令（http、tcp、udp、p2p、start）以及 token create 均接受 --json 标志。启用后，标准输出会输出 NDJSON—— 每行一个 JSON 事件对象——而不是人类可读的启动信息框，因此 CLI 易于通过脚本和 AI Agent 调用：

rustunnel http 3000 --json --token YOUR_AUTH_TOKEN

{"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.eu.edge.rustunnel.com","local_port":3000,"local_host":"localhost","tunnel_id":"6f9a…","name":"myapp"}

事件：

事件	时机	字段
tunnel_ready	隧道已注册并开始接受流量	protocol、public_url、public_addr（主机:端口，仅 tcp/udp）、local_port、local_host、tunnel_id、name
reconnecting	连接已断开，已安排重试	attempt、reason、delay_secs
reconnected	重新连接成功（随后会收到新的 tunnel_ready 事件）	—
error	致命错误；进程以代码 1 退出	code（config/auth/tunnel/connection/protocol/io）、message、hint
token_created	token create --json 成功	token、name、id

诊断信息仍会输出到标准错误，因此标准输出始终是有效的 NDJSON。对于 http、tcp、udp 和 p2p 命令，也可以通过环境变量 RUSTUNNEL_TOKEN 提供身份验证令牌，而无需使用 --token（start 会从配置文件读取令牌）。

配置文件

默认位置：~/.rustunnel/config.yml

# ~/.rustunnel/config.yml

# Tunnel server address (host:control_port)
server: edge.rustunnel.com:4040

# Auth token (from server admin_token or a token created via the dashboard)
auth_token: YOUR_AUTH_TOKEN

# Region preference: auto (probe & pick nearest), or eu / us / ap.
# Omit for self-hosted / single-server setups.
region: auto

# Named tunnels started with `rustunnel start`
tunnels:
  web:
    proto: http
    local_port: 3000
    subdomain: myapp      # optional — server assigns one if omitted

  db:
    proto: tcp
    local_port: 5432

启动配置文件中的所有隧道：

rustunnel start
# or with an explicit path
rustunnel start --config /path/to/config.yml

令牌管理

托管服务： 在 rustunnel.com 控制面板的 Dashboard → API Keys 中管理令牌。你可以创建、添加标签和撤销令牌，无需使用任何 CLI 命令。

自托管： 通过控制面板 API 创建其他令牌：

rustunnel token create \
  --name "ci-deploy" \
  --server your-server:8443 \
  --admin-token YOUR_ADMIN_TOKEN

或通过 curl：

curl -s -X POST https://your-server:8443/api/tokens \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-deploy"}'

---

端口参考

端口	协议	用途
80	TCP	HTTP 边缘端口 — 重定向到 HTTPS；也用于 ACME HTTP-01 挑战
443	TCP	HTTPS 边缘端口 — TLS 终止的隧道入口
4040	TCP	控制平面 WebSocket — 客户端在此连接
8443	TCP	控制面板 UI 和 REST API
9090	TCP	Prometheus 指标（/metrics）
20000–20099	TCP	TCP 隧道端口范围（可通过 tcp_port_range 配置）
20100–20199	UDP	UDP 隧道端口范围（可通过 udp_port_range 配置）

---

配置文件参考（服务端）

键	类型	默认值	描述
server.domain	string	—	隧道 URL 的基础域名
server.http_port	u16	—	HTTP 边缘端口
server.https_port	u16	—	HTTPS 边缘端口
server.control_port	u16	—	WebSocket 控制平面端口
server.dashboard_port	u16	4040	控制面板端口
tls.cert_path	string	—	TLS 证书路径（PEM）
tls.key_path	string	—	TLS 私钥路径（PEM）
tls.acme_enabled	bool	false	启用内置 ACME 续期
tls.acme_email	string	""	ACME 联系邮箱
tls.acme_staging	bool	false	使用 Let's Encrypt 暂存 CA
tls.acme_account_dir	string	/var/lib/rustunnel	ACME 状态目录
tls.cloudflare_api_token	string	""	Cloudflare DNS API 令牌（建议使用环境变量 CLOUDFLARE_API_TOKEN）
tls.cloudflare_zone_id	string	""	Cloudflare Zone ID（建议使用环境变量 CLOUDFLARE_ZONE_ID）
auth.admin_token	string	—	主身份验证令牌
auth.require_auth	bool	—	拒绝未通过身份验证的客户端
auth.max_failed_auth_per_minute	int	10	每个源 IP 每分钟允许的身份验证失败次数，超过后将拒绝后续尝试（控制平面握手和控制面板 API）；0 表示禁用
database.url	string	—	PostgreSQL 连接 URL（必填）
database.captured_path	string	/var/lib/rustunnel/captured.db	用于存储已捕获 HTTP 请求正文的每区域 SQLite 文件
server.dashboard_origin	string	""	控制面板 UI 允许的 CORS 来源（例如 http://localhost:3000）
logging.level	string	—	trace / debug / info / warn / error
logging.format	string	—	json 或 pretty
logging.audit_log_path	string	null	审计日志路径（JSON 行）；省略则禁用
limits.max_tunnels_per_session	usize	—	每个已连接客户端的最大隧道数
limits.max_connections_per_tunnel	usize	—	每条隧道的最大并发连接数
limits.rate_limit_rps	u32	—	每条隧道的请求速率上限（请求/秒）
limits.ip_rate_limit_rps	u32	100	每个源 IP 的速率上限（请求/秒）；0 = 禁用
limits.request_body_max_bytes	usize	—	代理请求正文大小上限（字节）
limits.tcp_port_range	[u16, u16]	—	TCP 隧道端口范围，包含 [low, high]
limits.udp_port_range	[u16, u16]	[0, 0]	UDP 隧道端口范围，包含 [low, high]；[0, 0] 表示禁用 UDP 隧道
region.id	string	"default"	记录在隧道历史中的区域标识符（例如 "eu"、"us"、"ap"）
region.name	string	"Default"	控制面板中显示的易读区域名称
region.location	string	""	实际位置标签（例如 "Helsinki, FI"）

---

监控

Prometheus 指标端点位于 :9090/metrics：

rustunnel_active_sessions      # gauge: connected clients
rustunnel_active_tunnels_http  # gauge: active HTTP tunnels
rustunnel_active_tunnels_tcp   # gauge: active TCP tunnels

启动完整的监控栈（Prometheus + Grafana）：

make docker-run-monitoring
# Grafana:    http://localhost:3000  (admin / changeme)
# Prometheus: http://localhost:9090

生产环境提示： Grafana 的默认密码为 changeme。在生产环境中启动监控栈之前，请设置 GRAFANA_PASSWORD 环境变量：

export GRAFANA_PASSWORD=your-strong-password
make docker-run-monitoring

---

REST API

仪表板端口提供 REST API，可通过编程方式访问隧道、令牌、捕获的请求和隧道历史记录。除健康检查外，所有端点都需要 Authorization: Bearer <token> 标头。

/api/tunnels、/api/groups 及其隧道级子资源均按调用方进行范围限制：管理员令牌可以查看所有内容；用户范围的 API 令牌只能查看自己的隧道和分组；调用方无权查看的隧道会返回 404，而非 403。完整规则请参阅 docs/api-reference.md § Visibility scope。

快速参考

Method	Path	Description
GET	/api/status	健康检查（无需身份验证）
GET	/api/tunnels	列出活动隧道
GET	/api/tunnels/:id	获取单个隧道
DELETE	/api/tunnels/:id	强制关闭隧道
GET	/api/tunnels/:id/requests	捕获的 HTTP 请求
POST	/api/tunnels/:id/replay/:req_id	获取存储的请求以供重放
GET	/api/tokens	列出 API 令牌
POST	/api/tokens	创建 API 令牌
DELETE	/api/tokens/:id	删除 API 令牌
GET	/api/history	分页查看隧道历史记录

完整的请求／响应架构、查询参数和示例见 docs/api-reference.md。

可通过 GET /api/openapi.json 获取机器可读的 OpenAPI 3.0 规范（无需身份验证）。

---

AI Agent 集成（MCP 服务）

rustunnel 附带 rustunnel-mcp 二进制文件，可通过标准输入／输出实现 Model Context Protocol， 让 AI Agent（Claude、GPT-4o、自定义 Agent）无需手动操作即可打开和管理隧道。

兼容任何 MCP 框架。 Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Cline 和自定义 Agent 的可复制粘贴配置，以及一键安装程序，请参阅 Agent 集成指南：

./integrations/install.sh        # prompts for your token, writes the config

快速设置（Claude Desktop — 托管服务）

{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server", "edge.rustunnel.com:4040",
        "--api",    "https://edge.rustunnel.com:8443"
      ],
      "env": { "RUSTUNNEL_TOKEN": "<your-token>" }
    }
  }
}

只需设置一次 RUSTUNNEL_TOKEN，之后 Agent 调用工具时就无需再传入令牌。

可用工具

Tool	Description
create_tunnel	打开隧道并返回公共 URL — 支持 HTTP／TCP／UDP、P2P，以及带健康检查的负载均衡池
list_tunnels	列出所有活动隧道
close_tunnel	根据 ID 强制关闭隧道
list_regions	列出可用的服务区域
get_connection_info	返回供云端／沙盒 Agent 使用的 CLI 命令
get_tunnel_history	获取过去的隧道活动记录

安装

Homebrew（macOS 和 Linux） — 将 rustunnel-mcp 与 CLI 一同安装：

brew tap joaoh82/rustunnel
brew install rustunnel

从源代码构建：

make release-mcp
sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp

完整的设置指南、配置选项和工作流示例见 docs/mcp-server.md。

Claude Code 插件

这是在 Claude Code 中使用 rustunnel 最简单的方式。 安装插件后，它会自动处理所有 MCP 配置 — 只需输入一次令牌，然后让 Claude 暴露端口即可。

/plugin install rustunnel

启用插件时，它会提示输入服务地址和 API 令牌，安全地存储这些信息，并在后台启动 MCP 服务。无需编辑 .mcp.json，也无需手动设置。

插件目录： plugins/claude-code/ 文档： docs/claude-plugin.md

OpenClaw 技能

rustunnel 提供了一个 OpenClaw 技能，让任何兼容 OpenClaw 的 AI Agent 都能全面了解 rustunnel，包括配置文件格式、身份验证、工具签名和常见工作流，无需你额外说明。

技能文件： skills/rustunnel/SKILL.md

涵盖内容：

主题	详情
配置文件	位置（~/.rustunnel/config.yml）、格式、命名隧道
首次设置	rustunnel setup 向导或手动创建配置
MCP 工具	create_tunnel、list_tunnels、close_tunnel、get_connection_info、get_tunnel_history
工作流	Webhook 测试、演示共享、云沙箱（无需子进程）、命名隧道
安全性	令牌处理、文件权限、仅使用 HTTPS 传输

在 Claude Code 中加载技能：

/skills load skills/rustunnel/SKILL.md

加载后，你可以向 Agent 提出如下请求：

“使用 rustunnel 将我的本地端口 3000 暴露为 HTTPS 隧道。”

“列出我当前活跃的隧道，并关闭转发端口 5432 的隧道。”

“使用我的令牌设置 rustunnel 配置文件。”

该技能会指示 Agent 自动从 ~/.rustunnel/config.yml 读取凭据，因此每次调用时都不会提示你输入令牌。

---

路线图

已发布功能和未来计划工作的详细列表见 docs/ROADMAP.md。

---

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库，并从 main 创建一个功能分支。
2. 克隆后运行一次 make install-hooks，以启用推送前质量检查。
3. 进行修改。确保 make check（fmt + Clippy）和 make test 在本地通过。
4. 提交 Pull Request，清晰说明修改内容及原因。
5. CI 通过后，维护者会审核并合并。

指南

• 让 PR 聚焦于单一目标——每个 PR 只包含一项逻辑变更。
• 为任何新行为添加或更新测试。
• 遵循现有代码风格；CI 会强制执行 cargo fmt。
• 对于较大的变更或新功能，请先提交 issue 讨论实现方案。

---

许可证

本项目采用 GNU AGPLv3 License 许可，详情请参阅 LICENSE 文件。

---

联系方式

João Henrique Machado Silva

• GitHub： @joaoh82
• 项目：github.com/joaoh82/rustunnel
• 问题与功能请求：GitHub Issues