Merge pull request #1225 from Fypy1019/main

updata server_plugin.md and server_plugin.zh_cn.md
OpenNHP · Oct 23, 2024 · e542aea · e542aea
2 parents 2205954 + 00350aa
commit e542aea
Show file tree

Hide file tree

Showing 8 changed files with 279 additions and 37 deletions.
diff --git a/docs/images/plugin_image10.png b/docs/images/plugin_image10.png
diff --git a/docs/images/plugin_image5.png b/docs/images/plugin_image5.png
diff --git a/docs/images/plugin_image6.png b/docs/images/plugin_image6.png
diff --git a/docs/images/plugin_image7.png b/docs/images/plugin_image7.png
diff --git a/docs/images/plugin_image8.png b/docs/images/plugin_image8.png
diff --git a/docs/images/plugin_image9.png b/docs/images/plugin_image9.png
diff --git a/docs/server_plugin.md b/docs/server_plugin.md
diff --git a/docs/zh-cn/server_plugin.zh-cn.md b/docs/zh-cn/server_plugin.zh-cn.md
@@ -117,7 +117,7 @@ NHP服务器接收到来自浏览器的HTTP请求后，会根据请求的URL路
 
 **2.开发工具**：推荐使用IDEA、VS Code等集成开发环境。
 
-**3.NHP SDK**：从GitHub下载最新版本的opennhp代码，并集成至开发环境。下载地址：https://github.com/OpenNHP/opennhp。
+**3.OpenNHP源码**：从GitHub下载最新版本的opennhp代码，并集成至开发环境。下载地址：https://github.com/OpenNHP/opennhp。
 
 ### 3.2 初始化项目
 
@@ -129,7 +129,7 @@ NHP服务器接收到来自浏览器的HTTP请求后，会根据请求的URL路
 
 NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例如，example 插件位于 NHP/server/plugins/example 目录下，并且有自己的 example.go 文件。
 
-初始化后的项目结构包括基础的配置文件和插件框架，主体包括etc目录及该目录下的配置文件(config.toml、resource.toml)、主程序文件main.go、	自动化编译文件Makefile等。如果待开发插件需要集成前端页面，则可添加templates目录及该目录下的前端html页面.
+初始化后的项目结构包括基础的配置文件和插件框架，主体包括etc目录及该目录下的配置文件(config.toml、resource.toml)、主程序文件main.go、自动化编译文件Makefile等。如果待开发插件需要集成前端页面，则可添加templates目录及该目录下的前端html页面.
 
 典型的插件文件，如 example.go，包含以下内容：
 
@@ -165,19 +165,13 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例
 
 例如“example”插件所要实现的功能主体为：
 
-(1) 在某省身份认证平台接收到用户所提交的包含用户民、密码的表单后，NHP-Server服务器接收来自某省认证平台跳转URL中所附带的ticket；
+1. 在H5页面提交包含用户名、密码的表单；
 
-(2) 调用某省身份认证平台验证ticket接口，接收响应报文，并提取报文信息中附带的Token信息；
+2. NHP-Server服务器接收表单进行验证，验证成功后向NHP-AC服务器发起敲门；
 
-(3) NHP-Server服务器向某省身份认证平台发送POST请求，验证Token有效性，请求格式参照对接文档中的接口签名方案与参数信息；
+3. NHP-AC开门成功后返回应用服务器地址给客户端；
 
-(4) Token验证成功后，NHP-Server服务器向NHP-AC门禁服务器发送开门请求，开门成功后302跳转到应用代理服务器。
-
-整个功能流程时序图如下：
-
-![插件功能时序图示例](/images/plugin_image5.png) 
-
-***图四 插件功能时序图示例***
+4. 访问应用服务器资源。
 
 ### 3.4 核心代码开发
 
@@ -191,19 +185,15 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例
 
 4. 在主应用程序中导入您的插件。在主应用程序文件 (main.go) 中，导入您的插件包并根据需要调用您的插件函数。
 
