Nacos 从入门到实战：Python 开发者完全指南

我们被要求由浅入深讲解 Nacos，并面向 Python 开发者如何使用。需要提供详细的解释和示例。用户说”我是一个小白”，所以需要从基础概念讲起。最终回答应包含 Nacos 的简介、安装、Python 客户端的安装使用（如 nacos-sdk-python），服务注册与发现，配置管理，以及可能的高级用法。也要提到 Nacos 的部署（可以用 Docker 快速启动）。用中文回答。要求结构化，由浅入深，先理论后实践。

Nacos 是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置和服务管理平台。作为 Python 开发者，你完全可以通过官方 SDK 或直接调用 HTTP API 来使用它。

下面我从零开始，带你由浅入深地掌握 Nacos 的核心用法。

一、先明白 Nacos 是干什么的

想象一下，你开发了一个微服务系统，里面有订单服务、用户服务、支付服务。这些服务之间要互相调用，就必须知道对方的地址（IP 和端口）。

传统做法是把地址写死在配置文件里，但一旦服务实例增多、地址变化（扩容、宕机），维护起来就是灾难。

Nacos 解决两个核心问题：

  • 服务发现：服务启动时自动向 Nacos 注册自己的地址；调用方从 Nacos 动态拉取可用地址列表，不再硬编码。
  • 配置管理：所有服务的配置集中存放在 Nacos，支持动态刷新，不用重启服务就能更改配置。

此外，Nacos 还提供服务健康检查、权重流量控制、命名空间隔离等功能。

和同类工具对比：Nacos = Eureka（注册中心） + Config Server（配置中心）。强在功能合一，且原生支持 CP/AP 切换，适合国内生态。

二、快速搭一个 Nacos 服务（用 Docker）

你在 Windows/Mac/Linux 上只需有 Docker，一行命令就能跑起来：

1
docker run -d -p 8848:8848 -p 9848:9848 --name nacos -e MODE=standalone nacos/nacos-server:v2.3.0
  • 8848 是主端口（HTTP 管理/API）
  • 9848 是 gRPC 客户端通信端口（Python SDK 2.x 需要）
  • MODE=standalone 单机模式，适合学习

启动后访问 http://localhost:8848/nacos，用默认账号 nacos/nacos 登录，看到控制台就成功了。

三、Python 如何接入：安装 SDK

官方推荐 nacos-sdk-python，支持服务发现和配置管理，兼容 Nacos 2.x。

1
pip install nacos-sdk-python

注意：目前最新版为 2.x 系列，内部通过 gRPC 与 Nacos 通信，需要 Nacos 2.x 版本且暴露 9848 端口。

四、入门第一步：服务注册与发现

假设我们有一个 user-service 服务，它要注册到 Nacos；然后 order-service 要去发现它并调用。

4.1 服务提供者：注册服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import nacos
import time

# Nacos 服务地址和命名空间（不填默认 public）
SERVER_ADDRESSES = "localhost:8848"
NAMESPACE = ""          # 默认命名空间，可改为你的 namespace id

client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE)

# 注册服务：服务名、IP、端口，还可以加元数据
client.add_naming_instance(
    "user-service",
    "192.168.1.10",     # 实际对外服务的 IP
    8080,
    cluster_name="DEFAULT",
    weight=1.0,
    metadata={"version": "1.0"}
)

print("注册成功")
# 服务提供者要保持心跳，SDK 会自动维持，这里让进程不退出
try:
    while True:
        time.sleep(5)
except KeyboardInterrupt:
    # 进程结束时最好主动注销（可选的优雅下线）
    client.remove_naming_instance("user-service", "192.168.1.10", 8080)

启动后，在 Nacos 控制台的”服务管理” -> “服务列表”就能看到 user-service。

4.2 服务消费者：发现并调用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import nacos
import requests
import random

client = nacos.NacosClient("localhost:8848")

# 获取 healthy 实例列表
instances = client.list_naming_instance("user-service", healthy_only=True)
if not instances:
    print("没有可用实例")
else:
    # 简单随机负载均衡
    instance = random.choice(instances)
    ip = instance["ip"]
    port = instance["port"]
    url = f"http://{ip}:{port}/api/users"
    resp = requests.get(url)
    print(resp.json())

# 还可以订阅服务变化，当实例上下线时收到通知
def on_change(instances):
    print("实例列表发生变化:", instances)

client.subscribe("user-service", on_change)
# 保持运行，等待通知
input("按回车退出...")
client.unsubscribe("user-service", on_change)

