服务注册与分布式协调 / 系统课时
开启 AI Registry 协议适配
开启 AI Registry 协议适配
本节把 Nacos 的 AI Registry 从“控制台能管理”推进到“外部 MCP Registry 客户端也能访问”的可用状态:开启 AI 模块与 MCP Registry 协议适配,明确独立端口和控制台入口,并完成端口与协议级验证。
学习目标
- 区分 AI 模块开关、MCP Registry 协议开关和独立协议端口的职责。
- 配置当前 3.x 使用的协议端口,并识别旧端口参数的兼容边界。
- 分别验证协议端口与控制台入口,快速定位“菜单存在但协议不可用”等问题。
先分清模块、协议和端口
nacos.extension.ai.enabled 控制 AI 模块是否加载。它关闭后,AI 管理相关控制台入口和 API 都不会加载;AI 模块还依赖 Nacos 的配置与服务发现能力。nacos.ai.mcp.registry.enabled 只控制官方 MCP Registry 协议适配器,默认不会因为 AI 模块可用就自动开启。
协议适配器使用独立端口。当前 3.x 配置应使用 nacos.ai.registry.port,默认值为 9080;历史参数 nacos.ai.mcp.registry.port 已进入废弃兼容阶段,不应继续作为新部署的主配置。控制台 HTTP 入口与这个协议端口是两条不同链路,因此“控制台能打开”不能证明 9080 已经监听。

开启协议适配
在 Nacos Server 的 conf/application.properties 中保留 AI 模块,并显式开启 MCP Registry 协议适配。下面是最小配置片段:
# AI Registry 总开关
nacos.extension.ai.enabled=true
# 官方 MCP Registry 协议适配器
nacos.ai.mcp.registry.enabled=true
# 当前 3.x 统一使用的 AI Registry 协议端口
nacos.ai.registry.port=9080修改这类启动参数后重启 Nacos Server,再做验证。若正在从旧版本升级,先把 nacos.ai.mcp.registry.port 迁移为 nacos.ai.registry.port,避免新旧键长期并存,让后续排障无法确认实际生效来源。
验证协议端口
先从 Nacos Server 所在主机访问标准 MCP Registry 列表入口,排除负载均衡、防火墙和外部网关的干扰。以下命令假设本机监听默认协议端口,且该入口未额外要求认证:
REGISTRY_HOST=127.0.0.1
REGISTRY_PORT=9080
curl -sS -o /dev/null -w 'registry_http=%{http_code}\n' "http://${REGISTRY_HOST}:${REGISTRY_PORT}/v0/servers"预期输出:
registry_http=200实际部署若启用了额外认证,可能返回 401 或 403。这两种状态至少说明 HTTP 服务已经响应,应继续检查认证配置;连接拒绝、超时或无法建立 TCP 连接,才优先检查适配开关、端口占用、监听地址和网络策略。
确认控制台入口
协议端口正常后,再打开实际部署的 Nacos Console。AI 模块加载且当前启动模式允许时,控制台应出现 AI 管理中心,其中包含 MCP 管理入口。进入后应能切换命名空间并查看 MCP Server 资源;这里验证的是管理面,不是 9080 协议端口本身。

按现象定位失败点
如果 AI 管理入口完全不出现,优先检查 nacos.extension.ai.enabled、Config/Naming 模块是否可用,以及是否使用了不会加载 AI 模块的功能模式。如果控制台正常而 9080 不监听,重点检查 nacos.ai.mcp.registry.enabled、端口冲突和启动日志。
如果 9080 已响应但 Registry API 返回认证或权限错误,说明协议适配器本身已经启动,应转向鉴权与访问策略排查。把“模块加载、协议监听、控制台展示”拆成三个独立检查点,可以避免只凭一个页面或一个端口就误判整个 AI Registry 状态。