云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载telepresence compose up是 Telepresence 提供的docker compose up增强版本它在启动本地容器之前会先解析 Compose 文件中的x-tele扩展自动建立到远程 Kubernetes 集群的连接并把本地服务以 proxy、intercept、replace、ingest、wiretap 等方式接入集群随后才把改写后的 Compose 规范交给 Docker Compose 执行。读完本文你将掌握该命令的完整参数体系、x-tele扩展的配置方法以及从源码层面理解连接—附加—改写—启动的完整执行链路能够在本地 Docker Compose 与远程集群服务之间搭建混合开发环境。本文以 docs/reference/cli/telepresence_compose_up.md 的命令参考为主体并结合 docs/reference/compose.mdx-tele扩展规范、docs/howtos/docker-compose.md实战走查以及pkg/client/cli/docker/compose/下的源码实现进行纵深解读。命令概述与适用场景telepresence compose up的行为与docker compose up基本一致解析 Compose 配置、构建并拉取镜像、创建并启动容器、附加日志输出。区别在于它额外完成三件事发现 Compose 文件或其 override 文件中的x-tele顶层扩展与服务级扩展依据扩展建立到集群的 Telepresence 连接connection并为每个扩展服务建立附件attachment在内存中改写 Compose 规范——注入网络、挂载卷、环境变量、DNS 配置必要时移除或替换部分服务——再把最终规范写入临时 Compose 文件并交给docker compose执行。典型场景是本地有一组与集群中服务镜像的 Compose 服务希望本地的web访问集群中的voting用proxy扩展或者让集群中的流量打到本地容器用replace、intercept扩展同时共享远程容器环境变量与卷配合mounts策略。这类混合开发模式可参考 docs/howtos/docker-compose.md 中的 Emojivoto 完整走查。语法与参数总览telepresence compose up [flags] [services]位置参数[services]用于指定要启动的 Compose 服务省略时启动全部服务。参数分为三组Compose flags作用于整个 compose 项目的通用选项、Compose up flagsup子命令专属选项和Global flagsTelepresence 客户端全局选项。Compose flags项目级选项参数类型说明--env-file stringArraystringArray可选的环境文件可重复指定多个文件按顺序加载-f, --file stringArraystringArrayCompose 配置文件可重复指定对应 Docker Compose 的-f--profile stringArraystringArray要启用的 Compose profile可重复指定--project-directory stringstring指定备用的工作目录默认取第一个指定 Compose 文件所在目录--project-name stringstring项目名称覆盖默认的目录名派生的项目名Compose up flagsup 子命令选项参数类型说明--abort-on-container-exitbool任一容器停止时停止所有容器与-d不兼容--abort-on-container-failurebool任一容器以失败退出时停止所有容器与-d不兼容--always-recreate-depsbool重建依赖容器与--no-recreate不兼容--attach stringArraystringArray只附加到指定服务的日志与--attach-dependencies不兼容--attach-dependenciesbool自动附加依赖服务的日志输出--buildbool启动容器前先构建镜像-d, --detachbool后台分离模式运行容器--exit-code-from stringstring返回指定服务容器的退出码隐含--abort-on-container-exit--force-recreatebool即使配置与镜像未变化也强制重建容器--menubool附加运行时启用交互快捷键与--detach不兼容也可通过环境变量COMPOSE_MENU开关--no-attach stringArraystringArray不附加不流式输出日志到指定服务--no-buildbool即使构建策略要求也不构建镜像--no-colorbool输出单色monochrome--no-depsbool不启动关联链接服务--no-log-prefixbool日志中不打印服务名前缀--no-recreatebool容器已存在时不重建与--force-recreate不兼容--no-startbool创建服务但不启动--pull stringstring运行前拉取镜像的策略always、missing、never默认policy即由 Compose 文件决定--quiet-buildbool抑制构建输出--quiet-pullbool拉取镜像时不打印进度信息--remove-orphansbool移除 Compose 文件中未定义服务对应的容器-V, --renew-anon-volumesbool重建匿名卷而不是复用旧容器中的数据--scale uint32uint32将SERVICE扩展到NUM个实例覆盖 Compose 文件中的 scale 设置-t, --timeout intint附加模式或容器已在运行时容器关闭所用的超时秒数--timestampsbool日志中显示时间戳--waitbool等待服务处于 running/healthy 状态隐含分离模式--wait-timeout intint等待项目进入 running/healthy 的最大秒数-w, --watchbool监听源码变化并自动重建/刷新容器-y, --yesbool对所有提示假设yes以非交互方式运行Global flagsTelepresence 全局选项参数类型说明--config stringstringTelepresence 配置文件路径--format stringstring输出格式json、yaml、json-stream、default默认default--progress stringstring进度输出类型auto、tty、plain、json、quiet默认auto--use stringstring唯一标识 daemon 容器的匹配表达式需要特别说明的是--format与--progress由全局层注入其中--progress的值会被telepresence compose的父命令透传给底层 Docker Compose见下文源码分析并在auto之外被显式追加到最终生成的命令行中。为什么telepresence compose up不同于docker compose upx-tele扩展机制x-tele扩展可以放在 Compose 文件的顶层也可以放在某个服务下Docker Compose 自身会忽略它但telepresence compose会处理它。顶层扩展结构如下x-tele: connections: - namespace: name services: some-name: x-tele: type: extension type ...顶层x-tele扩展包含两类配置完整字段见 docs/reference/compose.mdconnections连接配置列表。当列表为空时会基于当前 Kubernetes 上下文自动创建一个默认连接。每个连接可配置name、namespace、also-proxy额外代理的 CIDR、never-proxy永不代理的 CIDR、manager-namespaceTraffic Manager 所在命名空间默认取客户端配置或ambassador、mapped-namespaces映射为 DNS 域的命名空间。mounts卷挂载策略列表控制扩展服务所共享的远程卷如何处理。每个条目含volume卷名与volumePattern互斥、volumePattern匹配一个或多个卷名的正则与volume互斥、policy取值local、ignore、remote、remoteReadOnly默认跟随 traffic-agent 对该卷的策略。其中local表示不修改 Compose 卷、ignore表示不修改且远程卷不被 traffic-agent 共享、remote表示改为挂载远程卷无只读限制、remoteReadOnly表示以只读方式挂载远程卷。服务级x-tele扩展必须有type字段支持connect、proxy、ingest、intercept、replace、wiretap六种类型分别对应telepresence connect、拦截远程服务、telepresence ingest、telepresence intercept、telepresence replace、telepresence wiretap等命令的语义。所有类型都隐含connect即注入 teleroute 网络让本地容器能访问集群 DNS 与路由。从源码看命令的生成方式telepresence compose up的参数并不是手写的 Cobra 命令而是从嵌入的 Docker Compose CLI 定义动态生成的dc-cli.json 中第 1299–1458 行定义了up子命令包括usagedocker compose up [OPTIONS] [SERVICE...]、descriptionCreate and start containers以及上表列出的全部 flag 元数据名称、shorthand、类型、描述。config.go 中的GenerateSubCommands遍历dockerComposeCLI.Subcommands为每个子命令调用subCommand生成对应的 Cobra 命令init()中通过//go:embed dc-cli.json把这份定义嵌入二进制。config.go 的addComposeFlags把--file、--env-file、--project-directory、--project-name、--profile注册为父命令级 flags即文档中的 Compose flags并通过flags.WithFlagSets注入到 usage 上下文保证 help 输出与文档一致。命令解析在遇到第一个非 flag 参数服务名时停止cmdFlags.SetInterspersed(false)从而保证telepresence compose up svc后续参数不会被误解析为 flag。--dry-run虽然在 Docker Compose 中存在但 Telepresence 明确不支持因为intercept、replace、ingest、wiretap都会安装 traffic-agent无法真正干跑。源码 config.go 会直接返回错误--dry-run is not supported。执行链路连接、附加、改写、启动当 Compose 文件中存在x-tele扩展服务时up的执行流程如下对应 config.go 的run方法连接Connect为每个扩展服务解析其connection配置并建立到集群的连接。up与build、create、start一样mustBeConnected为false——如果 daemon 未运行会直接退化为普通docker compose命令让其产生应有的错误输出。附加Attach并行log.NewGroup协程组为每个扩展服务执行tr.attach根据扩展类型激活附件proxy 服务被代理、replace 服务被替换等并等待全部附件就绪后才继续。改写TransformapplyAttachments在 compose-go 解析出的项目对象上执行修改——删除被 proxy 替换的服务、为 replace/intercept 服务注入代理依赖与远程挂载卷、注入 DNS 与搜索域配置等见 transform.go。生成最终 Compose 文件createConfigFile把改写后的项目序列化为 YAML写入临时文件tpc-*.yaml并把该文件路径与 telemount 卷名保存到 daemon 信息中——这样docker compose down才能在连接断开时正确清理网络与卷见 transform.go。启动Run调用本机 Docker 可执行文件执行compose up见runCompose。其中runAttachedUptransform.go针对前台未加-d模式做了特殊处理它不直接杀死docker compose up进程而是在父上下文被取消时另起一个compose stop进程停掉容器。源码注释说明了原因直接中断docker compose up只会让容器detach后继续运行而其中部分容器可能依赖即将结束的附件在 Windows 上这种行为甚至不会停止容器。这也是up前台运行与--abort-on-container-exit、--timeout等参数配合时行为可靠的原因。网络自动避让IPAM 子网预分配configureDefaultNetworktransform.go会在项目没有显式配置 IPAM 时汇总所有连接所携带的集群子网通过teleroute.FindNonConflictingSubnet预计算一个不与集群子网冲突的子网写入default网络的ipam.config。这避免了 Docker 自动分配的子网 CIDR 与 Kubernetes 集群子网重叠导致路由冲突——这是up在混合网络场景下能稳定工作的底层保证之一。实战用telepresence compose up代理集群服务下面以 Emojivoto 示例假设已在集群emojivoto命名空间部署Traffic Manager 安装方法见 docs/install/manager.md演示proxy扩展。仓库自带的示例 override 文件可见 examples/compose/proxy-voting.override.yaml 与 examples/compose/proxy-web.override.yaml。假设原compose.yaml包含web、vote-bot、emoji、voting四个服务其中voting本地运行。现在不想本地跑voting希望它由集群中的同名服务代替只需在旁边新增compose.override.yamlDocker Compose 会自动合并x-tele: connections: - namespace: emojivoto services: voting: x-tele: type: proxy然后运行$ telepresence compose up ✔ Connected to context minikube, namespace emojivoto (https://192.168.49.2:8443) 2.4s ✔ Proxied service voting 0.0s [] Running 4/4 ✔ Network emojivoto_default Created 0.1s ✔ Container emojivoto-emoji-1 Created 0.0s ✔ Container emojivoto-web-1 Created 0.0s ✔ Container emojivoto-vote-bot-1 Created 0.0s Attaching to emoji-1, vote-bot-1, web-1 ...注意输出中的✔ Proxied service voting本地voting容器不再启动web、vote-bot对voting:8080的解析被改写为指向集群中的服务而vote-bot依然在投票说明流量确实到达了集群里的voting。如果要在浏览器里通过localhost:8080访问集群中的web服务则需指定端口映射集群中web用 80 端口本地 Compose 暴露 8080x-tele: connections: - namespace: emojivoto services: web: x-tele: type: proxy ports: - 8080:80再执行telepresence compose up后浏览器访问localhost:8080即可看到与集群一致的内容。关于连接名当顶层x-tele只声明一个连接时服务级扩展的connection字段可以省略多个连接时则必须显式指定。connections列表为空时Telepresence 会使用当前 Kubernetes 上下文自动创建默认连接对应源码 config.go 中的defaultConnectionConfig其Namespace默认为default实际生效值来自当前上下文。实战反向替换集群服务replace 扩展replace与proxy方向相反让集群中的服务把流量转发到本地 Compose 容器。仓库自带示例见 examples/compose/replace.override.yaml。沿用 Emojivoto让集群中的web、vote-bot使用本地运行的emoji、votingx-tele: connections: - namespace: emojivoto services: emoji: x-tele: type: replace voting: x-tele: type: replace vote-bot: profiles: - notEnabledvote-bot的profiles: [notEnabled]用于禁用本地 vote-bot让集群里的 vote-bot 保持活跃便于观察。运行$ telepresence compose up ✔ Connected to context minikube, namespace emojivoto (https://192.168.49.2:8443) 2.8s [] Attaching 2/2 ✔ emoji Replaced service emoji 2.0s ✔ voting Replaced service voting 1.6s [] Running 4/4 ...集群中voting、emoji的 Pod 被替换为 traffic-agent把流量转发给本地容器。可用以下命令验证集群 Pod 中只剩 traffic-agent 容器$ kubectl -n emojivoto get pod -l appvoting -o jsonpath{.items.*.spec.containers.*.name} traffic-agent一个值得注意的细节是投票计数不会从零开始而是与集群中voting服务的计数保持同步——因为replace扩展默认把本地data卷替换为远程容器卷的远程挂载。如不希望如此可在顶层x-tele中配置mounts策略x-tele: connections: - namespace: emojivoto mounts: - volume: data policy: local生命周期与其他状态的关系telepresence compose up只是telepresence compose生命周期的一部分各命令间的状态转换如下详见 docs/reference/compose.md 与 docs/reference/state-manifest.md命令行为telepresence compose up确保扩展服务处于正确状态连接、附加、启动一体完成telepresence compose create与up类似但不启动容器全部容器创建完成后结束附件telepresence compose stop结束附件但保持 Telepresence 连接——现有容器仍依赖该连接支撑的 teleroute 网络telepresence compose down结束附件、终止网络并退出 Telepresencetelepresence config检测项目是否已启动已启动则输出扩展后的项目文件否则输出原项目文件的规范形式telepresence quit检测是否有telepresence compose在运行若有则代为执行telepresence compose down从源码看create、stop、up未分离模式都会在命令结束时调用tr.detach撤销附件config.go而down还会逐个断开连接。up单独承担了启动即附加、退出即清理的角色是日常开发中最常用的入口。使用限制与注意事项首次调用必须包含全部扩展服务当存在已有 Compose 项目且本次只选择部分服务时若这些服务依赖某个未包含的扩展服务提供的卷会报错volume %q is provided extended service %q, but that service is not included而首次compose up/compose create若不包含全部扩展服务会返回the initial invocation of compose up or compose create must include all extended services见 transform.go 与 transform.go。--dry-run不可用telepresence compose up --dry-run会报错因为附件机制必须真实连接到集群。--force-recreate会重建 Compose 文件createConfigFile在forceRecreate时会把改写后的规范重新写入已保存的 Compose 文件而非复用旧文件以同步 telemount 卷集合的变化。分离模式与附加模式差异-d/--detach走runCompose直接透传前台模式走runAttachedUp在取消时由独立进程执行compose stop避免容器残留。网络冲突自动规避若 Compose 文件显式配置了default网络的 IPAMTelepresence 不会覆盖否则会自动为default网络预分配与集群子网不冲突的 IPAM 子网。小结telepresence compose up不是docker compose up的简单包装而是一套先接集群、再改规范、后启动容器的编排入口参数层面完整继承了 Docker Compose 的up语义构建、拉取、重建、伸缩、等待、watch 等 29 个选项均可使用功能层面通过x-tele扩展把 proxy、intercept、replace、ingest、wiretap 六种集群接入能力注入本地 Compose 服务。无论是本地服务代理集群服务还是集群流量反向打到本地容器都可以用这一条命令完成从连接到启动的全流程并借助自动 IPAM 避让与挂载策略确保混合网络环境下的稳定性。如需继续深入可阅读完整的x-tele字段参考 docs/reference/compose.md逐步走查指南 docs/howtos/docker-compose.md命令生成的源码实现 pkg/client/cli/docker/compose/config.go 与项目改写逻辑 pkg/client/cli/docker/compose/transform.go仓库内可直接参考的示例 examples/compose/proxy-voting.override.yaml、examples/compose/proxy-web.override.yaml 与 examples/compose/replace.override.yaml。赞分享云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载相关推荐Docker Compose docker compose up 命令完全指南构建、创建、启动与重建的编排核心Docker Compose docker compose up 命令完全指南构建、创建、启动与重建的编排核心 本文基于本仓库Docker Compose云原生容器编排DevOpsCLIDocker Compose start 命令完全指南启动既有服务容器Docker Compose start 命令完全指南启动既有服务容器 docker compose start 用于启动 Compose 项目下已经存在的云原生容器编排DevOpsCLIIntentKit 快速入门用 Docker Compose 启动 Agent 集群 API 并通过 REST 接口创建与交互IntentKit 快速入门用 Docker Compose 启动 Agent 集群 API 并通过 REST 接口创建与交互 本篇指南以 docs/cont人工智能AI Agent多智能体后端前端区块链Web3上一篇x64dbg 异常设置指南配置忽略异常Ignored Exceptions过滤列表下一篇微博超话自动签到部署指南4步完成Python脚本配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考