OpenNHP插件开发教程

English


简介

NHP服务器中的插件是添加特定功能到主应用程序的模块。它们被设计为高度模块化,与主应用程序松散耦合,允许开发人员添加、删除或更新插件,而不影响服务器的核心功能。

1. 应用OpenNHP插件的必要性

OpenNHP插件的开发一方面解决了UDP协议与网页端HTTP请求之间的兼容性问题,另一方面通过定制化身份认证服务满足了政务平台多样化的需求。插件的开发是NHP框架进一步扩展和灵活适应政务数据流通应用的关键步骤。具体原因如下:

1.1 协议兼容性与技术限制

NHP标准协议基于UDP协议进行通信,UDP具有轻量、快速的特点,适合大规模、高频次的数据传输。然而,在某些应用场景中,尤其是基于网页的应用,如HTML5网页,浏览器中的JavaScript只能发起HTTP请求,无法直接发送UDP请求。这就带来了协议不兼容的问题。由于很多现代政务应用通过网页端进行操作和数据交互,插件的开发变得非常必要,以弥补这个技术差距。

通过开发OpenNHP插件,NHP服务器能够接收来自网页端的HTTP请求(通常是网页中的敲门包),并转换为UDP协议进行内部通信。这种机制确保了基于HTTP请求的网页应用与NHP服务器的无缝对接,从而拓展了NHP框架的应用范围,特别是在依赖浏览器与后台服务交互的场景中,提升了数据传输的灵活性和兼容性。

1.2 身份认证的定制化需求

政务数据流通涉及到高度安全的身份认证与权限管理。然而,标准的身份认证协议无法满足政务场景中的复杂需求。不同的政务平台有各自的认证机制,它们的身份认证流程具有很高的定制化需求。传统的标准协议在应对这些平台时显得过于僵化,无法灵活对接各自的认证系统。

OpenNHP插件可以通过定制化服务来对接不同的政务平台,根据具体平台的要求,灵活适配其身份认证流程。插件提供了定制化开发的能力,允许开发者根据不同政务平台的需求对身份认证机制进行调整,使NHP框架能够与不同平台无缝集成。这不仅提高了身份认证的安全性,还确保了数据流通的合规性和灵活性。

2. 插件工作原理

整个插件的执行流程涵盖了从用户发起请求、服务器解析插件、插件执行逻辑再到最终反馈给用户的完整过程。每一步都起着关键作用,确保了NHP服务器能够通过插件来满足不同场景下的请求处理需求,特别是在身份验证和敲门包机制上。

插件工作原理架构图

图一 插件工作原理架构图

2.1 用户通过浏览器发起HTTP请求

用户在浏览器中输入指定的URL地址,向NHP服务器发送HTTP请求。例如,用户访问URL:

  • http://127.0.0.1:port/plugins/example?resid=demo&action=login.

这是整个流程的起点,通常由网页或应用发出的请求,需要通过插件来处理。

URL组成部分说明
127.0.0.1:port前半部分为NHP-Server服务器IP地址,后半部分为NHP服务端口号
plugin插件目录
example插件名称
resid插件资源id
action执行的动作,用于在插件程序代码中判断所要执行的辅助函数

表一 URL组成部分说明

2.2 NHP服务器解析URL并调用对应插件

NHP服务器接收到来自浏览器的HTTP请求后,会根据请求的URL路径和参数解析出需要调用的插件。在这个过程中,NHP服务器识别出plugins/example部分,并将请求导入到名为“example”的插件中进行进一步处理。

2.3 插件程序执行核心功能

插件程序根据URL中的参数(如resid=demo和action=login),执行相应的功能。插件的核心功能包括身份认证和一系列的“敲门包”(Knock)请求处理步骤。具体流程可以是根据这些参数执行一系列函数,核心函数处理主逻辑,辅助函数则提供支持,以完成身份验证、资源访问等任务。

2.4 插件完成代码执行流程

插件在处理请求时,经过身份验证或其他定制化服务的逻辑后,插件的代码流程执行完成。这一步是插件实现其核心功能的关键,所有的认证、授权或其他逻辑在此步完成。

2.5 NHP服务器向用户响应HTTP请求

