Telepresence：Kubernetes 微服务的快速高效本地开发工具

xuxiaowei · January 1, 2026, 5:55pm

说明

在 Kubernetes 环境下，Telepresence 处理网络的核心原理是：在您的本地开发机和远端 Kubernetes 集群之间，
建立一条双向的网络隧道，并拦截（Intercept）特定 Deployment 的流量，将其透明地重定向到本地环境。
这能让您用本地进程完全“替代”集群中的 Deployment 进行调试。
核心目标：打破本地与集群的隔阂
- 在 Kubernetes 中，服务在独立的 Pod 和网络命名空间中运行。
  传统调试需要反复构建镜像、推送仓库、部署 Pod，流程漫长。
  Telepresence 的核心思想是让本地服务“无缝嵌入”到集群网络，使其能直接访问集群内的其他服务（如数据库、Redis），
  同时让集群内其他组件也能像调用原服务一样调用您的本地进程。
两大核心工作原理
1. 建立双向网络隧道
  - Telepresence 会在您的本地电脑上启动一个轻量级的客户端，
    同时在 Kubernetes 集群中部署一个名为 traffic-manager 的 Pod 作为服务端。
  - 两者之间会建立一个加密的、双向的 VPN 隧道（或类似通道）。这个隧道：
    - 为本地服务赋予一个集群内的 IP 地址：让本地进程在集群网络内“有身份”。
    - 将集群的 DNS 和服务发现机制扩展到本地：
      本地服务能直接通过服务名（如 my-database.default.svc.cluster.local）访问集群内的其他服务。
2. 流量拦截与重定向
  - 当您想用本地代码调试一个名为 user-service 的 K8s 服务时，Telepresence 会执行“拦截”。
  - 它会修改 user-service 的 Kubernetes 资源
    （通常是修改其 Deployment，为其 Pod 注入一个边车容器 traffic-agent，或直接修改 Service 的端点，
    实际命令使用 Deployment 名字），
    将原本应该发送给该服务 Pod 的流量，通过隧道重定向到您的本地进程。
  - 同时，它可能也会将来自本地进程的出站流量导回集群网络。

文档

链接	说明
GitHub - telepresenceio/telepresence: Local development against a remote Kubernetes or OpenShift cluster	GitHub 源码
https://telepresence.io	文档官网
Quick start \| Telepresence	项目说明
Install client \| Telepresence	安装客户端
Install Traffic Manager \| Telepresence	安装/卸载边车容器管理器

安装客户端

Linux

# Linux AMD github.com
sudo curl -fL https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-amd64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Linux ARM github.com
sudo curl -fL https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-arm64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Linux AMD ghfast.top
sudo curl -fL https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-amd64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Linux ARM ghfast.top
sudo curl -fL https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-arm64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

Mac

brew

brew install telepresenceio/telepresence/telepresence-oss

download

# Apple ARM github.com
sudo rm -f /usr/local/bin/telepresence
sudo curl -fL https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-arm64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Apple AMD github.com
sudo curl -fL https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-amd64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Apple ARM ghfast.top
sudo rm -f /usr/local/bin/telepresence
sudo curl -fL https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-arm64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

# Apple AMD ghfast.top
sudo curl -fL https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-amd64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

Windows

# AMD github.com
# 以管理员身份在 PowerShell 中执行以下命令：

# 1. 下载包含 telepresence.exe 及其依赖的最新 Windows 压缩包（~60 MB）：
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-windows-amd64.zip -OutFile telepresence.zip

# 2. 将 telepresence.zip 文件解压到目标目录，然后移除zip文件：
Expand-Archive -Path telepresence.zip -DestinationPath telepresenceInstaller/telepresence
Remove-Item 'telepresence.zip'
cd telepresenceInstaller/telepresence

# 3. 运行 install-telepresence.ps1 来安装 telepresence 的依赖。
# 默认情况下，它会将远程存在安装到 C:\telepresence，但你可以通过输入-路径 C:\my\custom\path 来指定自定义路径
powershell.exe -ExecutionPolicy bypass -c " . '.\install-telepresence.ps1';"

# 4. 移除解压目录：
cd ../..
Remove-Item telepresenceInstaller -Recurse -Confirm:$false -Force

# 5. 现在已经安装了远程呈现功能，你可以在PowerShell中使用远程呈现命令。

# ARM github.com
# 以管理员身份在 PowerShell 中执行以下命令：

# 1. 下载包含 telepresence.exe 及其依赖的最新 Windows 压缩包（~60 MB）：
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-windows-arm64.zip -OutFile telepresence.zip

# 2. 将 telepresence.zip 文件解压到目标目录，然后移除zip文件：
Expand-Archive -Path telepresence.zip -DestinationPath telepresenceInstaller/telepresence
Remove-Item 'telepresence.zip'
cd telepresenceInstaller/telepresence

