腾讯云微服务平台TSF对接使用完全指南：从零搭建生产级微服务架构

1. 腾讯云TSF平台概述与前置准备

腾讯云微服务平台（Tencent Service Framework，简称TSF）是一款面向企业级微服务架构的云原生PaaS平台。TSF提供应用全生命周期管理、服务注册发现、服务治理、分布式配置、微服务网关以及可观测性等一站式能力，帮助用户快速构建和运行API服务、Web服务等分布式应用。TSF支持虚拟机与容器两种部署方式，兼容Spring Cloud、Dubbo等主流微服务框架，并支持Service Mesh多语言应用接入。

在开始对接TSF之前，需要完成以下前置准备：

• 拥有腾讯云账号并完成实名认证。
• 使用主账号登录腾讯微服务平台控制台，首次进入时会提示授权TSF服务角色访问其他云产品资源（如CVM、TKE、CLS等），单击"前往授权"并同意授权即可。
• 如果使用子账号操作，需要主账号在访问管理（CAM）中为子账号授予TSF相关操作权限。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2. 创建集群与命名空间

TSF中的集群是部署应用的资源集合，分为虚拟机集群和容器集群两种类型。在部署应用之前，需要先创建集群并将云主机或容器节点导入集群。

2.1 创建虚拟机集群

登录TSF控制台，在左侧导航栏选择"集群管理"，单击"新建集群"。选择集群类型为"虚拟机集群"，填写集群名称和集群描述，选择地域和私有网络VPC。创建完成后，在集群详情页单击"导入云主机"，选择同一VPC下的CVM实例导入集群。

2.2 创建容器集群

选择集群类型为"容器集群"时，需要关联腾讯云容器服务TKE集群。TSF会自动发现同地域下的TKE集群，选择目标集群完成关联即可。

2.3 创建命名空间

命名空间用于逻辑隔离不同环境（如开发、测试、生产）的应用和服务。在TSF控制台左侧导航栏单击"命名空间"，单击"新建命名空间"，选择注册配置中心类型（共享或独占），填写命名空间名称后提交。

3. 创建应用

应用是TSF中管理微服务的基本单位。TSF支持多种应用类型：虚拟机应用（V）、容器应用（C）和Serverless应用（S）。微服务类型分为：普通应用（N）、Service Mesh应用（M）和网关应用（G）。

3.1 控制台创建应用

在TSF控制台左侧导航栏选择"应用管理" > "业务应用"，单击"新建应用"。填写应用名称（最长60字符），选择部署方式（虚拟机部署或容器部署），选择开发语言（Java、Go、Python等）和开发框架（Spring Cloud、Dubbo等）。配置注册配置治理方式，可选择开启或关闭服务注册发现能力。

3.2 API方式创建应用

TSF提供完整的API接口，可通过调用CreateApplication接口创建应用。接口请求域名为tsf.tencentcloudapi.com，频率限制为20次/秒。关键请求参数包括：

{
  "ApplicationName": "application-user",     // 应用名称，最长60字符
  "ApplicationType": "C",                    // V:虚拟机 C:容器 S:Serverless
  "MicroserviceType": "N",                   // N:普通应用 M:Mesh G:网关
  "ApplicationDesc": "用户服务应用",
  "ApplicationRuntimeType": "Java 8",
  "ProgramLanguage": "Java",
  "FrameworkType": "SpringCloud"
}

返回结果中包含应用ID（如application-6a79x94v），后续操作需要用到该ID。

4. Spring Cloud应用接入TSF

TSF支持Spring Cloud原生应用零改造接入，这是最常用的接入方式。根据注册中心选型的不同，接入方式略有差异。

4.1 注册中心选型

TSF提供两种注册配置中心选型：

• 共享注册配置中心（TSF-Consul）：共享组件，自动实现租户隔离，节省部署和运维成本，与TSF其他组件紧密结合。
• 独占注册配置中心（Polaris北极星）：独占组件，资源隔离，故障隔离。Polaris是腾讯自研并开源的组件，在腾讯内部服务注册数量超过百万，日接口调用量超过十万亿。支持同城多活高可用架构。

对于新项目，推荐使用Polaris独占注册中心以获得更强的治理能力和稳定性保障。

4.2 接入共享注册中心（TSF-Consul）

在Spring Cloud应用的pom.xml中添加spring-cloud-tsf-starter依赖：

<dependency>
    <groupId>com.tencent.tsf</groupId>
    <artifactId>spring-cloud-tsf-starter</artifactId>
    <version>1.19.0-Finchley-RELEASE</version>
</dependency>

该starter中包含了服务注册发现、服务路由、服务鉴权、服务限流、服务熔断、服务容错、服务监控、分布式配置和调用链等全部功能。

在Application类中添加@EnableTsf注解开启TSF功能：

@SpringBootApplication
@EnableTsf
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

配置完成后，将应用打包部署到TSF集群，应用启动时会自动向TSF注册中心注册服务。

4.3 接入独占注册中心（Polaris）

接入Polaris需要使用Spring Cloud Tencent组件。在pom.xml的dependencyManagement中添加：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>2.1.0.0-2024.0.1-RC1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后引入starter依赖：

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-all</artifactId>
</dependency>

在Polaris控制台获取注册中心实例访问IP，通过-D参数指定注册中心地址启动应用：

nohup java -Dspring.cloud.polaris.server-addr=[实例IP:8091] -jar app.jar &

4.4 Java Agent无侵入接入

对于不想修改代码的存量Spring Cloud应用，TSF提供了Java Agent无侵入接入方案。Java Agent是JVM级别的AOP技术，无需对原有应用做任何修改即可实现动态增强。目前支持Spring Cloud 2020版本使用Java Agent接入。

在TSF控制台创建应用时，接入方式选择"无侵入接入"（通过字节码注入），部署时勾选"服务Agent"和"可观测Agent"即可获得完整的服务注册发现、服务治理和应用性能监控能力。

5. 服务注册与发现

服务注册与发现是微服务架构的核心能力。应用接入TSF后，启动时会自动向注册中心注册自身信息（服务名、IP、端口等），其他服务通过服务名调用时，TSF会从注册中心获取健康的服务实例列表。

5.1 服务调用示例

在Spring Cloud中，通过RestTemplate或Feign发起服务调用。使用RestTemplate时，在实例化方法上添加@LoadBalanced注解：

@Bean
@LoadBalanced
public RestTemplate restTemplate() {
    return new RestTemplate();
}

调用时直接使用服务名代替IP地址：

@RestController
public class ConsumerController {
    @Autowired
    private RestTemplate restTemplate;
    
    @RequestMapping("/echo/{str}")
    public String echo(@PathVariable String str) {
        return restTemplate.getForObject(
            "http://provider-demo/echo/" + str, 
            String.class
        );
    }
}

5.2 服务健康检查

TSF注册中心会定期对服务实例进行健康检查，不健康的实例会被自动剔除，保证服务调用的可靠性。在TSF控制台的"服务治理"页面可以查看所有注册服务的健康状态、实例列表和调用统计。

6. 分布式配置管理

TSF提供分布式配置管理能力，支持动态更新应用配置文件（如application.yml）中的配置，无需重启应用即可生效。

6.1 配置类型

TSF配置管理支持三种配置类型：

• 应用配置：关联到具体应用，应用部署组可以继承使用。
• 全局配置：不关联特定应用，可供多个应用共享使用。
• 文件配置：支持以文件形式管理配置内容。

6.2 配置使用方式

在Spring Cloud应用中，可通过两种方式读取配置：

• 使用@Value注解：适用于配置较少的场景。
• 使用@ConfigurationProperties注解：适用于配置较多的场景。

6.3 配置动态更新与回调

TSF支持配置更新触发回调功能，当配置发生变化时自动调用回调方法，程序可以在不重启的情况下动态修改业务逻辑。配置内容支持YAML格式编辑。在控制台的"配置管理"页面创建配置后，将其发布到目标部署组即可生效。

7. 微服务网关

微服务网关是微服务架构的统一流量入口，负责请求路由、转发、鉴权、限流等。TSF提供白屏化的微服务网关管理能力，支持Java网关和云原生网关两种类型。

7.1 创建微服务网关应用

在TSF控制台创建应用时，业务类型选择"微服务网关应用"。部署后，在"组件中心" > "微服务网关" > "网关管理"中管理网关实例。

7.2 路由配置

网关路由支持多种匹配属性：

• 主机名（Host）：支持精确匹配和通配符匹配（如*.example.com）。
• 请求路径（Path）：支持前缀匹配和正则匹配。
• 请求头（Header）：根据自定义请求头进行路由。
• HTTP方法：根据GET、POST等方法匹配。

在TSF控制台"路由管理"页面，选择目标网关实例后单击"服务"页签，进入服务路由管理页面配置路由规则。

7.3 Tag插件与业务参数路由

Tag插件是TSF微服务网关的重要扩展能力，可将外部请求参数（Path、Query、Header、Cookie）转化为TSF标签，实现基于业务参数的灵活路由、鉴权和限流。

创建Tag插件步骤：在TSF控制台选择"应用管理" > "中间件应用" > "网关插件"，单击"新建插件"，插件类型选择Tag，配置参数位置和参数名。例如将Header中的region参数转换为标签，转换后标签名为region。创建完成后将插件绑定到网关分组或API上即可生效。

配置服务路由规则时，可基于标签值进行流量分配。例如当region=cityA时，100%流量路由到版本1；当region=cityB时，100%流量路由到版本2。标签还可以与服务鉴权、服务限流、调用链进行联动。

8. 服务治理

TSF提供丰富的服务治理能力，包括服务鉴权、服务限流、服务路由和服务熔断。

8.1 服务鉴权

服务鉴权用于控制服务间的调用权限。在主调方和被调方都添加spring-cloud-tsf-starter依赖并开启@EnableTsf注解后，即可在控制台配置鉴权规则。

在主调方代码中设置标签：

import org.springframework.tsf.core.TsfContext;

// 设置单个标签
TsfContext.putTag("user", "admin");

// 设置多个标签
Map<String, String> tags = new HashMap<>();
tags.put("region", "cityA");
tags.put("userType", "vip");
TsfContext.putTags(tags);

在TSF控制台"服务治理"页面选择目标服务，配置鉴权规则，可以基于标签组合进行精确的权限控制。鉴权不通过时返回HTTP 403 Forbidden。

8.2 服务限流

服务限流通过监控服务流量的QPS指标，在达到指定阈值时进行流量控制，避免被瞬时高峰流量冲垮。TSF目前支持在被调服务上设置限流规则。在TSF控制台"服务治理"页面选择目标服务，在"服务限流"标签页配置限流规则。

8.3 服务路由

服务路由支持基于标签的流量路由，可实现灰度发布、金丝雀发布等场景。路由规则在被调用方配置。在TSF控制台"服务治理"页面选择目标服务，进入"服务路由"页面，单击"新建路由规则"配置基于标签的流量分配策略。

8.4 服务熔断

服务熔断当下游服务不可用或响应过慢时，上游服务不再继续调用目标服务，直接返回，避免级联故障。TSF支持服务、实例、API三种隔离级别的熔断规则：

• 服务级别：熔断下游目标服务的所有实例的所有API。
• 实例级别：仅熔断达到触发条件的单个实例。
• API级别：仅熔断指定API。

熔断器状态转换：

• closed：关闭状态，正常调用。检测到错误达到阈值后转为open。
• open：开启状态，不再调用下游服务。
• half open：半开状态，尝试放行部分请求，成功则回到closed，失败则回到open。

熔断规则在主调方服务上设置。在TSF控制台"服务治理"页面选择主调方服务，切换至"服务熔断"标签页，单击"新建熔断规则"。配置参数包括：

• 下游服务：选择目标服务。
• 隔离级别：服务/实例/API。
• 滑动时间窗口：统计请求结果的时间窗口。
• 最少请求次数：计算错误率之前的最小请求数。
• 失败请求率：触发熔断的失败请求比率阈值。
• 慢请求率：触发熔断的慢请求比率阈值。
• 开启到半开间隔：从open到half open的等待时间。

注意：服务熔断功能需要使用1.19.0及以上版本的SDK。

9. 可观测性：调用链、日志与监控

TSF提供多维度的可观测能力，包括分布式调用链追踪、日志服务和监控告警。

9.1 分布式调用链

TSF支持Spring Cloud Sleuth和Zipkin组件接入调用链，可以清晰地展示从用户发起请求开始，经过各个微服务的调用路径、顺序以及每个环节的耗时。TSF提供符合国人习惯的交互方式，并与日志服务联动。调用链支持按标签进行检索过滤。

9.2 日志服务

TSF日志配置项用于指定采集日志的规则，包括日志的采集路径和日志解析格式。在TSF控制台创建日志配置项后，将其发布到部署组上，同一个部署组可以关联多个日志配置项。TSF提供实时日志收集和聚合、多维度日志查询与筛选等能力。

9.3 监控告警

TSF提供细粒度的监控指标，精细到JVM监控级别。监控维度包括应用、微服务、实例等多个层次。告警功能通过与腾讯云可观测平台联动实现。在TSF控制台"日志告警"页面配置告警统计后，跳转至可观测平台配置告警策略。

10. 权限管理与安全

TSF通过访问管理（CAM）实现精细化的权限控制。

10.1 主账号授权

首次使用TSF时，主账号需要授权TSF服务角色访问其他云产品资源（VPC、CVM、TKE、CLS等）。在TSF控制台概览页单击"前往授权"，在CAM控制台同意授权即可。

10.2 子账号授权

子账号使用TSF时，需要主账号授予相关权限。在CAM控制台"用户列表"中选择目标用户，单击"授权"，关联TSF相关策略。如果子账号需要调用其他云产品接口，建议授予tsf_PassRole策略。

TSF支持为不同子账号灵活配置管理权限，包含对TSF中不同集群、命名空间、应用授予读权限或写权限。在TSF控制台"权限管理" > "角色管理"中可以进行策略配置。

10.3 数据集权限

数据集是TSF中用于精细化权限管理的功能，可以通过数据集管理配置不同的子账号使用不同资源的权限。创建应用时可以指定数据集ID。

11. 常见问题与排障

11.1 服务注册失败排查

如果服务部署成功但注册中心没有显示服务，可以按以下步骤排查：

1. 检查云服务器状态是否为"运行中"。
2. 登录云服务器执行 ps aux | grep 'agent' 查看tsf-agent进程是否存在。
3. 检查应用是否正确添加了TSF依赖和@EnableTsf注解。
4. 检查注册中心地址配置是否正确。

11.2 部署失败排查

部署失败时可以检查程序包版本、查看部署日志等方式排查。如果提示资源不足但实际资源充足，可能是集群资源配额或网络配置问题。

11.3 鉴权相关错误

遇到AuthFailure类错误时：

• 检查SecretId和SecretKey是否正确，注意前后不得有空格。
• 检查密钥是否已被删除或禁用。
• 检查请求头部的Authorization是否符合腾讯云标准。

12. 最佳实践建议

• 注册中心选型：生产环境推荐使用Polaris独占注册中心，获得更好的性能和稳定性保障。
• 接入方式选择：新项目推荐使用Spring Cloud Tencent原生接入；存量应用推荐使用Java Agent无侵入接入。
• 配置管理：将环境相关的配置（如数据库连接、Redis地址）放在TSF配置中心，实现环境隔离和动态调整。
• 服务治理：为核心服务配置合理的限流和熔断规则，防止级联故障。
• 可观测性：为关键业务接口配置调用链标签，便于问题定位和性能分析。
• 权限管理：遵循最小权限原则，为不同角色配置不同的资源访问权限。

常见问题问答

问1：TSF支持哪些微服务框架？

答：TSF支持Spring Cloud和Dubbo应用，兼容HTTP、gRPC、Dubbo等常见RPC协议，并支持Service Mesh多语言应用接入。

问2：TSF的Java Agent接入方式有什么优势？

答：Java Agent接入方式无需对原有应用做任何代码修改，通过JVM级别的字节码增强实现无侵入接入，特别适合存量应用的微服务化改造。

问3：TSF的共享注册中心和独占注册中心有什么区别？

答：共享注册中心（TSF-Consul）为多租户共享，节省成本；独占注册中心（Polaris）资源隔离、故障隔离，性能和稳定性更好。生产环境推荐使用Polaris。

问4：如何在TSF中实现灰度发布？

答：通过TSF的服务路由功能，基于标签配置流量分配规则，可以实现将特定比例的流量路由到新版本服务，从而完成灰度发布。

问5：TSF的配置管理支持动态更新吗？

答：支持。TSF配置管理支持配置动态更新，配置变更后会自动推送到应用，并触发回调方法，无需重启应用即可生效。

问6：子账号如何使用TSF？

答：子账号需要主账号在CAM中授予TSF相关操作权限，建议授予tsf_PassRole策略。TSF支持为不同子账号配置不同集群、命名空间和应用的读写权限。