要让 FastAPI 服务在启动后自动注册到 Nacos核心思路是利用 FastAPI 的生命周期事件lifespan或app.on_event在应用启动时调用 Nacos 客户端进行注册并在应用关闭时优雅注销。主要有两种实现方式你可以根据项目的复杂度和对控制粒度的需求来选择。️ 方案一使用官方 SDKnacos-sdk-python(灵活可控)这是最基础、最灵活的方式适合需要精细控制注册逻辑的项目。1. 安装依赖bashpip install nacos-sdk-python2. 编写注册与注销逻辑创建一个nacos_client.py文件来封装 Nacos 客户端操作并在 FastAPI 的主文件中调用。nacos_client.pypythonimport nacos import socket # Nacos 服务器配置 SERVER_ADDRESSES 127.0.0.1:8848 # 替换为你的 Nacos 地址 NAMESPACE public # 替换为你的命名空间 ID USERNAME nacos PASSWORD nacos client nacos.NacosClient( SERVER_ADDRESSES, namespaceNAMESPACE, usernameUSERNAME, passwordPASSWORD ) def get_local_ip(): 获取本机在局域网中的 IP 地址 try: s socket.socket(socket.AF_INET, socket.SOCK_DGRAM) s.connect((8.8.8.8, 80)) ip s.getsockname()[0] s.close() return ip except Exception: return 127.0.0.1 def register_service(service_name, port, group_nameDEFAULT_GROUP): 注册服务到 Nacos ip get_local_ip() client.add_naming_instance( service_nameservice_name, ipip, portport, group_namegroup_name, # ephemeralTrue 为临时实例默认开启心跳设为 False 则为持久化实例需主动上报健康状态 ephemeralTrue ) print(f服务 {service_name} 已注册到 Nacos地址: {ip}:{port}) def deregister_service(service_name, port, group_nameDEFAULT_GROUP): 从 Nacos 注销服务 ip get_local_ip() client.remove_naming_instance( service_nameservice_name, ipip, portport, group_namegroup_name ) print(f服务 {service_name} 已从 Nacos 注销)main.py(FastAPI 入口)pythonfrom contextlib import asynccontextmanager from fastapi import FastAPI from nacos_client import register_service, deregister_service # 服务配置 SERVICE_NAME ai-inference-service SERVICE_PORT 8000 asynccontextmanager async def lifespan(app: FastAPI): # 启动时注册服务 register_service(SERVICE_NAME, SERVICE_PORT) yield # 关闭时注销服务 (优雅下线) deregister_service(SERVICE_NAME, SERVICE_PORT) app FastAPI(lifespanlifespan) app.get(/) def read_root(): return {message: AI Service is running}启动服务bashuvicorn main:app --host 0.0.0.0 --port 8000服务启动后会自动注册到 Nacos并在 Nacos 控制台看到ai-inference-service实例。使用lifespan比旧的app.on_event更符合 FastAPI 的新版本规范且能更好地处理异步逻辑。 方案二使用fastapi-nacos-extension库 (开箱即用)如果希望更自动化、减少样板代码可以使用社区封装的集成库例如fastapi-nacos-extension它提供了类型安全的配置和进程安全的注册机制。1. 安装依赖bashpip install fastapi-nacos-extension2. 快速集成pythonfrom fastapi import FastAPI from fastapi_nacos_extension import FastAPINacos app FastAPI() nacos FastAPINacos( app, { NACOS_SERVER_ADDR: 127.0.0.1:8848, NACOS_SERVICE_NAME: ai-inference-service, NACOS_SERVICE_IP: 127.0.0.1, # 生产环境建议动态获取 NACOS_SERVICE_PORT: 8000, NACOS_AUTO_REGISTER: True, # 启动时自动注册 NACOS_HEALTH_CHECK_ENABLED: True, # 启用健康检查 }, ) app.get(/) def read_root(): return {message: AI Service is running with auto-registration}该库会自动处理服务的注册、健康检查和优雅下线。类似的库还有fastapi-nacos等用法大同小异。 生产环境关键考量心跳机制Nacos 默认使用临时实例 (ephemeralTrue)客户端 SDK 会自动启动后台线程每 5-10 秒发送心跳包以维持健康状态。如果服务异常退出心跳停止Nacos 会在约 15 秒后将实例标记为不健康并自动剔除。优雅下线应用关闭时务必在lifespan的yield之后调用remove_naming_instance向 Nacos 发送注销请求避免流量被路由到已关闭的实例上。配合uvicorn的--timeout-graceful-shutdown参数使用效果更佳。与 Spring Cloud Gateway 集成注册到 Nacos 后你的 Java 网关如 Spring Cloud Gateway就可以通过服务名自动发现并转发请求到 FastAPI 服务实现跨语言的服务调用。在网关路由配置中目标 URI 使用lb://ai-inference-service即可。配置管理Nacos 还可以作为配置中心。你可以在 Nacos 中创建 Data ID 为ai-inference-service.yaml的配置并在 Python 代码中通过client.get_config()读取实现配置的动态更新无需重启服务。 总结与建议快速原型或简单项目推荐方案二使用fastapi-nacos-extension这类库能快速集成减少手动编码。需要精细控制或已有成熟 Nacos 客户端封装推荐方案一使用官方 SDK控制力最强便于融入现有代码规范。生产环境必备无论选择哪种方案务必确保优雅下线逻辑的正确实现并考虑将 Nacos 地址、服务名等配置外部化如通过环境变量注入以便在不同环境中灵活部署。