域名代理与路由
NPS 的域名代理按 HTTP 请求中的 Host 和可选的 URL 路径匹配规则。DNS 只负责把域名解析到 NPS 公网地址;请求到达 NPS 后才由 Host 规则决定转发目标。需要管理员统一提供泛解析子域名、证书续期热更新或查看路由决策时,阅读平台泛域名、证书热更新与规则诊断。
启用 HTTP 和 HTTPS 入口
在 conf/nps.conf 中配置入口端口,然后重启 NPS:
http_proxy_port=80
https_proxy_port=443
80 和 443 被其他服务占用时可以使用任意未占用端口:
http_proxy_port=30111
https_proxy_port=30443
show_http_proxy_port=true
此时访问 URL 必须带端口,例如 http://app.example.com:30111/。除 DNS 外,云安全组、宿主机防火墙和 Docker 网络策略都必须放行对应 TCP 端口。
创建域名规则
在 Web 面板的「域名反代」页面新增规则,至少填写:
| 字段 | 说明 |
|---|---|
| 域名 | 请求中的 Host,例如 app.example.com。 |
| 所属客户端 | 负责连接内网目标的 NPC;勾选本地转发时除外。 |
| 内网目标 | NPC 所在网络可达的 IP:端口,例如 127.0.0.1:8081。 |
| 协议 | http、https 或 all。 |
| 路径 | 可选;同一域名按路径转发时填写,例如 /api。 |
新增表单在有可用平台泛域名时默认选中平台域名,并预选域名池第一项;可切换为自定义域名。两种来源是互斥模式。服务端会校验域名格式、协议、路径和每行一个 host:port 的目标地址;编辑规则也可将规则迁移到当前账号有权限的另一个客户端。
域名列表会在平台域名和自定义域名后显示来源标签;访问入口中的“HTTP”“HTTPS”是带外链图标的可点击按钮,点击后会在新窗口打开对应入口。客户端列固定为两行,分别显示“客户端备注 · 客户端 ID”和“所属用户备注 · 用户 ID”,内容过长时单行省略,悬浮可查看完整信息。管理员按所属用户筛选时,客户端选项会同步收窄,但仍可单独按客户端筛选。
目标可分行填写多个地址,NPS 会轮流选择,用于简单负载均衡。域名规则表单中的“后端健康检查”可以直接配置 HTTP 200 或 TCP 检查;服务端会把有效配置下发给支持该能力的 NPC,由 NPC 从内网探测并回报结果。旧版 NPC 不认识新控制消息时仍可继续使用本地 [health_*] 配置,不会被发送新消息。
配置文件模式仍支持 [health_*] 节,适合批量部署或需要把检查规则纳入配置管理的场景。Web 规则和配置文件规则会按目标去重,设置项、默认值和限制见 NPC 健康检查说明。
自定义域名与平台域名
管理员可在「系统 → 全局参数」的「证书设置」Tab 中预置多个平台泛域名,例如 *.example.com。新增 Host 时可选择:
- 自定义域名:填写完整域名、自己完成 DNS 解析,并按需上传或粘贴自己的证书与私钥。
- 平台域名:从管理员提供的泛域名中选择,填写一个唯一前缀。系统默认生成可修改的 8 位字母数字前缀,并锁定平台证书路径,普通用户不会接触服务器文件路径。
平台域名的 DNS 泛解析、前缀限制、证书状态、引用保护和兼容性见平台域名说明。
DNS、泛域名和非标准端口
精确域名可在 DNS 中添加 A/AAAA 记录:
app.example.com -> NPS 公网 IP
泛域名可添加一条通配记录,并在 NPS 使用通配 Host 规则:
*.example.com -> NPS 公网 IP
NPS Host: *.example.com
DNS 不会替代端口开放,也不会隐藏非 80/443 端口。即使 *.example.com 已正确解析,http_proxy_port=30111 时仍需访问 http://sub.example.com:30111/。
路径路由、Host 重写和 Header
同一域名可用路径区分目标,例如:
| Host | 路径 | 目标 |
|---|---|---|
app.example.com | /api | 127.0.0.1:8081 |
app.example.com | /static | 127.0.0.1:8082 |
域名规则还可配置:
- 请求 Host:将发给后端的
Host改为后端虚拟主机需要的值。 - 自定义请求 Header:每行使用
名称: 值,例如X-Environment: production。 - 真实来源 Header:启用
http_add_origin_header=true后,NPS 会维护X-Forwarded-For、X-Real-IP、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-Port和X-Real-Proto。默认覆盖访问者传入的转发头;也可选择保留链路或只信任指定代理。后端只能信任来自 NPS 或受控反向代理的这些 Header。 - Basic 认证:域名规则可单独配置
auth/独立账号;留空时使用所属客户端的公共 Basic。HTTP 正向代理和 SOCKS5 的规则级认证是另一组代理端口配置。
域名规则的“兼容与响应”选项还包括:
- 路径重写:按行填写
旧路径 => 新路径,例如/api => /v1/api;只改发往后端的路径,查询参数保持不变。 - 响应 Header 修改:按行填写
名称: 值,或用-名称删除响应头。Content-Length、Transfer-Encoding和Connection由 NPS 管理,不能被规则覆盖,以避免响应截断。 - 自动 CORS:向响应追加通用跨域 Header,适合内网 API 被浏览器直接调用的场景。
- 兼容模式:使用标准 HTTP 反向代理链路,适合 SSE、流式响应、复杂 Header 和 WebSocket;默认链路保留轻量的原始 HTTP 转发。
- 重定向地址:填写完整 URL 后该规则返回
307,{path}会替换为原始请求路径和查询参数。
HTTPS、证书和自动跳转
自定义域名的“证书与私钥”区域只提供上传和粘贴两种录入方式,并且必须同时提供一组成对的证书链和私钥。请先点击“校验证书”;只有证书与私钥匹配、证书当前有效并覆盖当前域名时才能保存。保存后页面会显示证书来源、文件名、有效期、剩余天数、主题、SAN、颁发者、算法、证书链和指纹。NPS 终结 TLS 时,后端可以读取 HTTP Header;未配置证书时由内网服务处理 TLS,NPS 只转发加密流量。
历史版本已经保存的服务器路径证书继续可用,编辑页会以只读方式读取并显示详情,但不再允许普通用户填写或修改服务器路径。平台泛域名和 Bridge 证书仍由管理员在“证书设置”页通过路径、上传或粘贴维护。使用既有路径时,外部脚本原子替换有效证书和私钥后,新的 TLS 连接会自动加载;错误或不完整的新文件会回退到最近有效证书,不需要重启 NPS。详细续期脚本和限制见证书热更新。
勾选「自动 HTTPS」后,HTTP 请求会 301 跳转到对应 HTTPS 地址。若 https_proxy_port 不是 443,跳转 URL 也会带上该端口。
当 Nginx 或 Caddy 负责公网 80/443 时,可让它保留 Host 并反代到 NPS 的内部 HTTP 端口。示例和注意事项见服务端增强功能。
转发到 NPS 服务器本机
若后端服务实际运行在 NPS 服务器上,而不是 NPC 所在内网,需要在 nps.conf 中开启:
allow_local_proxy=true
重启 NPS 后,在对应 Host 规则勾选「转发到本地」。两项缺一不可。NPS 使用 Docker network_mode: host 时,规则目标 127.0.0.1:8081 指向宿主机回环;默认 bridge 网络中则只指向 NPS 容器本身。
本地转发让规则创建者访问 NPS 主机可达的服务,只应开放给可信管理员。
未匹配规则与 404 页面
没有可用 Host 规则、所属客户端离线或目标不可达时,NPS 会返回代理错误页面。当前项目将默认页面编译进 nps 二进制,源码位置为 web/static/page/error.html。
如需定制默认 404 内容,请修改该源码文件并重新构建、替换 NPS 二进制;仅修改运行目录下释放出的 web/static/page/error.html 不会改变已运行进程使用的嵌入内容。页面不应包含密钥、内网地址、调试堆栈或管理入口信息。
排查顺序
先在「域名反代」的“规则诊断”中输入实际 Host、路径和协议,确认命中的 Host 规则和选择的内网目标。
检查启动日志是否有
start http listener, port is <端口>。从 NPS 机器本地带 Host 头验证:
curl -i -H 'Host: app.example.com' http://127.0.0.1:30111/确认对应客户端在线、未到期,Host 规则已启用且目标地址从 NPC 网络可达。
确认 DNS 指向 NPS 公网 IP,外部访问 URL 包含非标准端口。
检查云安全组、系统防火墙、Docker 端口发布和前置反向代理。
更多代理模式、Secret 和 P2P 的说明见隧道模式。
