一、项目定位与设计目标

pipenet 是一款将本地 HTTP 服务即时暴露到公网的隧道代理工具，由 glama.ai 开发并开源。其核心目标是为本地运行的 Model Context Protocol (MCP) 服务器提供零配置的公网可达能力，该能力已集成到 mcp-proxy 项目中。资料来源：README.md

项目支持任意基于 HTTP 的协议，包括 HTTP/HTTPS 请求响应、WebSocket 全双工通信、Server-Sent Events 长连接以及分块传输（HTTP Streaming）。资料来源：README.md

相较于其前体 localtunnel，pipenet 提供了三项关键差异：云部署下的单端口模式（--tunnel-port）、多域名支持（--domain 可重复指定）、以及完全的 TypeScript + ESM 重写并附带完整类型定义。资料来源：README.md

二、运行时拓扑与数据流

pipenet 同时提供客户端与服务器两端代码，二者通过 npm 子导出分离：根导出 ./ 暴露 pipenet、Tunnel、TunnelCluster，./server 暴露 createServer 工厂。资料来源：package.json

整体数据流如下：

sequenceDiagram
    participant U as 互联网用户
    participant S as pipenet 服务器 (Koa)
    participant TS as TunnelServer (可选)
    participant CM as ClientManager
    participant C as 本地 pipenet 客户端
    participant L as 本地 HTTP 服务
    U->>S: HTTP 请求 (子域名)
    S->>CM: 路由到对应 Client
    CM->>C: 通过长连接回传
    C->>L: 转发到本地 port
    L-->>C: HTTP 响应
    C-->>S: 原路返回
    S-->>U: 返回响应

客户端组件

• 入口函数 pipenet(port | opts, [cb]) 创建 Tunnel 实例，未指定 host 时默认指向 https://pipenet.dev。资料来源：src/pipenet.ts src/Tunnel.ts
• Tunnel 通过 _init 流程向远端注册，获取子域名、最大连接数 (maxConn)、远端地址/端口后建立 TunnelCluster。资料来源：src/Tunnel.ts
• TunnelCluster 与远端维持长连接，使用 HeaderHostTransformer 改写 Host 头，并通过 pump 在 maxConn 条 socket 上并行转发公网到本地的流量。资料来源：src/TunnelCluster.ts

服务器组件

• createServer(opt) 工厂创建 PipenetServer，内部实例化 ClientManager 与可选的 TunnelServer（仅在传入 tunnelPort 时启用）。资料来源：src/server/server.ts
• ClientManager 负责子域名前缀解析、客户端注册与统计信息维护，并按需创建 Client 与 TunnelAgent。资料来源：src/server/ClientManager.ts
• Client 通过 pump 将 http.IncomingMessage 与 TunnelAgent 提供的 socket 双向桥接，并提供 1 秒离线宽限期（graceTimeout）。资料来源：src/server/Client.ts

三、运行模式与配置接口

pipenet 支持两种主要运行模式：

1. 默认模式：每个客户端在远端分配一个随机 TCP 端口，适用于本地开发与单机部署。资料来源：README.md
2. 共享隧道模式：服务器启动时传入 --tunnel-port，所有客户端共享同一固定端口，便于在 Docker、fly.io、Kubernetes 等仅暴露有限端口的容器环境中部署。资料来源：README.md src/server/server.ts

配置入口分为两端：

• 服务器通过 ServerOptions 传入 domains、landing、maxTcpSockets、secure、tunnelPort 等字段。资料来源：src/server/server.ts
• 客户端通过 TunnelOptions 配置 port、subdomain、localHost、localHttps、localCert/Key/Ca、allowInvalidCert 等字段。资料来源：src/TunnelCluster.ts src/Tunnel.ts

CLI 通过 bin 字段注册 pipenet 入口，提供 client 与 server 两个子命令；服务器也可通过 npm run start:server 启动。资料来源：package.json

四、依赖、测试与版本演进

项目声明 engines.node >= 22.0.0，使用 [email protected] 作为包管理器，并通过 semantic-release 自动发布。核心依赖包括 axios（注册请求）、koa+koa-router（服务器路由）、ws+pump（流桥接）、yargs（CLI 解析）、tldjs（子域名解析）、debug（结构化日志）、human-readable-ids（默认子域名前缀生成）。资料来源：package.json

