内容
# volter-tunnel
[](https://github.com/volter-ai/volter-tunnel/actions/workflows/ci.yml)
[](./LICENSE)
一个开源的、基于WebSocket的 **HTTP/WS反向隧道** — 一个ngrok / Cloudflare-Tunnel替代品，其主要特点是提供一个 **免费、稳定、可预留的子域名**，该子域名在重新连接后仍然有效。 该项目基于Cloudflare Workers + Durable Objects构建，因此空闲隧道的成本几乎为零。
📖 **文档:** <https://volter-ai.github.io/volter-tunnel/>
```bash
volter-tunnel login --host https://your-relay # GitHub登录，无OAuth应用
volter-tunnel --port 3000 --tunnel-id my-app # → https://my-app.your-relay
```
**为什么存在：** 预留一个友好的子域名并保持不变；通过HTTP、流和WebSocket公开本地端口；使用基本身份验证/JWT进行权限控制；将隧道应用嵌入iframe（它会剥离`frame-ancestors`/X-Frame-Options — 其他OSS隧道不执行此操作）；实时检查每个请求。 有关完整的原因，请参见 [dev-docs/DECISIONS.md](./dev-docs/DECISIONS.md)。
## 安装
```bash
bun add @volter/tunnel # 客户端库 + CLI（在Bun下运行）
```
## CLI
```bash
volter-tunnel login [--gist] [--host <url>] # 验证GitHub身份，保存API令牌
volter-tunnel --port 3000 [--tunnel-id my-app] # 公开本地端口；打印URL（+二维码）
volter-tunnel whoami # 您的账户 + 使用情况
volter-tunnel usage [--json] # 当前花费（今日 / 本月）
volter-tunnel account <list|usage|create|limits|suspend|resume> [slug] \
[--day-usd N] [--month-usd N] # 管理操作（需要根令牌）
```
常见运行标志： `--host <relayUrl>`， `--basic-auth user:pass`， `--auth-not-required`， `--no-qr`。
## 库
```ts
import { createTunnel } from '@volter/tunnel/client';
const tunnel = await createTunnel({
port: 3000,
host: 'https://your-relay',
tunnelId: 'my-app', // → https://my-app.your-relay
});
console.log(tunnel.url);
// … 稍后
tunnel.close();
```
以及用于中继的管理/自助服务的API的typed客户端：
```ts
import { VolterClient } from '@volter/tunnel/client';
const client = new VolterClient({ host: 'https://your-relay', token });
const me = await client.whoami(); // { slug, name, usage }
await client.createAccount({ slug: 'x', dayUsd: 10 }); // 根令牌
```
## MCP服务器（用于AI代理）
`@volter/tunnel-mcp` 公开账户/使用情况/滥用操作作为MCP工具（`whoami`，`usage`，`account_*`，`reports`，`waitlist`，`revoke_reservation`）：
```bash
VOLTER_HOST=https://your-relay VOLTER_TOKEN=<token> bunx @volter/tunnel-mcp
```
## 架构
一个具有共享协议合约的monorepo，由双方使用：
```
packages/core/ @volter/tunnel-core — 线协议（消息联合 + 帧编解码 + DTO）。纯净，无依赖，100%覆盖。
client/ @volter/tunnel — 核心 ← 传输 ← SDK（createTunnel + VolterClient）← CLI（二进制文件）。
packages/mcp/ @volter/tunnel-mcp — 基于SDK的MCP服务器。
server-cf/ Cloudflare Worker + Durable Objects 中继（主要）。一个DO对应一个tunnelId，持有可休眠的控制套接字 → 空闲 = 免费。
```
协议存在于 `core` 而非其他地方，因此客户端和中继不会漂移 — 对协议的更改在双方都会进行类型检查。
## 在本地运行中继
要尝试使用没有托管帐户的隧道，请在本地运行中继，并将客户端指向它：
```bash
cd server-cf && npm install && npm run dev # wrangler dev --local （实际workerd）
# 然后，在另一个shell中：
volter-tunnel --port 3000 --host http://127.0.0.1:8787 --auth-not-required
```
> 包通过 `bun run build` 构建为Node可消费的JS，并在版本标签上发布。 请参阅 [dev-docs/PUBLISHING.md](./dev-docs/PUBLISHING.md)。
## 开发
```bash
bun install
bun run typecheck # 客户端 + 核心 + MCP
cd packages/core && bun test # 协议（100% 门控）
cd packages/mcp && bun test # MCP工具
bun test ./test # 客户端SDK + CLI
cd server-cf && npm install && npx vitest run # 中继（实际workerd，无模拟）
```
请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 使用 **自托管指南**（源码：[docs/self-hosting/deploy.md](./docs/self-hosting/deploy.md)）部署您自己的中继。
## 许可证
[Apache-2.0](./LICENSE) © Volter.
