快速开始

一个本地搭建的 Docker 调试环境,模拟 nhp-server、nhp-ac、traefik、web-app 等。此环境可用于:

  • 快速理解 opennhp 的运作方式
  • 插件调试
  • 基本逻辑验证
  • 局部性能压力测试

English


1. 概述

快速入门指南帮助开发人员快速设置 OpenNHP Docker 环境,构建源代码,并测试 OpenNHP 的关键功能。无论您是在探索 OpenNHP 如何使服务器对未经授权的扫描“不可见”,还是将其集成到现有的零信任架构中,本指南都提供了快速启动和运行的基本步骤。

1.1 网络拓扑

Workflow

容器名IP说明
NHP-Agent177.7.0.8nhp-agentd & nginx(默认均不运行),443->AC:80, 80-> NHP-Server:62206
NHP-Server177.7.0.9nhp-serverd,开放端口 62206
NHP-AC177.7.0.10nhp-acd & traefik,禁止任何端口访问
Web app177.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