测试使用 vitest，覆盖 src/**/*.spec.ts，并显式排除 dist 与 server 目录中可能引入的端到端依赖；build 调用 tsc，lint 脚本同时运行 eslint 与 knip 检测未使用代码。资料来源：package.json vitest.config.ts

近期版本变更体现了架构持续演进：

社区提示：早期版本（v1.0.1）的 npx pipenet client --port 3303 存在返回 404 后立即退出的问题（见 issue #1）。该问题已在 1.2.x – 1.4.x 系列中得到修复：v1.4.2 增加了 4XX 中止保护，v1.4.1 修复了重连泄漏，CLI 进程因此可以稳定保持为前台服务。

See Also

• 客户端与服务器代码索引：src/pipenet.ts、src/server/server.ts
• 协议支持与 CLI 用法：README.md
• 完整版本变更：GitHub Releases

概述

pipenet 客户端组件负责将本地 HTTP 服务透明地暴露到公网，支持 HTTP/HTTPS、WebSocket、SSE（Server-Sent Events）以及 HTTP Streaming 协议 README.md。它既可以作为一个独立的命令行工具（pipenet client）使用，也可以作为一个无依赖的 JavaScript 库被嵌入到测试脚本、CLI 工具（如 mcp-proxy）或自动化流程中 README.md。客户端通过 HTTP 请求向 pipenet 服务器申请一个公共子域名，建立长连接隧道后将公网流量反向代理到本地端口 src/Tunnel.ts。

CLI 使用

通过 npx 或全局安装后即可调用 pipenet 命令行工具 package.json。CLI 入口在 src/cli.ts 中基于 yargs 解析参数，并使用 pipenet() API 启动隧道 package.json。

# 暴露本地端口 3000
npx pipenet client --port 3000

# 请求指定子域名
npx pipenet client --port 3000 --subdomain myapp

# 使用自建隧道服务器
npx pipenet client --port 3000 --host https://your-tunnel-server.com

CLI 主要选项包括：

编程式 API

pipenet() 是客户端的核心入口，定义于 src/pipenet.ts。它支持函数重载以兼容旧的 Node 回调风格，并统一返回 Promise<Tunnel>：

import { pipenet } from 'pipenet';

// Promise 风格
const tunnel = await pipenet({ port: 3000, host: 'https://loud-shrimp-92.pipenet.dev' });
console.log(tunnel.url);

// 回调风格
pipenet({ port: 3000 }, (err, tunnel) => {
  if (err) return console.error(err);
  console.log(tunnel.url);
});

函数内部会构造一个 Tunnel 实例并调用 client.open() 完成子域分配 src/pipenet.ts。open() 方法通过 axios 向 ${host}/ 发起 GET 请求（携带 ?new 或指定的 subdomain），服务器返回 JSON 格式的 TunnelInfo，包含 id、domain 与 url 字段 src/Tunnel.ts。

Tunnel 实例与事件

成功建立隧道后，Tunnel 实例提供以下能力 src/Tunnel.ts：

• 属性：url（公网地址）、clientId、cachedUrl。
• 事件：
• request：每当有请求被代理时触发，回调参数包含 method 与 path。
• error：隧道内部错误，例如本地连接断开。
• close：隧道已关闭。
• 方法：close() 用于主动关闭隧道并断开与服务器的长连接。

底层连接复用由 TunnelCluster 管理，它负责维护到隧道服务器的 TCP 长连接集合，并在每次新请求到达时建立到本地服务的临时 socket src/TunnelCluster.ts。HeaderHostTransformer 会在转发时重写请求头中的 Host 字段，使其匹配本地服务的监听地址 src/HeaderHostTransformer.ts。

典型调用流程

sequenceDiagram
  participant CLI as CLI/JS 调用方
  participant C as Tunnel 客户端
  participant S as pipenet 服务器
  participant L as 本地服务

  CLI->>C: pipenet({ port: 3000 })
  C->>S: GET / (申请子域名)
  S-->>C: { id, domain, url }
  C-->>CLI: resolve(Tunnel)
  S->>C: 公网请求 → 建立到客户端的 TCP 连接
  C->>L: 反向代理到 localhost:3000
  L-->>C: 响应
  C-->>S: 透传响应回公网

常见问题与故障排查

社区中报告的最常见问题是 npx pipenet client --port 3303 出现 404 Issue #1。通常原因包括：

1. 本地端口无服务监听：CLI 不会校验 --port 是否真实可用，需确保 localhost:3303 上已有进程运行。
2. 使用了错误的服务器地址：部分用户配置了自建服务器但未正确开放入站流量。
3. CLI 输出后立即退出：必须保持进程前台运行，命令行没有内置 daemon 模式。

v1.4.2 版本专门修复了「在 4XX 响应时中止隧道创建」的逻辑，确保服务器返回错误（如子域名被占用）时不会无限重试 v1.4.2。v1.4.1 还修复了快速重连时 close 监听器泄漏的问题 v1.4.1。

测试与集成

src/pipenet.spec.ts 演示了如何在内置测试中启动本地 HTTP 服务器与本地 pipenet 服务器，再通过 pipenet(fakePort, { host }) 创建隧道并断言返回的 URL 模式 src/pipenet.spec.ts。这一模式可直接复用于需要临时公网 URL 的端到端测试场景。

参见

• Server Configuration（服务器配置）
• Cloud Deployment（云部署指南）
• Tunnel Protocol Reference（隧道协议参考）

概述与适用场景

pipenet 是一个用于将本地服务即时暴露到公网的隧道工具，它同时提供客户端 SDK 与服务端实现。本页重点说明如何以自托管方式部署 pipenet 服务端，以及在容器化云端环境（Docker、fly.io、Kubernetes 等仅暴露固定端口的场景）下应如何使用「共享单端口模式」运行服务端。

与 localtunnel 不同，pipenet 增加了 --tunnel-port 单端口模式，使其能够在云端容器中正常工作；同时原生 ESM、TypeScript 类型与多域名支持也是其相对于 localtunnel 的关键改进。资料来源：README.md

服务端运行时要求 Node.js >= 22.0.0，核心依赖包括 koa、koa-router、tldjs、yargs、axios 等。资料来源：package.json

服务端架构与核心组件

createServer() 是构建服务端实例的入口函数，它在内部组装了 Koa 路由器、客户端管理器以及（可选的）共享隧道服务器。资料来源：src/server/server.ts

graph TB
    Browser[Public Browser] -->|HTTPS :443| K[Koa + Router]
    K -->|CORS + Routing| CM[ClientManager]
    CM --> TA[TunnelAgent]
    TA -->|HTTP/WS| Local[Local App :3000]
    K -.->|optional| TS[TunnelServer<br/>shared single port]
    Client[pipenet client] -->|TCP tunnel| TA
    Client -.->|cloud mode| TS

• Koa 应用与路由器：负责 HTTP/HTTPS 入口、CORS 预检（OPTIONS 204）、根路径重定向到落地页。资料来源：src/server/server.ts
• ClientManager：根据请求的子域名解析目标隧道客户端，暴露 newClient(id, url, domain)、hasClient(id)、removeClient(id)、stats.tunnels 等 API。资料来源：src/server/ClientManager.spec.ts
• TunnelAgent：为每个客户端提供本地 TCP 监听器，封装 listen()、createConnection()、destroy() 等方法；通过 maxTcpSockets 控制最大并发 TCP 连接数。资料来源：src/server/TunnelAgent.spec.ts
• TunnelServer（共享单端口隧道服务）：当传入 tunnelPort 时被创建，所有客户端通过同一端口与服务器建立长连接，规避云端容器需逐个映射随机端口的限制。资料来源：src/server/server.ts，v1.3.0 release notes

部署模式

标准模式（独立端口模式）

在传统 VPS 或开发机上，每个 pipenet client 启动后会在服务端随机占用一个 TCP 端口用于隧道回连。该模式与 localtunnel 默认行为一致，适合本地开发。客户端可通过 pipenet({ port: 3000 }) 启动并自动获得形如 https://<slug>.<host> 的公网 URL。资料来源：src/pipenet.ts，src/Tunnel.ts

云端单端口模式

在 Docker / fly.io / Kubernetes 等仅暴露少量端口的容器环境中，应启用 --tunnel-port：

# 服务端：暴露 443 给公网，并通过 3303 接收所有客户端的隧道长连接
npx pipenet server --port 443 --tunnel-port 3303

# 客户端：明确指向共享隧道端口
npx pipenet client --port 3000 --tunnel-port 3303

此模式下服务端会在内部创建 TunnelServer，并将其实例化引用传入 ClientManager；客户端的 TunnelCluster 通过 sharedTunnel: true 选项复用同一长连接。资料来源：src/server/server.ts，src/TunnelCluster.ts

配置项、API 端点与运行验证

服务端的核心可配置项通过 ServerOptions 传递，主要包括 domains（允许的基础域名数组，用于子域名解析与归属校验）、landing（根路径重定向目标，默认 https://pipenet.dev/）、secure（生成 URL 时使用 https://）、tunnelPort（启用共享单端口模式）。资料来源：src/server/server.ts

ServerHooks 允许在客户端注册、请求、关闭等生命周期注入回调；这些能力随 v1.4.0 的 add hooks 提交加入。资料来源：src/server/index.ts，v1.4.0 release notes

运行自带测试可验证部署正确性：npm test（vitest）。server.spec.ts 会校验根路径重定向、自定义域名下的子域名合法性（必须小写、长度 4–63、[a-z0-9-]），以及 WebSocket Upgrade 握手。资料来源：src/server/server.spec.ts

常见问题与故障排查

• 子域名非法（HTTP 4XX）：当请求的子域名长度不在 4–63 字符或包含非允许字符时，服务端会以 4XX 中止隧道创建。客户端对此做了 abort tunnel creation on 4XX 的修复（v1.4.2），并以错误回调形式向用户抛出 message 字段。资料来源：src/Tunnel.ts，v1.4.2 release notes
• 快速重连导致监听器泄漏：v1.4.1 修复了快速重连场景下 close 监听器未清理的问题，部署到生产环境前应至少升级到该版本。资料来源：v1.4.1 release notes
• CLI 返回 your url is: … 后立即退出：常见原因是使用了不兼容的旧版客户端或在子进程中未保活；建议改用 API 模式 await pipenet({ port }) 并在主进程中保持引用。资料来源：issue #1
• 多域名解析失败：自 v1.2.0 起服务端支持 --domain 多次传入，部署时需确保 DNS 已为每个域名配置通配 A/CNAME 指向服务端 IP。资料来源：v1.2.0 release notes

See Also

• README.md — 完整 CLI 与 API 使用说明
• src/server/index.ts — 服务端模块导出清单
• src/TunnelCluster.ts — 客户端长连接管理
• package.json — 脚本、依赖与 Node 版本约束

概述

pipenet 的核心职责是"将本地 HTTP 服务即时暴露到公网"，要稳定运行就必须妥善管理两类生命周期：客户端隧道（Tunnel → TunnelCluster）和服务端代理（Client → ClientManager）。本页聚焦于它们的启动、运行、关闭全过程，常见故障模式（4XX、监听器泄漏、隧道立即退出等）以及在云环境下的运维实践。

1. 客户端生命周期

1.1 启动阶段

Tunnel 构造函数默认 host = 'https://pipenet.dev'，并初始化 closed = false src/Tunnel.ts。open() 内部调用 _init，向 ${host}/?new（或 ${host}/${subdomain}）发起 HTTP GET 请求 src/Tunnel.ts。pipenet() 工厂函数接受 port 或 OptionsWithPort，并支持 Node 风格回调与 Promise 双 API src/pipenet.ts。

成功获取 ServerResponse 后，_establish 创建 TunnelCluster 并以 info.maxConn 设置最大监听数；当首个底层 TCP 隧道打开时触发 'url' 事件 src/Tunnel.ts。

1.2 状态机

stateDiagram-v2
    [*] --> Constructed: new Tunnel(opts)
    Constructed --> Resolving: open() -> _init()
    Resolving --> Established: 2xx + TCP open
    Resolving --> Retrying: 5xx/网络错误
    Resolving --> Aborted: 4xx (v1.4.2+)
    Retrying --> Resolving: 1s 后重试
    Established --> Closed: close()
    Aborted --> [*]
    Closed --> [*]

1.3 事件清单

2. 服务端生命周期与钩子

2.1 客户端注册与离线检测

服务端 Client 在构造时启动 1 秒宽限 graceTimeout，并监听其 TunnelAgent 的 online/offline 事件：上线即清除定时器，下线则再次启动 1 秒计时后强制 close() src/server/Client.ts。ClientManager 负责 newClient / removeClient，并根据冲突情况自动为重名 ID 重新分配随机子域 src/server/ClientManager.spec.ts。

2.2 Hooks 钩子机制

v1.4.0 起服务端支持 onRequest 等钩子，可在 Koa 路由中获取 { method, path, tunnelId, headers, remoteAddress } 上下文，常用于日志、限流与认证 README.md. 钩子通过 ServerOptions 传入，集成在 router 与 TunnelAgent 中。

2.3 共享隧道端口

针对 Docker / fly.io / Kubernetes 等只能暴露少数端口的环境，v1.3.0 引入 TunnelServer，由 --tunnel-port 启用，使所有客户端连接到同一端口 README.md. 服务端 createServer 在检测到 opt.tunnelPort 时构造 TunnelServer 并注入 ClientManager src/server/server.ts。

3. 常见故障模式

3.1 4XX 导致的中止

Tunnel._init 区分 4XX 与 5XX：4XX 直接以服务端返回的 message 调用 cb(new Error(...))，不再重试 src/Tunnel.ts. v1.4.2 将此行为正式固化为"创建中止"（abort tunnel creation on 4XX），解决了 issue #1 中"pipenet client 偶发 404 但客户端仍处于半挂起状态"的问题。

3.2 监听器泄漏

v1.4.1 修复了"快速重连导致 close 监听器泄漏"问题：之前的 Tunnel 内部对 tunnelCluster 多次调用 on('error', ...) 累积监听器，触发 MaxListenersExceededWarning。修复后使用 Map<Socket, handler> 精确管理每次新 TCP 通道的处理器 src/Tunnel.ts.

3.3 网络中断与重试

当 axios 请求触发非 4XX 错误时，_init 走 setTimeout(getUrl, 1000) 循环重试 src/Tunnel.ts。注意：该重试仅覆盖"获取隧道信息"阶段，已建立 TCP 隧道后的断线重连由 TunnelCluster 通过 error 事件透传，调用方应监听 tunnel.on('error', ...) 自行处理 README.md.

3.4 进程立即退出

issue #1 反馈"打印 your url is: ... 后立即返回命令行"。pipenet 客户端默认不会自动 process.exit，CLI 模式下应通过事件或 tunnel.close() 显式阻塞；集成方需保持事件循环活跃（如 await 一个永不 resolve 的 Promise 或保持 stdin 打开）。

4. 运维最佳实践

1. 始终监听 error/close：服务端可能因 4XX 提前终止（v1.4.2），客户端可能因网络抖动断流。
2. 云部署使用 --tunnel-port：与 --port 双端口同时暴露，避免每个客户端分配随机端口被防火墙拦截 README.md.
3. 使用 onRequest 钩子集中记录访问日志与限流，避免在回调中散落处理。
4. 测试时显式 close()：createServer() 与 pipenet() 返回的实例都实现了 close，vitest 用例中应在 afterAll 调用以释放端口 src/pipenet.spec.ts.
5. 构建产物：pnpm build 通过 tsc 生成 dist/，start:server 直接运行 dist/server/index.js package.json.

See Also

• 客户端 API 与配置参数
• 服务端 API 端点（/api/status, /api/tunnels/:id/status）
• Hooks 与多域名部署
• pipenet vs localtunnel vs zrok 对比

Pitfall Log / 踩坑日志

项目：punkpeye/pipenet

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Gives 404。

1. 安装坑 · 来源证据：Gives 404

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Gives 404
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/punkpeye/pipenet/issues/1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/punkpeye/pipenet | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/punkpeye/pipenet | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/punkpeye/pipenet | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/punkpeye/pipenet | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/punkpeye/pipenet | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/punkpeye/pipenet | release_recency=unknown