portless Windows 完全指南certutil、Task Scheduler、netstat 三大机制详解【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless是一个把“端口号”换成“稳定命名本地域名”的开发工具运行portless run next dev应用就能通过https://myapp.localhost这样的固定 HTTPS 地址访问而不再是localhost:3000。在 Windows 上portless 依赖三套系统机制才能完整工作certutil 负责证书信任让浏览器信任本地 HTTPS、Task Scheduler 负责开机自启服务、netstat 负责端口占用检测。本文带你用最短的时间看懂这三块拼图在源码里是如何落地的。一、先搞懂portless 在 Windows 上要解决什么问题在 macOS/Linux 上portless 依靠 sudo 生成根证书、绑定 443 端口、写入系统信任库在 Windows 上则必须换一套“本地化”方案环节macOS / LinuxWindows证书信任update-ca-certificates / update-ca-trustcertutil开机自启launchd / systemdTask Scheduler任务计划程序端口占用检测lsofnetstat -ano状态目录~/.portlessos.tmpdir()下的临时目录守护进程直接 forkwindowsHide: true隐藏控制台窗口下面按三大机制逐一拆解。二、机制一certutil —— 让 Windows 浏览器信任 portless 证书2.1 信任的核心命令HTTPS 是 portless 的默认模式。首次运行时它会在本地生成一套 CA 证书并把 CA 加入 Windows 的“受信任的根证书颁发机构”库。这一步由 windows-ca.ts 中的trustWindowsCA完成实际执行的就是系统自带的certutilcertutil -addstore -user Root 证书路径三个参数各管一件事-addstore把证书添加到证书库-user只写入当前用户的 Root 库无需管理员权限也不污染整台机器Root目标库名称即“受信任根证书颁发机构”。2.2 先查指纹再决定加不加重复执行portless trust是安全的因为写入前会先做指纹比对。isWindowsCATrusted见 windows-ca.ts的流程是用 Node 的crypto.X509Certificate读取本地 CA 文件算出指纹去掉冒号、转小写见 windows-ca.ts执行certutil -store -user Root列出当前 Root 库全部内容把列表中的空白字符剔除后做包含匹配判断指纹是否已在库中。卸载untrustWindowsCA见 windows-ca.ts则是按指纹执行certutil -delstore -user Root fingerprint删除后再复查一次确认确实移除而不是“看起来删掉了”。所有 certutil 调用统一设置了30 秒超时windows-ca.ts防止证书库被卡住导致命令挂起。2.3 WSL 用户的特殊通道 ️如果你在 WSL 里跑 portless只更新 Linux 侧信任库是不够的——Windows 里的浏览器依然会报证书错误。portless 的做法是“两头都写”先用wslpath -u C:\Windows\System32\certutil.exe拿到 Windows 程序的 Linux 侧路径/mnt/c/...再用它执行 certutil用wslpath -w把 Linux 证书路径转回 Windows 格式再传给 certutil。这条转换逻辑在 windows-ca.ts 的wslWindowsCAStoreOptions中实现测试用例 windows-ca.test.ts 明确验证了“通过 Windows 版 certutil 添加 WSL 证书”这条路径。 一个容易踩的坑Windows CISSM 服务里命令是以SYSTEM 账户运行的此时certutil -addstore -user Root写入的是 SYSTEM 的信任库而不是某个真实用户的。这一点在 AGENTS.md 中有专门提醒。三、机制二Task Scheduler —— 开机自动恢复 .localhost 地址3.1 服务安装流程portless service install会把代理配置端口、是否 HTTPS、TLD、LAN 模式等持久化进系统的启动管理器。在 Windows 分支见 service.ts中流程是四步在C:\ProgramData\portless\service\下生成启动脚本portless-service.cmd负责设置环境变量并拉起 Node 进程见 service.ts生成任务定义文件portless-task.xml以 UTF-16LE 编码写入Windows 任务计划 XML 的硬性要求见 service.tsschtasks /Create /TN Portless Proxy /XML path /F注册任务/F保证重复安装时原子替换旧任务/End结束可能存在的旧实例停掉占用 443 端口的旧代理后/Run立即启动新任务。3.2 任务定义里的三个关键细节任务 XML 由 service.ts 的buildWindowsTaskXml生成有三个值得注意的设计开机触发BootTrigger表示系统启动即运行而不是用户登录才运行保证无人登录时.localhost域名也活着SYSTEM 身份UserIdS-1-5-18/UserId即 SYSTEM 账户配合RunLevelHighestAvailable/RunLevel以最高权限运行——这样才能绑定 443 端口永不超时ExecutionTimeLimitPT0S/ExecutionTimeLimit取消了任务计划程序默认的“最长运行时间”代理可以无限期常驻。测试 service.test.ts 对这几项都有断言。配套设置里还有MultipleInstancesPolicyIgnoreNew/MultipleInstancesPolicy防止重复启动和StartWhenAvailabletrue/StartWhenAvailable错过开机时机时尽快补跑。3.3 状态查询与卸载状态portless service status执行schtasks /Query /TN Portless Proxy /FO LIST /V解析输出中的Status:行展示运行状态见 service.ts卸载portless service uninstall依次执行/End、/Delete /F再删除脚本目录portless clean也会顺带清掉该服务见 service.ts。由于 Windows 上绑定 443 需要 SYSTEM 权限安装和卸载可能需要管理员权限——这与 macOS/Linux 使用 root 属主服务的思路一致只是 Windows 用的是任务计划程序见 README.md。四、机制三netstat —— Windows 上的端口占用检测4.1 谁在占着这个端口Linux 上有lsofWindows 上的等价物是netstat -ano -p tcp。portless 在 cli-utils.ts 的findPidsOnPort中做了平台分支Windows 执行netstat -ano -p tcp再用parsePidFromNetstatcli-utils.ts解析输出。解析逻辑很直白TCP 0.0.0.0:443 0.0.0.0:0 LISTENING 1234 ^只认 LISTENING 行 ^取本地地址最后一个冒号后的端口 ^最后一列即 PID只有当本地地址的端口与目标端口匹配时才取最后一列的进程号避免误伤TIME_WAIT等瞬时连接。4.2 端口被占用时的友好提示当代理启动遇到EADDRINUSECLI 不会只甩一句“端口冲突”而是按平台给出排查命令Windows 下提示你执行netstat -ano | findstr :443找到占用者macOS/Linux 下提示lsof -ti tcp:443见 cli.ts。E2E 测试里也用同一手法验证并行代理和僵尸进程清理例如 parallel.test.ts 和 zombie.test.ts。五、三大机制如何协同工作把它们串起来看一个完整的 Windows 使用闭环是首次运行portless run 你的应用自动生成 CA通过certutil写入当前用户 Root 库浏览器即刻信任*.localhost开机自启portless service install把配置写入Task Scheduler开机时以 SYSTEM 身份拉起 443 代理重启后地址不失效冲突排查端口被占时CLI 直接给出netstat排查命令portless proxy stop则内部用 netstat 定位并结束残留进程。补充两个 Windows 特有的工程细节守护进程启动时设置windowsHide: true避免每次拉起代理都弹出黑色控制台窗口见 cli.ts命令执行使用shell: true以正确解析 Windows 的.cmd/.exe包装背景见 CHANGELOG.md。六、常见问题速查Q1浏览器仍然提示证书不受信重新执行portless trust。若你在 WSL 中使用portless 会同时更新 Linux 信任库和 Windows 当前用户 Root 库见 SKILL.md。Q2portless service install失败Windows 任务以 SYSTEM 身份运行安装/卸载可能需要管理员权限用portless service status查看Manager state与Installed字段定位问题。Q3443 端口被占用了怎么办先portless proxy stop仍不行就按提示netstat -ano | findstr :443找到 PID在任务管理器中确认进程后手动结束。延伸阅读命令全文档docs/commandsWindows 服务生命周期更新记录CHANGELOG.md平台能力速查SKILL.md【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考