-参照插件功能设计进行代码开发，以“example”插件为例，AuthWithHttp函数接收HTTP请求，authRegular函数处理URL参数信息，并且需要设计验证ticket函数（ValidateTicket）、验证token有效性函数（ValidateToken）、构造带有token的POST请求函数（fetchToken）以及生成签名方案函数（signDemo）等辅助函数来实现功能。按照具体功能要求可进行拓展开发。
+参照插件功能设计进行代码开发，以“example”插件为例，设计AuthWithHttp函数接收处理HTTP请求，authRegular函数验证用户名密码并进行敲门，authAndShowLogin函数加载登录页面资源等，并且需要设计验辅助函数来实现功能。按照具体功能要求可进行拓展开发。
 
 ![example插件核心代码以及辅助代码函数示例](/images/plugin_image6.png) 
 
 ![example插件核心代码以及辅助代码函数示例](/images/plugin_image7.png) 
 
 ![example插件核心代码以及辅助代码函数示例](/images/plugin_image8.png) 
 
-![example插件核心代码以及辅助代码函数示例](/images/plugin_image9.png) 
-
-![example插件核心代码以及辅助代码函数示例](/images/plugin_image10.png) 
-
-***图五、六、七、八、九 example插件核心代码以及辅助代码函数示例***
+***图四、五、六 example插件核心代码以及辅助代码函数示例***
 
 ### 3.5 插件的编译测试与部署
 
@@ -213,43 +203,43 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例
 
  编译过程确保插件的代码与主项目保持一致，同时通过 Makefile 中的任务依赖关系，保证了插件的构建流程和主系统的编译紧密结合，实现一体化的构建与发布流程。具体步骤如下：
 
-**(1)定义插件目录**: 在 Makefile 的顶部，我们可以看到一行定义插件目录的代码,如下图所示：
+***定义插件目录***: 在 Makefile 的顶部，我们可以看到一行定义插件目录的代码,如下图所示：
 
 ![定义插件目录](/images/plugin_image11.png) 
 
-***图十 定义插件目录***
+***图七 定义插件目录***
 
 这行代码指定了插件的存放位置，即 server/plugins 目录。所有插件的源码和配置文件将会放在这个目录下，在启动NHP服务时，要确保插件能够正常加载，需要在NHP-Server的etc/resource.toml配置文件中配置插件文件路径。
 
 ![插件文件路径配置](/images/plugin_image12.png) 
 
-***图十一 插件文件路径配置***
+***图八 插件文件路径配置***
 
-**(2)生成版本信息并开始构建**: 在 generate-version-and-build 任务中，包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。
+***生成版本信息并开始构建***: 在 generate-version-and-build 任务中，包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。
 
-**(3)插件的编译逻辑**: 在 Makefile 中的 plugins: 任务负责执行插件的编译，如下图：
+***插件的编译逻辑***: 在 Makefile 中的 plugins: 任务负责执行插件的编译，如下图：
 
 ![插件编译任务plugins](/images/plugin_image13.png) 
 
-***图十二 插件编译任务plugins***
+***图九 插件编译任务plugins***
 
 插件目录检查: test -d $(NHP_PLUGINS) 用于检查是否存在定义好的插件目录 (server/plugins)。
 
 执行编译: 如果插件目录存在，$(MAKE) -C $(NHP_PLUGINS) 会进入该目录并执行其中的 Makefile，即在插件目录内执行插件的编译操作。
 
