后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载导读本文聚焦 nginx-ui 内置的MCPModel Context Protocol配置管理模块系统讲解其提供的 9 个配置文件管理工具读取、创建、修改、重命名、启用、历史回溯等。读者将掌握每个工具的调用参数与返回结构、路径解析与安全性约束、写入-校验-重载的原子化流程以及如何通过 MCP 服务令牌和读写权限分类让 AI Agent 与自动化工具在完全受控的前提下操作 Nginx 配置。文中所涉实现细节均有仓库源码佐证可直接对照 mcp/config 目录下的真实代码深入研读。一、模块概览AI Agent 操作 Nginx 配置的统一入口MCPModel Context Protocol是一套让 AI 模型与外部工具交互的标准协议。nginx-ui 将管理 Nginx 配置文件这一高频操作抽象为一组 MCP 工具供 AI 助手、自动化脚本和第三方工具通过标准化的 JSON 请求调用而无需关心底层文件系统、Nginx 语法校验与重载等细节。从源码结构看该模块位于 mcp/config 目录共 9 个工具全部通过 mcp/config/register.go 中的Init()函数注册到 MCP 服务器工具名类型功能nginx_config_base_pathtool获取 Nginx 配置根目录路径nginx_config_listtool列出配置目录下的文件nginx_config_gettool读取指定配置文件的完整内容nginx_config_addtool新建配置文件nginx_config_modifytool修改已有配置文件nginx_config_renametool重命名文件或目录nginx_config_mkdirtool创建配置目录nginx_config_historytool查看配置文件变更历史nginx_config_enabletool启用配置文件在 sites-enabled 中创建软链接这些工具从读写维度分为两类见 mcp/router.go 中的writeMCPTools与readOnlyMCPTools两个集合只读工具nginx_config_base_path、nginx_config_get、nginx_config_history、nginx_config_list写工具nginx_config_add、nginx_config_enable、nginx_config_mkdir、nginx_config_modify、nginx_config_rename此外还有reload_nginx、restart_nginx。读写分类直接决定了调用所需的授权级别详见第六节这是理解整个模块安全模型的关键。二、路径体系所有操作均以 Nginx 配置根目录为锚点2.1 获取基础路径nginx_config_base_path该工具无需任何参数返回 Nginx 配置目录的绝对路径。其实现mcp/config/config_base_path.go直接调用nginx.GetConfPath()该值由 nginx-ui 的 Nginx 配置解析逻辑internal/nginx计算得出通常为/etc/nginx一类目录。调用示例{ tool: nginx_config_base_path, parameters: {} }响应示例{ base_path: /etc/nginx }2.2 路径安全约定模块遵循两条重要规则所有路径操作都相对 Nginx 配置根目录nginx_config_list、nginx_config_get使用relative_path参数nginx_config_add等使用base_dirname组合写入前会做路径包含性校验如nginx_config_enable在创建软链接前会调用helper.IsUnderDirectory(dstPath, sitesEnabledDir)检查目标是否位于sites-enabled目录内防止链接逃逸mcp/config/config_enable.go。config.ResolveConfPath、config.ResolveAbsoluteOrRelativeConfPath等函数internal/config/path.go负责把相对路径安全地解析为绝对路径目录穿越类攻击会在该层被拦截。实战提示在开始批量操作前先调用nginx_config_base_path确认根路径所有后续调用均以此为锚点组织relative_path或base_dir避免硬编码绝对路径带来的跨环境兼容问题。三、读取与检索列出、查看与回溯3.1 列出配置文件nginx_config_list参数参数类型说明relative_pathstring相对 Nginx 配置根目录的路径用于限定要列出的目录filter_by_namestring按文件名关键字过滤可选实现mcp/config/config_list.go将参数透传给config.GetConfigList过滤逻辑为strings.Contains(file.Name(), filterByName)即子串匹配。调用示例{ tool: nginx_config_list, parameters: { relative_path: 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 } ] }每个条目包含name、is_dir是否为目录、path绝对路径三个字段便于后续用nginx_config_get精确读取。3.2 读取配置内容nginx_config_get参数参数类型说明relative_pathstring配置文件的相对路径必填调用示例{ tool: nginx_config_get, parameters: { relative_path: conf.d/default.conf } }该工具的实现mcp/config/config_get.go返回的信息比文档示例更丰富实际包含name文件名content文件完整内容file_path解析后的绝对路径modified_at文件修改时间dir文件所在相对目录sync_node_ids、sync_overwrite该文件在集群环境下的同步配置来自数据库configs表的记录见 model/config.go。这意味着 AI Agent 在一次调用中即可同时拿到文件内容与集群同步元数据为读取后决策、决策后修改的完整工作流打下基础。3.3 查看变更历史nginx_config_history参数参数类型说明filepathstring配置文件的完整路径必填用于精确匹配历史记录实现mcp/config/config_history.go查询config_backups表gorm gen 生成的query.ConfigBackup按file_path过滤并按 ID 倒序返回即最新的历史记录排在最前。自动备份机制正如文档 Important Notes 所述每次配置修改都会自动生成备份记录之后可通过历史工具查询到每次变更的版本配合 nginx-ui 的恢复能力见 api/config/history.go 与 internal/config/history.go实现一键回滚。这条修改即备份、历史可恢复的链路是 MCP 写操作能够安全放手的前提。四、写入操作创建、修改与原子化安全落地4.1 新建配置文件nginx_config_add参数参数类型说明namestring要创建的文件名必填contentstring文件内容必填base_dirstring存放目录可选相对 Nginx 配置根目录overwriteboolean是否覆盖已存在的文件可选默认 falsesync_node_idsarray需要同步配置的节点 ID 列表可选集群场景以文档示例为基础、补充完整字段的调用{ tool: nginx_config_add, parameters: { name: example.com.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}, base_dir: sites-available, overwrite: false } }底层安全流程见 mcp/config/config_add.go参数校验name与content缺一不可缺失即报错语法校验调用config.ValidateConfigFile(path, content)做 Nginx 语法与安全指令校验防覆盖overwritefalse时若文件已存在返回ErrFileAlreadyExists目录自动创建目标目录不存在时以0755权限递归创建加锁 事务写入获取config.LockApply()写锁通过config.FileTransaction以0644权限落盘测试并重载调用tx.TestAndReload()执行nginx -t测试通过后触发重载任一环节失败立即回滚保证Nginx 拒绝的配置不会残留在磁盘上也不会破坏正在运行的内存配置写入数据库并同步在configs表创建记录若指定sync_node_ids则通过config.SyncToRemoteServer同步到集群节点。4.2 修改已有配置nginx_config_modify参数参数类型说明relative_pathstring配置文件的相对路径必填contentstring新的完整文件内容必填sync_overwriteboolean同步时是否覆盖远端已有文件可选sync_node_idsarray需要同步的节点 ID 列表可选调用示例{ tool: nginx_config_modify, parameters: { relative_path: 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} } }实现要点mcp/config/config_modify.go目标文件不存在时返回ErrFileNotFound修改前同样执行config.ValidateConfigFile语法与安全校验若数据库尚无该文件记录则FirstOrCreate自动创建随后更新sync_node_ids、sync_overwrite字段最终调用config.Save(absPath, content, cfg, )完成保存。该函数内部同样走写文件 → 语法测试 → 重载 → 写历史备份的完整链路见 internal/config/save.go自动备份由此产生。注意content必须为文件的完整新内容而非增量补丁。AI Agent 应先用nginx_config_get获取现状再基于现状生成完整内容提交修改。4.3 创建配置目录nginx_config_mkdir参数参数类型说明base_pathstring目标目录所在的基路径可选folder_namestring要创建的目录名必填调用示例{ tool: nginx_config_mkdir, parameters: { base_path: conf.d, folder_name: includes } }实现mcp/config/config_mkdir.go将两个参数解析合并后以0755权限调用os.Mkdir创建单级目录注意与nginx_config_add的自动递归创建不同这里不会递归创建多级目录。成功时返回message与完整path。4.4 重命名文件或目录nginx_config_rename参数参数类型说明base_pathstring文件/目录所在的基路径orig_namestring原名称必填new_namestring新名称必填sync_node_idsarray需要同步重命名操作的节点 ID可选调用示例{ tool: nginx_config_rename, parameters: { base_path: sites-available, orig_name: old-name.conf, new_name: new-name.conf } }实现细节mcp/config/config_rename.go名称相同则直接返回无需变更目标已存在返回ErrFileAlreadyExists文件系统层面执行os.Rename元数据联动更新同步更新configs表记录filepath、name迁移config_backups历史记录的 filepath并联动更新 LLM 会话记录query.LLMSession——文件重命名后AI 会话中记录的旧路径引用会被自动改写目录重命名时则用Like前缀匹配 Replace批量更新其下所有记录若配置了sync_node_ids通过config.SyncRenameOnRemoteServer把重命名操作同步到集群节点。五、启用配置nginx_config_enable与 sites-enabled 软链接这是模块中最能体现安全自动化设计的一个工具。参数参数类型说明namestring要启用的配置文件名必填base_dirstring源目录默认sites-availableoverwriteboolean目标已存在时是否覆盖可选默认 false调用示例{ 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 }完整执行链路mcp/config/config_enable.go默认源目录为sites-available解析出源文件绝对路径确认其存在目标为sites-enabled/name校验目标路径必须位于sites-enabled目录内防路径逃逸sites-enabled不存在时自动创建0755目标已存在且overwritefalse时报错overwritetrue时先移除旧链接通过os.Symlink创建sites-available→sites-enabled的软链接而非复制文件保证两处内容始终一致先测试后重载执行nginx.Control(nginx.TestConfig)即nginx -t失败则删除刚创建的链接并回滚测试通过后再nginx.Control(nginx.Reload)重载重载失败同样回滚并恢复 Nginx 状态。这套失败即回滚的设计保证了启用失败的配置绝不会让 Nginx 处于带病运行或下次启动即挂的状态。六、权限与安全模型读写分级 服务令牌MCP 配置管理工具并非裸奔的 API。从 mcp/router.go 可以看到完整的四层防护6.1 路由与认证MCP 端点注册在/mcp与/mcp_message统一经过IPWhiteList()IP 白名单、mcpAuthRequired()认证、authorizeMCPToolRequest()工具级授权三个中间件认证支持三种凭证mcpAuthRequiredMCP 服务令牌以nui_pat_开头的令牌经internalmcp.VerifyServiceToken验证用于 Agent/自动化程序用户会话令牌普通用户 token≤16 字符用 short token 查询否则用完整 token 查询遗留节点密钥X-Node-Secret请求头需与NodeSettings.Secret常量时间比较subtle.ConstantTimeCompare匹配对应旧的节点认证方式。6.2 读写作用域分级authorizeMCPToolRequest中间件会解析请求体仅对tools/call方法分类依据readOnlyMCPTools/writeMCPTools判定所需作用域只读工具需要MCPTokenScopeRead写工具需要MCPTokenScopeWrite此时还会叠加RequireSecureSession()安全会话校验未知工具默认按写权限处理fail closed保证未来新增的可变工具在显式归类前不会绕过写权限保护。这意味着即使服务令牌泄露只读令牌也无法执行nginx_config_add等破坏性操作——权限模型遵循最小化原则。6.3 内容安全受限指令校验写入前执行的config.ValidateConfigFile不止做语法检查还会拦截危险指令。测试用例 mcp/config/config_validation_test.go 验证了两类场景nginx_config_add拒绝包含lua_package_path的配置TestNginxConfigAddRejectsRestrictedDirectiveContentnginx_config_modify拒绝包含js_import的配置TestNginxConfigModifyRejectsStatementSeparatedRestrictedDirectiveContent且被拒后磁盘上的原文件内容保持不变。被拦截时返回ErrConfigDirectiveNotAllowedcosy 错误错误参数中携带具体的受限指令名方便 Agent 定位问题。这条防线从根源上阻止 AI 生成的配置夹带可执行代码如 Lua/JS 扩展属于指令级的纵深防御。七、实践组合工具构建完整的 Agent 工作流将上述工具串联起来即可形成一条安全、可审计的配置管理流水线探查nginx_config_base_path确认根路径 →nginx_config_list定位目标目录读取nginx_config_get获取现有内容与同步元数据修改nginx_config_modify提交完整新内容或nginx_config_add新建nginx_config_mkdir建目录nginx_config_rename改名启用对位于sites-available的新站点调用nginx_config_enable创建软链接并触发重载审计nginx_config_history随时回溯每次修改的版本配合 nginx-ui 的恢复功能回滚异常变更。每步写入都伴随语法校验、自动备份、失败回滚与集群同步可选因此即使 Agent 生成的配置存在缺陷也不会污染磁盘或中断线上服务。结语nginx-ui 的 MCP 配置管理模块mcp/config把读写 Nginx 配置文件这一危险操作封装成了 9 个参数明确、行为可预期、失败可回滚的标准工具。其核心价值在于AI Agent 只需关心配置长什么样而把路径安全、语法校验、受限指令拦截、自动备份、test-and-reload 原子操作、集群同步等工程细节全部交由 nginx-ui 兜底。结合 mcp/router.go 的读写分级授权与 mcp/config/config_validation_test.go 的安全测试可以确认这是一套面向自动化场景、具备生产级安全考量的配置管理能力。希望本文能帮助你在此基础上安全地把 Nginx 配置管理接入自己的 AI 工具链。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Nginx-UI MCP 配置文件管理用 AI 代理安全操作 Nginx 配置的 9 个工具Nginx UI MCP 配置文件管理用 AI 代理安全操作 Nginx 配置的 9 个工具 Nginx UI 通过 MCPModel Context Pr后端前端运维MCP 服务Nginx UI 的 MCP 模块为 AI Agent 提供 Nginx 配置管理与服务控制接口Nginx UI 的 MCP 模块为 AI Agent 提供 Nginx 配置管理与服务控制接口 MCPModel Context Protocol模型上后端前端运维MCP 服务Nginx GUI 管理工具简化Nginx配置Nginx GUI 管理工具简化Nginx配置 Nginx GUI 是一个开源项目旨在提供一个图形用户界面来管理和配置 Nginx 服务器。该项目主要使用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考