快速开始
一个本地搭建的 Docker 调试环境，模拟 nhp-server、nhp-ac、traefik、web-app 等。此环境可用于：
- 快速理解 opennhp 的运作方式
- 插件调试
- 基本逻辑验证
- 局部性能压力测试
1. 概述
快速入门指南帮助开发人员快速设置 OpenNHP Docker 环境，构建源代码，并测试 OpenNHP 的关键功能。无论您是在探索 OpenNHP 如何使服务器对未经授权的扫描“不可见”，还是将其集成到现有的零信任架构中，本指南都提供了快速启动和运行的基本步骤。
1.1 网络拓扑
| 容器名 | IP | 说明 |
|---|---|---|
| NHP-Agent | 177.7.0.8 | nhp-agentd & nginx（默认均不运行），443->AC:80, 80-> NHP-Server:62206 |
| NHP-Server | 177.7.0.9 | nhp-serverd，开放端口 62206 |
| NHP-AC | 177.7.0.10 | nhp-acd & traefik，禁止任何端口访问 |
| Web app | 177.7.0.11 | 被保护的 Web app，只允许 NHP-AC 访问 8080 端口 |
1.2 测试场景
| 场景 | 状态 | 期望结果 |
|---|---|---|
| 场景一 | 隐身（对于未授权的用户） | ping 或者访问 NHP-AC Server 代理的 Web-app 失败 |
| 场景二 | 通过 NHP-Agent 敲门后 | 能正常访问通过 NHP-AC 防护的 Web-app |
| 场景三 | 通过 web 身份认证敲门后 | 能正常访问通过 NHP-AC 防护的 Web-app |
2. 安装 Docker 环境
2.1 Docker Desktop for Mac
brew install --cask docker
或者从 Docker 官网下载 .dmg 文件手动安装： https://www.docker.com/products/docker-desktop/
2.2 Docker Desktop for Windows
- 系统要求：
- Windows 10/11（64 位，专业版/企业版/家庭版）
- 启用 WSL 2（推荐）或 Hyper-V
- 安装步骤
- 下载 Docker Desktop：官网下载
- 运行安装程序，按提示完成安装。
安装完成后，启动 Docker Desktop。
3. 根据最新代码构建基础镜像
3.1 获取最新代码
git clone https://github.com/OpenNHP/opennhp.git
3.2 构建 opennhp-base 镜像
注意: 先进入到 docker 目录(cd ./docker)
cd ./docker
docker build --no-cache -t opennhp-base:latest -f Dockerfile.base ../..
4. 运行与测试
以下启动命令，在启动过程会相应的构建 nhp-server、nhp-ac、web-app、nhp-agent 镜像，在实际调试过程中，可使用 docker compose build [container_name]（如：docker compose build nhp-ac 编译 nhp-ac）对服务单独编译
4.1 启动所有服务
注意: 先进入到 docker 目录(cd ./docker)
cd ./docker
docker compose up -d
4.2 场景一: 隐身（对于未授权的用户）
进入 nhp-agentd 容器进行验证 注意: 先进入到 docker 目录(cd ./docker)
cd ./docker
docker exec -it nhp-agent bash
默认情况下，通过 curl NHP-AC 会出现以下错误（保护中）
root@68a230812459:/workdir# curl -i http://177.7.0.10
curl: (28) Failed to connect to 177.7.0.10 port 80: Connection timed out
端口扫描验证，进入 NHP-Agent 容器 并安装 nmap
root@ee88ec992447:/# docker exec -it nhp-agent bash
root@ee88ec992447:/# apt-get update && apt-get install -y nmap
通过 NHP-Agent 扫描 NHP-AC 扫描不到任何端口
root@ee88ec992447:/# nmap 177.7.0.10
Starting Nmap 7.93 ( https://nmap.org ) at 2025-07-03 07:33 UTC
Nmap scan report for nhp-ac.docker_nginx (177.7.0.10)
Host is up (0.000044s latency).
All 1000 scanned ports on nhp-ac.docker_nginx (177.7.0.10) are in ignored states.
Not shown: 1000 filtered tcp ports (no-response)
MAC Address: 12:B4:5C:EB:72:F4 (Unknown)
Nmap done: 1 IP address (1 host up) scanned in 21.84 seconds
4.3 场景二: 使用 nhp-agentd 服务来敲门
通过nohup /nhp-agent/nhp-agentd run 2>&1 & 命令来启动 nhp-agentd 服务后，访问正常，如下：
root@68a230812459:/workdir# nohup /nhp-agent/nhp-agentd run 2>&1 &
root@6e21724b68f1:/workdir# curl -i http://177.7.0.10
HTTP/1.1 200 OK
Content-Length: 26
Content-Type: application/json; charset=utf-8
Date: Tue, 08 Jul 2025 06:21:10 GMT
{"message":"Hello World!"}
当 nhp-agent 启动，可以扫描到 NHP-AC 的 80 端口
root@ee88ec992447:/# nmap 177.7.0.10
Starting Nmap 7.93 ( https://nmap.org ) at 2025-07-03 07:37 UTC
Nmap scan report for nhp-ac.docker_nginx (177.7.0.10)
Host is up (0.000094s latency).
Not shown: 999 filtered tcp ports (no-response)
PORT STATE SERVICE
80/tcp open http
MAC Address: 12:B4:5C:EB:72:F4 (Unknown)
Nmap done: 1 IP address (1 host up) scanned in 4.96 seconds
4.4 场景三: 使用模拟授权服务的登录来验证
停止 nhp-agentd 服务，并启动 NHP-Agent 容器中的 nginx
root@6e21724b68f1:/workdir# ps -aux|grep nhp-agentd
root 38 0.3 0.2 1974072 20448 pts/0 Sl 02:55 0:00 /nhp-agent/nhp-agentd run
root 51 0.0 0.0 2844 1424 pts/0 S+ 02:55 0:00 grep --color=auto nhp-agentd
root@6e21724b68f1:/workdir# kill 38
root@6e21724b68f1:/workdir# nginx
访问：http://localhost/plugins/example?resid=demo&action=login
- 预期页面正常显示
- 敲门前访问：https://localhost/ 超时（504 Gateway Time-out）
- 点击登录（敲门后），页面正常跳转，并能正常访问 https://localhost/ （注：开门时间为 15s，15s后禁止访问）
- 在 NHP-Agent 容器内，通过
curl -i http://177.7.0.10能正常显示内容 - 当点击登录（敲门后），可以扫描到 NHP-AC 的 80 端口
root@ee88ec992447:/# nmap 177.7.0.10
Starting Nmap 7.93 ( https://nmap.org ) at 2025-07-03 07:37 UTC
Nmap scan report for nhp-ac.docker_nginx (177.7.0.10)
Host is up (0.000094s latency).
Not shown: 999 filtered tcp ports (no-response)
PORT STATE SERVICE
80/tcp open http
MAC Address: 12:B4:5C:EB:72:F4 (Unknown)
Nmap done: 1 IP address (1 host up) scanned in 4.96 seconds
4.5 验证 ipset 规则是否生效
docker exec -it nhp-ac ipset list
通过 nhp-agentd 或 授权插件敲门后，如果 NHP-AC 的 ipset 中出现以下结果，则表示规则写入成功，这意味着敲门成功： Name: defaultset Rules
Name: defaultset
Type: hash:ip,port,ip
Revision: 5
Header: family inet hashsize 1024 maxelem 1000000 timeout 120 counters
Size in memory: 656
References: 7
Number of entries: 2
Members:
177.7.0.8,udp:80,177.7.0.10 timeout 8 packets 0 bytes 0
177.7.0.8,tcp:80,177.7.0.10 timeout 8 packets 90 bytes 14565
Name: defaultset_down
Type: hash:ip,port,ip
Revision: 5
Header: family inet hashsize 1024 maxelem 1000000 timeout 121 counters
Size in memory: 208
References: 2
Number of entries: 0
Members:
Name: tempset
Type: hash:net,port
Revision: 7
Header: family inet hashsize 1024 maxelem 1000000 timeout 5 counters
Size in memory: 456
References: 2
Number of entries: 0
Members:
5. 修改代码重新构建镜像并调试
在实际的调试中，修改完代码后，可以使用 docker compose build [container_name] (如：docker compose build nhp-ac 构建 nhp-ac 镜像) 来重新构建相应的服务来进行调试
5.1 代码修改
用 IDE 打开项目（如：vscode）并修改 OpenNHP 源代码。
5.2 重新构建服务并调试
采用以下方式对相应修改的服务进行重新构建并调试
5.2.1 重新构建 nhp-server 并启动
cd ./docker
docker compose build nhp-server
docker stop nhp-server && docker rm nhp-server
docker compose up -d
5.2.2 重新构建 nhp-ac 并启动
cd ./docker
docker compose build nhp-ac
docker stop nhp-ac && docker rm nhp-ac
docker compose up -d