# 3. 运行 install-telepresence.ps1 来安装 telepresence 的依赖。
# 默认情况下，它会将远程存在安装到 C:\telepresence，但你可以通过输入-路径 C:\my\custom\path 来指定自定义路径
powershell.exe -ExecutionPolicy bypass -c " . '.\install-telepresence.ps1';"

# 4. 移除解压目录：
cd ../..
Remove-Item telepresenceInstaller -Recurse -Confirm:$false -Force

# 5. 现在已经安装了远程呈现功能，你可以在PowerShell中使用远程呈现命令。

# AMD ghfast.top
# 以管理员身份在 PowerShell 中执行以下命令：

# 1. 下载包含 telepresence.exe 及其依赖的最新 Windows 压缩包（~60 MB）：
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-windows-amd64.zip -OutFile telepresence.zip

# 2. 将 telepresence.zip 文件解压到目标目录，然后移除zip文件：
Expand-Archive -Path telepresence.zip -DestinationPath telepresenceInstaller/telepresence
Remove-Item 'telepresence.zip'
cd telepresenceInstaller/telepresence

# 3. 运行 install-telepresence.ps1 来安装 telepresence 的依赖。
# 默认情况下，它会将远程存在安装到 C:\telepresence，但你可以通过输入-路径 C:\my\custom\path 来指定自定义路径
powershell.exe -ExecutionPolicy bypass -c " . '.\install-telepresence.ps1';"

# 4. 移除解压目录：
cd ../..
Remove-Item telepresenceInstaller -Recurse -Confirm:$false -Force

# 5. 现在已经安装了远程呈现功能，你可以在PowerShell中使用远程呈现命令。

# ARM ghfast.top
# 以管理员身份在 PowerShell 中执行以下命令：

# 1. 下载包含 telepresence.exe 及其依赖的最新 Windows 压缩包（~60 MB）：
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest https://ghfast.top/https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-windows-arm64.zip -OutFile telepresence.zip

# 2. 将 telepresence.zip 文件解压到目标目录，然后移除zip文件：
Expand-Archive -Path telepresence.zip -DestinationPath telepresenceInstaller/telepresence
Remove-Item 'telepresence.zip'
cd telepresenceInstaller/telepresence

# 3. 运行 install-telepresence.ps1 来安装 telepresence 的依赖。
# 默认情况下，它会将远程存在安装到 C:\telepresence，但你可以通过输入-路径 C:\my\custom\path 来指定自定义路径
powershell.exe -ExecutionPolicy bypass -c " . '.\install-telepresence.ps1';"

# 4. 移除解压目录：
cd ../..
Remove-Item telepresenceInstaller -Recurse -Confirm:$false -Force

# 5. 现在已经安装了远程呈现功能，你可以在PowerShell中使用远程呈现命令。

集群初始化 Telepresence

# k8s.gcr.io
kubectl create deploy hello --image=k8s.gcr.io/echoserver:1.10
kubectl expose deploy hello --port 80 --target-port 8080
kubectl get ns,svc,deploy,po

# 国内作者镜像
kubectl create deploy hello --image=registry.cn-qingdao.aliyuncs.com/xuxiaoweicomcn/echoserver:1.10
kubectl expose deploy hello --port 80 --target-port 8080
kubectl get ns,svc,deploy,po

# 查看版本
telepresence version

# 查看版本：未连接 Kubernetes 集群
root@k8s-sh:~# telepresence version
OSS Client : v2.25.1
Root Daemon: not running
User Daemon: not running
root@k8s-sh:~#

# 查看版本：已连接 Kubernetes 集群
root@k8s-sh:~# telepresence version
OSS Client         : v2.25.1
OSS User Daemon    : v2.25.1
OSS Traffic Manager: v2.25.1
Traffic Agent      : ghcr.io/telepresenceio/tel2:2.25.1
root@k8s-sh:~#

安装边车容器管理器

安装边车容器管理器时，创建 ambassador 命名空间
安装边车容器管理器时，要拉取镜像：ghcr.io/telepresenceio/tel2:x.y.z，在 ambassador 命名空间创建 traffic-manager
Deployment
卸载边车容器管理器时，要拉取镜像：docker.io/curlimages/curl:x.y.z，在 ambassador 命名空间创建 uninstall-agents
Job
如果要使用 telepresence connect，必须确保 traffic-manager Deployment Pod 正常
如果拉取 ghcr.io/telepresenceio/tel2:x.y.z 等镜像失败，可以使用下列方式处理：
1. 离线解决方案：找到 ghcr.io/telepresenceio/tel2:x.y.z 等镜像的 tar 包，
  使用 ctr -n=k8s.io i import tar包路径 导入镜像
2. 在线解决方案：找到 ghcr.io/telepresenceio/tel2:x.y.z 等镜像的其他能拉取的地址
  （如：registry.cn-qingdao.aliyuncs.com/xuxiaoweicomcn/telepresenceio-tel2:2.25.1，
  更多国内地址），
  使用 ctr -n=k8s.io i import 镜像地址 拉取镜像成功后，
  再使用 ctr -n=k8s.io i tag 镜像地址 ghcr.io/telepresenceio/tel2:x.y.z 重打标签，
  然后等待 Deployment 恢复（或者使用 kubectl -n 命名空间 rollout restart deployment Deployment名称 手动触发滚动重启一下）即可

