Skip to content

About

Local HTTP&WebSocket Free Tunnel To Public SubDomain - https://httptunnel.top

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

English | 简体中文

http-tunnel icon

http-tunnel

一个用 Rust 编写的 HTTP / WebSocket 隧道系统,将本地服务安全暴露到公网子域名。

Rust Protocol Runtime Storage

http-tunnel 由两个二进制组成:

  • http-tunnel-server:公网入口、管理后台、隧道调度、请求日志和运维 API。
  • http-tunnel-client:运行在本地网络中,连接 server 并把请求转发到本地目标服务。

典型链路:

https://<subdomain>.<domain>
  -> http-tunnel-server
  -> persistent WebSocket tunnel
  -> http-tunnel-client
  -> http://127.0.0.1:<port>

项目只支持二进制运行路径,不维护容器镜像或编排运行方式。当前目标是可靠的 HTTP / WebSocket 隧道、单机自托管运维和可审计的管理能力;不实现原始 TCP 隧道、SSH 反向转发、Caddy 集成、OAuth、多用户/团队系统。

特性

  • 通过公网子域名访问本地 HTTP 服务,支持 GET/POST、大请求体、SSE 流式响应和 WebSocket 升级。
  • 客户端自动重连,支持本地运行态文件、status --watch、disconnect、doctor 和纯 NDJSON 事件输出,方便交给进程管理器托管。
  • / 提供公开只读 dashboard,以表格和来源地图展示隧道状态、公开地址、会话、请求、流量、最近活跃和过期时间。
  • 管理后台内置 setup/login、隧道列表、会话管理、请求/事件/审计日志、诊断包、告警、备份、维护、升级和重启入口。
  • Web UI 使用 Next.js static export、Tailwind CSS、shadcn/ui 风格组件、Tremor 指标组件和 Lucide/Fluent 图标,构建后嵌入 server binary。
  • 支持隧道级访问控制:公开访问、Bearer、Basic Auth、方法白名单、路径前缀阻断、每隧道限流和可选 Inspector 请求预览/重放。
  • 支持单连接替换/拒绝、轮询和 least-loaded 多客户端会话池,并在断开或替换前发送协议级 GOAWAY 以尽量排空进行中的请求。
  • 公开创建隧道可关闭、可使用管理员生成的创建令牌保护、可按 IP 限制活跃隧道数量,并可接入 Cloudflare Turnstile。
  • /metrics 默认受保护,支持管理员认证、可信直连来源、专用 metrics bearer token 或显式公开。
  • /api/v1/health 用于存活检查,/api/v1/ready 用于 setup 完成和 SQLite 可用性检查。
  • 配置、诊断和审计路径统一遮蔽密码、secret、token 和 hash 等敏感信息。
  • 升级流程解析 GitHub release 资产,要求 SHA256 校验文件,下载后先校验再执行 --help 探测和二进制替换。
  • 可选根域路径 GitHub Proxy Server,通过 https://<domain>/gh/... 对外代理 GitHub 下载和 raw 文件,支持白名单、黑名单、直连旁路和 jsDelivr raw 文件重写。

快速开始

先构建前端静态资源并编译二进制:

./build.sh

启动 server:

./target/release/http-tunnel-server

如需使用非特权端口运行:

./target/release/http-tunnel-server serve --port 8080

首次启动后打开:

http://<server>/admin/setup

完成管理员密码、域名、公网协议、监听地址、数据库地址等初始化配置。

创建客户端配置:

http-tunnel-client config init
http-tunnel-client config set \
  --server https://example.com \
  --target http://127.0.0.1:3000 \
  --subdomain demo \
  --ttl-seconds 3600

启动隧道:

http-tunnel-client connect

也可以不写配置,直接用命令行参数覆盖:

http-tunnel-client connect \
  --server https://example.com \
  --subdomain demo \
  --target http://127.0.0.1:3000 \
  --ttl-seconds 3600

--ttl-seconds 用于限制本次 tunnel 暴露时长。到期后 server 会删除该 tunnel,并通知 client 进程退出;通过配置或命令行修改 TTL 会清除本地保存的 tunnel token,并重新创建 tunnel。

访问:

https://demo.example.com

本地验证

开发和发布前建议执行:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
./build.sh

基础 smoke:

curl http://127.0.0.1/api/v1/health
curl http://127.0.0.1/api/v1/ready
curl -H 'Host: demo.example.com' http://127.0.0.1/

长时间 reconnect / HTTP / SSE / WebSocket 行为可以手动运行被忽略的非 UI smoke-soak harness:

cargo test -p http-tunnel-server --test e2e_http \
  smoke_soak_harness_exercises_http_sse_websocket_and_reconnect -- --ignored

