Portless 本地命名路由
团队部署 Portless：管理本地状态、证书信任与启动方式
制定可重复的本地开发接入方案，明确代理配置、Node.js 兼容性、证书责任和可逆的系统服务决策。
你将学会
- 这里的部署首先是开发机器接入
- 把持久化配置纳入接入方案
- 持久系统服务需要单独批准
开始前需要
- 了解 HTTP 访问源、端口和命令行基础
- 能够区分回环、局域网与公网暴露
追踪命名请求，明确安装权限边界，并区分已观察行为和未测试集成。
先看结论
- 可重复接入包含机器状态，不只是依赖版本。
- 高端口和证书信任解决不同的安装问题。
- 服务安装与 clean 都可能产生系统层面的影响。
这里的部署首先是开发机器接入
介绍 Portless 部署时，首先应说明它的位置：运行本地应用的开发机器。固定版本的包要求现代 Node.js，元数据列出了 Windows、macOS 和 Linux；这些声明不能证明本文已经测试每一种证书库、shell、防火墙与框架组合。团队仍需针对实际环境设定验收范围。
决定由团队维护全局安装，还是由项目依赖固定版本。项目依赖能明确仓库版本，但同一开发者可能在不同仓库运行不同 Portless 版本，同时共用本地状态。README 提醒这个 1.0 前项目的状态格式可能变化，因此排障记录应包含 CLI 版本和状态目录，不能认为包锁文件已经解释了整台机器。
把持久化配置纳入接入方案
代理自动启动会复用最近一次运行的配置，明确指定的 PORTLESS 环境变量优先。因此重启不等于恢复 HTTPS 443 默认值，被记住的 LAN 设置尤其需要检查。在修改共享开发环境之前，记录协议、代理端口、域名后缀、LAN 模式和状态目录，才能判断新行为来自哪里。
默认 HTTPS 可能生成并信任本地 CA，绑定特权端口也可能要求提权。选择高端口只解决端口绑定问题，本身不能解决证书信任。明确使用 --no-tls 可以避开该证书路径，却会改变浏览器访问源与安全属性；不要为了消除尚未解释的信任错误，而全局关闭证书验证。
持久系统服务需要单独批准
文档中的服务安装会写入 launchd、systemd 或 Windows 任务计划配置，可能以 root 或 SYSTEM 身份运行。这与普通权限的前台开发进程有实质差别。启用开机启动前，应明确可执行文件位置、服务所有者、启动选项、日志和移除过程；一次 HTTP 成功请求无法验证整个服务生命周期。
使用 doctor 检查健康情况，使用 service status 检查已安装服务。不要把 clean 描述为无害刷新：它会移除 Portless 状态、信任条目、托管 hosts 修改以及系统服务。本次审查没有执行这些机器变更；接入验收清单应先在临时机器验证，再用于共享开发工作站。
实施步骤
- 1
记录 Node、CLI 版本、状态目录和现有代理配置。
- 2
选择仅本地 HTTP 或经过批准的 HTTPS 配置。
- 3
确认命名路由正常，再考虑持久服务。
- 4
记录恢复流程，移除共享状态或信任前先获得批准。
可复制示例
{
"接入检查清单": true,
"最低Node主版本": 24,
"Portless版本": "0.15.6",
"状态目录": "记录实际路径",
"代理协议": "明确选择",
"启用LAN": false,
"系统服务已获批准": false,
"证书信任已验证": false
}常见问题
能直接部署到生产服务器吗？
本系列覆盖文档中的开发工作流，不是生产入口认证。生产可用性、认证与边缘安全需要单独设计和验证。
为什么重启保留了意外配置？
代理有意复用上次配置。应检查持久化设置和明确环境变量，而不是假定重启会恢复默认值。
资料来源
- README.md来源核查 2026-09-08
- packages/portless/package.json来源核查 2026-09-08
- packages/portless/src/cli-utils.ts来源核查 2026-09-08