From cd365353d97fe78630f39999bb85e76447a8796d Mon Sep 17 00:00:00 2001 From: qq_51961435 <1548345616@qq.com> Date: Tue, 24 Sep 2024 00:32:59 +0800 Subject: [PATCH 1/8] modify server_plugin.md --- docs/server_plugin.md | 269 +++++++++++++++++++++++++++++- docs/zh-cn/server_plugin.zh-cn.md | 39 +++-- 2 files changed, 289 insertions(+), 19 deletions(-) diff --git a/docs/server_plugin.md b/docs/server_plugin.md index 8eba0d55..b4501a6a 100644 --- a/docs/server_plugin.md +++ b/docs/server_plugin.md @@ -8,7 +8,274 @@ permalink: /server_plugin/ # Develop NHP-Server Plugins {: .fs-9 } -[中文版](/zh-cn/server_plugin/){: .label .fs-4 } +# OpenNHP Plugin Development Guide + +## Table of Contents + +- [Introduction](#introduction) + +- [1. The Necessity of Applying OpenNHP Plugins](#1-the-necessity-of-applying-opennhp-plugins) + + - [1.1 Protocol Compatibility and Technical Limitations](#11-protocol-compatibility-and-technical-limitations) + + - [1.2 Customization Needs for Authentication](#12-customization-needs-for-authentication) + +- [2. How the Plugin Works](#2-how-the-plugin-works) + + - [2.1 User Initiates an HTTP Request via Browser](#21-user-initiates-an-http-request-via-browser) + + - [2.2 NHP Server Parses the URL and Calls the Appropriate Plugin](#22-nhp-server-parses-the-url-and-calls-the-appropriate-plugin) + + - [2.3 The Plugin Executes Core Functionality](#23-the-plugin-executes-core-functionality) + + - [2.4 Plugin Completes the Code Execution Process](#24-plugin-completes-the-code-execution-process) + + - [2.5 NHP Server Responds to the User with the HTTP Request Results](#25-nhp-server-responds-to-the-user-with-the-http-request-results) + +- [3. Plugin Development Principles](#3-plugin-development-principles) + + - [3.1 Environment Setup](#31-environment-setup) + + - [3.2 Project Initialization](#32-project-initialization) + + - [3.3 Plugin Function Design](#33-plugin-function-design) + + - [3.4 Core Code Development](#34-core-code-development) + + - [3.5 Plugin Compilation, Testing, and Deployment](#35-plugin-compilation-testing-and-deployment) + +- [Conclusion](#conclusion) + +## Introduction + +Plugins in the NHP server are modules that add specific features to the main application. They are designed to be highly modular and loosely coupled with the core application, allowing developers to add, remove, or update plugins without affecting the main functionality of the server. + +## 1. The Necessity of Applying OpenNHP Plugins + +The development of OpenNHP plugins solves the compatibility issues between the UDP protocol and web-based HTTP requests, while also addressing the customization needs for authentication in government platforms. Developing plugins is crucial for further extending the NHP framework and adapting it to the flexible needs of government data flow applications. The reasons are as follows: + +### 1.1 Protocol Compatibility and Technical Limitations + +The NHP standard protocol communicates over the UDP protocol, which is lightweight and fast, making it suitable for large-scale, high-frequency data transmissions. However, in certain scenarios, especially web-based interactions (e.g., HTML5 web pages), JavaScript running in a browser can only make HTTP requests and cannot directly send UDP requests. This creates a protocol incompatibility issue. Many modern government applications rely on web interactions, making plugin development essential to overcome this technical limitation. + +By developing OpenNHP plugins, the NHP server can receive HTTP requests from web clients (often "knock packets") and convert them into the UDP protocol needed for internal communication. This mechanism ensures seamless integration between web applications based on HTTP and the NHP server, extending the NHP framework's application scope. It particularly enhances flexibility and compatibility in data transmission in scenarios involving browser-to-backend service interactions. + +### 1.2 Customization Needs for Authentication + +Government data flow involves highly secure identity authentication and access management. However, standard authentication protocols cannot meet the complex needs of government scenarios. Different government platforms have their own authentication mechanisms and demand highly customized authentication processes. Traditional standard protocols are too rigid to flexibly integrate with these platforms. + +OpenNHP plugins can interface with different government platforms by offering custom services to accommodate their authentication processes. The plugins allow developers to tailor the authentication mechanisms according to the specific requirements of different platforms, ensuring seamless integration with the NHP framework. This not only enhances authentication security but also ensures compliance and flexibility in data flow management. + +## 2. How the Plugin Works + +The entire plugin execution process covers the complete flow from user requests, server plugin parsing, plugin logic execution, to final feedback to the user. Each step ensures that the NHP server, via the plugin, meets the demands of various request processing scenarios, especially in authentication and "knock packet" handling. + +![Plugin Workflow Diagram](/images/plugin_image2.png) + +***Figure 1: Plugin Workflow Diagram*** + +### 2.1 User Initiates an HTTP Request via Browser + +The user inputs a specific URL address in their browser, sending an HTTP request to the NHP server. For example, a user accesses the following URL: +- `http://127.0.0.1:port/plugins/example?resid=demo&action=login` + +This is the starting point of the entire process, typically initiated by a webpage or application request that needs to be handled by the plugin. + +| URL Component | Description | +| ---------------- | ------------------------------------------------------------| +| `127.0.0.1:port` | The first part is the IP address of the NHP server, followed by the port number | +| `plugins` | Plugin directory | +| `example` | Plugin name | +| `resid` | Plugin resource ID | +| `action` | The action to be executed, used to determine which auxiliary function the plugin performs | + +***Table 1: URL Component Breakdown*** + +### 2.2 NHP Server Parses the URL and Calls the Appropriate Plugin + +After the HTTP request reaches the NHP server, the server parses the URL path and parameters to determine which plugin to call. During this process, the NHP server identifies the `plugins/example` part of the URL and routes the request to the "example" plugin for processing. + +### 2.3 The Plugin Executes Core Functionality + +Based on the parameters in the URL (such as `resid=demo` and `action=login`), the plugin executes the corresponding functionality. The core functions of the plugin include authentication and a series of "knock packet" processing steps. The core functionality handles the main logic, while auxiliary functions provide support for tasks such as authentication and resource access. + +### 2.4 Plugin Completes the Code Execution Process + +After processing the request and completing the authentication or other custom services, the plugin finishes its code execution process. This step is key to the core functionality of the plugin, where all authentication, authorization, or other logic is executed. + +### 2.5 NHP Server Responds to the User with the HTTP Request Results + +Once the plugin finishes its process, the result is sent back to the NHP server, which responds to the user via HTTP. The user will eventually see a feedback message in their browser, such as a confirmation message or relevant data or page update. + +## 3. Plugin Development Principles + +### 3.1 Environment Setup + +Before developing OpenNHP plugins, ensure the following environment is properly set up: + +1. **Development Language**: Go language is used for development. +2. **Development Tools**: IDEs like IntelliJ IDEA or VS Code are recommended. +3. **NHP SDK**: Download and integrate the latest version of the OpenNHP code from GitHub into your development environment. Download URL: [https://github.com/OpenNHP/opennhp](https://github.com/OpenNHP/opennhp). + +### 3.2 Project Initialization + +First, create a new plugin project under the `server/plugins` directory. For example, let's create a plugin named "example." + +![Example Plugin Directory Structure](/images/plugin_image3.png) + +***Figure 2: Example Plugin Parent Directory*** + +Each plugin in the NHP server is typically structured as a separate Go package. For instance, the "example" plugin would be located in the `NHP/server/plugins/example` directory and would have its own `example.go` file. + +The initialized project structure includes basic configuration files and the plugin framework, primarily consisting of the `etc` directory with configuration files (`config.toml`, `resource.toml`), the main program file `main.go`, and the automation build file `Makefile`. If the plugin requires integration with front-end pages, the `templates` directory and corresponding front-end HTML files can also be added. + +A typical plugin file, such as `example.go`, contains the following: + +- Necessary import statements +- Constants and variables related to the plugin +- Helper functions +- Main plugin function + +![Example Plugin Directory Structure](/images/plugin_image4.png) + +***Figure 3: Example Plugin Directory Structure*** + +| ***File/Directory Name*** | ***Purpose*** | +| ------------------------- | ---------------------------------------------------------- | +| etc | Contains configuration and resource files for the plugin | +| config.toml | Defines configuration details for the plugin during runtime | +| resource.toml | Defines resource-related information for the plugin | +| templates | Stores integrated front-end page templates (optional) | +| main.go | Main program file defining core functions and helper logic | +| Makefile | Automation build file | + +***Table 2: Plugin Directory and File Purposes*** + +## 3.3 Plugin Function Design + +In the plugin function design phase, the following core points need to be clarified: + +***Data Flow Scenarios***: Define the participants, permissions, and flow paths involved in the data circulation process. + +***Security Policies***: Establish strict access control and verification mechanisms through a zero-trust architecture. + +***Logging and Auditing***: Design comprehensive logging functionalities for subsequent tracing and auditing. + +For example, the main functionality to be implemented by the "example" plugin is as follows: + +1. When the identity authentication platform of a province receives a user-submitted form containing the user's ID and password, the NHP-Server receives the ticket attached to the redirect URL from the provincial authentication platform; + +2. Call the ticket verification interface of the provincial identity authentication platform, receive the response message, and extract the Token information included in the message; + +3. The NHP-Server sends a POST request to the provincial identity authentication platform to verify the validity of the Token, with the request format referring to the interface signature scheme and parameter information in the integration document; + +4. After successful Token verification, the NHP-Server sends an open door request to the NHP-AC access control server, and after a successful opening, redirects to the application proxy server with a 302 response. + +The sequence diagram for the entire functionality process is as follows: + +![Plugin Function Sequence Diagram Example](/images/plugin_image5.png) + +***Figure 4 Plugin Function Sequence Diagram Example*** + +## 3.4 Core Code Development + +The steps for developing the plugin for the NHP server are as follows: + +1. Create a new directory for your plugin under NHP/server/plugins. The directory name should be the name of your plugin. + +2. In the plugin directory, create a new Go file. The file name should be the same as the directory name. For example, for a plugin named myplugin, you would create a file named myplugin.go. + +3. Define your plugin functions. Your plugin should have at least one main function that executes the core functionality of the plugin. You can also define auxiliary functions as needed. + +4. Import your plugin in the main application. In the main application file (main.go), import your plugin package and call your plugin functions as needed. + +Following the plugin function design, taking the "example" plugin as an example, the AuthWithHttp function receives HTTP requests, the authRegular function processes URL parameter information, and you need to design auxiliary functions such as ValidateTicket for ticket verification, ValidateToken for Token validity verification, fetchToken for constructing POST requests with Token, and signDemo for generating signature schemes to achieve functionality. Development can be extended according to specific functional requirements. + +![Example Plugin Core Code and Auxiliary Code Function Example](/images/plugin_image6.png) + +![Example Plugin Core Code and Auxiliary Code Function Example](/images/plugin_image7.png) + +![Example Plugin Core Code and Auxiliary Code Function Example](/images/plugin_image8.png) + +![Example Plugin Core Code and Auxiliary Code Function Example](/images/plugin_image9.png) + +![Example Plugin Core Code and Auxiliary Code Function Example](/images/plugin_image10.png) + +***Figures 5, 6, 7, 8, 9 Example Plugin Core Code and Auxiliary Code Function Example*** + +## 3.5 Plugin Compilation Testing and Deployment + +Testing and deployment of the plugin are crucial steps to ensure the completeness and stability of plugin functionality. Through local environment testing and optimization, developers can deploy the plugin in a way that ensures the correctness of its functionality. In the production environment, the plugin must be accurately configured, combined with security and operation strategies, to ensure that it meets business needs and runs stably in real applications. The specific steps are as follows: + +**1. Plugin Compilation** + +The compilation process ensures that the plugin's code is consistent with the main project, while the task dependencies in the Makefile ensure that the plugin's build process is closely integrated with the main system's compilation, achieving an integrated build and release process. The specific steps are as follows: + +**Define Plugin Directory**: At the top of the Makefile, we can see a line of code defining the plugin directory, as shown in the image below: + +![Define Plugin Directory](/images/plugin_image11.png) + +***Figure 10 Define Plugin Directory*** + +This line of code specifies the storage location of the plugin, which is the server/plugins directory. All plugin source codes and configuration files will be placed in this directory. When starting the NHP service, to ensure the plugin loads correctly, the plugin file path needs to be configured in the NHP-Server's etc/resource.toml configuration file. + +![Plugin File Path Configuration](/images/plugin_image12.png) + +***Figure 11 Plugin File Path Configuration*** + +**Generate Version Information and Start Build**: The generate-version-and-build task includes a series of steps to generate version numbers, commit IDs, build times, and other information. This information is helpful for tracking the version and build status of the plugin. + +**Plugin Compilation Logic**: In the Makefile, the plugins: task is responsible for executing the plugin compilation, as shown in the image below: + +![Plugin Compilation Task plugins](/images/plugin_image13.png) + +***Figure 12 Plugin Compilation Task plugins*** + +Plugin Directory Check: test -d $(NHP_PLUGINS) checks if the defined plugin directory (server/plugins) exists. + +Execute Compilation: If the plugin directory exists, $(MAKE) -C $(NHP_PLUGINS) enters that directory and executes the Makefile within it, performing the compilation operation for the plugin. + +**Overall Compilation Process**: During the overall project build process (Linux and macOS: run the script make in the root directory; Windows: run the BAT file build.bat in the root directory), the plugins task in the Makefile will be called. If the plugin directory exists and is valid, the plugin's Makefile will be executed to complete the plugin's build. During compilation, plugin binary files or other forms of output files may be generated for use by the NHP server. + +**2. Local Environment Function Testing** + +To test your plugin, you can write a separate _test.go file in the same directory as the plugin file to write unit tests. Go's built-in testing package (testing) can be used to write and run tests. + +Once the plugin development is complete and compiled successfully, it is necessary to perform functional testing in the local environment first. This step is primarily used to verify whether the core functionality of the plugin has been correctly implemented and to ensure that all functional modules of the plugin are working correctly. You can simulate actual application scenario requests to verify whether the plugin's response meets expectations and check the logs for potential issues. Common testing steps include: + +1. Initiate HTTP or UDP requests to test the plugin's response; + +2. Verify whether the identity authentication, knocking, opening, and authorization processes in the plugin are executed as expected; + +3. Test the plugin's error handling and exception capture mechanisms; + +During the local testing phase, developers can use debugging tools, logging, and breakpoint debugging to thoroughly investigate and resolve potential issues in the code, ensuring the logic of the plugin is rigorous and free of major vulnerabilities. + +**3. Function Confirmation and Optimization** + +After local environment testing passes, developers need to confirm and optimize the plugin's functionality. Confirm whether the core functions of the plugin fully meet the description in the requirements document, and whether all expected functionalities have been correctly implemented. If certain functions of the plugin are found to be below expectations or have further optimization potential during testing, code adjustments and functionality optimizations can be made based on the test results. + +**4. Configuration and Deployment in Actual Application Scenarios** + +Once local testing and optimization are complete, the plugin can proceed to the deployment phase in actual application scenarios. To deploy your plugin, simply build and run the main application. Your plugin will be included in the build and will be available when the server runs. During plugin deployment, it is usually necessary to configure according to the specific needs of the application scenario. The specific steps are as follows: + +**Deployment Environment Preparation**: Ensure that the server configuration in the production environment is consistent or close to that of the local testing environment, including the operating system, network configuration, dependency libraries, etc. + +**Plugin Installation and Configuration**: Deploy the tested plugin code to the production server, configuring it according to the requirements of the actual application scenario, including plugin paths, interface addresses, access control server addresses, authentication mechanisms, etc. + +**Logging and Monitoring Setup**: After deployment, improve log level configuration to facilitate timely detection and resolution of issues during actual application. + +**Start NHP Service to Check Plugin Loading Status**: Start the NHP service according to the NHP service startup process, check the plugin loading status based on the log files in the log directory, and verify whether the plugin functions normally according to the local plugin testing process. + +**5. Production Environment Validation and Maintenance** + +After the plugin deployment is complete, it is necessary to validate its functionality in the actual application environment to ensure that the plugin works correctly in the production environment. After the plugin goes live, regular maintenance should also be carried out to continuously monitor the plugin's performance, record operation data, and timely perform necessary updates and maintenance to ensure that the plugin remains in optimal condition during long-term use. + +## Conclusion +Developing plugins for the NHP server can extend the server's functionality in a modular and maintainable way. By following the steps outlined above, you can create your own plugins and contribute to the NHP server project. + + +[Chinese version](/docs/zh-cn/server_plugin.zh-cn.md){: .label .fs-4 } --- diff --git a/docs/zh-cn/server_plugin.zh-cn.md b/docs/zh-cn/server_plugin.zh-cn.md index a797c93a..0ef9fb9f 100644 --- a/docs/zh-cn/server_plugin.zh-cn.md +++ b/docs/zh-cn/server_plugin.zh-cn.md @@ -3,9 +3,11 @@ layout: page title: 服务器插件开发 parent: 中文版 nav_order: 7 -permalink: /zh-cn/server_plugin/ +permalink: /zh-cn/server_plugin.zh-cn/ --- +- {: .fs-9 } + # OpenNHP插件开发教程 # 目录 @@ -126,7 +128,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,包含以下内容: @@ -162,13 +164,13 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 例如“example”插件所要实现的功能主体为: -(1) 在某省身份认证平台接收到用户所提交的包含用户民、密码的表单后,NHP-Server服务器接收来自某省认证平台跳转URL中所附带的ticket; +1. 在某省身份认证平台接收到用户所提交的包含用户民、密码的表单后,NHP-Server服务器接收来自某省认证平台跳转URL中所附带的ticket; -(2) 调用某省身份认证平台验证ticket接口,接收响应报文,并提取报文信息中附带的Token信息; +2. 调用某省身份认证平台验证ticket接口,接收响应报文,并提取报文信息中附带的Token信息; -(3) NHP-Server服务器向某省身份认证平台发送POST请求,验证Token有效性,请求格式参照对接文档中的接口签名方案与参数信息; +3. NHP-Server服务器向某省身份认证平台发送POST请求,验证Token有效性,请求格式参照对接文档中的接口签名方案与参数信息; -(4) Token验证成功后,NHP-Server服务器向NHP-AC门禁服务器发送开门请求,开门成功后302跳转到应用代理服务器。 +4. Token验证成功后,NHP-Server服务器向NHP-AC门禁服务器发送开门请求,开门成功后302跳转到应用代理服务器。 整个功能流程时序图如下: @@ -210,7 +212,7 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 编译过程确保插件的代码与主项目保持一致,同时通过 Makefile 中的任务依赖关系,保证了插件的构建流程和主系统的编译紧密结合,实现一体化的构建与发布流程。具体步骤如下: -**(1)定义插件目录**: 在 Makefile 的顶部,我们可以看到一行定义插件目录的代码,如下图所示: +**定义插件目录**: 在 Makefile 的顶部,我们可以看到一行定义插件目录的代码,如下图所示: ![定义插件目录](/images/plugin_image11.png) @@ -222,9 +224,9 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 ***图十一 插件文件路径配置*** -**(2)生成版本信息并开始构建**: 在 generate-version-and-build 任务中,包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。 +**生成版本信息并开始构建**: 在 generate-version-and-build 任务中,包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。 -**(3)插件的编译逻辑**: 在 Makefile 中的 plugins: 任务负责执行插件的编译,如下图: +**插件的编译逻辑**: 在 Makefile 中的 plugins: 任务负责执行插件的编译,如下图: ![插件编译任务plugins](/images/plugin_image13.png) @@ -234,7 +236,7 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 执行编译: 如果插件目录存在,$(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.本地环境功能测试** @@ -242,11 +244,11 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 插件开发完成,且编译成功后,首先需要在本地环境进行功能测试。这一步主要用于验证插件的核心功能是否正确实现,确保插件的所有功能模块能够正常工作。可以通过模拟实际应用场景的请求,验证插件的响应是否符合预期,并观察日志记录以查找可能存在的问题。常见的测试步骤包括: -(1) 发起HTTP请求或UDP请求,测试插件的响应情况; +1. 发起HTTP请求或UDP请求,测试插件的响应情况; -(2) 验证插件中的身份认证、敲门、开门、授权流程是否按预期执行; +2. 验证插件中的身份认证、敲门、开门、授权流程是否按预期执行; -(3) 测试插件的错误处理和异常捕获机制; +3. 测试插件的错误处理和异常捕获机制; 在本地测试阶段,开发者可以通过调试工具、日志记录以及断点调试来细致排查和解决代码中的潜在问题,确保插件的逻辑严谨且无重大漏洞。 @@ -258,13 +260,13 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 本地测试和优化完成后,插件即可进入实际应用场景的部署阶段。要部署您的插件,只需构建并运行主应用程序。您的插件将包含在构建中,并在服务器运行时可用。在部署插件时,通常需要根据应用场景的具体需求进行配置。具体步骤如下: -**(1)部署环境准备**:确保生产环境的服务器配置与本地测试环境一致或接近,包括操作系统、网络配置、依赖库等。 +**部署环境准备**:确保生产环境的服务器配置与本地测试环境一致或接近,包括操作系统、网络配置、依赖库等。 -**(2)插件安装与配置**:将经过测试的插件代码部署到生产服务器上,按照实际应用场景的要求进行相应的配置,包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。 +**插件安装与配置**:将经过测试的插件代码部署到生产服务器上,按照实际应用场景的要求进行相应的配置,包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。 -**(3)日志与监控设置**:在部署完成后,完善日志等级配置,便于在实际应用中及时发现和解决问题。 +**日志与监控设置**:在部署完成后,完善日志等级配置,便于在实际应用中及时发现和解决问题。 -**(4)启动NHP服务查看插件加载情况**:按照NHP服务启动流程启动NHP服务,根据log目录下的日志文件查看插件的加载情况,并且按照本地插件测试流程验证插件功能是否正常。 +**启动NHP服务查看插件加载情况**:按照NHP服务启动流程启动NHP服务,根据log目录下的日志文件查看插件的加载情况,并且按照本地插件测试流程验证插件功能是否正常。 **5. 生产环境验证与运维** @@ -273,5 +275,6 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 # 结论 为 NHP 服务器开发插件可以以一种模块化和可维护的方式扩展服务器的功能。通过遵循上述步骤,您可以创建自己的插件并为 NHP 服务器项目做出贡献。 +[英文版](/docs/server_plugin.md){: .label .fs-4 } - \ No newline at end of file + --- \ No newline at end of file From 6e65c53c01890fc162c48391cd06a80bddaf0f6b Mon Sep 17 00:00:00 2001 From: qq_51961435 <1548345616@qq.com> Date: Tue, 24 Sep 2024 00:37:35 +0800 Subject: [PATCH 2/8] modify server_plugin.md --- docs/server_plugin.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/server_plugin.md b/docs/server_plugin.md index b4501a6a..b282a9b4 100644 --- a/docs/server_plugin.md +++ b/docs/server_plugin.md @@ -5,7 +5,6 @@ nav_order: 7 permalink: /server_plugin/ --- -# Develop NHP-Server Plugins {: .fs-9 } # OpenNHP Plugin Development Guide From f25feca68f873f022f84f8be7410b9eab07ea886 Mon Sep 17 00:00:00 2001 From: qq_51961435 <1548345616@qq.com> Date: Tue, 24 Sep 2024 00:43:58 +0800 Subject: [PATCH 3/8] modify server_plugin.md --- docs/server_plugin.md | 16 ++++++++-------- docs/zh-cn/server_plugin.zh-cn.md | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/server_plugin.md b/docs/server_plugin.md index b282a9b4..7fbd5077 100644 --- a/docs/server_plugin.md +++ b/docs/server_plugin.md @@ -210,7 +210,7 @@ Testing and deployment of the plugin are crucial steps to ensure the completenes The compilation process ensures that the plugin's code is consistent with the main project, while the task dependencies in the Makefile ensure that the plugin's build process is closely integrated with the main system's compilation, achieving an integrated build and release process. The specific steps are as follows: -**Define Plugin Directory**: At the top of the Makefile, we can see a line of code defining the plugin directory, as shown in the image below: +***Define Plugin Directory***: At the top of the Makefile, we can see a line of code defining the plugin directory, as shown in the image below: ![Define Plugin Directory](/images/plugin_image11.png) @@ -222,9 +222,9 @@ This line of code specifies the storage location of the plugin, which is the ser ***Figure 11 Plugin File Path Configuration*** -**Generate Version Information and Start Build**: The generate-version-and-build task includes a series of steps to generate version numbers, commit IDs, build times, and other information. This information is helpful for tracking the version and build status of the plugin. +***Generate Version Information and Start Build***: The generate-version-and-build task includes a series of steps to generate version numbers, commit IDs, build times, and other information. This information is helpful for tracking the version and build status of the plugin. -**Plugin Compilation Logic**: In the Makefile, the plugins: task is responsible for executing the plugin compilation, as shown in the image below: +***Plugin Compilation Logic***: In the Makefile, the plugins: task is responsible for executing the plugin compilation, as shown in the image below: ![Plugin Compilation Task plugins](/images/plugin_image13.png) @@ -234,7 +234,7 @@ Plugin Directory Check: test -d $(NHP_PLUGINS) checks if the defined plugin dire Execute Compilation: If the plugin directory exists, $(MAKE) -C $(NHP_PLUGINS) enters that directory and executes the Makefile within it, performing the compilation operation for the plugin. -**Overall Compilation Process**: During the overall project build process (Linux and macOS: run the script make in the root directory; Windows: run the BAT file build.bat in the root directory), the plugins task in the Makefile will be called. If the plugin directory exists and is valid, the plugin's Makefile will be executed to complete the plugin's build. During compilation, plugin binary files or other forms of output files may be generated for use by the NHP server. +***Overall Compilation Process***: During the overall project build process (Linux and macOS: run the script make in the root directory; Windows: run the BAT file build.bat in the root directory), the plugins task in the Makefile will be called. If the plugin directory exists and is valid, the plugin's Makefile will be executed to complete the plugin's build. During compilation, plugin binary files or other forms of output files may be generated for use by the NHP server. **2. Local Environment Function Testing** @@ -258,13 +258,13 @@ After local environment testing passes, developers need to confirm and optimize Once local testing and optimization are complete, the plugin can proceed to the deployment phase in actual application scenarios. To deploy your plugin, simply build and run the main application. Your plugin will be included in the build and will be available when the server runs. During plugin deployment, it is usually necessary to configure according to the specific needs of the application scenario. The specific steps are as follows: -**Deployment Environment Preparation**: Ensure that the server configuration in the production environment is consistent or close to that of the local testing environment, including the operating system, network configuration, dependency libraries, etc. +***Deployment Environment Preparation***: Ensure that the server configuration in the production environment is consistent or close to that of the local testing environment, including the operating system, network configuration, dependency libraries, etc. -**Plugin Installation and Configuration**: Deploy the tested plugin code to the production server, configuring it according to the requirements of the actual application scenario, including plugin paths, interface addresses, access control server addresses, authentication mechanisms, etc. +***Plugin Installation and Configuration***: Deploy the tested plugin code to the production server, configuring it according to the requirements of the actual application scenario, including plugin paths, interface addresses, access control server addresses, authentication mechanisms, etc. -**Logging and Monitoring Setup**: After deployment, improve log level configuration to facilitate timely detection and resolution of issues during actual application. +***Logging and Monitoring Setup***: After deployment, improve log level configuration to facilitate timely detection and resolution of issues during actual application. -**Start NHP Service to Check Plugin Loading Status**: Start the NHP service according to the NHP service startup process, check the plugin loading status based on the log files in the log directory, and verify whether the plugin functions normally according to the local plugin testing process. +***Start NHP Service to Check Plugin Loading Status***: Start the NHP service according to the NHP service startup process, check the plugin loading status based on the log files in the log directory, and verify whether the plugin functions normally according to the local plugin testing process. **5. Production Environment Validation and Maintenance** diff --git a/docs/zh-cn/server_plugin.zh-cn.md b/docs/zh-cn/server_plugin.zh-cn.md index 0ef9fb9f..f047bc6d 100644 --- a/docs/zh-cn/server_plugin.zh-cn.md +++ b/docs/zh-cn/server_plugin.zh-cn.md @@ -212,7 +212,7 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 编译过程确保插件的代码与主项目保持一致,同时通过 Makefile 中的任务依赖关系,保证了插件的构建流程和主系统的编译紧密结合,实现一体化的构建与发布流程。具体步骤如下: -**定义插件目录**: 在 Makefile 的顶部,我们可以看到一行定义插件目录的代码,如下图所示: +***定义插件目录***: 在 Makefile 的顶部,我们可以看到一行定义插件目录的代码,如下图所示: ![定义插件目录](/images/plugin_image11.png) @@ -224,9 +224,9 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 ***图十一 插件文件路径配置*** -**生成版本信息并开始构建**: 在 generate-version-and-build 任务中,包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。 +***生成版本信息并开始构建***: 在 generate-version-and-build 任务中,包含了一系列步骤用于生成版本号、提交 ID、构建时间等信息。这些信息有助于跟踪插件的版本和构建状态。 -**插件的编译逻辑**: 在 Makefile 中的 plugins: 任务负责执行插件的编译,如下图: +***插件的编译逻辑***: 在 Makefile 中的 plugins: 任务负责执行插件的编译,如下图: ![插件编译任务plugins](/images/plugin_image13.png) @@ -236,7 +236,7 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 执行编译: 如果插件目录存在,$(MAKE) -C $(NHP_PLUGINS) 会进入该目录并执行其中的 Makefile,即在插件目录内执行插件的编译操作。 -**整体编译过程**:在整体项目构建过程中(Linux与macOS:运行代码根目录下脚本 make; Windows:运行代码根目录下BAT文件 build.bat),Makefile 中的 plugins 任务会被调用。如果插件目录存在且有效,插件的 Makefile 会被执行以完成插件的构建。在编译的过程中,可能会生成插件的二进制文件或其他形式的输出文件,以供 NHP 服务器使用。 +***整体编译过程***:在整体项目构建过程中(Linux与macOS:运行代码根目录下脚本 make; Windows:运行代码根目录下BAT文件 build.bat),Makefile 中的 plugins 任务会被调用。如果插件目录存在且有效,插件的 Makefile 会被执行以完成插件的构建。在编译的过程中,可能会生成插件的二进制文件或其他形式的输出文件,以供 NHP 服务器使用。 **2.本地环境功能测试** @@ -260,13 +260,13 @@ NHP 服务器中的每个插件通常都结构化为一个单独的 Go 包。例 本地测试和优化完成后,插件即可进入实际应用场景的部署阶段。要部署您的插件,只需构建并运行主应用程序。您的插件将包含在构建中,并在服务器运行时可用。在部署插件时,通常需要根据应用场景的具体需求进行配置。具体步骤如下: -**部署环境准备**:确保生产环境的服务器配置与本地测试环境一致或接近,包括操作系统、网络配置、依赖库等。 +***部署环境准备***:确保生产环境的服务器配置与本地测试环境一致或接近,包括操作系统、网络配置、依赖库等。 -**插件安装与配置**:将经过测试的插件代码部署到生产服务器上,按照实际应用场景的要求进行相应的配置,包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。 +***插件安装与配置***:将经过测试的插件代码部署到生产服务器上,按照实际应用场景的要求进行相应的配置,包括配置插件路径、接口地址、门禁服务器地址、身份认证机制等。 -**日志与监控设置**:在部署完成后,完善日志等级配置,便于在实际应用中及时发现和解决问题。 +***日志与监控设置***:在部署完成后,完善日志等级配置,便于在实际应用中及时发现和解决问题。 -**启动NHP服务查看插件加载情况**:按照NHP服务启动流程启动NHP服务,根据log目录下的日志文件查看插件的加载情况,并且按照本地插件测试流程验证插件功能是否正常。 +***启动NHP服务查看插件加载情况***:按照NHP服务启动流程启动NHP服务,根据log目录下的日志文件查看插件的加载情况,并且按照本地插件测试流程验证插件功能是否正常。 **5. 生产环境验证与运维** From 43da33344e80a9a16898762f600f67b2017ece4b Mon Sep 17 00:00:00 2001 From: qq_51961435 <1548345616@qq.com> Date: Tue, 22 Oct 2024 16:49:45 +0800 Subject: [PATCH 4/8] modify server_plugin.md and server_plugin.zh-cn.md --- docs/images/plugin_image10.png | Bin 14097 -> 0 bytes docs/images/plugin_image5.png | Bin 141455 -> 0 bytes docs/images/plugin_image6.png | Bin 20412 -> 23632 bytes docs/images/plugin_image7.png | Bin 20855 -> 28389 bytes docs/images/plugin_image8.png | Bin 15670 -> 29351 bytes docs/images/plugin_image9.png | Bin 68389 -> 0 bytes docs/server_plugin.md | 28 +++++++++------------------- docs/zh-cn/server_plugin.zh-cn.md | 28 +++++++++------------------- 8 files changed, 18 insertions(+), 38 deletions(-) delete mode 100644 docs/images/plugin_image10.png delete mode 100644 docs/images/plugin_image5.png delete mode 100644 docs/images/plugin_image9.png diff --git a/docs/images/plugin_image10.png b/docs/images/plugin_image10.png deleted file mode 100644 index d09eb352524c4307f3f08a3291436a19ad1f0cc3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 14097 zcmY+r19V(Zz&E_{#%ydgX{^R}8ry8_#
6;pZEG9b=DYv*`ObOXZ_euM?!7ZR
zJ2UsEiBOc6L`J|z0002U(o$l|005LC_%$UE7W^0{wC)9df_IS8asmJlG5@ Qp)79oSfwH9tYfAqeL&LB>KH#Ns;FHn2n#eJ$
zn208YmyR=*&`jJ>o;24>1`73r9Erfhn|{xKa=dQ=U|sZ$p8Xb%@7~3IL(I`2j=(^=
z_`T$;z+Az-tI8@(s}YS0Q#|%vHItSOYQ~4TWQy%Nu(`AZJXU7sRl67uD#10$pSjsL
zo)7=Y0iY+>>vm&a`sOEklT)Aq?p$-+OD|PX#w@py7##P^^j0abFtSNkIzoEJ(ftSR
zhq;r`ml;#94;3RSiW!U{h~L3e=7Comu9*mq8r{1&Kvm37oeIro2{_;@aOrWs6^kDa
zM;W2tJ;Pe)L_e8Rd|@v{bQ>wzVbC?ie$FDgMdiZ0`iY2G4VIgQJLL4gm*NyoSi7f(
zlXCp(TXi|vD0lLrrK}Z?3CsMcCf?%ncb1FhK%i#&W;uU8;;)B2*=>kfKtp}{GvJ&s
znX|`8EL{BFDc5aE2tcw6f!SFI7H=l=-RZ#Fv$`T+xhBgUQZAs6A=WKNAq7(c9urKl
zt7l9;_RidXG5E8z3W#qw5(x`{aYWkbKUQIPZ3gm~v{#rvEiuXtmpXDF%2| G`8xs9Sj1y3ujNHq)8`j 0g$kojx;sb~lwGk@k9yeIq@@nzSo
zqeY$Z^zw2!7f0vR{bV(?#=@!6{LK9PNMNr>1|u#OO{4W{oG^4z3VylH{eqUd-SM2+0$J0aJF6`M93;`Lijn&5ntI@7M)@
zk9rFrjCOTCi|8EygiwOIT6i@ux{O?9z*hi6IKw{Hu`%Nr>$=@%T&&`4R^EdMPQjvv
zF+6Fg8w?XA9et!4y99^3yCPpN9p9msVK1FVdIT|yU=$x*aCIKioMfq^{}ve_0W(F*
zhVEe!WP)wCx)Ht(UphHwD{#Hg)FCa;_ZW|YyP1D{*OdV2VrA%S=dkF9L
aA{z_AM%QAfn_pqTrI0
z&W@Q+3JS1jHX-8x{Ak+0nKV!c*_QeTwC7-|nD}eRhKEex`OMw6n2(qa*In~t^)_{|
zrlQ3Rh`hZAm@#_F?$kqZD~Q|3(fj&Hf~704NANpPFTDfd2Tv}#}4
ziwtW`o{U5pM{}{81IUh3D;(HVwV4hr`t?WO3H;SzH45ErTw8&-4-VtYk2~ci>TbdY
zv{&53Ql}~UDrut5gy(@++S7kPh)Neo;spDoAVxc|V!TH0mmYq$QIP`Q(*EBu>36!^
zWu&H1F=E$sTbtNTlx*~6o<#lu6A&o)q`FALW9+FsRK<94I_IkVN&)P>!$nCK#v$wg
z1#vKB)qsrqAqDYumea6RAQe-u%Ea^7YB(~gdoz*)j)%_9oSHSZ3<4`<$iODr{?)h6
zrzh0VeIRl|b)P5ca3i>fDMdX^VpW*>$+pOL@yo&nc8gihYb>0Ywxg89r0juo=V@d#
z$Yqg@lOpn2^H297Y;XJ@k4UXFcMx>K<8d8v4$h1s6p$NH(W
zXrW^O=!7QHIfU(=*#*^d`QP#7HPQ2rur60&p^63W6d`inzT&6k`?(HNC=ps@PzJo`
zy<`BE?zp?zi|zNfqHbOPcyj!wEy~+Um3B+CKH^B6gaAy3eXOg?N&bC@#R+&9V!$pa
z$6SO5?@=gB2?1gdp7M0e3dE=YGyxP2%k@R0g)1C73uAy59xFrgfJ>32j0*J2dKQs^
z-w$9COg=#$7(Cl{i21lI*Lgp9rloa|*Ho3LfBFJAy7IMg<%jAJHLd)p!t0px`gAQs
zXS*A`Eak9367jT@qQ_J!s=@&j^!(w002dUeko~J&GjEN_a1=E^5hJgWl7D07%p1|;
zE;qd0-mRk9(--%1MHv;Ta
Ir?{en
z=%|N{jA}MUzHMv_cPz_4^5LBv7Rg}gmd%^{Cnm&_p77#td
z@y{2H;!c2x0RHku0BGL#32bF3zoJJJVf~PiGf+=@pdhqKG8D3xrwyL*Kf|go#%AvR
zn=v*tWJf2