云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载本文基于 Telepresence 开源仓库根目录的CLAUDE.md该文件与AGENTS.md内容一致面向贡献者与 AI 助手展开系统讲解从零构建 Telepresence 三个交付产物、运行单元与回归测试、理解七组件架构与 RPC 分层、调试守护进程到最终走完make prepare-release发布流程的完整开发闭环。读完本文你将掌握 Telepresence 仓库的构建命令与环境变量、测试与 Lint 约定、代码生成规则、文档维护规范以及 macOS/Windows 安装包签名发布的完整细节可直接按此手册在本地开展开发与贡献。项目概览Telepresence 解决什么问题Telepresence 是一个 Kubernetes 开发工具它把开发者的本地工作站与 Kubernetes 集群连接起来实现在本地运行服务同时访问集群资源并把集群发往该服务的流量拦截到本地进程的开发模式。这允许开发者跳过镜像构建与重新部署的漫长循环直接在本地 IDE 中调试。仓库内的用户文档遵循 Diátaxis 框架组织详见下文文档规范入门可看 docs/quick-start.md概念说明在 docs/concepts/实操指南在 docs/howtos/完整参考在 docs/reference/。Git 工作流与设计计划规范分支、提交与合并纪律仓库对版本分支的管理非常严格release/v2分支不允许直接提交必须遵循以下约定分支命名始终创建功能分支命名模式为username/topic例如thallgren/fix-dns-resolution。签名提交所有提交必须签名并 sign-off即git commit -s -S。提交信息主题行限制在 72 个字符内不要折行宁可改写得更短。正文默认按 72 字符折行除非需要保留外部原文的精确格式。Lint 前置推送前必须运行make lint并修复全部问题这是硬性要求——CI 运行相同的 linter带 lint 错误的推送只会浪费一次 CI 周期。若make lint发现问题应在对应提交中修复用git commit --fixupsha后接GIT_SEQUENCE_EDITOR: git rebase -i --autosquash --gpg-sign base折叠进原提交然后再推送。合并方式PR 一律用 merge commit 合并绝不 squash 或 rebase。设计计划Design Plans重大改动多文件修改、新特性、重构必须先在docs/plans/topic/下编写书面计划评审通过后才开始实现。计划的定位是评审脚手架而非长期文档它在实现该计划的 PR 的最后一个提交中被删除——到那时计划中的一切都已实现并文档化计划本身不再有存在价值。当前仓库中可看到auth-hardening、quic-enforcing-auth等计划目录见 docs/plans/其中quic-enforcing-auth/findings.md这类文件正是这一流程的产物。构建产物与构建命令三个交付产物Telepresence 开源版由三个构件组成位置构件用途客户端工作站telepresence二进制同一个二进制身兼三职CLI、用户守护进程user daemon、根守护进程root daemon客户端工作站telepresenceDocker 镜像执行telepresence connect --docker时作为用户/根守护进程容器运行集群侧Kubernetestel2Docker 镜像供 traffic-manager 部署使用并作为 traffic-agent sidecar 注入被拦截的 Pod常用构建命令# 设置必需的环境变量 export TELEPRESENCE_VERSIONv2.x.x-alpha.0 # 或使用自动生成的版本 export TELEPRESENCE_REGISTRYlocal # local 用于 Docker Desktop或 ghcr.io/telepresenceio # 构建 telepresence 二进制 make build # 构建 Docker 镜像用于本地 Kubernetes 开发 make client-image # 客户端容器镜像 make tel2-image # Traffic-manager / traffic-agent 镜像 # 本地开发一次性构建全部 make build client-image tel2-image # 安装到系统 make install # 清理构建产物 make clean make clobber # 连同工具链一并移除环境变量的语义在 Makefile 中可以验证这两个变量的真实默认与约束TELEPRESENCE_REGISTRY必需——镜像仓库。local用于基于 Docker 的 Kubernetes 集群ghcr.io/telepresenceio是发布仓库也是 Makefile 中的默认值TELEPRESENCE_REGISTRY ? ghcr.io/telepresenceio。TELEPRESENCE_VERSION可选——编译进二进制与镜像的版本字符串。未设置时由go run ./build-aux/genversion根据CHANGELOG.yml与源码哈希自动生成Makefile 用:确保该值只展开一次避免多次调用 genversion 产生不一致结果。Makefile 还强制校验该值必须以v2.开头否则直接报错中止构建。更多命令可运行make help查看。Windows 构建Windows 构建不直接使用make而是使用build-aux/winmake.bat向脚本传入与 make 相同的参数即可。脚本会在一个配置好 Windows 二进制交叉编译参数的 Docker 容器内运行 make。对应的版本号派生逻辑在 build-aux/winversion.mk详见下文Windows 版本号。测试体系单元测试与回归测试测试命令一览# 单元测试 make check-unit # 回归测试需要 Kubernetes 集群见下述指南 make check-regression # 只跑一个回归区域 / 套件 / 用例——普通的 go test 选择即可 go test ./regression_test -run TestIntercept/HeaderFilter/Test_PathPrefix # Chart 值组合测试无需集群 go test ./regression_test/golden回归测试框架的核心机制regression_test/ 是仓库的集成测试包其设计要点在 regression_test/README.md 中有完整说明在编写或调试这些测试之前必须先读它声明式、记忆化的 fixture 引擎测试声明它需要的资源框架在首次使用时逐个供给、在之后每个声明相同 spec 的测试中复用并在开发模式下收养上一次运行遗留的资源。在热集群上跑单个 scoped 测试只需数秒。惰性访问器与 Mutate 纪律rt.Get/rt.Mutate/rt.Reconnect等 API 规定了获取、变更与重连的语义套件绝不在SetupSuite中供给资源。RTEST_* 环境变量整个框架没有配置文件shell 环境始终优先。关键变量包括RTEST_KUBECONFIG运行所用 kubeconfig、RTEST_REGISTRYmanager/agent 镜像仓库local意味着pullPolicy: Never、RTEST_EXECUTABLE被测客户端二进制默认build-output/bin/telepresence、RTEST_LABELS/RTEST_SKIP_LABELS标签选择、RTEST_FRESH、RTEST_TEARDOWN、RTEST_COVER等。面积Areas与标签测试按 smoke、connect、attach、intercept、install、injector、namespaces、dns、routing、mounts、docker、session、nodeagent、auth、quic 等面积组织compat-core、slow、stress、flaky-retry等标签用于选择平台门控rt.On/rt.Requires单独判断。双向兼容子集CompatRTEST_LABELScompat-core配合RTEST_MANAGER_VERSION或RTEST_CLIENT_VERSION可双向运行兼容子集regression_test/framework/compat/manifest_test.go会在某个 RPC 既未被声明覆盖也未获豁免时让测试失败保证新增 RPC 必然带兼容覆盖。覆盖率TELEPRESENCE_COVER1 make build tel2-image对二进制插桩RTEST_COVER1将GOCOVERDIR指向收集目录最后make rtest-coverage合并为一份报告。黄金文件测试chart 值组合由 regression_test/golden 在无集群情况下覆盖golden/chart_test.go、statefulset_test.go 等。Lint、格式与代码规范Lint 命令# 运行全部 linter make lint # 只运行 Go linter make lint-go # 只运行 protobuf linter make lint-rpc # 只运行文档 linter链接/导航一致性通过 tools/src/docslint术语与陈旧引用通过 Docker 内的 Vale配置在 .vale.ini make lint-docs # 自动修复 lint 问题 make formatGo 侧的 lint 使用运行在 Docker 中的 golangci-lint v2配置在 .golangci.yml。代码注释规范注释必须描述代码现状。禁止写描述变迁的注释代码为什么被移动、取代了什么、与旧版有何不同——读者只看到当前代码这类注释对他们毫无信息量。保持注释简短避免长篇解释。对未导出的内部函数与方法文档注释保持极简只写代码本身无法呈现的内容例如加锁顺序或发布顺序的不变量。设计决策的多段论证属于评审讨论不应进入源码。代码生成# 重新生成 protobuf 与许可证文件 make generate # 只重新生成 protobuf 文件 make protoc # 重新生成文档文件修改 CHANGELOG.yml 之后 make docs-files两个必须遵守的规则修改CHANGELOG.yml后必须运行make docs-files重新生成docs/release-notes.md、docs/release-notes.mdx、docs/variables.yml。docs/reference/cli/ 下的所有文件都是从 Go 源码生成的禁止直接编辑应修改对应 Go 源码后重新生成。许可证文档的更新同样走make generate并把变更提交到DEPENDENCY_LICENSES.md与DEPENDENCIES.md。文档规范Diátaxis 四象限仓库文档 docs/ 遵循 Diátaxis 框架四个象限与目录布局的映射如下Diátaxis 象限取向位置Tutorials教程learningdocs/quick-start.mdHow-to guides指南taskdocs/howtos/Reference参考informationdocs/reference/Explanation解释understandingdocs/concepts/记录新特性时先判断它需要哪些象限——通常是一个 how-to 指南如何启用/使用 一个 reference 页面完整行为、配置与限制并保持两者分离how-to 完成任务并链接到 reference 获取细节reference 穷尽描述而不负责教学。新增页面要加入 docs/doc-links.yml 的导航推送前运行make lint-docs。架构全景七大组件与 RPC 分层主要组件CLI/Clientcmd/telepresence/、pkg/client/cli/——单一二进制同时充当 CLI、用户守护进程与根守护进程命令实现位于pkg/client/cli/cmd/。User Daemonuserdpkg/client/userd/——以用户身份运行管理到 traffic-manager 的连接处理拦截、端口转发与集群通信。Root Daemonrootdpkg/client/rootd/——以提权身份运行管理工作站的虚拟网络接口VIF与 DNS。Traffic Managercmd/traffic/cmd/manager/——运行在 Kubernetes 集群内默认 namespace 为ambassador协调客户端与 traffic-agent 之间的拦截。Traffic Agentcmd/traffic/cmd/agent/——作为 sidecar 注入被拦截的 Pod在 Pod 与本地机器之间路由流量。Agent Initcmd/traffic/cmd/agentinit/——负责在 Pod 中设置 iptables 规则的 init 容器。Docker Network Drivercmd/teleroute/——仅在--docker连接时使用提供让 Telepresence 守护进程容器与其他容器通信的 Docker 网络。关键包pkg/vif/——虚拟网络接口实现pkg/tunnel/——基于 gRPC 的网络流量隧道pkg/dnsproxy/——DNS 解析与代理pkg/agentconfig/——traffic-agent 配置pkg/client/k8s/——Kubernetes 客户端交互pkg/routing/——网络路由逻辑pkg/client/cli/cmd/——CLI 命令每个文件一个命令RPC 定义Protocol buffers 位于 rpc/按职责拆分为独立包rpc/connector/——客户端与 userd 之间的通信rpc/daemon/——客户端与 rootd 之间的通信rpc/manager/——客户端/userd 与 traffic-manager 之间的通信rpc/agent/——traffic-manager 与 traffic-agent 之间的通信CLI 与守护进程的版本对等CLI 绝不与不同版本的 user/root 守护进程通信。pkg/client/cli/connect/version_check.go 中的versionCheck在每一个触达守护进程的命令上强制这一约束宿主机上的 user daemon 与 root daemon 必须与客户端版本完全一致容器化的 user daemon 只需匹配 major.minor.patch预发布仅在rc.X/test.X形态时比较。其直接推论是rpc/connector/与rpc/daemon/的改动永远不需要向后兼容回退——可以假定新 RPC 在守护进程侧必然存在。而rpc/manager/与rpc/agent/则必须考虑向后兼容因为集群侧是独立于客户端升级的。这一机制在源码中有清晰体现versionCheck会依次比较 user daemon 版本、可执行文件路径、root daemon 版本任何不匹配都返回version mismatch...please run telepresence quit -s and reconnect类错误。Helm Charttraffic-manager 的 Helm chart 位于 charts/telepresence-oss/。chart 的values.yaml中apiPort默认 8081是已知名称连接契约的一部分客户端直接拨号traffic-manager-0这个 Pod 名建立会话覆盖它将使客户端退回 discovery 回退路径从而需要clientRbac.legacyAccess见 charts/telepresence-oss/values.yaml。调试与排障三类日志文件日志内容位置connector.loguser daemon 输出traffic-manager 交互、拦截、端口转发macOS~/Library/Logs/telepresence/Linux~/.cache/telepresence/logs/Windows%USERPROFILE%\AppData\Local\logsdaemon.logroot daemon 输出工作站网络变更同上cli.log命令行界面输出同上日志按天轮转用tail -F filename可以无缝跟随轮转中的日志。早期初始化错误的调试如果守护进程在日志文件建立之前的早期初始化阶段失败直接前台运行它们查看 stderr 输出即可。注意--address参数是强制的# 直接运行 user daemon telepresence userd --logfile - --address :8083 # 直接运行 root daemon需要 sudo sudo telepresence rootd --logfile - --address :8084守护进程性能剖析先停掉所有守护进程再带剖析端口重新连接telepresence quit -s telepresence connect --userd-profiling-port 6060 --rootd-profiling-port 6061 # 然后访问 http://localhost:6060/debug/pprof/导出 goroutine 栈向守护进程发送 SIGQUIT 即可把 goroutine 栈转储到其日志文件Windows 上用剖析代替。受限 RBAC 测试仓库记录了用有限权限的 ServiceAccount 测试的方法kubectl apply -f k8s/client_rbac.yaml kubectl get sa telepresence-test-developer -o jsonpath{.secrets[0].name} # 从 secret 取 token 并配置 kubectl kubectl get secret secret-name -o jsonpath{.data.token} | base64 --decode kubectl config set-credentials telepresence-test-developer --token token kubectl config use-context telepresence-test-developer需要说明的是上述流程引用的独立清单在当前仓库快照中未包含实际回归测试中的受限 RBAC 是由测试框架渲染的——telepresence-test-developer这个 ServiceAccount 名在 regression_test/framework/managers/values.go 中定义为TestServiceAccount常量chart 侧则由clientRbac/managerRbac形状与 charts/telepresence-oss/templates/clientRbac/cluster-scope.yaml、connect.yaml、namespace-scope.yaml渲染。关于如何把客户端权限一步步收缩到零 Kubernetes 权限可参考 docs/howtos/client-rbac.md 中从legacyAccess: false、requiredGrant: telepresence到 Direct Connect 的完整阶梯。发布流程创建发布设置TELEPRESENCE_VERSION后运行make prepare-release它会创建两个带注释的 tagvX.Y.Z与rpc/vX.Y.Z并生成一个更新 go.mod 引用的提交。推送 tag 即发布且不可撤销——因此永远不要直接推送 tag只推送分支、为它开 PR并遵循发布技能流程/ship-release驱动发布 PR 的 CI包括必需的regression门禁、在 telepresence.io 仓库创建文档 PR并只在一切变绿后推送 tag。# 测试版标记为预发布不提升为 latest export TELEPRESENCE_VERSIONv2.27.0-test.0 make prepare-release git push origin HEAD $TELEPRESENCE_VERSION rpc/$TELEPRESENCE_VERSION # 发布候选 export TELEPRESENCE_VERSIONv2.27.0-rc.0 make prepare-release git push origin HEAD $TELEPRESENCE_VERSION rpc/$TELEPRESENCE_VERSION # GA 版成为 latest触发 Homebrew 更新 export TELEPRESENCE_VERSIONv2.27.0 make prepare-release git push origin HEAD $TELEPRESENCE_VERSION rpc/$TELEPRESENCE_VERSION版本格式语义vX.Y.Z-test.N——测试版预发布vX.Y.Z-rc.N——发布候选预发布vX.Y.Z——GA 版标记为 latest触发 Homebrew 更新Changelog 约定为即将发布的版本向CHANGELOG.yml添加条目时未发布版本使用date: (TBD)make prepare-release会在TELEPRESENCE_VERSION是 GA 版本如v2.27.0时写入真实日期修改CHANGELOG.yml后运行make docs-files重新生成文档。macOS 安装包签名与公证macOS.pkg安装包需要签名并公证才能通过 Gatekeeper 验证签名凭据由受保护的 GitHub Environment 保管。build-macos-pkg任务使用macos-signing环境需在仓库设置中创建并配置以下 secrets务必放在环境级而非仓库级Secret 名说明MACOS_CERTIFICATE_P12Base64 编码的 P12 文件包含 Application 与 Developer ID Installer 两枚证书MACOS_CERTIFICATE_PASSWORDP12 文件密码MACOS_SIGN_APPLICATIONDeveloper ID Application 证书名如Developer ID Application: Your Name (TEAMID)MACOS_SIGN_INSTALLERDeveloper ID Installer 证书名MACOS_NOTARIZE_APPLE_ID用于公证的 Apple ID 邮箱MACOS_NOTARIZE_TEAM_IDApple Developer Team IDMACOS_NOTARIZE_PASSWORD公证用的 App 专用密码发布 tag 被推送后的工作流所有平台二进制Linux/Windows/macOS立即构建Linux.deb/.rpm与 Windows.exe安装包随即构建并随发布一同发布build-macos-pkg任务等待必需评审人批准后才构建签名.pkg并补传到发布。这一设计保证紧急发布不依赖签名审批人二进制与 Linux/Windows 安装包先行发布、签名凭据经显式审批后才暴露、签名包随后补入。若环境未配置或从未批准发布仍会包含 macOS 独立二进制只是没有.pkg安装包。本地预演签名流程配置好环境变量后export MACOS_SIGN_APPLICATIONDeveloper ID Application: Your Name (TEAMID) export MACOS_SIGN_INSTALLERDeveloper ID Installer: Your Name (TEAMID) export MACOS_NOTARIZE_APPLE_IDyouremail.com export MACOS_NOTARIZE_TEAM_IDABCD123456 export MACOS_NOTARIZE_PASSWORDxxxx-xxxx-xxxx-xxxx cd build-aux/pkg-installer VERSION2.26.0 ./build-pkg.sh # 校验签名 pkgutil --check-signature ../../build-output/Telepresence.pkg spctl --assess --type install ../../build-output/Telepresence.pkgWindows 版本号Windows 需要四段式数字版本。build-aux/winversion.mk 从TELEPRESENCE_VERSION派生GA 版为X.Y.Z.100预发布第 N 版为X.Y.Z.N如v2.32.0-rc.4→2.32.0.4。它同时是 Windows 可执行文件的 file version 与 MSI 的 product version因此每个预发布都会替换前一个可执行文件内的 product version 字符串仍保留完整 semver。Windows 安装包签名Windows 的telepresence.exe与两个MainPackage.msiamd64/arm64发布为telepresence-windows-amd64.msi与telepresence-windows-arm64.msi通过 SignPath Foundation 的开源免费代码签名计划做 Authenticode 签名。签名运行在受保护的 GitHub Environment 之后仓库需创建windows-signing环境、配置 secretSIGNPATH_API_TOKEN与变量SIGNPATH_ORGANIZATION_ID、SIGNPATH_PROJECT_SLUGSIGNPATH_ORGANIZATION_ID未设置时签名任务整体跳过工作流在门户配置好之前是空操作。发布 tag 推送后所有平台二进制与两个未签名 MSI 立即构建发布sign-windows等待评审人批准后签署core构件两个独立 exe 与两个 MSI其中 MSI 内嵌的 exe 会被深度签名签名后的.zip与.msi通过gh release upload --clobber替换未签名版本并由make verify-signatures把关上传。在等待审批人的场景下可对预发布 tag 用test-signing策略手动派发工作流gh workflow run sign-windows.yaml -f tagv2.32.0-rc.2 -f signing-policytest-signing。验证签名可用make verify-signatures仅 Windows或对单个文件使用Get-AuthenticodeSignature详见 docs/install/client.md。给贡献者的快速核对清单功能分支命名username/topic提交全部git commit -s -S主题 ≤ 72 字符。推送前make lint必须零告警必要时用--fixup autosquash 折叠修复。改动 protobuf 后make protoc改动CHANGELOG.yml后make docs-files不要手改 docs/reference/cli/ 下的生成文件。新功能先在 docs/plans/ 写计划评审落地后由实现 PR 的最后一个提交删除计划。新增文档页面按 Diátaxis 分好象限并登记进 docs/doc-links.yml。涉及rpc/manager/或rpc/agent/的改动必须考虑集群侧独立升级的向后兼容并补齐compat-core覆盖。走发布流程时只推分支开 PR绝不直接推 tag——发布不可撤销。赞分享云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载相关推荐MediaGo 开发者指南从仓库架构到多端构建的完整上手手册MediaGo 开发者指南从仓库架构到多端构建的完整上手手册 MediaGo 是一个基于 pnpm monorepo 组织的跨平台视频下载工具核心能力是 m音视频桌面应用后端Angular CLI 源码仓库开发者指南从本地构建、调试到测试的完整工作流Angular CLI 源码仓库开发者指南从本地构建、调试到测试的完整工作流 本篇指南围绕当前开源仓库angular cli即 Angular CLI 与CLI开发工具前端构建构建工具代码生成前端PostgresApp 构建中的 create-dmg 开发者笔记仓库结构、回归测试与版本管理实践PostgresApp 构建中的 create dmg 开发者笔记仓库结构、回归测试与版本管理实践 导读 本文基于 PostgresApp 仓库内 vendo数据库桌面应用上一篇Crawl4AI 自适应爬取AdaptiveCrawler实战三层评分、统计/嵌入双策略与从查询到自动停止的完整机制下一篇Gemma 4 26B A4B QAT对齐量化未来路线图技术创新与发展方向创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考