运维能力

管理后台默认位于 /admin,首次初始化位于 /admin/setup。登录后可以完成:

  • 管理隧道生命周期:启用、禁用、延长 TTL、立即过期、断开、删除、轮换隧道 token。
  • 查看请求、事件、审计日志,按条件过滤分页,并导出 CSV。
  • 查看请求详情、隧道详情、运行中 session、Inspector 预览和可重放请求。
  • 管理管理员 session,撤销单个 session 或撤销除当前外的全部 session。
  • 轮换或清理创建隧道 token、metrics token、Turnstile secret。
  • 下载诊断包,查看告警,执行 SQLite WAL checkpoint、ANALYZE、VACUUM 和清理任务。
  • 创建备份,在线校验备份,离线恢复配置和数据库。
  • 查看 release 升级状态,下载带 SHA256 校验的 server 二进制并请求重启;自动升级会等待代理流量空闲窗口。

关键配置

默认情况下,server 配置、SQLite 数据库和本地数据文件会保存在 $HOME/.http-tunnel,client 配置和运行态文件也使用同一个目录。常见配置项会保存到 $HOME/.http-tunnel/server.toml,也可通过命令行参数或环境变量覆盖。公开 dashboard 的地图使用国家级热力图,不暴露精确坐标;Cloudflare proxy 场景只读取可信代理传入的 CF-Connecting-IP / X-Forwarded-For 来识别 client IP。国家信息只采用 client 注册时主动上报并每小时刷新的 country 数据,server 不读取代理国家 header,也不根据 IP 本地解析国家。更完整的字段说明见 Admin 文档 和 Security 文档。

领域 配置
公网入口 domain、public_scheme、addr、trust_proxy_headers、trusted_proxy_cidrs
隧道行为 tunnel_ttl_seconds、max_body_bytes、max_concurrent_streams、request_timeout_seconds
会话池 session_pool_policy、heartbeat_interval_seconds、stale_session_seconds
安全 public_tunnel_create_enabled、tunnel_create_bearer_token_hash、metrics_public、metrics_bearer_token_hash、turnstile_secret
日志维护 request_log_retention_days、event_retention_days、session_retention_days、cleanup_interval_seconds
升级重启 release_repo、release_tag、github_proxy、auto_upgrade_enabled、systemd_unit
GitHub Proxy Server github_proxy_server_enabled、github_proxy_server_path_prefix、github_proxy_server_size_limit_bytes、github_proxy_server_request_timeout_seconds、github_proxy_server_jsdelivr、github_proxy_server_white_list、github_proxy_server_black_list、github_proxy_server_pass_list

github_proxy 只用于 server 自升级下载时借用外部 GitHub 代理;github_proxy_server_* 是本 server 对外提供根域路径 GitHub 代理能力,默认关闭,开启后要求 server 自身能直连 GitHub。

GitHub Proxy Server

开启 github_proxy_server_enabled = true 后,server 会在根域路径上提供 GitHub 代理,默认入口是 /gh:

https://example.com/gh/https://github.com/owner/repo/releases/download/v1.0/app.tar.gz
https://example.com/gh/github.com/owner/repo/archive/refs/heads/main.zip
https://example.com/gh/raw.githubusercontent.com/owner/repo/main/file.txt

/gh?q=https://github.com/... 会重定向到规范的 /gh/<target> 路径。该能力只处理根域 example.com 或 www.example.com 请求;子域名上的 /gh/... 仍按普通 tunnel 代理转发,避免和业务隧道路由混淆。github_proxy_server_path_prefix 默认为 /gh,不能使用 /api、/admin、/metrics、/_next 等保留路径,修改后需要重启 server。

支持的上游包括 GitHub release/archive、github.com/<owner>/<repo>/blob|raw/...、Git smart HTTP service、raw.githubusercontent.com 文件和 gist raw 文件。github_proxy_server_white_list、github_proxy_server_black_list、github_proxy_server_pass_list 使用 owner、owner/repo 或 */repo 规则;白名单存在时必须命中,黑名单命中时拒绝,pass list 命中时直接重定向到上游而不经 server 代理。开启 github_proxy_server_jsdelivr = true 时,raw/blob 文件会重定向到 jsDelivr。

这项功能是对外提供 GitHub Proxy Server 能力,不参与 http-tunnel 自升级。若 server 所在环境无法直连 GitHub,需要继续通过 github_proxy 配置一个外部 GitHub 代理供自升级下载使用。

文档

About

Local HTTP&WebSocket Free Tunnel To Public SubDomain - https://httptunnel.top

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages