腾讯云微服务平台TSF对接使用完全指南：从零搭建到全链路治理
引言：微服务架构的挑战与TSF的定位
在数字化转型的浪潮中，越来越多的企业选择微服务架构来应对业务规模的快速增长。然而微服务架构在带来灵活性和可扩展性的同时，也引入了服务注册发现、配置管理、流量治理、链路追踪、分布式事务等一系列新的技术挑战。当企业的微服务数量从几十个增长到几百甚至上千个时，如何高效地管理这些服务的生命周期、如何保障服务调用的高可用与高稳定性、如何在异构技术栈（Java、Go、Python等多语言并存，Spring Cloud、Dubbo、gRPC等多框架共存）下实现统一的治理能力，成为困扰众多开发团队的核心痛点。
腾讯云微服务平台TSF（Tencent Service Framework）正是为解决上述问题而诞生的一站式微服务PaaS平台。TSF整合了腾讯内部历经多年锤炼的分布式系统构建经验，提供了从应用开发、部署、运行到运维的全生命周期管理能力。它支持原生Spring Cloud应用零代码改造直接接入，兼容Dubbo等主流微服务框架，同时通过Service Mesh模式支持多语言应用的接入。TSF以腾讯云中间件团队多款成熟的分布式产品为核心基础组件，提供秒级推送的分布式配置服务、高可用的注册中心和全链路追踪等高可用稳定性组件。
本文将从零开始，系统地介绍TSF的对接使用方法。无论你是正在评估微服务解决方案的架构师，还是即将上手TSF的开发者，本文都能为你提供从开通服务到生产级治理的完整实践指引。
需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联
一、开通TSF服务与权限准备
1.1 开通TSF服务
使用TSF的第一步是开通服务。登录腾讯云控制台后，在产品列表中找到"微服务平台TSF"，点击进入产品详情页，按照指引开通服务。需要注意的是，TSF的首次使用需要主账号进行服务角色授权。主账号登录TSF控制台后，系统会提示"由于没有授权腾讯微服务平台TSF服务角色权限无法访问其他云产品资源"，此时需要单击"前往授权"，进入CAM控制台完成授权操作。该授权使得TSF能够访问您账号下的其他云产品资源，包括容器服务TKE、云服务器CVM、镜像仓库、云监控等。
1.2 子账号与协作者的权限配置
在实际的企业开发场景中，通常使用子账号或协作者进行日常操作。对于子账号用户，除了主账号完成服务角色授权外，还需要主账号为子账号创建PassRole策略并绑定。这是因为TSF平台在运行过程中需要调用其他云产品的接口获取信息，包含VPC、CVM、API网关、镜像仓库、云监控、TKE等云产品。建议对子账号授权tsf_PassRole策略，如果没有该策略，需要主账号或具有QcloudCamRoleFullAccess策略的用户创建角色。权限配置完成后，子账号即可正常使用TSF控制台的全部功能。
二、创建应用与部署组
2.1 应用的概念与类型
在TSF中，"应用"是管理微服务的基本单元。每个应用对应一个独立的微服务，可以包含多个版本的程序包和多个部署组。TSF支持三种应用类型：虚拟机应用（ApplicationType为V）、容器应用（ApplicationType为C）和Serverless应用（ApplicationType为S）。同时，根据微服务架构模式，TSF还区分了三种微服务类型：Service Mesh应用（M）、普通应用（N）和网关应用（G）。
创建应用可以通过TSF控制台或调用API完成。控制台操作路径为：登录TSF控制台，在左侧导航栏单击"应用管理"，进入应用列表页后单击"新建应用"。需要填写应用名称（最长60字符）、部署方式（容器部署或虚拟机部署）、开发语言（Java、C/C++、Python、Go等）、开发框架（Spring Cloud、Dubbo、Go-gRPC等）等信息。如果通过API创建，可以调用CreateApplication接口，该接口的请求域名为tsf.tencentcloudapi.com。以下是一个通过API创建应用的请求示例参数：
{
"ApplicationName": "order-service",
"ApplicationType": "C",
"MicroserviceType": "N",
"ApplicationRuntimeType": "Java 8",
"FrameworkType": "SpringCloud"
}创建应用时还需要配置注册配置治理方式。可以选择开启或关闭注册配置治理，开启后应用将接入注册配置治理中心，进行服务注册和配置管理。实例类别目前主要有两种选择：共享实例（TSF-Consul）和独占实例（Polaris北极星）。需要注意的是，TSF Consul已转为内测阶段，官方推荐新用户直接使用Polaris（北极星）。
2.2 部署组与实例管理
应用创建完成后，需要创建部署组来实际运行服务实例。部署组是应用在特定集群和命名空间下的运行单元。在容器部署场景下，部署组对应Kubernetes中的Deployment资源；在虚拟机部署场景下，部署组对应一组云服务器实例。创建部署组时需要选择集群（已导入TSF的容器集群或虚拟机集群）、命名空间（用于隔离不同环境，如开发、测试、生产）、部署组名称等。
TSF支持将容器服务集群导入到TSF中进行统一管理。导入集群后，TSF可以自动感知集群中的Pod变化，实现服务实例的自动注册与发现。在虚拟机部署模式下，TSF需要在每台虚拟机上安装TSF Agent，Agent负责与TSF控制面通信、上报服务实例状态、拉取配置等。
三、Spring Cloud应用接入TSF
3.1 零改造接入的核心理念
TSF最吸引人的特性之一是对原生Spring Cloud应用的零改造接入支持。这意味着您现有的Spring Cloud应用无需修改任何业务代码、无需重新编译打包，只需添加TSF的SDK依赖并做一些简单的配置，即可直接接入TSF平台，享受服务注册发现、服务治理、应用监控和调用链跟踪等一系列能力。
3.2 Maven依赖配置
在Spring Cloud工程的pom.xml文件中，引入TSF的SDK依赖。推荐使用spring-cloud-tsf-dependencies作为父依赖来统一管理版本：
<parent>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-dependencies</artifactId>
<version>1.40.0-Greenwich-RELEASE</version> <!-- 请使用最新的稳定版本 -->
</parent>然后在dependencies中添加spring-cloud-tsf-starter依赖：
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-starter</artifactId>
</dependency>如果希望使用TSF提供的默认日志采集能力，还可以添加logger依赖：
<dependency>
<groupId>com.tencent.tsf</groupId>
<artifactId>spring-cloud-tsf-logger</artifactId>
</dependency>3.3 启用TSF注解
在Spring Boot的启动类上添加@EnableTsf注解，即可启用TSF的全部能力：
import com.tencent.tsf.annotation.EnableTsf;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableTsf
public class OrderServiceApplication {
public static void main(String[] args) {
SpringApplication.run(OrderServiceApplication.class, args);
}
}添加该注解后，应用启动时会自动向TSF注册中心注册服务信息，同时开启配置管理、服务治理等功能的SDK端支持。
3.4 配置文件调整
在application.yml或application.properties中，需要配置应用名称（spring.application.name），该名称将作为服务名在TSF注册中心中显示。其他Spring Cloud的标准配置（如server.port等）保持不变。TSF会自动接管服务注册与发现的逻辑，无需额外配置Eureka、Consul或Zookeeper的客户端地址。
3.5 双注册发现模式与平滑迁移
对于已经运行在自有注册中心（如Eureka、Zookeeper、Consul）上的Spring Cloud应用，TSF提供了双注册发现模式来实现平滑迁移。在这种模式下，改造后的应用同时向原有注册中心和TSF注册中心进行服务注册，同时从两个注册中心发现服务。这样，已迁移的应用和未迁移的应用可以互相发现和调用，保障迁移过程中业务流量不中断。
启用双注册发现需要在application.properties中添加如下配置：
tsf:
migration:
registry:
excludes: ZOOKEEPER # 不注册到Zookeeper
subscribes:
- EUREKA # 从Eureka发现服务
- TSF # 从TSF发现服务需要注意的是，使用双注册发现功能要求SDK版本在1.24.0-Finchley-RELEASE或1.24.0-Greenwich-RELEASE以上。目前TSF支持与Eureka、Zookeeper、Consul等主流注册中心进行双注册发现。
四、服务注册发现与配置管理
4.1 注册中心架构
TSF的注册中心经历了从Consul到Polaris（北极星）的演进。早期TSF使用Consul作为注册中心，采用共享实例的多租户架构。随着业务规模的增长，共享架构存在稳定性风险和性能瓶颈。为此，腾讯云推出了基于自研开源组件Polaris的独占注册配置治理中心。Polaris在腾讯内部的服务注册数量超过百万，日接口调用量超过十万亿，通用性和稳定性都得到了大规模验证。
目前，TSF Consul已转为内测阶段，官方推荐新用户直接使用Polaris（北极星）。对于仍在使用的TSF Consul用户，腾讯云提供了平滑迁移方案，通过数据同步机制将Consul中的数据实时同步至Polaris，客户无需修改任何代码即可完成迁移。迁移完成后，注册、配置、服务治理等数据流和控制面将完全由TSF Polaris承载。
4.2 服务注册与健康检查
应用接入TSF后，启动时会自动向注册中心注册服务实例信息，包括IP地址、端口、服务元数据等。注册中心会对注册上来的服务实例进行健康检查。TSF支持多种健康检查机制：对于Spring Cloud应用，默认通过Spring Boot的Actuator健康检查端点（/actuator/health）来判定实例健康状态；对于Service Mesh应用，通过Sidecar代理进行流量层面的健康探测。当实例不健康时，注册中心会将其从可用实例列表中剔除，阻止主调方向不健康的服务实例发送请求。同时，TSF提供了保护能力——当不健康实例剔除超过一定数量时，停止剔除操作，防止因不健康实例过多导致雪崩效应。
4.3 分布式配置管理
TSF提供了一键对接的分布式配置中心能力。配置管理支持两种类型：应用配置（针对特定应用）和全局配置（跨应用共享）。配置内容支持动态推送和热生效——配置变更后，TSF会秒级将新配置推送到所有订阅该配置的应用实例，应用无需重启即可生效。
通过TSF控制台创建配置的路径为：在左侧导航栏选择TSF Consul或Polaris后，单击"配置管理" > "全局配置"或"应用配置"。配置内容支持直接输入文本，也可以从配置模板导入。TSF提供了Ribbon、Hystrix、Zuul等Spring Cloud组件的配置模板，例如Ribbon的超时配置模板：
# 请求处理超时时间
ribbon.ReadTimeout: 5000
# 请求连接超时时间
ribbon.ConnectTimeout: 2000
# 同一实例最大重试次数，不包括首次调用
ribbon.MaxAutoRetries: 0
# 重试其他实例的最大重试次数
ribbon.MaxAutoRetriesNextServer: 1在代码中通过@ConfigurationProperties或@Value注解即可获取配置中心推送的配置值，实现配置与代码的分离。
五、服务治理核心能力
5.1 服务路由与灰度发布
服务路由是TSF服务治理的核心能力之一。通过配置路由规则，可以实现按比例、按标签的流量调度，从而支持灰度发布、蓝绿部署、A/B测试等场景。
灰度发布的具体操作流程如下：首先在同一个应用下创建两个部署组，分别部署稳定版本（如v1）和灰度版本（如v2-beta）。然后在服务治理页面找到该服务，进入服务路由选项卡，新建路由规则。规则中可以指定流量来源（如主调服务名等于consumer-demo）和流量目的地（配置各部署组的流量权重）。例如，初始时可以设置v1版本权重为90，v2-beta版本权重为10，实现10%的灰度流量。灰度版本运行稳定后，可以逐步调整权重至50:50、10:90，最终达到100%新版本覆盖。
TSF的路由规则支持基于多种条件的流量匹配：HTTP方法（GET、POST等）、主机名（Host头）、请求头（自定义Header）、请求路径（支持前缀匹配和正则匹配）。对于HTTPS和gRPC等协议，还支持基于SNI的路由匹配。路由规则始终是在被调用方（服务提供方）进行配置的。
5.2 基于业务参数的服务治理
TSF支持通过微服务网关结合Tag插件实现基于业务参数的精细化服务治理。其核心思路是：在微服务网关层配置Tag插件，将请求中的业务参数（如Header中的region、usertype等）转换为TSF的标签（Tag）。然后在下游服务的服务路由、服务鉴权、服务限流等治理规则中，基于这些标签进行流量控制。整个过程中应用代码无需任何修改。
配置Tag插件的步骤为：在TSF控制台左侧导航栏单击"微服务网关" > "插件管理"，单击"新建插件"，插件类型选择Tag。在插件配置中，将请求参数（Header或URL参数）映射为自定义标签。创建完成后，将插件绑定到对应的网关分组即可生效。标签生效后，可以在服务路由中配置规则：例如当标签region值为cityA时，100%流量路由到部署了cityA版本的部署组。
5.3 服务限流与熔断
TSF提供了服务级别的限流和熔断能力。限流策略可以在控制台上通过可视化方式配置。配置路径为：在服务治理页面进入目标服务的详情页，选择"限流策略"页签，单击"配置限流规则"。限流规则可以基于QPS（每秒请求数）进行限制，支持针对全局或特定标签的细粒度限流。
熔断方面，TSF提供服务、实例、接口三级熔断策略。当某个服务实例的失败率达到阈值时，熔断器会打开，后续请求不再发往该实例，实现故障隔离。TSF还支持宕机自恢复与异常实例屏蔽。
5.4 服务鉴权
服务鉴权用于控制服务之间的调用权限。在TSF控制台中，可以配置服务级别的鉴权规则，指定哪些主调服务可以调用当前服务。鉴权规则支持基于标签的细粒度控制，例如只允许携带特定标签（如usertype=vip）的请求访问某个敏感接口。
六、微服务网关
6.1 网关的定位与部署
微服务网关是TSF微服务架构中的流量入口。TSF的微服务网关基于业界主流的网关技术（如Spring Cloud Gateway、Kong等）构建，提供了请求路由、API管理、流量监控、访问限制等功能。通过网关，外部请求可以统一接入，然后根据路由规则分发到后端的各个微服务。
部署微服务网关时，需要先创建网关应用（MicroserviceType选择G，即网关应用），然后创建网关部署组并部署网关程序。网关部署后，需要新建网关分组并将网关部署组绑定到分组上。最后将后端微服务的API导入到网关分组中并发布。
6.2 路由配置
网关路由配置决定了外部请求如何转发到后端服务。在TSF控制台中，进入网关管理页面，选择目标网关实例，可以配置路由规则。路由规则支持精确主机名匹配和通配符主机名匹配。例如配置Host为["example.com", "service.com"]，则只有Host头为这两个值之一的请求才会匹配该路由。请求路径支持前缀匹配（如/api/v1/匹配/api/v1/users）和正则匹配。请求头匹配支持配置多个自定义Header，多个Header之间为逻辑"与"关系。
网关调用后端微服务的访问路径格式为：
IP或域名/分组context/命名空间名/微服务名/API路径需要注意的是，当微服务网关部署在非全局命名空间中时，访问路径中必须填写正确的命名空间名，否则访问不通。网关还支持自定义路由模式，通过在请求Header中设置TSF-Opensource-Mode: true来标识走自定义路由逻辑。
七、可观测性：监控、日志与调用链
7.1 应用性能监控（APM）
TSF与腾讯云应用性能监控（APM）深度集成。在TSF控制台新建应用时会自动关联免费的APM业务系统。APM提供了应用、部署组、实例级别的监控能力。监控指标包括：请求量、响应时间、错误率、JVM内存使用率、GC次数等。通过APM控制台可以配置告警策略，当指标超过阈值时发送告警通知。
TSF还支持自定义Dashboard监控面板。在云监控控制台中，可以新建Dashboard并选择TSF相关的监控指标进行展示。
7.2 调用链追踪
TSF提供了分布式调用链追踪能力。对于Spring Cloud应用，TSF支持通过Spring Cloud Sleuth和Zipkin组件接入调用链。调用链可以清晰地展示从用户发起请求开始，经过各个微服务的调用路径、顺序以及每个环节的耗时信息。TSF的调用链支持服务间调用链的串联，但不支持方法级调用链。
在TSF控制台中查询调用链的路径为：左侧导航栏单击"依赖分析" > "调用链查询"，选择对应的命名空间和微服务后即可查询。调用链与日志服务实现了联动，可以从调用链中的某个Span直接跳转到对应的应用日志，方便进行根因分析。
对于Service Mesh应用，TSF通过Sidecar流量劫持的方式实现调用链采集，支持服务间调用链的串联。
7.3 日志服务
TSF提供了完善的日志采集和管理能力。TSF默认提供标准输出（stdout）日志的查看功能，无需额外设置即可在控制台查看应用的标准输出日志。
对于文件日志，需要在TSF控制台创建日志配置项。创建时可以选择日志格式（Spring Boot默认格式、自定义logback格式等）并配置日志采集路径。然后在部署应用时选择对应的日志配置项，TSF Agent会自动采集指定路径下的日志文件并上报到日志服务CLS。如果使用Spring Boot应用且不想配置日志路径，可以依赖spring-cloud-tsf-logger，TSF会使用默认日志路径进行采集。
以下是一个自定义logback配置的示例：
<configuration scan="true" scanPeriod="60 seconds" debug="false">
<property name="log.path" value="/var/root.log" />
<appender name="stdout" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %contextName [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
</configuration>TSF的日志服务支持多维度日志查询与筛选。日志存储上限根据版本不同有所区别：基础版每个节点最大2.5GB，专业版每个节点最大4GB，铂金版每个节点最大20GB。日志存储天数最多30天。
八、分布式事务集成
在微服务架构中，跨服务的数据一致性是经典难题。TSF可以与腾讯云分布式事务DTF（Distributed Transaction Framework）产品无缝集成，解决跨数据库和跨服务的事务问题。DTF支持TCC、FMT、SAGA等多种事务模式，且支持原生Spring Cloud框架。
在Spring Cloud应用中集成DTF的步骤为：在Maven pom文件中引入TSF SDK依赖，并在Spring Boot启动类上添加@EnableTsf注解。然后根据所选的事务模式（TCC、FMT或SAGA），在代码中实现对应的Try-Confirm-Cancel或补偿逻辑，并在分布式事务控制台配置事务分组。DTF支持单独部署或与TSF协同部署。
九、CI/CD与弹性伸缩
9.1 持续集成与持续交付
TSF支持与主流的CI/CD工具无缝集成。代码提交后可以触发自动化构建流程，经测试无误后借助TSF快速部署至目标环境。TSF可以与CODING持续集成（全面兼容Jenkins）配合使用。通过TSF的API，CI/CD流水线可以实现应用创建、程序包上传、部署组创建、应用部署等全流程自动化。
TSF记录了每次构建和部署的信息，方便团队追溯版本变更。TSF支持滚动更新、蓝绿发布、金丝雀（灰度）发布等多种部署策略。
9.2 弹性伸缩
TSF支持基于监控指标的弹性伸缩。在TSF控制台中可以为部署组配置弹性伸缩策略。伸缩规则可以基于CPU使用率、内存使用率或业务QPS等指标触发。TSF的弹性伸缩与底层容器平台（TKE）的弹性伸缩需要协调使用：请勿同时开启容器平台的弹性伸缩和TSF的弹性伸缩，否则可能导致TSF的弹性伸缩规则被容器平台的规则覆盖。当需要使用被动触发弹性时，建议使用TSF页面的弹性伸缩能力。
十、从TSF Consul到Polaris的迁移
如前所述，TSF正在从Consul向Polaris（北极星）演进。对于正在使用TSF Consul共享实例的用户，腾讯云提供了分阶段平滑迁移方案。
阶段一：数据流迁移（平台侧完成，对业务透明）：通过数据同步机制将TSF Consul中的服务注册数据、配置数据、治理规则等实时同步至TSF Polaris。此阶段TSF Consul控制台保持可读写，TSF Polaris控制台仅可查看实例列表。
阶段二：应用切换与控制台迁移（客户配合操作）：第一步，客户更新应用SDK版本，使应用注册到TSF Polaris；第二步，客户重新部署应用，将注册配置中心切换至Polaris；第三步，确认服务在Polaris中注册成功；最后，观察稳定后完成控制台迁移，TSF Consul禁止读写并彻底下线。
迁移前建议对现有TSF Consul环境中的服务列表、服务实例数量、配置文件数量、治理规则进行完整盘点，形成资产清单作为迁移验证的基线。
结语
腾讯云微服务平台TSF为企业的微服务架构转型提供了完整的解决方案。从零改造的Spring Cloud接入、到秒级推送的分布式配置管理、再到精细化的服务治理与全链路可观测性，TSF覆盖了微服务全生命周期的每一个环节。随着Polaris（北极星）的逐步普及，TSF在服务注册发现的性能、稳定性和治理能力丰富度上还将持续提升。希望本文的实践指南能帮助开发者快速上手TSF，在微服务架构的征途上少走弯路。
常见问题问答
问1：Spring Cloud应用接入TSF需要修改业务代码吗？
答：不需要。TSF支持原生Spring Cloud应用零改造接入，只需在pom.xml中添加TSF的SDK依赖并在启动类上添加@EnableTsf注解即可，业务代码无需任何修改。
问2：TSF Consul和Polaris（北极星）有什么区别？应该选择哪个？
答：TSF Consul是共享实例架构，存在多租户间的稳定性风险和性能瓶颈；Polaris是腾讯自研开源的独占实例，提供更高的稳定性、更丰富的治理能力（路由、限流、熔断等）和更好的多语言支持。目前TSF Consul已转为内测阶段，新用户推荐直接使用Polaris。
问3：TSF的配置管理支持配置热生效吗？
答：支持。TSF的分布式配置管理支持配置的动态推送和热生效。配置变更后TSF会秒级推送到所有订阅该配置的应用实例，应用无需重启即可生效。
问4：如何在TSF中实现灰度发布？
答：在TSF中实现灰度发布的典型步骤为：创建两个部署组分别部署稳定版本和灰度版本，在服务治理中配置路由规则，设置各部署组的流量权重（如90:10），然后逐步调整权重直至新版本完全上线。
问5：TSF的调用链追踪支持方法级别的调用链吗？
答：TSF的调用链支持服务间调用链的串联，但不支持方法级别的调用链。如果需要方法级别的性能分析，可以结合JVM火焰图等工具进行辅助排查。
问6：子账号无法使用TSF控制台怎么办？
答：子账号使用TSF需要主账号完成两项授权：首先主账号需要在TSF控制台完成服务角色授权；其次主账号需要为子账号创建PassRole策略并绑定。完成这两项授权后子账号即可正常使用。
