vtunnel

<div align="center"> <img src=".github/vtunnel-logo.svg" alt="vtunnel" width="440"> **在您的Cloudflare域名上暴露本地应用程序 — 拥有精致的CLI和TUI。** [](https://go.dev) [](https://charm.sh) [](https://github.com/valent1d/vtunnel/releases) ```bash vtunnel http 3000 dev → https://dev.example.com ``` <img src="site/demo.gif" alt="vtunnel demo — expose a local port, get a public URL, and inspect requests live" width="820"> </div> --- `vtunnel` 将 Cloudflare Tunnel 打造成一个愉快的日常本地开发体验。只需将通配符域名指向隧道一次，然后通过一条命令暴露任意本地端口，获得干净的公共网址 — 无需随机子域名，无需按座位定价，无需每次都重新配置 Cloudflare。 引导式向导设置所有内容，内置 TUI 仪表盘让您实时查看请求。 > **状态：测试版 — 正在积极开发中。** 每天的工作流程（`onboarding`、`http`、`list`、`logs`）已经稳定。在不常用的路径中可能会遇到一些问题，一些功能（服务、Keychain）目前仅限 macOS。 ## 工作原理 `vtunnel` 不会取代 `cloudflared` — 它位于 `cloudflared` 前面，使本地侧更加愉快。 ```txt Internet → Cloudflare 通配符 DNS (*.example.com) → Cloudflare Tunnel → cloudflared → vtunnel 本地代理 (127.0.0.1:8787) → localhost:<您的应用端口> ``` Cloudflare 和 `cloudflared` 配置 **一次**，使用通配符 ingress 规则。之后，暴露应用程序只需更改本地路由 — `vtunnel` 动态将每个公共主机名映射到本地端口。您的 Cloudflare 设置在日常基础上永远不会被触及。 ## 快速开始 **1. 安装。** 在 **macOS** 上，建议使用 Homebrew tap： ```bash brew install valent1d/tap/vtunnel ``` 在 **Linux**（或没有 Homebrew 的 macOS）上，使用安装脚本 — 它检测您的操作系统/架构，验证校验和，安装二进制文件： ```bash curl -fsSL https://vtunnel.valent1.dev/install.sh | sh ``` （`vtunnel` 还需要安装 `cloudflared` — 在 macOS 上使用 `brew install cloudflared`，或在 Linux 上使用您的发行版软件包 / [Cloudflare 的下载](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)。） **2. 运行引导设置：** ```bash vtunnel onboarding ``` 向导会引导您完成 11 个步骤 — 本地依赖、Cloudflare 认证、域名、隧道、通配符 DNS、本地 `cloudflared` 配置和运行时进程 — 并在途中修复可以修复的问题，最终提供一个准备好的摘要。 **3. 暴露本地应用程序：** ```bash vtunnel http 3000 dev ``` 这将启动本地守护进程，确保 `cloudflared` 正在运行，并将 `localhost:3000` 服务于 `https://dev.<您的域名>`，同时实时跟踪其请求日志。 ## 每天的命令 | 命令 | 功能 | | --- | --- | | `vtunnel http 3000 dev` | 在 `dev.<域名>` 暴露 `localhost:3000` | | `vtunnel http` | 打开请求仪表盘（TUI） | | `vtunnel list` | 列出活动路由 | | `vtunnel logs dev` | 显示请求日志（`-f` 跟随） | | `vtunnel stop dev` | 删除路由 | | `vtunnel orbstack` | 暴露 OrbStack 容器（打开仪表盘创建模式） | | `vtunnel status` | 显示守护进程和配置状态 | | `vtunnel service install` | 在登录时自动启动 vtunnel（macOS） | | `vtunnel uninstall` | 删除服务、配置和（可选）Cloudflare 资源 | | `vtunnel --help` | 显示每个命令和标志 | ### 暴露应用程序 ```bash vtunnel http 3000 dev # → https://dev.<默认域名> vtunnel http 5173 app --domain example.dev # 选择特定域名 vtunnel http 3000 dev --detach # 创建路由并返回（无日志尾部） ``` 第一个参数也可以是完整的 URL 或 `host:port`，因此您可以转发到任何 HTTP 上游 — 另一台机器、虚拟机、NAS — 而不仅仅是本地端口： ```bash vtunnel http http://192.168.1.10:8080 nas # 转发到任何主机 vtunnel http 3000 dev --target http://web.local:8080 # 或通过 --target ``` ### OrbStack 容器（仅限 MacOS） 如果您使用 [OrbStack](https://orbstack.dev)，`vtunnel` 直接暴露 Docker 容器。每个容器在其主机上都可以通过其 `<name>.orb.local` 域名访问，`vtunnel` 直接转发到它。 ```bash vtunnel orbstack # 交互式 TUI → 选择、命名、访问、暴露 vtunnel orbstack list # 列出正在运行的容器 vtunnel orbstack expose my-container # 暴露容器 vtunnel orbstack expose my-container my-app # …使用您自己的子域名 vtunnel orbstack watch # 自动暴露容器，当它们来来去去时 ``` 子域名默认为容器的自定义域名（`dev.orbstack.domains` 标签）或其名称。暴露打开了聚焦于新路由的仪表盘，OrbStack 支持的隧道带有 `⬡` 徽章和紧凑的 OrbStack 详情卡。 `vtunnel orbstack watch` 使您的路由与正在运行的容器同步：每个 HTTP 容器都获得一个路由，当其容器停止时，路由被删除。它只管理它创建的路由 — 手动路由保持不变。 ### 仪表盘 ```bash vtunnel http # 无端口 → 打开 TUI 仪表盘 ``` 仪表盘列出了您的活动路由，并流式传输传入的请求，以便您无需离开终端即可检查流量。 按 `enter` 查看请求的详情：完整的请求和响应 **头和正文**（每个捕获高达 64 KiB）。从那里，按 `r` **重放** 请求到您的本地应用程序 — 在不重新触发发送者的情况下，迭代 webhook（Stripe、GitHub、…）非常方便。 ### 日志 ```bash vtunnel logs # 所有路由 vtunnel logs dev # 一个路由 vtunnel logs dev --follow # 实时日志 vtunnel logs --limit 100 # 更多历史记录 ``` ## 使用 Cloudflare Access 保护路由 默认情况下，暴露的路由是公开的。 [Cloudflare Access](https://www.cloudflare.com/zero-trust/products/access/) （Zero Trust）在 **边缘** 放置了一个登录页面 — 在流量到达您的本地应用程序之前 — 只有您允许的人才能进入。它对最多 50 个用户免费。 ```bash vtunnel access setup # 引导式一次性 Zero Trust 启用 vtunnel cloudflare auth --access # 授予 vtunnel 一个 Access-write token vtunnel access status # Zero Trust 状态、身份提供者、受保护的路由 vtunnel http 8080 admin --protect --allow you@example.com # 电子邮件一次性 PIN vtunnel http 8080 admin --protect=sso --idp "My IDP" # SSO（允许可选） vtunnel access protect admin --allow @example.com # 保护现有路由 vtunnel access pause admin # 暂时公开（保留配置）· 恢复以重新启用 vtunnel access unprotect admin # 返回公开 vtunnel access idp list # 身份提供者 vtunnel access idp add authentik --issuer https://auth.example.com/application/o/cf/ \ --client-id … --client-secret … # OIDC（自动发现端点） vtunnel access idp add google --apps-domain example.com --client-id … --client-secret … ``` 您也可以从 **HTTP 仪表盘** 管理所有这些：按 `a` 进入路由的 Access 面板（选择公共 / SSO / OTP，挑选身份提供者，设置谁被允许，暂停/恢复），并且“新建隧道”表单有一个保护步骤，以便您在创建路由时保护它。 - **`--protect` / `--protect=otp`** — 电子邮件一次性 PIN（不需要身份提供者）。 `--allow` 是必需的（电子邮件或 `@domain`）。对于单个人的路由，只需允许一个电子邮件。 - **`--protect=sso`** — 使用身份提供者（ `--idp <name>` ）; Authentik（OIDC）和 Google Workspace 目前受支持。 `--allow` 是可选的 — 保留它以允许任何通过该提供者登录的人，或使用 `@domain` 缩小范围。 保护在路由 **发布之前** 创建，如果发布失败，则回滚。受保护的路由在仪表盘中显示一个 🔒 徽章。 如果您必须先启用 Zero Trust，`vtunnel access status` 将引导您完成一次性仪表盘步骤。 > 首次 Zero Trust 激活（选择团队名称和计划）只在 Cloudflare 仪表盘上进行一次 — 附加提示，Cloudflare 需要一张卡，即使在免费计划上，您也不会被收费。 ## TCP 隧道（数据库、SSH、…） `vtunnel` 还可以通过同一个 Cloudflare Tunnel 暴露 **TCP** 服务（Postgres、MySQL/MariaDB、SSH、Redis…）。 > **重要 — TCP 不像 HTTP 那样零安装。** 浏览器使用 HTTP，因此 HTTP 路由适用于任何具有链接的人。数据库/SSH 客户端使用原始协议，Cloudflare 的边缘仅在其 Web 端口上提供 HTTP 服务 — 在免费计划上没有公共的 `db.example.com:5432` 可以拨号。因此，**连接的机器** 必须使用 `cloudflared` 将原始 TCP 封装到隧道中（这就是 `vtunnel tcp connect` 所做的）。使用 TCP 隧道从另一台机器访问您自己的服务，或给予可以安装 `cloudflared` 和 `vtunnel` 的队友访问权限 — 而不是匿名、无需安装的访问权限。 **在具有服务的机器上** （并运行隧道）： ```bash vtunnel tcp # 打开 TCP 仪表盘（列表 / 新建 / 删除） vtunnel tcp 5432 db # 在 db.<域名> 暴露 localhost:5432 vtunnel tcp 192.168.1.10:22 ssh # …或任何主机:端口 vtunnel orbstack expose db-container --tcp # OrbStack 容器的端口（例如 MariaDB） vtunnel tcp list # 列出 TCP 隧道 vtunnel tcp rm db # 删除一个 ``` 添加或删除 TCP 隧道 **重启 cloudflared** 以应用更改，这会短暂地重新连接所有隧道（包括 HTTP）。 **在想要连接的机器上** （需要安装 `cloudflared` 和 `vtunnel`）： ```bash vtunnel tcp connect db --port 5432 # 打开 127.0.0.1:5432，保持运行 psql -h 127.0.0.1 -p 5432 … # 然后将您的客户端指向本地端口 ``` （`vtunnel tcp connect` 封装了 `cloudflared access tcp` ； `--port` 默认值为服务的端口。） ## 浏览器中的 SSH（零安装） 对于 SSH，特别是有一个比 TCP 隧道更好的选择： **`vtunnel ssh`** 在 **浏览器中渲染一个完整的 SSH 终端**。访问者打开一个 URL，通过 Cloudflare Access 登录页面登录，并获得一个终端 — **无需 SSH 客户端和无需 `cloudflared`** 在他们这边。Cloudflare 在其边缘渲染会话。 ```bash vtunnel ssh # 打开浏览器-SSH 仪表盘（列表 / 新建 / 删除） vtunnel ssh box --allow you@example.com # localhost:22 → https://box.<域名> vtunnel ssh box --allow @example.com --target 192.168.1.10:22 vtunnel ssh box --allow you@example.com --idp My-idp # SSO 代替电子邮件 OTP vtunnel ssh list # 列出浏览器 SSH 端点 vtunnel ssh rm box # 删除一个（也删除其 Access 应用） ``` `--allow` 是 **必需的**：浏览器 SSH 始终由 Cloudflare Access 登录保护，并且每个登录用户的 **电子邮件前缀必须与其在服务器上的 SSH 用户名匹配** （例如， `you@example.com` 登录为 `you` ）。登录默认使用电子邮件一次性 PIN；传递 `--idp <name>` 使用 SSO（[参见 Access](#protect-routes-with-cloudflare-access)）。这需要启用 Zero Trust。 > 正因为如此，当您运行 `vtunnel tcp 22 …` （或任何端口 22）时，vtunnel 会注意到它是 SSH 并提供设置浏览器 SSH 代替。选择 **yes**，它会引导您完成此过程；选择 **no** 以保留纯 TCP 隧道。选中 *不再询问我* 以静默提示（存储为 `prefs.suppress_ssh_suggestion` 在配置文件中）。 ## 与 Claude Code 及其他 AI 代理（MCP）一起使用 `vtunnel` 配备了一个内置的 **模型上下文协议** 服务器，以便 AI 代理可以为您创建和检查隧道 — 例如， *"为我的 Stripe webhook 创建一个公共 URL，并向我展示 Stripe 发送的内容。"* ### 连接到您的编辑器/代理 运行 **`vtunnel mcp`** 以打开一个仪表盘，注册您的 AI 客户端，显示已配置的客户端，并让您添加/删除它并验证它是否正常工作： ```bash vtunnel mcp # 仪表盘：添加/删除每个客户端，自我检查 vtunnel mcp add # 在每个已安装的客户端中注册（非交互式） vtunnel mcp add cursor codex # …或特定的客户端 vtunnel mcp status --check # 已配置的客户端 + 启动服务器以确认其响应 vtunnel mcp remove cursor # 注销 ``` 支持的客户端（每个客户端存储在其自己的位置/格式中，由您处理）： **Claude Code, Cursor, VS Code, Codex, OpenCode, Antigravity**。注册默认为 **用户/全局** 范围；传递 `--scope project` 以写入当前存储库。 在幕后，每个客户端都指向 `vtunnel mcp serve` （stdio 服务器）。它公开了： | 工具 | 功能 | |------|--------------| | `create_http_tunnel` | 创建一个 **公共** HTTPS 隧道到本地端口并返回其 URL — 适用于 webhook。 | `list_tunnels` | 列出活动隧道（主机名、URL、目标、是否受 Access 保护）。 | `stop_tunnel` | 删除隧道（并拆除其 Access 保护，如果有）。 | `protect_tunnel` | 在隧道前添加 Cloudflare Access 登录页面（电子邮件 OTP 或 SSO）。 | `unprotect_tunnel` | 再次使隧道公开。 | `inspect_requests` | 列出最近捕获的请求，或获取一个请求的全部信息（头和正文） — 用于调试负载。 | `replay_request` | 将捕获的请求重新发送到您的上游（重放 webhook，同时您修复处理程序）。 它还发布了一个 `vtunnel://requests` 资源（最近捕获的请求作为 JSON）。 > **注意：** `create_http_tunnel` 创建一个 **公共** URL — 任何拥有链接的人都可以访问本地服务。对于其他情况，请使用 `protect_tunnel`、`vtunnel access protect` 或仪表盘进行保护。vtunnel 必须已经设置（一个隧道 + 域名）；MCP 服务器根据需要启动 cloudflared 和守护进程。 ## 一次性设置 大多数人只需运行 `vtunnel onboarding`，而无需触及此部分。如果您更喜欢自己驱动设置，`vtunnel setup` 运行相同的诊断并应用修复，带有显式标志（默认打印干燥运行计划）。 添加一个或多个域名： ```bash vtunnel setup --domain example.com ``` 连接原生 `cloudflared` 凭证（创建 `~/.cloudflared/cert.pem`）： ```bash vtunnel cloudflared login vtunnel cloudflared status ``` 应用本地 `cloudflared` ingress 规则（首先创建时间戳备份）： ```bash vtunnel setup --domain example.com --write-cloudflared ``` 修复缺少的隧道或通配符 DNS： ```bash vtunnel setup --fix-tunnel # 重新创建隧道并更新本地配置 vtunnel setup --fix-dns # 将通配符 DNS 指向隧道 ``` 启动 `cloudflared` 并配置隧道： ```bash vtunnel setup --start-cloudflared ``` `vtunnel` 管理的预期 `cloudflared` ingress 形状： ```yaml ingress: - hostname: "*.example.com" service: http://127.0.0.1:8787 - service: http_status:404 ``` ### 可选：Cloudflare API 访问 为了更安全的 DNS 验证和修复，`vtunnel` 可以使用 Cloudflare API token： ```bash vtunnel cloudflare auth # 打开预填充的 token 模板，然后存储它 vtunnel cloudflare status # 只读发现帐户、区域、DNS ``` 该令牌存储在 macOS 钥匙串中，完全可选 — 隧道通过 `cloudflared` 和 `cert.pem` 发现，而不是 API 令牌。DNS 修复在没有令牌的情况下回落到 `cloudflared tunnel route dns`。 ## 在登录时运行（macOS 和 Linux） 安装 `vtunnel` 和 `cloudflared` 作为用户 LaunchAgents / Linux systemd 服务，以便它们在启动时自动启动： ```bash vtunnel service install vtunnel service status ``` 在 **macOS** 上，这会将 LaunchAgents（`sh.vltn.vtunnel.daemon`、`sh.vltn.vtunnel.cloudflared`）写入 `~/Library/LaunchAgents/`，并使用 `launchctl` 管理它们。在 **Linux** 上，它会将 systemd **用户** 单元写入 `~/.config/systemd/user/`，并使用 `systemctl --user` 管理它们。无论哪种方式，它们在您登录时都会自动启动。 > 在无头 Linux 服务器上，运行 `loginctl enable-linger "$USER"` 一次，以便用户服务在没有活动登录会话的情况下继续运行。 ```bash vtunnel service start vtunnel service stop vtunnel service uninstall ``` 您也可以直接驱动守护进程，而无需服务： ```bash vtunnel daemon stop vtunnel daemon restart ``` ## 卸载 `vtunnel uninstall` 会拆除它安装的所有内容 — LaunchAgents、本地配置文件和 Keychain 令牌 — 并在删除任何内容之前显示计划： ```bash vtunnel uninstall # 交互式；打印计划，然后确认 vtunnel uninstall --dry-run # 预览将删除的内容，不更改任何内容 vtunnel uninstall --keep-config # 删除服务，但保留您的配置 + 令牌 vtunnel uninstall --cloudflare # 还删除隧道和通配符 DNS 记录 ``` 您的 Cloudflare 帐户默认情况下不会被 `vtunnel` 触及 — 传递 `--cloudflare` 以删除隧道、通配符 DNS 和 `vtunnel` 创建的任何 Access 应用程序。二进制文件本身可以使用 `brew uninstall vtunnel` 单独删除。（停止受保护的路由与 `vtunnel stop` 也会删除其 Access 应用程序。） ## 配置 默认路径： ```txt ~/.config/vtunnel/config.yml ~/.config/vtunnel/routes.json ~/.config/vtunnel/logs/requests.jsonl ``` `config.yml` 示例： ```yaml default_domain: example.com domains: - example.com proxy: listen: 127.0.0.1:8787 api: listen: 127.0.0.1:8788 cloudflared: tunnel_name: example config_path: ~/.cloudflared/config.yml ``` 出于安全原因，本地代理和 API 必须绑定到 `127.0.0.1`。 ## 平台支持 `vtunnel` 在 **macOS 和 Linux** 上运行。每个平台特定的部分都有一个原生后端： | | macOS | Linux | |---|---|---| | 安装 | Homebrew tap | `install.sh`（curl） | | 后台服务 | LaunchAgents（`launchctl`） | systemd 用户服务（`systemctl --user`） | | 令牌存储 | 钥匙串 | 配置目录中的 `0600` 文件 | | 剪贴板/打开 URL | `pbcopy` / `open` | `xclip`/`xsel`/`wl-copy` / `xdg-open` | 核心 — 代理、守护进程、路由、请求日志、MCP 服务器 — 是共享的。OrbStack 容器发现仍然仅限 macOS（OrbStack 是 Mac 独有的；如果在 Linux 上，请直接使用 Docker 守护进程）。在无头 Linux 上，`systemctl --user` 可能需要 `loginctl enable-linger <user>` 以使服务在没有活动会话的情况下运行。 ## 构建工具 - **[Go](https://go.dev)** — 一个静态二进制文件，无需安装运行时 - **[Cobra](https://github.com/spf13/cobra)** — 命令行框架 - **[Bubble Tea](https://github.com/charmbracelet/bubbletea)**、 **[Lip Gloss](https://github.com/charmbracelet/lipgloss)** 和 **[Bubbles](https://github.com/charmbracelet/bubbles)** — 引导程序和 TUI 仪表盘背后的 [Charm](https://charm.sh) 堆栈 --- <div align="center"> _{vltn.sh 的 vtunnel} </div>