Portless 本地命名路由
Portless 架构：控制层状态与回环 HTTP 转发路径
追踪启动器登记、逐请求路由和协议边界，区分持久路由管理与代理库自身的职责。
你将学会
- 把登记与转发分开理解
- 沿一个普通请求向后追踪
- 协议增加分支，不等于普遍兼容保证
开始前需要
- 了解 HTTP 访问源、端口和命令行基础
- 能够区分回环、局域网与公网暴露
追踪命名请求，明确安装权限边界，并区分已观察行为和未测试集成。
先看结论
- 路由登记与 HTTP 转发由不同组件承担。
- 后端连接器使用回环地址，不会直接按请求主机名访问远程 DNS。
- 源码存在协议支持，不等于浏览器端到端兼容已验证。
把登记与转发分开理解
启动器和路由存储管理应用名称、端口及进程归属。代理库接收 getRoutes 回调，每次请求都会调用它。这个接口很关键：createProxyServer 不需要知道 CLI 如何推断应用名称，也不需要知道调用方将路由保存在哪里。实验使用内存列表，添加路由后无需重启代理即可访问。
RouteStore 是独立的持久化组件。它检查记录的基本字段，并可过滤已不存活进程对应的条目；pid 为 0 表示静态路由。其锁和清理行为属于控制层，不属于 HTTP 请求协议。进程号也不是永久应用身份，实际排障仍需把路由与当前进程、真实监听联系起来。
沿一个普通请求向后追踪
HTTP/1.1 通过请求 Host 选择路由，HTTP/2 兼容路径则可以使用 :authority。匹配后，代理通过 createLoopbackConnection 连接该端口；这个函数明确只提供 127.0.0.1 和 ::1 地址。浏览器提供的主机名在这里是路由键，不是后端连接任意远程 DNS 目标的依据。
处理器转发方法、路径和正文，保留原始主机信息并构建转发头。未知名称产生代理错误页，后端连接失败产生网关错误，跳数计数器则捕获达到阈值的循环转发。这是不同的失败边界；有效的追踪应先记录匹配了哪个名称、选中应用是否监听，再调查响应渲染。
协议增加分支，不等于普遍兼容保证
提供 TLS 配置时，实现会创建支持 HTTP/1.1 回退的 HTTP/2 安全服务器。源码还分别处理传统 WebSocket Upgrade，以及桥接到后端 HTTP/1.1 握手的 HTTP/2 扩展 CONNECT。看到这些分支可以解释设计，却不能证明每种浏览器和框架的热更新都正常。
有界实验只运行普通 HTTP/1.1 路径，没有证书、持久路由存储、系统守护进程或外部分享进程。分离这些职责让结论更容易复现和解释：动态回调路由已观察到，而证书生命周期、持久启动和热更新仍是部署负责人需要执行的集成测试。
实施步骤
- 1
从启动器和 RouteStore 追踪登记行为。
- 2
沿 getRoutes 进入请求处理器。
- 3
确认 Host 如何匹配以及选择的回环端口。
- 4
补充协议专属集成测试，不扩大 HTTP 实验结论。
可复制示例
启动器 / RouteStore -> getRoutes()
浏览器 Host -> 匹配路由 -> 回环连接 -> 应用
| 未匹配：404
| 后端失败：502
| 跳数上限：508
TLS / HTTP2 / WebSocket 分支：已阅读，本次未执行常见问题
每次改变路由都要重启代理吗？
代理库接口不要求这样做，getRoutes 每次请求都会调用。实验添加内存路由后无需重启；持久 CLI 登记还有独立生命周期。
传入 Host 会成为远程连接目标吗？
在检查的后端连接器中，它用于选择已登记端口，实际地址查找只提供回环地址。公网分享由其他组件处理。
资料来源
- packages/portless/src/proxy.ts来源核查 2026-09-08
- packages/portless/src/routes.ts来源核查 2026-09-08
- packages/portless/src/utils.ts来源核查 2026-09-08
- packages/portless/src/types.ts来源核查 2026-09-08