<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 04-使用教程 -->
<!-- Title: 20250402-使用KtConnect实现本地Debug -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# 使用KtConnect实现本地DEBUG

## 解决问题

- 功能开发完成后无法快速测试验证的问题
- Feign无法调用集群服务的问题
- 发现BUG后无法本地DEBUG的问题

### 搭配ModHeader食用最佳

### 前置说明

- 实现本地服务远程调用（feign）集群服务只需要启动 `connect` 即可
    - 对所有服务生效
    - 需要修改 `hosts`, 所以 `hosts` 需要取消 `只读`
- 实现集群流量分流到本地（本地DEBUG）只需要启动 `mesh` 即可
    - 对单个服务生效，每个服务指令不一致
- 需要实现完整流程调用则需要启动 connect 和 mesh

## 快速使用

1. 解压工具包到某个文件夹下: [工具包下载](https://drive.weixin.qq.com/s?k=AE0Auwd4ACgrCkKGyD)
2. 执行 `Connect.bat` 文件
    - 如果报错，请编辑 `C:\Windows\System32\drivers\etc` 下的 `hosts` 文件
    - 右键`hosts` >> 属性 >> 把 `只读` 去掉
3. 修改 `Mesh.bat` 里面的 `服务名` `服务端口映射` `流量转发请求头`
4. 执行 `Mesh.bat`
5. 服务配置修改
    - 本地服务修改 `spring.cloud.nacos.discovery.namespace: qifu-develop`
    - Nacos配置和本地配置添加 `spring.cloud.nacos.discovery.ip: ${spring.application.name}`
        - 解决nacos默认通过ip路由的问题
6. 启动需要DEBUG的服务
7. 将 `modheader.crx` 拖入浏览器
8. 将 `流量转发请求头` 配置到浏览器 ModHeader 中
9. 完成

## 多服务配置（可选）
1. 复制 `Mesh.bat` 为 `xxx.bat`。例如 `qifu-saas-oms.bat`
2. 修改 `xxx.bat` 里面的 `服务名` `服务端口映射` `流量转发请求头`
   - `流量转发请求头` 可以一样
   - 如果需要同链路一起测试, 则 `流量转发请求头` 必须一样
3. 执行 `xxx.bat`
---

## 完整教程

### 1. 下载 kt-connect

- 访问 release 页面：https://github.com/alibaba/kt-connect/releases/tag/v0.3.7
- 或者直接使用wget下载

```shell
wget https://github.com/alibaba/kt-connect/releases/download/v0.3.7/ktctl_0.3.7_Windows_x86_64.zip
```

### 2. 下载 kubectl

- 官方下载链接：https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/README.md
- 推荐版本：https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.27.md#v1276

### 3. 创建 KubeConfig

```yaml
apiVersion: v1
clusters:
  - cluster:
      certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvakNDQWVhZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJek1EZ3lNakEyTURRek5Gb1hEVE16TURneE9UQTJNRFF6TkZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBS0FiCnVjQlU3amh4V0w5R1Y5NUVtOWNGdGhXUFliSTBQdnlDM3F2L25JVzBPSmR6K0pnOHU2eEp6clF6S0E3NmxUS1UKUG0rQTNjZlVWSUVBaEhFWDBUNmluYVgvZnEwWVRZSEptM3lJSGxTTHpBR2JMNCtuK0NKRU96ZHM4RHZMUW5maQpKNmwxckpWWDd6UTZsbG9oVUR0UU1BMzNISGFxUFh1NlZpdnJQYStMYjcxQjQ0d1lDRE4xeWk2bS9YY2lpV04xCkJNRDM2L2JUL280RFFLNXhwS0E5V1F1ZlBNWXMxL0Z1WGRvelM0MVZ1WENkL3h5T1lKZi9nYXhhNDZHbmRGS28KMWo3amYzc2xGQ3E1TDFubmt0Q2xFMXYvTmpiTHJkWEtGVlJzVk4xMUFGWUtXdHdrU1RaemhpdHZ3cFhwME5DbgpEU25VU21uenMxQ2d6RkFXdmljQ0F3RUFBYU5aTUZjd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0hRWURWUjBPQkJZRUZMdUExbGs5ak1Pak1wODBHa1EyKzFLUnkzSmdNQlVHQTFVZEVRUU8KTUF5Q0NtdDFZbVZ5Ym1WMFpYTXdEUVlKS29aSWh2Y05BUUVMQlFBRGdnRUJBSFlBRW9PVDl1bDJITzc3K2NFSAp6azhWdGtZRkdQRDFacUxGZklJZTZicDAvVFdZQVkzYnREekFWSGg0cjkzSlRwSEUwWHk4NTlGbzFKcXE3VHBJClFlV01ObFRLTmRDZm05bUF5eERqZGZlOHNQV3l4VlRZbGNtNTlvTlRudWNKdE40NnlxOWsyOEdEell6T3Y3b0UKNkY3TDRlbFgwRGt2TjBqZlJWb0l6Mld1Z3ZEQWpyaVVGSERyZzRVelBwNGFZOEovWVlrUURXWmFNekZUaHRJbwpDYUhGMFhrWGNKS1VoU2M0REZOTDA1MkYwcWtscWJHMmRnRlVDSGhJbmpCaC9SbEtUTjR6Qjd3UlFsNm9YamNOCmhVV0JFWSswZWV1U1lKdEcvRitCWnU0NENnY0JrYmVGcnNjaVZDbkdDNEpXWGpvdGQxaHVTN0hmcFFLZk1oRXIKQ0h3PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
      server: https://10.168.2.187:6443
    name: local
contexts:
  - context:
      cluster: local
      namespace: default
      user: develop
    name: develop@local
current-context: develop@local
kind: Config
preferences: { }
users:
  - name: develop
    user:
      client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURCekNDQWUrZ0F3SUJBZ0lRUGxBSFZ0WU9hTEloTzNXamhhNG9hekFOQmdrcWhraUc5dzBCQVFzRkFEQVYKTVJNd0VRWURWUVFERXdwcmRXSmxjbTVsZEdWek1CNFhEVEl6TURrd056QXlNREkwTkZvWERUTXpNRGd4T1RBMgpNRFF6TkZvd0VqRVFNQTRHQTFVRUF4TUhaR1YyWld4dmNEQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQCkFEQ0NBUW9DZ2dFQkFOZ2VTM29ySno4OFVYblhSbWVFMUw5YUk3NGF2aHJGU0FLTGlzSXY1MWg5SW5xY0tSanQKUE9wL2s4dHpDYkJWSXBLVW1JdWxCZTUrajFWNEpHelI5N2wxWlhtK1h6RDFkMmkwOHB1blJjd0orV0hMNmJ4aApJMG9leUVjTi9DWExod0orZjk4QlpESjhaWnJqWW44QUZ4RXJTb1BpdENLV3FteU12MzJaaHZJQkErWm1VOWE3CnNXeFRKMS96UnBYYWQ0MWQ0dVpWM0dEenJabHVmNFY5RktkRzh0VkR5MkhXcHBpK1lUcHVhNy9CQStOMG5iaW0KbUZINEp1aVhYR1dMKzBzSVM3ZWdscnh2V0lrMzMxU2NxZjFCSFpZRzZrRzNMUVkwNkFtWW5Hbm9BY0lVOFZHUgpzRDF1ZVVURm10WWJPNDEyVDk1L2JJa3BSNDhKb3ZhTFJHMENBd0VBQWFOV01GUXdEZ1lEVlIwUEFRSC9CQVFECkFnV2dNQk1HQTFVZEpRUU1NQW9HQ0NzR0FRVUZCd01DTUF3R0ExVWRFd0VCL3dRQ01BQXdId1lEVlIwakJCZ3cKRm9BVXU0RFdXVDJNdzZNeW56UWFSRGI3VXBITGNtQXdEUVlKS29aSWh2Y05BUUVMQlFBRGdnRUJBSng1ZG4ySApzc0ZnWjNXdzk3SkZPWEtWeWc4R2pGVEVyM1I0a2JuUVBSQVpsQTAxbFhpRzFzOW9LRUZ6cThHcGhpYmVidTlNCjNGckJ1NFJUeE1FTU1keW8xNEZOS2ZzTkc0Qk56VEh5Q3lqSStBb0M4MFlsNGVJUUIrZ1JsbFA0M2NOWXRnR0QKenovUmh4TUxhUHkzd3lWcnR2azVDeTU3NXNkNHRwRDcrWmNxY29GOGU1NGtzb3dXYjBkU1BZY2FlRXBkSzk3KwpqeTBQV2tTVnZ2NVJ1MjVuVmZkVGlNdkxEV3pMTzdzbTJhYllKRWw5WmtSbTlLUWhKdkhlOHNjZTdWdmpSY1BUCm5nZW0xWmFHazBvcmhyWjFMNDROMDB6b3JSSHU2V2YvdjZrK0djL2wzdHU4TUV6ekVYSGhTRytKcVdDMzgzeGYKTWNLY2UyZnRQdUJmYVlZPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
      client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBMkI1TGVpc25QenhSZWRkR1o0VFV2MW9qdmhxK0dzVklBb3VLd2kvbldIMGllcHdwCkdPMDg2bitUeTNNSnNGVWlrcFNZaTZVRjduNlBWWGdrYk5IM3VYVmxlYjVmTVBWM2FMVHltNmRGekFuNVljdnAKdkdFalNoN0lSdzM4SmN1SEFuNS8zd0ZrTW54bG11Tmlmd0FYRVN0S2crSzBJcGFxYkl5L2ZabUc4Z0VENW1aVAoxcnV4YkZNblgvTkdsZHAzalYzaTVsWGNZUE90bVc1L2hYMFVwMGJ5MVVQTFlkYW1tTDVoT201cnY4RUQ0M1NkCnVLYVlVZmdtNkpkY1pZdjdTd2hMdDZDV3ZHOVlpVGZmVkp5cC9VRWRsZ2JxUWJjdEJqVG9DWmljYWVnQndoVHgKVVpHd1BXNTVSTVdhMWhzN2pYWlAzbjlzaVNsSGp3bWk5b3RFYlFJREFRQUJBb0lCQUVoMmIrdzRoK0pHQVRPUApJTVlZM1pTRFRyU3hGc2kzR1J2eFdjY2VkTDFReDd6QW0yOEdMSVNiM2h3N0tDWjloU2dNdHRFcnRiOXZvL09PCll2Z3h0cFB5YnVIUkdPMjdnQndWZjdyODdRUXEyL2tVZS94enZYZGV0dHhNTGgwbUR0Q2hSWktxVHNRMnZZS2YKZHlrS0NMSHpCL3NNaWtXR3F3SFdkMlpQa2RXV0w3U1VwQ3NGUjlJREhUc1NpY2pTaGxLTjlrL2hXVnIvYTZLZwpZdE9hZVcvZFV3eUFNUDA1dVhDNkwycUVzczl4ZThSYnlsRzRrNVdGOHlLbHl2Y0JPZzdjRzJ5Sk1La3RhRnNICmVIdGpTY2laREQ2K3FYMGNsRlNtUDQzTzI0UjZWS01pVTVjbnZid2Y1VnBuaG1RbVppS2ZPdXJwZHcvZWZZRisKTUVPZXVTa0NnWUVBNGszWWV5UWs0WmI3UVg4TWJSWVhvSzdnbytuTWUrZDhmQVNnR2xoMTM0ckZMR2k2bmtyNwpKZ2d3eUZWTHhhUExJNEJSVCtmOEJ4VVFlTlcrSFA5S3B5Rm9yZE5tRlRCdC9yL3JuSE5uVXdpQy9HWlB4SC9rCkhNWW9xS2g4WTRNdGpBMVJmVEo0QTFweEwzdWxqVENkT1ZSajBPSkVKMWtSdCtTbUR1ZDUzM2NDZ1lFQTlIcEkKY3hiUFdnOE1GblVZR0t4c2tZUFRHUEJndWc5WTMyYVVDTkJURlpVSHc2Yzg4WkJjS0pQZHVhV2tDd1ZoQ3lzYgpIaUFLTXlDQjVaRmhyTnJTL1ZoRXlmM09HV25xaTVMcXgxVHJqckVMdGE1dlcwM0QydHJmRU9VSUUwMXFGWTFaCi9QaFFLZzZvalI2eVpKdFk3MFNYQ0lacndpZXBuVkhaL2oyS1hEc0NnWUFXR21aWGVLdEZnVnFmQmdxdnFPVzcKNHZpNzZiejRLUjdtZWdrdEtaQ3h1YnNTWUZSQjI2NzJBdnpJeEZQM1JNMDFkWFg3cVB2YnNUbi9vMWpET2tnUApWTnNGaDAxRUtvdkR3dmovT2VKUW9OY3lVY2ZldUdNT1VHaHVPSzZWaFoxd1BXakZJcVhJSmhCQ0JBQ2licW9jCmpGcUhiMklhdWI5YVI3SFVhTlZsZHdLQmdRQzlubWE1RlRVSVJlbDdOYURWNms1ZTR0OEZWZFBBSEEwellPMXEKbEtJTWVFWElZOXNxQld6bGNDS21UaW9ZL2pnUm9JSnM4QzdaRHRxUlF4eCtKRTlIZm9JRUpSNElxaFRuNHJERQpvRUgvcjZSRWF5SWxzQUE3ckUwZFhuYlArZGhSRlF4NTMrTFZhLzhoVFhEU0JZZUtOU25yeTg2aWpYN0o3V1ZtCkF6ZGdad0tCZ1FDUVphYXdLL2RzUDExVmJ5aEoyMUlCTzhyanB3TTQzSVlJK2hSeE1oTlZGc3p6OWYyWGZ0cTEKVjBhdmxtZ1BmZ0psM2plVUxzRWs2Nmh1cllXZ0Q1TVk3U2wvU1F5K1pzVU9NUm9zc1htcjE1ZW9tRy85a1J2QgoyRFB4aDNkdjB3bTRwRXpJZ1dGTTdMaDdMNmEwMUd0RHRHV2lGbmlDS0hoQWZFWXR5M0Qrc2c9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=
```

### 4. 使本地服务可以使用serviceId访问服务

#### 4.1. 启动Connect服务

```shell
C:\Programs\Developer\ktctl_0.3.7\ktctl.exe connect --namespace qifu-develop --kubeconfig C:\Documents\Workspace\Env\.kube\kubeconfig.yaml
```

- 替换 `ktctl.exe` 路径
- 替换 `kubeconfig` 路径

### 5. 使集群请求可以转发到本地（本地DEBUG）

#### 5.1. 配置discovery配置为服务名

- 由于Nacos里面的服务最后基于ip访问，因此集群内无法通过这种方式来访问本机注册的服务。
- 解决：添加 `spring.cloud.nacos.discovery.ip: ${spring.application.name}`
- 在discovery下注册指定ip为服务名，这样pod在调ip时会走k8s的服务代理到对应的本机ip

#### 5.2. 启动本地服务

- 直接idea启动本地服务，本地服务端口要和映射端口一致

#### 5.3. 启动Mesh服务

```shell
#- 启动mesh
C:\Programs\Developer\ktctl_0.3.7\ktctl.exe mesh qifu-saas-eg --namespace qifu-develop --expose 8933:8933 --versionMark ym-version:liuxiaohua  --kubeconfig C:\Documents\Workspace\Env\.kube\kubeconfig.yaml 
```

- 替换 `ktctl.exe` 路径
- 替换 `kubeconfig` 路径
- 替换 `qifu-saas-eg` 为自己的服务名
- 替换 `expose` 为自己服务的端口
- 替换 `--versionMark ym-version:liuxiaohua` 为自己想要自定义转发的请求头

#### 5.4. 打开浏览器配置ModHeader

##### 添加路由请求头

- 路由请求头要和 `--versionMark` 配置的一致

![](https://picture.texous.cn/blog/20250430151450020.png)

#### 5.5. 进行本地DEBUG和问题排查

### 6. 资源清理（异常关闭或Mesh服务无法重新启动问题）（可选）

- 正常停止 connect 和 mesh 会自动清理资源
- 异常停止资源清理

```shell
C:\Programs\Developer\ktctl_0.3.7\ktctl.exe clean --namespace qifu-develop --kubeconfig C:\Documents\Workspace\Env\.kube\kubeconfig.yaml

#- --dryRun                  只打印要删除的Kubernetes资源名称，不删除资源
#- --thresholdInMinus value  清理至少已失联超过多长时间的Kubernetes资源 (单位：分钟，默认值：15)
#- --localOnly               仅清理本地日志和还原本地路由/DNS配置
```

## 参考文档

- [ktctl 快速使用文档](https://github.com/alibaba/kt-connect/blob/master/docs/zh-cn/guide/quickstart.md)
- [ktctl connect 文档](https://github.com/alibaba/kt-connect/blob/master/docs/zh-cn/cli/connect.md)
- [ktctl mesh 文档](https://github.com/alibaba/kt-connect/blob/master/docs/zh-cn/cli/mesh.md)
- [ktctl clean 文档](https://github.com/alibaba/kt-connect/blob/master/docs/zh-cn/cli/clean.md)
- 别的一些使用文档都可以在上面链接的文件夹中获取
- 一些启动问题参考：https://www.cnblogs.com/zhangs1986/p/17003842.html