-**(4)整体编译过程**：在整体项目构建过程中（Linux与macOS：运行代码根目录下脚本 make; Windows：运行代码根目录下BAT文件 build.bat），Makefile 中的 plugins 任务会被调用。如果插件目录存在且有效，插件的 Makefile 会被执行以完成插件的构建。在编译的过程中，可能会生成插件的二进制文件或其他形式的输出文件，以供 NHP 服务器使用。
+***整体编译过程***：在整体项目构建过程中（Linux与macOS：运行代码根目录下脚本 make; Windows：运行代码根目录下BAT文件 build.bat），Makefile 中的 plugins 任务会被调用。如果插件目录存在且有效，插件的 Makefile 会被执行以完成插件的构建。在编译的过程中，可能会生成插件的二进制文件或其他形式的输出文件，以供 NHP 服务器使用。
 
 **2.本地环境功能测试**
 
 要测试您的插件，您可以在与插件文件相同的目录中编写一个单独的 _test.go 文件来编写单元测试。Go 的内置测试包 (testing) 可用于编写和运行测试。
 
 插件开发完成，且编译成功后，首先需要在本地环境进行功能测试。这一步主要用于验证插件的核心功能是否正确实现，确保插件的所有功能模块能够正常工作。可以通过模拟实际应用场景的请求，验证插件的响应是否符合预期，并观察日志记录以查找可能存在的问题。常见的测试步骤包括：
 
-(1) 发起HTTP请求或UDP请求，测试插件的响应情况；
+1. 发起HTTP请求或UDP请求，测试插件的响应情况；
 
-(2) 验证插件中的身份认证、敲门、开门、授权流程是否按预期执行；
+2. 验证插件中的身份认证、敲门、开门、授权流程是否按预期执行；
 
-(3) 测试插件的错误处理和异常捕获机制；
+3. 测试插件的错误处理和异常捕获机制；
 
 在本地测试阶段，开发者可以通过调试工具、日志记录以及断点调试来细致排查和解决代码中的潜在问题，确保插件的逻辑严谨且无重大漏洞。
 
@@ -261,20 +251,17 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例
 
 本地测试和优化完成后，插件即可进入实际应用场景的部署阶段。要部署您的插件，只需构建并运行主应用程序。您的插件将包含在构建中，并在服务器运行时可用。在部署插件时，通常需要根据应用场景的具体需求进行配置。具体步骤如下：
 
-**(1)部署环境准备**：确保生产环境的服务器配置与本地测试环境一致或接近，包括操作系统、网络配置、依赖库等。
+***部署环境准备***：确保生产环境的服务器配置与本地测试环境一致或接近，包括操作系统、网络配置、依赖库等。
 
-**(2)插件安装与配置**：将经过测试的插件代码部署到生产服务器上，按照实际应用场景的要求进行相应的配置，包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。
+***插件安装与配置***：将经过测试的插件代码部署到生产服务器上，按照实际应用场景的要求进行相应的配置，包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。
 
-**(3)日志与监控设置**：在部署完成后，完善日志等级配置，便于在实际应用中及时发现和解决问题。
+***日志与监控设置***：在部署完成后，完善日志等级配置，便于在实际应用中及时发现和解决问题。
 
-**(4)启动NHP服务查看插件加载情况**：按照NHP服务启动流程启动NHP服务，根据log目录下的日志文件查看插件的加载情况，并且按照本地插件测试流程验证插件功能是否正常。
+***启动NHP服务查看插件加载情况***：按照NHP服务启动流程启动NHP服务，根据log目录下的日志文件查看插件的加载情况，并且按照本地插件测试流程验证插件功能是否正常。
 
 **5. 生产环境验证与运维**
 
 插件部署完成后，需要在实际应用环境中对其进行功能验证，确保在生产环境下插件能够正常工作。在插件上线后，还应定期进行运维，持续监控插件的表现，记录运行数据，并及时进行必要的更新和维护，确保插件在长期使用中保持最佳状态。
 
 # 结论
-为 NHP 服务器开发插件可以以一种模块化和可维护的方式扩展服务器的功能。通过遵循上述步骤，您可以创建自己的插件并为 NHP 服务器项目做出贡献。
-
-
-
+为 NHP 服务器开发插件可以以一种模块化和可维护的方式扩展服务器的功能。通过遵循上述步骤，您可以创建自己的插件并为 NHP 服务器项目做出贡献。