OpenNHP/nhp-frp
GitHub: OpenNHP/nhp-frp
将 OpenNHP 网络隐藏协议与 frp 反向代理结合，通过加密敲门实现零信任端口隐藏的安全内网穿透隧道。
Stars: 3 | Forks: 2
# NHP-FRP
[English](README.md) | [中文](README_zh.md)
NHP-FRP 将 [OpenNHP](https://github.com/OpenNHP/opennhp)（网络基础设施隐藏协议）与 [frp](https://github.com/fatedier/frp)（快速反向代理）结合，为反向代理隧道提供**零信任网络访问**。
## 快速演示
通过**零配置**即刻试用 NHP-FRP —— 只需构建并运行：
```
# 构建客户端
make frpc # Linux/macOS
build.bat frpc # Windows
# 运行它
./bin/nhp-frpc # Linux/macOS
bin\nhp-frpc.exe # Windows
```
启动时，`nhp-frpc` 将显示您唯一的**机器 ID** 和公开 URL：
```
_ _ _ _ ____ _____ ____ ____
| \ | | | | | _ \ | ___| _ \| _ \
| \| | |_| | |_) |_____| |_ | |_) | |_) |
| |\ | _ | __/______| _| | _ <| __/
|_| \_|_| |_|_| |_| |_| \_\_|
nhp-frp 0.1.0 (client)
Machine ID: 70a22f85
nhp agent started successfully
Config portal available at http://127.0.0.1:7400
Public URL: http://70a22f85.ac.opennhp.org:6060
Admin API: http://70a22f85-admin.ac.opennhp.org:6060 (user: admin, password: 70a22f85)
File server listening on :8888 (serving .../bin/public)
```
在浏览器中打开 `http://.ac.opennhp.org:6060/` —— 您将看到来自您本机的 `bin/public/index.html`，它是通过 NHP 保护的隧道提供的。将其替换为您自己的内容即可即时共享文件。
### 演示数据流
```
Your Machine Demo Server (acdemo.opennhp.org) Browser
┌─────────────────┐ ┌─────────────────────────────────┐
│ │ 1. NHP Knock │ │
│ NHP Agent ─────│────── UDP ─────>│ NHP Server │
│ │ │ │ verify + open firewall │
│ │ 2. FRP Tunnel │ v │
│ FRP Client ────│──── TCP:7000 ──>│ nhp-frps (:7000) │
│ │ │ │ │ │
│ │ proxy │ │ │ vhost routing │
│ v │ │ v │
│ File Server │ │ :6060 │ ┌──────────┐
│ (:8888) │ │ .ac.opennhp.org │<────│ Browser │
│ │ │ │ │ │ │ requests │
│ v │ │ │ forward to client │ │ :6060 │
│ bin/public/ │<── HTTP ────────│────┘ │ └──────────┘
│ index.html │ via FRP tunnel │ │
│ │ │ │
│ Admin API ─────│── HTTP ────────>│ -admin │<─── Server
│ (:7400) │ via FRP tunnel │ (basic auth protected) │ management
└─────────────────┘ └─────────────────────────────────┘
Step 1: NHP Agent sends encrypted knock → server opens port for your IP only
Step 2: FRP client connects to server through the opened port
Step 3: Browser visits http://.ac.opennhp.org:6060
Step 4: Server routes request via FRP tunnel → your local file server (:8888)
Step 5: bin/public/index.html is returned to the browser
```
位于 `http://127.0.0.1:7400` 的**配置控制台**允许您通过内置的 Web 仪表板监控代理状态。
### 远程管理（Admin API）
客户端的 Admin API 通过 FRP 隧道暴露，允许服务器远程管理客户端。它受 HTTP Basic Auth 保护（用户名：`admin`，密码：客户端的机器 ID）。
```
# 获取客户端代理状态
curl -u admin: http://-admin.ac.opennhp.org:6060/api/status
# 获取当前客户端配置
curl -u admin: http://-admin.ac.opennhp.org:6060/api/config
# 远程更新客户端配置
curl -u admin: -X PUT \
-H "Content-Type: application/toml" \
-d @new-frpc.toml \
http://-admin.ac.opennhp.org:6060/api/config
# 重新加载客户端以应用新配置
curl -u admin: -X PUT http://-admin.ac.opennhp.org:6060/api/reload
```
## 什么是 NHP-FRP？
标准的 frp 会将服务器端口暴露给公共互联网，使其对端口扫描器可见且容易受到攻击。NHP-FRP 通过添加 NHP 层解决了这个问题，该层**默认隐藏服务器端口**，并仅向经过身份验证和授权的客户端开放。
**工作原理：**
1. NHP Agent（内置于 `nhp-frpc`）在连接之前向 NHP 服务器发送加密的“敲门”请求
2. NHP 服务器验证客户端身份，并**仅针对该特定客户端 IP** 开放 frp 服务器端口
3. frp 隧道通过现已开放的端口建立
4. 会话结束后端口再次隐藏，对所有其他流量不可见
这将 frp 转变为一个**零信任反向代理** —— 在经过验证的客户端需要访问之前，服务在网络上是完全不可见的。
## 架构
### 问题：标准的 frp
使用标准的 frp 时，服务器端口（例如 7000）始终处于开放状态，对互联网上的任何人可见：
```
Public Internet
┌──────────┐ ┌──────────────────────────┐
│ frpc │──── frp tunnel (TCP:7000) ────────>│ frps (:7000 OPEN) │
│ client │ │ │ │
└──────────┘ │ v │
│ Backend Services │
┌──────────┐ │ ┌─────────────────┐ │
│ Attacker │──── port scan / exploit ──────────>│ │ Web App :8080 │ │
│ │ :7000 is visible! │ │ SSH :22 │ │
└──────────┘ │ │ DB :3306 │ │
│ └─────────────────┘ │
└──────────────────────────┘
Private Network
```
**问题：** 端口 7000 暴露在整个互联网中。攻击者可以通过端口扫描发现它，然后尝试暴力破解攻击、利用漏洞或发起 DDoS 攻击。
### 解决方案：NHP-FRP
NHP-FRP 隐藏了所有服务器端口。它们仅在有限时间内为经过验证的客户端开放：
```
Public Internet
┌──────────────────────────┐
1. NHP Knock (UDP) │ │
┌──────────┐ ─────────────────────────────────> │ NHP Server (nhp-door) │
│ nhp-frpc │ │ │ 2. Verify identity │
│ client │ 3. Port opened │ │ Open firewall │
│ (with │ (for this IP only) │ v │
│ NHP │ │ Firewall │
│ Agent) │ ── 4. frp tunnel (TCP:7000) ─────> │ [allow client IP:7000] │
└──────────┘ │ │ │
│ v │
│ nhp-frps (:7000) │
┌──────────┐ │ │ │
│ Attacker │──── port scan ─────────── X ──────>│ v │
│ │ :7000 is INVISIBLE! │ Backend Services │
└──────────┘ (all ports closed) │ ┌─────────────────┐ │
│ │ Web App :8080 │ │
│ │ SSH :22 │ │
│ │ DB :3306 │ │
│ └─────────────────┘ │
└──────────────────────────┘
Private Network
```
**逐步流程：**
| 步骤 | 操作 | 详情 |
|------|--------|--------|
| 1 | **NHP Knock** | `nhp-frpc` 向 NHP 服务器发送加密的 UDP敲门数据包 |
| 2 | **验证并开放** | NHP 服务器验证客户端的加密身份，并指示防火墙**仅为此客户端的 IP** 开放端口 7000 |
| 3 | **端口已开放** | 防火墙现在允许来自该客户端 IP 的流量访问端口 7000。所有其他 IP 仍然看到该端口处于关闭状态 |
| 4 | **FRP 隧道** | `nhp-frpc` 通过现已可访问的端口建立 frp 隧道 |
| 5 | **服务访问** | 流量通过 frp 隧道流向私有网络中的后端服务 |
**结果：** 服务器在公共互联网上拥有**零暴露端口**。即使攻击者知道服务器的 IP 地址，端口扫描也不会返回任何结果。只有能够通过 NHP 的加密敲门证明其身份的客户端才能访问服务。
### 组件
| 二进制文件 | 描述 |
|--------|-------------|
| `nhp-frpc` | 内置 NHP Agent 的 frp 客户端 —— 在连接前执行 NHP 敲门 |
| `nhp-frps` | frp 服务器（轻量级封装，计划未来集成 NHP） |
| `nhp-agent.dll/.so/.dylib` | nhp-frpc 使用的 NHP SDK 共享库 |
## 项目结构
```
nhp-frp/
cmd/
frpc/ # nhp-frpc entry point (NHP Agent + frp client)
frps/ # nhp-frps entry point (frp server wrapper)
pkg/version/ # Version info (injected at build time)
web/frpc/ # Embedded admin dashboard (Vue.js)
hack/ # Build helper scripts
third_party/
opennhp/ # OpenNHP submodule (NHP SDK source)
bin/ # Build output + runtime directory
nhp-frpc(.exe)
nhp-frps(.exe)
etc/ # Configuration files (frpc.toml, frps.toml, nhp-frpc.toml)
public/ # Static files served by the built-in file server
logs/ # Runtime log files
sdk/ # NHP SDK shared libraries
build.bat # Windows build script
Makefile # Linux/macOS build script
```
本项目是上游 frp 的一个**轻量级封装** —— 它将 [frp v0.67.0](https://github.com/fatedier/frp) 作为 Go 模块依赖导入，而不是 fork 源码。此仓库中仅包含特定于 NHP 的代码，这使得上游升级非常简单（只需更改 `go.mod` 中的版本）。
## 构建
### 前置条件
- **Go** 1.23+
- **GCC**（用于通过 CGO 构建 NHP SDK 共享库）
- Linux：`apt install gcc` 或同等命令
- macOS：Xcode Command Line Tools
- Windows：带有 `mingw-w64-x86_64-gcc` 的 [MSYS2](https://www.msys2.org/)
### Linux / macOS
```
# 构建所有内容 (包含 SDK 的 nhp-frps + nhp-frpc)
make
# 构建单独目标
make frps
make frpc # includes SDK build
make build-sdk # SDK only
```
### Windows
```
:: Build everything
build.bat
:: Build individual targets
build.bat frps
build.bat frpc &:: includes SDK build
build.bat build-sdk &:: SDK only
:: Other commands
build.bat clean
build.bat help
```
## 配置
配置文件位于二进制文件旁边的 `bin/etc/` 目录中。NHP-FRP 使用与 frp 相同的 TOML 格式，并支持用于动态值的模板变量。
**frps（服务器）：** `bin/etc/frps.toml`
```
bindPort = 7000
vhostHTTPPort = 6060
subDomainHost = "ac.opennhp.org"
log.to = "{{ .Envs.NHP_BIN_DIR }}/logs/nhp-frps.log"
log.level = "info"
```
**frpc（客户端）：** `bin/etc/frpc.toml`
```
serverAddr = "acdemo.opennhp.org"
serverPort = 7000
auth.method = "token"
auth.token = "opennhp-frp"
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "{{ .Envs.NHP_MACHINE_ID }}"
[[proxies]]
name = "file-server"
type = "http"
localIP = "127.0.0.1"
localPort = 8888
subdomain = "{{ .Envs.NHP_MACHINE_ID }}"
[[proxies]]
name = "admin-api"
type = "http"
localIP = "127.0.0.1"
localPort = 7400
subdomain = "{{ .Envs.NHP_MACHINE_ID }}-admin"
```
**nhp-frpc.toml**（NHP 特定设置，与 frp 配置分开）：
```
subDomainHost = "ac.opennhp.org"
vhostHTTPPort = 6060
```
有关完整的示例配置，请参阅 `bin/etc/`。有关 frp 配置的详细信息，请参阅 [frp 文档](https://github.com/fatedier/frp#configuration)。
NHP Agent 单独配置 —— 它从与 `nhp-frpc` 二进制文件相同的目录中读取其配置。有关 NHP 配置的详细信息，请参阅 [OpenNHP 文档](https://github.com/OpenNHP/opennhp)。
## 运行
```
# 启动服务器
./bin/nhp-frps
# 启动客户端 (NHP Agent 自动启动)
./bin/nhp-frpc
```
默认情况下，这两个二进制文件会从其旁边的 `etc/` 子文件夹（例如 `bin/etc/frps.toml`）读取配置。您可以使用 `-c` 进行覆盖：
```
./bin/nhp-frps -c /path/to/frps.toml
./bin/nhp-frpc -c /path/to/frpc.toml
```
当 `nhp-frpc` 启动时，它首先初始化执行加密敲门序列的 NHP Agent。一旦 NHP 握手成功，frp 客户端就会正常连接到服务器。
## 相关项目
- [frp](https://github.com/fatedier/frp) —— 上游快速反向代理
- [OpenNHP](https://github.com/OpenNHP/opennhp) —— 网络隐藏协议实现
## 许可证
Apache License 2.0 —— 详见 [LICENSE](LICENSE)。
本项目基于 fatedier 的 [frp](https://github.com/fatedier/frp)（Apache 2.0）和 OpenNHP 团队的 [OpenNHP](https://github.com/OpenNHP/opennhp) 构建。
标签：DNS解析, frp, Go语言, NHP-FRP, OpenNHP, Python安全, Streamlit, UDP敲门, 内网穿透, 反向代理, 后端开发, 基础设施隐藏协议, 开源项目, 微隔离, 日志审计, 程序破解, 端口隐藏, 网络安全, 网络隐身, 访问控制, 防火墙, 隐私保护, 隧道代理, 零信任网络