此时你不用再关心 user-service 的具体地址，Nacos 帮你动态管理。

五、入门第二步：配置管理

5.1 在 Nacos 控制台创建配置

进入”配置管理” -> “配置列表”，点击 + 号，Data ID 填 order-service.yaml，Group 默认 DEFAULT_GROUP，配置内容写：

1
2
3
4
5
db:
  host: 127.0.0.1
  port: 3306
  user: root
  password: 123456

发布。

5.2 Python 拉取配置并监听变化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import nacos
import yaml

client = nacos.NacosClient("localhost:8848")

# 获取配置
config = client.get_config("order-service.yaml", "DEFAULT_GROUP")
cfg_dict = yaml.safe_load(config)
print("当前数据库配置：", cfg_dict["db"])

# 监听配置变化，实现动态刷新
def config_change_callback(args):
    new_cfg = args["content"]
    d = yaml.safe_load(new_cfg)
    print("配置更新了！新数据库：", d["db"])
    # 在这里重新建立数据库连接等操作

client.add_config_watcher(
    "order-service.yaml",
    "DEFAULT_GROUP",
    config_change_callback
)

input("等待配置变更...")

当你在 Nacos 控制台修改配置并发布后，Python 程序会立刻收到回调，无需重启。

六、进阶：将 Nacos 集成到你的 Python 项目中

上面的代码是脚本式的，实际项目（如 FastAPI、Flask）中该如何优雅使用？

6.1 封装配置管理器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import yaml
import nacos
from functools import lru_cache

class NacosConfig:
    def __init__(self, server, namespace=""):
        self.client = nacos.NacosClient(server, namespace=namespace)
        self._cache = {}

    def get(self, data_id, group="DEFAULT_GROUP"):
        # 使用缓存避免频繁请求
        raw = self.client.get_config(data_id, group)
        return yaml.safe_load(raw)

    def watch(self, data_id, group, callback):
        self.client.add_config_watcher(data_id, group, callback)

nacos_config = NacosConfig("localhost:8848")

在 FastAPI 的 startup 事件中初始化，并注入到路由里。

6.2 服务发现结合负载均衡

生产环境中，可以自己实现加权轮询或随机算法，也可集成第三方负载均衡器。

1
2
3
4
5
6
7
8
9
10
11
12
def get_instance(service_name, client):
    instances = client.list_naming_instance(service_name, healthy_only=True)
    # 按权重加权随机选一个
    total_weight = sum(ins.get("weight", 1) for ins in instances)
    r = random.uniform(0, total_weight)
    upto = 0
    for ins in instances:
        w = ins.get("weight", 1)
        if upto + w >= r:
            return ins
        upto += w
    return instances[0]

6.3 命名空间与灰度发布

  • 命名空间（Namespace）：用于隔离环境（dev/test/prod）。创建命名空间会获得一个 UUID，传给 NacosClient 的 namespace 参数即可。
  • 分组（Group）：同一个服务的不同分组，可用于灰度。例如让 user-service 的新版本注册到 BETA_GROUP，调用方根据需要选择分组。

6.4 鉴权

如果 Nacos 开启了权限认证，需要在创建 Client 时传入用户名密码：

1
2
3
4
5
6
client = nacos.NacosClient(
    "localhost:8848",
    namespace="",
    username="nacos",
    password="nacos"
)

七、Nacos 核心原理（小白也能懂）

  • 注册中心：采用”服务-实例”模型，服务名为索引，实例是具体的 IP:Port。客户端定期发送心跳（5s），若 Nacos 长时间收不到，则剔除该实例。
  • 配置中心：数据存储在内置 Derby（单机）或 MySQL（集群）。客户端通过长轮询或长连接监听配置变更，实现毫秒级推送。
  • CAP 选择：Nacos 默认 AP 模式，优先保证可用性；必要时可切换到 CP 模式（通过 Raft 协议），保证一致性。
  • Python SDK 内部通过 gRPC 双向流与 Nacos 服务器通信，相比 HTTP 更轻量、实时性更高。

八、总结与下一步

对于 Python 开发者，使用 Nacos 的典型流程是：

  1. 部署 Nacos Server（Docker 一键搞定）
  2. 安装 nacos-sdk-python
  3. 在代码中完成服务注册/发现，和配置拉取/监听
  4. 根据项目需要加入命名空间隔离、鉴权等

从零开始搭建一个微服务配置中心 + 注册中心，就是这么简单。