# 安装
telepresence helm install

# 卸载
telepresence helm uninstall

Telepresence 命令

执行 telepresence connect 等命令时，请确保在 $HOME/.kube/config 正确配置了 Kubernetes KUBECONFIG
1. 或者在执行命令时，使用 --kubeconfig 指定 KUBECONFIG 的路径

# 查看版本
telepresence version

# 查看版本：未连接
root@k8s-sh:~# telepresence version
OSS Client : v2.25.1
Root Daemon: not running
User Daemon: not running
root@k8s-sh:~#

# 查看版本：已连接
root@k8s-sh:~# telepresence version
OSS Client         : v2.25.1
OSS User Daemon    : v2.25.1
OSS Traffic Manager: v2.25.1
Traffic Agent      : ghcr.io/telepresenceio/tel2:2.25.1
root@k8s-sh:~#

# 查看状态
telepresence status

# 查看状态：未连接
root@k8s-sh:~# telepresence status
User Daemon: Not running
Root Daemon: Not running
Traffic Manager: Not connected
root@k8s-sh:~#

# 查看状态：已连接
root@k8s-sh:~# telepresence status
OSS User Daemon: Running
  Version           : 2.25.1
  Executable        : /usr/local/bin/telepresence
  Install ID        : 854e1be9-635d-4925-8d78-903d299152d7
  Status            : Connected
  Kubernetes server : https://172.25.25.201:6443
  Kubernetes context: kubernetes-admin@kubernetes
  Namespace         : default
  Manager namespace : ambassador
  Mapped namespaces : [aaaa ambassador default ingress-nginx k8s-sh kube-public kubernetes-cloud]
OSS User Daemon: Running
  Version: v2.25.1
  DNS    : 
    Local addresses : [127.0.0.1:52893]
    VIF Address     : 172.16.0.2:53
    Exclude suffixes: [.com .io .net .org .ru]
    Include suffixes: []
    Timeout         : 4s
  Subnets: (1 subnets)
    - 172.16.0.1/30
OSS Traffic Manager: Connected
  Version      : v2.25.1
  Traffic Agent: ghcr.io/telepresenceio/tel2:2.25.1
root@k8s-sh:~#

# 连接
telepresence connect

# 指定命名空间
# telepresence connect -n 命名空间

# 连接：默认命名空间
 xuxiaowei@172  ~  telepresence connect                    
 ✔ Connected to context kubernetes-admin@kubernetes, namespace default (https://172.25.25.201:6443)                                                                                                 3.4s 
 xuxiaowei@172  ~ 

# 连接：指定命名空间
 xuxiaowei@172  ~  telepresence connect -n kubernetes-cloud    
 ✔ Connected to context kubernetes-admin@kubernetes, namespace kubernetes-cloud (https://172.25.25.201:6443)                                                                                        6.7s 
 xuxiaowei@172  ~ 

# 将 Kubernetes 集群中名为 user 的 Deployment 流量拦截到本地开发环境
# 转发的服务名 所在的命名空间 与要 连接的命名空间 相同
# user：Deployment 名称
# --port=本机端口:容器端口：容器端口写错会提示：✘ connector.CreateIntercept: Deployment Deployment名称.命名空间 has no interceptable port matching port 端口号
# 访问 Kubernetes 的 user Pod 的 8080，流量会被拦截转发到本机的 8082 端口
telepresence intercept user --port=8082:8080

# 转发结果
 xuxiaowei@172  ~  telepresence intercept user --port=8082:8080
 ✔ Intercepted
   Using Deployment user
      Intercept name    : user
      State             : ACTIVE
      Workload kind     : Deployment
      Intercepting      : 192.168.231.207 -> 127.0.0.1
          8080 -> 8082 TCP
      Volume Mount Error: remote volume mounts are disabled: sshfs is not installed on your local machine
 xuxiaowei@172  ~ 

# 转发列表
telepresence list

# 转发列表：示例
 xuxiaowei@172  ~  telepresence list                           
deployment gateway: ready to engage (traffic-agent not yet installed)
deployment system : ready to engage (traffic-agent not yet installed)
deployment user   : intercepted
   Intercept name: user
   State         : ACTIVE
   Workload kind : Deployment
   Intercepting  : 192.168.231.207 -> 127.0.0.1
       8080 -> 8082 TCP
 xuxiaowei@172  ~ 

# 删除现有拦截：退出代理
# 不会删除边车容器：
# 1. 避免重新创建 pod 影响 Deployment 使用
# 2. 方便下次快速代理
# 3. 如需彻底删除所有边车容器，请运行：kubectl -n 命名空间 rollout restart deployment Deployment名称
telepresence leave Deployment名称

# 退出
telepresence quit -s