实例生命周期
实例生命周期描述一个服务实例从注册到被发现、更新、注销和清理的过程。理解这个过程，有助于排查实例丢失、健康状态异常和订阅结果不符合预期的问题。
注册实例
注册实例时，需要指定所属服务和实例地址：
| 字段 | 说明 |
|---|---|
namespaceId | 命名空间，默认 public。 |
groupName | 分组，默认 DEFAULT_GROUP。 |
serviceName | 服务名。 |
ip / port | 实例地址。 |
clusterName | 集群名，默认 DEFAULT。 |
ephemeral | 是否临时实例，必须和所属 Service 类型匹配。 |
metadata | 实例元数据。 |
临时实例通常由应用运行进程注册。持久实例通常由管理流程维护。不要把持久实例当成不会健康检查的临时实例，也不要把临时实例当成长期持久数据。
临时实例
临时实例是运行时状态。它依赖客户端存活。
对于 gRPC SDK 客户端，实例挂在客户端连接上。连接断开后，服务端会移除连接维度的 publisher 和 subscriber 状态。客户端重连后，SDK 会根据 redo 数据重新注册实例和恢复订阅。
对于 HTTP 或兼容客户端，需要通过心跳续约维持实例存活。Nacos 3.x HTTP OpenAPI 中，注册和续约使用同一接口，通过 heartBeat=true 表示续约。
续约请求只表示实例仍然存活。它不会重新解析完整实例元数据。实例已经过期被移除时，客户端需要重新注册完整实例信息。
持久实例
持久实例通过服务端持久路径维护。它适合由控制台、Admin API 或 Maintainer SDK 管理。
持久实例写入失败时，不会回退到临时 Distro 路径。它需要对应 CP 路径可用。持久实例恢复依赖服务端 snapshot 和元数据恢复。
持久服务和临时服务不能在同一个 Service 身份下混用。如果一个服务已经按临时服务创建，再尝试写入持久实例，应先调整服务设计，而不是强行混合。
注销实例
注销会从所属 client 或持久路径中移除实例，并触发服务变更事件。
为了方便运行时客户端处理，注销不存在的实例通常可以视为成功 no-op。应用退出时，应尽量主动调用注销接口或关闭 SDK，让服务端尽快清理运行时状态。
更新实例
实例更新常用于调整：
enabled状态。weight权重。- 实例扩展元数据。
通过管理路径写入的 instance metadata 属于运维态元数据。它会覆盖运行时注册元数据中的同名 key。更多规则见 健康、权重与元数据。
批量注册
批量注册适合 SDK 或接入层一次发布多个临时实例。服务端会把这些发布信息挂到所属 client 下，并触发服务变更事件。
批量注册不是批量管理接口。批量管理、列表和诊断应使用 Admin API 或 Maintainer SDK。
清理行为
常见清理来源包括：
- gRPC 连接断开。
- HTTP 心跳超时。
- 临时 client 过期。
- 空服务清理。
- 元数据过期清理。
清理会影响订阅推送和服务发现结果。排查实例“突然消失”时，需要同时看客户端连接、心跳日志、服务端清理日志和 Distro 同步状态。