portless 路由表深度解析：崩溃后路由为何残留，以及陈旧路由清理机制

portless 路由表深度解析崩溃后路由为何残留以及陈旧路由清理机制【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 用稳定、命名的本地 URL取代端口号如https://myapp.localhost核心是一套路由表每条路由记录由主机名 端口 进程 PID组成。当运行 portless 的进程被强杀或崩溃时这条路由记录不会自动消失就会变成陈旧路由stale route。本文带你读懂路由表的残留原理以及 portless 内置的三层陈旧路由清理机制。一、路由表长什么样每个名字都绑定一个 PIDportless 把所有路由持久化在用户状态目录默认~/.portless的routes.json文件里每条记录包含三个关键字段字段含义hostname应用名字如myapp.localhostport该应用实际监听的本地端口pid注册这条路由的 portless CLI 进程 ID静态alias路由为0路由的注册与注销逻辑集中在 routes.ts 的RouteStore类中。正常运行时一切都很干净应用正常退出CtrlC、SIGTERM时portless 会在清理回调里注销路由源码见 cli.ts#L1516-L1532。二、崩溃后路由为何残留清理代码根本没机会执行残留的根源只有一句话注销路由靠的是进程体面地退出而崩溃不允许它体面。收到SIGKILLkill -9或进程直接崩溃时信号处理器和清理回调都不会执行routes.json里的记录就原样留下了更糟的是孤儿子进程你的 dev server往往还活着继续霸占端口让这条幽灵路由真实可访问官方端到端测试专门模拟了这个场景SIGKILL 后确认 dev server 存活再靠prune善后见 zombie.test.ts#L299-L331。三、如何判定一条路由陈旧只问一个问题——PID 还活着吗portless 的判定逻辑极其简单源码在 routes.ts#L159-L166向目标 PID 发送信号0不真正终止只探测抛错即代表进程已死。两个关键规则pid 0的路由永不判定为陈旧——这是portless alias注册的静态路由比如指向 Docker 端口没有属主进程可查判定只看注册它的 CLI 进程是否存活不看端口是否被占所以 prune 时会额外查一遍端口上的真实进程再决定杀谁。四、陈旧路由清理机制内置的三道防线防线一懒清理——任何一次写操作都顺手扫除 loadRoutes在加载路由表时会默认过滤掉属主 PID 已死的条目当调用方持有文件锁即addRoute/updateRoute内部并开启持久化参数时清理结果会被直接写回磁盘防止陈旧条目无限堆积逻辑见 routes.ts#L168-L209。也就是说只要你再运行任意portless应用陈旧路由就被动被清掉了——这是第一道自愈防线。防线二portless prune——主动猎杀孤儿进程 当孤儿 dev server 还占着端口时光删记录不够还得杀进程。portless prune的完整流程实现见 cli.ts#L2128-L2205 与 routes.ts#L287-L310用loadRoutesRaw读取未经过滤的完整路由表才能发现属主已死但端口仍被占的陈旧条目把存活条目写回磁盘剔除陈旧记录对每条陈旧路由查找该端口上真实监听的 PID发送SIGTERM结束孤儿进程加--force则直接SIGKILL顺带清理附带的 Tailscale serve 注册和 ngrok 隧道。端口已空闲的陈旧路由只会删记录、不会误杀任何进程。防线三portless doctor——无副作用的体检报告portless doctor只做诊断不修改状态它统计存活/陈旧路由数量对陈条目明确给出修复建议Run: portless prune代码见 cli.ts#L2729-L2757。建议把它当作日常排障的第一站。五、并发安全文件锁如何保证清理不乱写路由表会被多个 portless 进程并发读写一个在跑应用、一个在执行 prune所以所有写操作都先抢占一个目录型文件锁routes.lock机制细节在 routes.ts#L118-L154参数值作用获取锁总超时15 秒超时报错绝不无限等待陈旧锁阈值10 秒锁目录超过 10 秒未更新视为持有者已死强制移除重试策略10ms 起步指数退避上限 100ms附加随机抖动避免多进程羊群效应同时重试注意一个设计取舍懒清理只在持锁路径内持久化源码注释明确写出避免无保护的并发写把路由文件写坏。锁文件自身也可能因崩溃残留但 10 秒阈值保证了它最多只造成十几秒的短暂等待。六、一个容易忽略的细节ownerPid 防止误删新路由--force接管场景下存在一个微妙的竞态旧进程被杀前可能还在执行退出清理。因此removeRoute(hostname, ownerPid)规定只有当前属主 PID 与自己一致时才允许删除源码与注释见 routes.ts#L353-L372。否则被 SIGTERM 的旧进程会在退出回调里把新进程刚刚注册的同名路由删掉——这个细节保证了强制接管cli.ts#L502-L521的原子性。七、总结什么时候该手动清理场景推荐操作只是发现portless list有异常路由先跑portless doctor看诊断强杀/崩溃后端口被占用、URL 打不开portless prune不听话的进程加--force什么都不用做正常运行新应用即可懒清理会自动写回干净的表一句话记住这套机制注册时记下 PID判活只问 PID写时顺手清理崩溃交给 prune。路由表设计在 routes.ts命令入口与 help 文案见 cli.ts更多用法参考 README.md 的 Commands 章节。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考