插件处理完毕后,将结果反馈给NHP服务器,NHP服务器则通过HTTP协议将处理结果响应给用户。用户最终会在浏览器端接收到返回的内容,可能是操作成功的确认信息,或是相关数据、页面更新等内容。

3. 插件开发原理

3.1 环境准备

在开发OpenNHP插件之前,确保以下开发环境已经搭建完成:

1.开发语言:选择Golang语言进行开发。

2.开发工具:推荐使用IDEA、VS Code等集成开发环境。

3.OpenNHP源码:从GitHub下载最新版本的opennhp代码,并集成至开发环境。下载地址:https://github.com/OpenNHP/opennhp。

3.2 初始化项目

首先在server/plugins目录下创建新的插件项目,例如现在我需要创建一个名为”example”的插件项目。

example插件上级目录

图二 example插件上级目录

NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例如,example 插件位于 NHP/server/plugins/example 目录下,并且有自己的 example.go 文件。

初始化后的项目结构包括基础的配置文件和插件框架,主体包括etc目录及该目录下的配置文件(config.toml、resource.toml)、主程序文件main.go、自动化编译文件Makefile等。如果待开发插件需要集成前端页面,则可添加templates目录及该目录下的前端html页面.

典型的插件文件,如 example.go,包含以下内容:

  • 必要包的导入语句
  • 与插件相关的常量和变量
  • 辅助函数
  • 主插件函数

example插件目录结构示例

图三 example插件目录结构示例

文件(夹)名称作用
etc目录下包含插件配置文件和资源文件
config.toml定义了插件代码运行过程中的一些配置文件信息
resource.toml定义了插件资源信息
templates存放集成的前端页面模版,如不需要可忽略
main.go插件主程序文件,定义了核心主函数和一系列辅助函数的功能
Makefile自动化编译文件

表二 插件目录及文件作用

3.3 插件功能设计

在插件功能设计阶段,需明确以下几个核心点:

数据流通场景:定义数据流通过程中的参与者、权限及流转路径。

安全策略:通过零信任架构设置严格的访问控制和验证机制。

日志与审计:设计完善的日志记录功能,以便后续追溯和审计。

例如“example”插件所要实现的功能主体为:

  1. 在H5页面提交包含用户名、密码的表单;

  2. NHP-Server服务器接收表单进行验证,验证成功后向NHP-AC服务器发起敲门;

  3. NHP-AC开门成功后返回应用服务器地址给客户端;

  4. 访问应用服务器资源。

3.4 核心代码开发

以下是为 NHP 服务器开发插件的步骤:

  1. 在 NHP/server/plugins 下创建您的插件的新目录。目录名称应为您的插件名称。

  2. 在插件目录中创建一个新的 Go 文件。文件名应与目录名称相同。例如,对于名为 myplugin 的插件,您将创建一个名为 myplugin.go 的文件。

  3. 定义您的插件函数。您的插件应至少有一个执行插件核心功能的主要函数。您还可以根据需要定义辅助函数。

  4. 在主应用程序中导入您的插件。在主应用程序文件 (main.go) 中,导入您的插件包并根据需要调用您的插件函数。

参照插件功能设计进行代码开发,以“example”插件为例,设计AuthWithHttp函数接收处理HTTP请求,authRegular函数验证用户名密码并进行敲门,authAndShowLogin函数加载登录页面资源等,并且需要设计验辅助函数来实现功能。按照具体功能要求可进行拓展开发。

example插件核心代码以及辅助代码函数示例

example插件核心代码以及辅助代码函数示例

example插件核心代码以及辅助代码函数示例

图四、五、六 example插件核心代码以及辅助代码函数示例

3.5 插件的编译测试与部署

插件的测试与部署是确保插件功能完备、性能稳定的关键步骤。通过本地环境测试和优化,开发者可以在保证插件功能正确性的基础上进行实际部署。在生产环境中,需对插件进行精确配置,并结合安全与运维策略,确保插件在实际应用中能够满足业务需求并长期稳定运行。具体步骤如下:

1.插件的编译

编译过程确保插件的代码与主项目保持一致,同时通过 Makefile 中的任务依赖关系,保证了插件的构建流程和主系统的编译紧密结合,实现一体化的构建与发布流程。具体步骤如下:

定义插件目录: 在 Makefile 的顶部,我们可以看到一行定义插件目录的代码,如下图所示:

定义插件目录

图七 定义插件目录

这行代码指定了插件的存放位置,即 server/plugins 目录。所有插件的源码和配置文件将会放在这个目录下,在启动NHP服务时,要确保插件能够正常加载,需要在NHP-Server的etc/resource.toml配置文件中配置插件文件路径。

插件文件路径配置

图八 插件文件路径配置

生成版本信息并开始构建: 在 generate-version-and-build 任务中,包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。

插件的编译逻辑: 在 Makefile 中的 plugins: 任务负责执行插件的编译,如下图:

插件编译任务plugins

图九 插件编译任务plugins

插件目录检查: test -d $(NHP_PLUGINS) 用于检查是否存在定义好的插件目录 (server/plugins)。

执行编译: 如果插件目录存在,$(MAKE) -C $(NHP_PLUGINS) 会进入该目录并执行其中的 Makefile,即在插件目录内执行插件的编译操作。

整体编译过程:在整体项目构建过程中(Linux与macOS:运行代码根目录下脚本 make; Windows:运行代码根目录下BAT文件 build.bat),Makefile 中的 plugins 任务会被调用。如果插件目录存在且有效,插件的 Makefile 会被执行以完成插件的构建。在编译的过程中,可能会生成插件的二进制文件或其他形式的输出文件,以供 NHP 服务器使用。

2.本地环境功能测试

要测试您的插件,您可以在与插件文件相同的目录中编写一个单独的 _test.go 文件来编写单元测试。Go 的内置测试包 (testing) 可用于编写和运行测试。

插件开发完成,且编译成功后,首先需要在本地环境进行功能测试。这一步主要用于验证插件的核心功能是否正确实现,确保插件的所有功能模块能够正常工作。可以通过模拟实际应用场景的请求,验证插件的响应是否符合预期,并观察日志记录以查找可能存在的问题。常见的测试步骤包括:

  1. 发起HTTP请求或UDP请求,测试插件的响应情况;

  2. 验证插件中的身份认证、敲门、开门、授权流程是否按预期执行;

  3. 测试插件的错误处理和异常捕获机制;

在本地测试阶段,开发者可以通过调试工具、日志记录以及断点调试来细致排查和解决代码中的潜在问题,确保插件的逻辑严谨且无重大漏洞。

3.功能确认与优化

在本地环境测试通过后,开发者需要对插件的功能进行确认与优化。确认插件的核心功能是否完全符合需求文档的描述,是否所有预期的功能都得到了正确的实现。如果在测试中发现插件的某些功能未达预期或有进一步优化空间,此时可以根据测试结果进行相应的代码调整和功能优化。

4.实际应用场景的配置与部署

本地测试和优化完成后,插件即可进入实际应用场景的部署阶段。要部署您的插件,只需构建并运行主应用程序。您的插件将包含在构建中,并在服务器运行时可用。在部署插件时,通常需要根据应用场景的具体需求进行配置。具体步骤如下:

部署环境准备:确保生产环境的服务器配置与本地测试环境一致或接近,包括操作系统、网络配置、依赖库等。

插件安装与配置:将经过测试的插件代码部署到生产服务器上,按照实际应用场景的要求进行相应的配置,包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。

日志与监控设置:在部署完成后,完善日志等级配置,便于在实际应用中及时发现和解决问题。

启动NHP服务查看插件加载情况:按照NHP服务启动流程启动NHP服务,根据log目录下的日志文件查看插件的加载情况,并且按照本地插件测试流程验证插件功能是否正常。

5. 生产环境验证与运维

插件部署完成后,需要在实际应用环境中对其进行功能验证,确保在生产环境下插件能够正常工作。在插件上线后,还应定期进行运维,持续监控插件的表现,记录运行数据,并及时进行必要的更新和维护,确保插件在长期使用中保持最佳状态。

结论

为 NHP 服务器开发插件可以以一种模块化和可维护的方式扩展服务器的功能。通过遵循上述步骤,您可以创建自己的插件并为 NHP 服务器项目做出贡献。