Nginx UI 的 MCP 模块为 AI Agent 提供 Nginx 配置管理与服务控制接口【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-uiMCPModel Context Protocol模型上下文协议是 Nginx UI 提供的一组特殊接口让 AI Agent、LLM 与自动化脚本能够直接读写 Nginx 配置文件、执行 reload/restart 等运维操作并获取服务运行状态。本文以 docs/guide/mcp.md 为主体结合 mcp/ 目录下的 Go 实现完整讲解 MCP 模块的接口、认证、工具清单与调用方式帮助读者掌握如何让 AI 安全地管理 Nginx。MCP 模块整体概览从官方文档与源码结构来看Nginx UI 的 MCP 模块分为两大功能域配置文件管理围绕 Nginx 配置文件的读取、创建、修改、重命名、目录创建、历史记录与启用等操作详见 docs/guide/mcp-config.mdNginx 服务管理查询 Nginx 状态、平滑重载配置、重启服务详见 docs/guide/mcp-nginx.md。模块由mcp目录组织入口 mcp/register.go 在初始化时依次调用config.Init()与nginx.Init()完成工具注册两个子目录分别对应上述两大功能域。MCP 服务端本体位于 internal/mcp/server.go它基于mark3labs/mcp-go构建了一个名为Nginx、版本1.0.0的 MCP Server并启用了资源能力Resource Capabilities与日志、恢复等特性。接口与传输方式MCP 接口挂载在/mcp路径并通过SSEServer-Sent Events提供流式传输。路由注册见 mcp/router.go/mcp—— SSE 主端点/mcp_message—— 客户端向服务器发送消息的端点。两个端点都依次经过IPWhiteListIP 白名单、mcpAuthRequired认证与authorizeMCPToolRequest工具级权限分类三道中间件最终交由internalmcp.ServeHTTP处理。SSE 端点与消息端点的具体配置定义在 internal/mcp/server.go 中。认证与访问令牌MCP 接口不对外开放调用方必须先持有有效凭据。官方文档要求在Preferences Access Tokens偏好设置 访问令牌中创建服务令牌Service Token并授予客户端所需的最小 MCP 作用域mcp:read允许访问 Resources 与只读工具mcp:write允许调用变更类mutating工具且包含mcp:read的全部权限。作用域常量定义在 model/mcp_service_token.go前端创建入口为 app/src/views/preference/tabs/AccessTokens.vue对应的 API 封装在 app/src/api/service_token.ts 中支持创建、列出、轮换与撤销令牌名称最长 64 字符。令牌格式与传递方式服务令牌以nui_pat_前缀开头格式为nui_pat_publicID_secret通过Authorization请求头发送Authorization: Bearer nui_pat_...从 internal/mcp/service_token.go 的实现可以确认publicID 为 12 字节随机数经 base64url 编码16 个字符secret 为 32 字节随机数编码43 个字符由 HMAC-SHA256 派生验证器verifier校验验证密钥通过 HKDF 从CryptoSettings.Secret与NodeSettings.InstanceID派生。令牌验证时还会检查revoked_at撤销标记与expires_at过期时间并更新last_used_atservice_token.go。安全要点来自文档与实现令牌只显示一次创建后立即保存到密码管理器并尽可能设置过期时间拒绝 URL 查询参数传凭据避免令牌通过日志与浏览器历史泄露认证中间件会直接拒绝携带node_secret查询参数的请求mcp/router.go除服务令牌外mcpAuthRequired还兼容普通用户令牌短令牌/长令牌以及旧式X-Node-Secret头认证详见 mcp/router.go。工具级作用域控制authorizeMCPToolRequest中间件会根据请求体中的工具名动态判定所需作用域mcp/router.go只读工具集readOnlyMCPToolsnginx_config_base_path、nginx_config_get、nginx_config_history、nginx_config_list、nginx_status写工具集writeMCPToolsnginx_config_add、nginx_config_enable、nginx_config_mkdir、nginx_config_modify、nginx_config_rename、reload_nginx、restart_nginx。classifyMCPRequest的默认策略是fail-closed失败即关闭无法识别的新增工具一律按写作用域处理mcp/router.go确保新加入的变更类工具在明确归类前始终处于写权限与安全会话检查的保护之下。当使用写工具且请求由服务令牌认证时还会额外校验令牌是否具备mcp:write作用域。Resources 与 Tools 两种能力按文档定义MCP 向 AI 客户端暴露两类能力Resources资源只读信息例如 Nginx 的运行状态。服务端在创建时启用了资源能力internal/mcp/server.go并且实现中预留了Resource注册结构server.goTools工具可执行操作例如重启 Nginx、修改配置文件。值得一提的实现细节是 internal/mcp/context.goIsServiceTokenRequest用于识别当前请求是否由服务令牌认证处理器可据此在返回资源时剔除凭据类敏感字段而交互式管理员仍能看到完整响应。配置文件管理工具9 个配置文件管理子模块注册了 9 个工具mcp/config/register.go全部以nginx_config_为前缀。重要约定所有路径操作都相对于 Nginx 配置根路径base path工具内部通过config.ResolveConfPath/config.ResolveAbsoluteOrRelativeConfPath解析并做路径包含校验防止越出配置目录如config_enable.go中的IsUnderDirectory检查。nginx_config_base_path —— 获取配置根路径无参数返回 Nginx 配置根目录mcp/config/config_base_path.go{ tool: nginx_config_base_path, parameters: {} }示例响应{ base_path: /etc/nginx }nginx_config_list —— 列出配置文件参数relative_path相对路径、filter_by_name按名称过滤可选。实现调用config.GetConfigList并对文件名做子串匹配过滤mcp/config/config_list.go{ tool: nginx_config_list, parameters: { relative_path: /etc/nginx/conf.d } }示例响应{ files: [ { name: default.conf, is_dir: false, path: /etc/nginx/conf.d/default.conf }, { name: example.conf, is_dir: false, path: /etc/nginx/conf.d/example.conf } ] }nginx_config_get —— 读取配置文件内容参数relative_path必填。返回内容的同时附带文件元数据与集群同步设置mcp/config/config_get.go{ tool: nginx_config_get, parameters: { path: /etc/nginx/conf.d/default.conf } }nginx_config_add —— 新增配置文件参数name必填、content必填、base_dir基础目录、overwrite是否覆盖已存在文件、sync_node_ids同步到的节点 ID 数组。实现流程值得注意mcp/config/config_add.go对目标路径与内容执行语法校验ValidateConfigFile若文件已存在且overwritefalse返回ErrFileAlreadyExists持有 apply 锁通过config.FileTransaction写入文件随后执行写入 → 配置测试nginx -t→ reload的完整链路测试或重载失败会触发回滚RollbackErrortx.Rollback被 Nginx 拒绝的文件绝不会残留在磁盘上成功后写数据库并调用config.SyncToRemoteServer向集群节点同步。nginx_config_modify —— 修改已有配置文件参数relative_path必填、content必填、sync_overwrite同步时是否覆盖、sync_node_ids。修改前同样执行语法校验并通过config.Save落盘、自动生成历史备份mcp/config/config_modify.go{ tool: nginx_config_modify, parameters: { path: /etc/nginx/conf.d/default.conf, content: server {\n listen 80;\n server_name example.com;\n location / {\n root /usr/share/nginx/html;\n index index.html;\n }\n} } }nginx_config_rename —— 重命名文件或目录参数base_path、orig_name必填、new_name必填、sync_node_ids。重命名会同步更新配置表configs、备份表config_backups以及 LLM 会话表llm_sessions中的记录若重命名的是目录则批量更新该目录下所有记录mcp/config/config_rename.go。新旧名称相同时直接返回无需变更。nginx_config_mkdir —— 创建配置目录参数base_path、folder_name必填以 0755 权限创建目录mcp/config/config_mkdir.go。nginx_config_history —— 查询配置变更历史参数filepath必填。从config_backups表按文件路径查询按 ID 倒序返回mcp/config/config_history.go。配置文件的每次修改都会自动备份可借此回滚——对应文档配置修改自动备份可通过历史功能恢复的说明。nginx_config_enable —— 启用配置创建软链接参数name必填、base_dir源目录默认sites-available、overwrite是否覆盖已存在的启用配置。实现mcp/config/config_enable.go在sites-enabled下为sites-available中的文件创建符号链接随后执行nginx -t配置测试与 reload任何一步失败都会回滚删除刚创建的软链接避免无效配置在下次启动时破坏 Nginx{ tool: nginx_config_enable, parameters: { name: my-site.conf, base_dir: sites-available, overwrite: false } }示例响应{ status: success, message: Site enabled and Nginx reloaded successfully, source: /etc/nginx/sites-available/my-site.conf, destination: /etc/nginx/sites-enabled/my-site.conf }Nginx 服务管理工具3 个服务管理子模块注册了 3 个工具mcp/nginx/register.go让 AI 无需命令行即可完成服务级操作。nginx_status —— 查询运行状态无参数返回running是否运行、message最近一次控制命令输出、level日志级别三个字段mcp/nginx/status.go。当上次执行结果出错时直接返回错误结果。reload_nginx —— 平滑重载配置执行 Nginx 平滑重载graceful reload返回命令输出mcp/nginx/reload.go。restart_nginx —— 重启 Nginx 服务执行优雅重启graceful restart同样返回命令输出出错时返回ToolResultErrormcp/nginx/restart.go。典型使用场景按官方文档MCP 模块主要服务于以下四类场景AI 驱动的 Nginx 配置管理让 LLM 直接读取、校验、修改站点配置再通过 reload 生效与自动化运维工具集成把 Nginx 的配置与状态管理能力暴露给 Ansible 等自动化链路第三方系统对接 Nginx UI外部系统通过标准 MCP 协议获得统一的配置与服务控制入口为自动化脚本提供机器可读 API以 JSON 请求/响应替代脆弱的命令行解析。安全与可靠性设计小结结合文档与源码MCP 模块在安全与可靠性上有几个值得关注的设计最小权限令牌作用域区分mcp:read/mcp:write写工具默认需要写作用域与安全会话检查fail-closed 分类未识别的工具名默认按写作用域处理防止新工具绕过权限mcp/router.go写后验证与回滚新增、启用配置都遵循写入 → nginx -t → reload → 失败回滚的事务式流程杜绝坏配置存活凭据保护令牌仅通过Authorization头传递拒绝 URL 参数携带凭据服务令牌实现采用 HMAC 验证器并支持轮换、撤销与过期测试保障路由层测试验证了/mcp与/mcp_message在无认证时返回 403mcp/router_test.gointernal/mcp/service_token_test.go与 mcp/config/config_validation_test.go 分别覆盖令牌与配置校验逻辑。对开发者而言接入 Nginx UI 的 MCP 只需三步在Preferences Access Tokens创建带最小作用域的nui_pat_令牌 → 在 MCP 客户端中把 Server 地址配置为http(s)://host/mcp并设置Authorization: Bearer nui_pat_...→ 即可通过 SSE 会话调用上述 12 个工具完成 Nginx 的配置管理与服务控制。【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
