tencent cloud

注册配置治理

文档注册配置治理Polaris（北极星）Java 应用开发使用 Java AgentJava Agent 支持无损上下线

Java Agent 支持无损上下线

PDF
聚焦模式
字号
最后更新时间： 2026-05-08 14:26:44

使用场景

微服务发布过程中，可能会因为服务的变更造成流量的错误或中断。Spring Cloud Tencent 提供了插件来实现无损上下线，其原理为：
无损上线：在服务启动后，等待服务完全就绪后再注册到注册中心（无配置健康探测接口时为延迟注册），并对外提供服务。然后再结合K8s生命周期，滚动更新下一个节点。
无损下线：在服务停止前，先从注册中心注销，拒绝新的请求，等待旧的请求处理完毕后再下线服务。

无损上线

TSE 北极星支持以下 2 种方式支持服务无损上线：服务就绪/延迟注册 和 服务注册就绪检查 。

方案一：服务就绪/延迟注册

在一些场景下，服务支持延迟加载，启动后异步加载一些资源，例如：服务需要从文件存储 COS 获取数据或者文件，待数据或者文件拉取完成后才能对外提供服务。如果在应用启动后直接注册服务，会导致服务实际没有就绪而调用失败。因此通过确保服务就绪之后，再进行注册从而对外提供服务，可以确保服务平滑、无损上线。
TSE 北极星支持以下两种服务就绪/延迟注册场景：
场景一：业务暴露健康检查接口，接口探测成功后，服务注册。
场景二：业务没有暴露健康检查接口，则延迟一段时间服务注册，默认延迟注册时长30s，可通过配置自定义延迟注册的时长。




操作步骤

步骤1：服务通过 Java Agent 接入北极星。具体步骤参见：Spring Cloud 使用 Java Agent。
步骤2：在上一步接入操作中 步骤3 SpringCloud 应用 yaml 文件中声明 Java Agent 标签 中配置无损上下线相关配置项。具体参数如下：
配置项Key
默认值
是否必填
配置项说明
spring.cloud.polaris.lossless.enabled
false
否
无损上下线开关
spring.cloud.polaris.lossless.health-check-path
无
否
业务程序健康探测接口
spring.cloud.polaris.lossless.delay-register-interval
30000
否
无配置业务程序健康探测接口，延迟注册时间。默认 30000（单位ms）
spring.cloud.polaris.lossless.health-check-interval
5000
否
配置业务程序健康探测接口后，健康探测间隔。默认 5000（单位ms）
配置示例：
apiVersion: apps/v1
kind: Deployment
......
spec:
......
  template:
    metadata:
      annotations:
        # 声明需要往这个POD中注入javaagent
        polarismesh.cn/javaagent: "true"
        # 声明应用的框架类型，对于SpringCloud应用则填写spring-cloud
        polarismesh.cn/javaagentFrameworkName: spring-cloud
        # 声明应用的框架版本，当前支持hoxton, 2023
        polarismesh.cn/javaagentFrameworkVersion: hoxton
        # 声明java-agent包的镜像版本，可用版本:https://github.com/polarismesh/polaris-java-agent/releases
        polarismesh.cn/javaagentVersion: 1.7.0-RC3
        # 用户自定义的JavaAgent配置，不填写的配置则使用默认配置，格式为JSON。具体配置查看：https://github.com/polarismesh/polaris-controller/blob/main/deploy/kubernetes_v1.22/kubernetes/javaagent-configmap.yaml
        # 无损上线配置示例:
        # polarismesh.cn/javaagentConfig: "{\\"spring.cloud.polaris.lossless.enabled\\": \\"true\\", \\"spring.cloud.polaris.lossless.delay-register-interval\\": \\"30000\\"}"
......

方案二：服务注册就绪检查

通常 K8s 提供就绪检查机制来对实例在就绪前进行健康检查，它一般会简单地认为端口起来了应用即处于就绪状态。但是实际上，应用端口起来了和服务成功注册之间存在 gap，这样会造成服务没有成功注册，旧的应用实例就被下线，下一个节点开始部署。最终导致消费端调用异常。
TSE 北极星提供服务注册状态的接口和端口，以配合 K8s 就绪检查，当应用注册完成返回200状态码，帮助 K8s 判定应用已就绪；未完成注册返回500状态码，帮助 K8s 判定应用未就绪。尤其在实例滚动更新的过程中，等实例就绪后才滚动更新下一个节点。

操作步骤：

步骤1：服务通过 Java Agent 接入北极星。具体步骤参见 Spring Cloud 使用 Java Agent。
步骤2：在上一步接入操作中 步骤3 SpringCloud 应用 yaml 文件中声明 Java Agent 标签中打开无损上下线的开关。具体参数参见 方案一。
步骤3：在容器服务 TKE等 K8s 应用部署平台中配置就绪检查，如下图所示。
路径：/online。
端口：28080。




无损下线

应用在滚动发布或者下线过程中，被调方服务实例向注册中心发起反注册，主调方从注册中心更新 IP 的过程中，存在时间 gap，导致依然有可能调用到已经下线的实例，从而调用失败。
TSE 北极星提供服务无损下线的接口：/offline，结合 K8s 的生命周期，实现服务无损下线。整体流程如下：




操作步骤：

步骤1：服务通过 Java Agent 接入北极星。具体步骤参见 Spring Cloud 使用 Java Agent。
步骤2：在上一步接入操作中 步骤3 SpringCloud 应用 yaml 文件中声明 Java Agent 标签 中打开无损上下线的开关。具体参数参见 方案一。
步骤3：在容器服务 TKE等 K8s 应用部署平台中配置 preStop 生命周期检查。
preStop 配置检查指令：curl -X PUT http://localhost:28080/offline && sleep 20

上一篇: 使用 Java Agent 接入下一篇: Java Agent 支持配置管理

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