服务注册与分布式协调 / 系统课时
按环境与租户隔离目录
按环境与租户隔离目录
同名 MCP Server 同时存在于开发、测试、生产或多个租户时,不能只靠服务名区分。最稳妥的做法是先用 Nacos Namespace 划出资源边界,再让 MCP Server、Router 与 Agent 使用同一命名空间和受限凭据。
学习目标
- 设计同时包含环境与租户维度的 Namespace 划分方式。
- 验证两个命名空间可以保存同名 MCP 服务且互不覆盖。
- 把 Router 与 Agent 的运行时访问范围固定到目标命名空间。
先确定隔离边界
Namespace 是 Nacos 资源隔离的第一层边界。环境和租户都需要硬隔离时,可以直接组合成命名空间,例如 dev-tenant-a、test-tenant-a、prod-tenant-a。这样同一个 catalog-mcp 可以在不同空间拥有不同版本、端点和工具配置。
不要把 public 当作生产环境的默认落点,也不要仅用命名约定代替访问控制。Namespace 决定“资源放在哪里”,认证、RBAC 与可见性策略决定“谁能读写或看到这些资源”,两者要一起配置。

创建两个空间并验证同名目录项
下面的实验针对 Nacos 3.x Admin API。它会登录获取 accessToken,创建两个 Namespace,并在每个空间创建同名 catalog-mcp 目录项;如果资源已经存在则直接复用。实验使用管理员账号只为了搭建测试数据,生产运行时不要把管理员凭据交给 Agent。
export NACOS_URL="http://127.0.0.1:8848"
export NACOS_PASSWORD="<PASSWORD>"
python - <<'PY'
import json
import os
import urllib.parse
import urllib.request
base = os.environ["NACOS_URL"].rstrip("/")
password = os.environ["NACOS_PASSWORD"]
service = "catalog-mcp"
namespaces = ("dev-tenant-a", "prod-tenant-a")
# 统一封装表单式 Admin API,并在需要时携带 accessToken。
def request(path, method="GET", data=None, token=None):
body = urllib.parse.urlencode(data).encode() if data else None
req = urllib.request.Request(base + path, data=body, method=method)
if token:
req.add_header("accessToken", token)
if body is not None:
req.add_header("Content-Type", "application/x-www-form-urlencoded")
with urllib.request.urlopen(req) as resp:
return json.load(resp)
# 管理员只用于创建实验资源,运行时 Agent 不应使用该身份。
login = request(
"/nacos/v3/auth/user/login",
"POST",
{"username": "nacos", "password": password},
)
token = login["accessToken"]
ids = []
for ns in namespaces:
# 先检查 Namespace,保证脚本可以重复执行。
query = urllib.parse.urlencode({"namespaceId": ns})
exists = request(
"/nacos/v3/admin/core/namespace/check?" + query,
token=token,
)["data"]
if not exists:
request(
"/nacos/v3/admin/core/namespace",
"POST",
{
"namespaceId": ns,
"namespaceName": ns,
"namespaceDesc": "MCP isolated namespace",
},
token,
)
list_query = urllib.parse.urlencode(
{
"pageNo": 1,
"pageSize": 20,
"namespaceId": ns,
"mcpName": service,
"search": "accurate",
}
)
result = request("/nacos/v3/admin/ai/mcp/list?" + list_query, token=token)
if result["data"]["totalCount"] == 0:
# 只创建最小目录项,用于证明同名资源在两个空间中互不覆盖。
spec = {
"protocol": "stdio",
"frontProtocol": "stdio",
"name": service,
"description": "namespace isolation demo",
"versionDetail": {"version": "1.0.0"},
"enabled": True,
"localServerConfig": {service: {}},
}
request(
"/nacos/v3/admin/ai/mcp",
"POST",
{
"namespaceId": ns,
"mcpName": service,
"serverSpecification": json.dumps(spec, separators=(",", ":")),
},
token,
)
result = request("/nacos/v3/admin/ai/mcp/list?" + list_query, token=token)
item = result["data"]["pageItems"][0]
ids.append(item["id"])
print(f"{ns}: id={item['id']} name={item['name']}")
assert ids[0] != ids[1], "同名目录项不应共享同一个 MCP ID"
PY预期输出
dev-tenant-a: id=<ID_DEV> name=catalog-mcp
prod-tenant-a: id=<ID_PROD> name=catalog-mcp<ID_DEV> 和 <ID_PROD> 是 Nacos 生成的动态 ID,实际值不同。这里创建的是用于验证目录隔离的最小目录项;真正提供工具时,应让各环境的 MCP Server 在自己的 Namespace 中完成正常注册,并提供有效的启动或远程端点信息。
让 MCP Server 注册到正确空间
使用 Spring AI Alibaba 自动注册时,可以把 Namespace 做成环境变量,而 MCP 服务名保持一致。下面是配置文件片段,开发和生产只需要注入不同的 NACOS_NAMESPACE 与 SERVER_PORT。
spring:
ai:
mcp:
server:
name: catalog-mcp
version: 1.0.0
alibaba:
mcp:
nacos:
server-addr: ${NACOS_ADDR:127.0.0.1:8848}
namespace: ${NACOS_NAMESPACE}
username: ${NACOS_USERNAME:nacos}
password: ${NACOS_PASSWORD}
register:
enabled: true
server:
port: ${SERVER_PORT}这段配置的生效结果是:NACOS_NAMESPACE=dev-tenant-a 的实例只向开发空间注册,NACOS_NAMESPACE=prod-tenant-a 的实例只向生产空间注册。验证时再次按 Namespace 查询 catalog-mcp,应分别看到各自的 MCP ID、版本和端点,不应发生覆盖。
把 Router 与 Agent 锁在目标空间
Router 自身也必须绑定 Namespace,否则 MCP Server 已经隔离,运行时却仍可能从错误空间发现资源。下面是生产 Agent 的 MCP 客户端配置片段,核心字段是 NACOS_NAMESPACE。
{
"mcpServers": {
"nacos-mcp-router": {
"command": "uvx",
"args": [
"nacos-mcp-router@latest"
],
"env": {
"NACOS_ADDR": "127.0.0.1:8848",
"NACOS_USERNAME": "prod-agent",
"NACOS_PASSWORD": "<PASSWORD>",
"NACOS_NAMESPACE": "prod-tenant-a"
}
}
}
}生产上不要使用管理员账号替代 prod-agent。应给运行时身份只授予 prod-tenant-a 所需的读取权限,并配合 AI Registry 的可见性策略,使“配置指向错误空间”和“凭据越权访问其他空间”都不能悄悄成功。
验收时用开发 Agent 与生产 Agent 分别搜索同名 catalog-mcp:两边都可以看到自己的服务,但查询到的 MCP ID、端点和版本应属于各自 Namespace。只要任一 Agent 能读取另一个租户或环境的目录,就说明隔离还没有真正闭环。