企业官网建设流程全解析

• 云原生
• 开发工具
• 微服务
• 网络

telepresence compose stop是 Telepresence 的 Docker Compose 扩展命令族中的停止子命令，用于停止由telepresence compose up启动的本地容器，同时结束这些服务在远端 Kubernetes/OpenShift 集群上建立的 intercept、ingest、replace、wiretap 等附件（attachment）连接。本文以 docs/reference/cli/telepresence_compose_stop.md 为骨架，结合 compose 扩展机制文档 与 compose 子命令实现源码，完整讲解该命令的语法、全部参数、与原生docker compose stop的本质区别，以及它在up生命周期中的自动调用场景。

命令概览：语法与定位

telepresence compose stop的用法与原生 Docker Compose 保持高度一致：

telepresence compose stop [flags] [services]

从 compose.go 命令注册入口 可以看到，所有telepresence compose子命令都通过compose.GenerateSubCommands(cmd)动态生成，其定义数据来自内嵌的 dc-cli.json（对应其中"name": "stop"、"usage": "docker compose stop [OPTIONS] [SERVICE...]"的命令描述），因此参数风格与docker compose保持一致。未指定[services]时停止项目内所有服务，指定一个或多个服务名时仅停止列出的服务。

该命令的定位可以从 docs/reference/compose.md 的 "States" 一节得到权威解释：

telepresence compose stopends the attachments, but it keeps telepresence connected, because the existing containers use theteleroutenetwork backed by that connection.

即：stop 会结束附件（远端集群侧的资源占用），但不会退出 Telepresence 连接——因为容器仍在运行期间依赖teleroute网络访问集群，连接需要保留。只有telepresence compose down才会彻底终止网络并退出 Telepresence。

参数详解：四组 Flag 的完整说明

该命令共包含四组参数：命令自身 Flag、Compose 通用 Flag、Compose stop 专属 Flag 与全局 Flag。

命令 Flag

Compose 通用 Flag（所有 compose 子命令共享）

这些 Flag 由 config.go 中的 addComposeFlags 函数 统一注册，对stop同样生效：

从 toProjectOptions 实现 可以看到这些参数在底层如何被解析：项目工作目录来自projectDir，env 文件按--env-file显式指定、当前目录.env、COMPOSE_FILE环境变量、默认compose.yaml探测的优先级顺序加载，profiles 与 project name 分别注入WithDefaultProfiles与WithName。在生成最终转发的docker compose命令行时，createProject 会把--project-name、--project-directory、--env-file、--profile等原样透传给底层 docker CLI。

Compose stop 专属 Flag

值得注意：dc-cli.json 中stop还声明了一个--dry-run布尔 Flag，但它在 subCommand 生成阶段 被隐藏，并且当用户显式传入--dry-run时，run 函数会直接报错：因为 Telepresence 必须实际挂接到工作负载才能获取修改 compose 项目所需的数据，intercept、replace、ingest、wiretap 都会安装 traffic-agent，无法作为 dry-run 执行。

全局 Flag

其中--progress的值会被 run 函数 读取并传给底层 compose，非auto时以显式--progress <mode>透传（见 createProject）。

与原生docker compose stop的区别：附件生命周期

这是使用本命令时必须理解的核心差异。普通docker compose stop只停止容器进程；而telepresence compose stop是Telepresence 扩展的 compose 生命周期管理的一部分。完整状态语义如下：

从 run 函数 的源码可以看到，当命令名是create、stop或非 detached 模式的up时，在底层docker compose命令执行完毕后会调用tr.detach(ctx)结束所有附件——stop正是触发 detach 的命令之一。detach 过程（transform.go 中的 detach 方法）会遍历全部 attachment，逐个执行其deactivate()释放远端资源。

典型使用场景与示例

场景一：手动停止整个项目

# 停止项目内所有服务（结束附件，保留连接） telepresence compose stop # 指定项目目录与项目名 telepresence compose --project-name myapp --project-directory ./stack stop # 从多个配置文件和 profile 构建项目后停止 telepresence compose -f docker-compose.yml -f docker-compose.prod.yml --profile prod stop

场景二：仅停止指定服务

# 只停止 db 服务，其他服务不受影响 telepresence compose stop db # 停止多个服务并指定 30 秒优雅退出超时 telepresence compose stop -t 30 db web

由于子命令在第一个非 Flag 参数（即服务名）处停止解析 Flag（见 subCommand 中SetInterspersed(false)的设置），telepresence compose stop db web中的db、web都会被当作服务名处理。

场景三：compose up退出时自动 stop

该命令还有一个容易被忽略的自动触发场景：当前台运行的telepresence compose up（未使用--detach）被中断时，runAttachedUp 会主动执行一次docker compose --file <file> [--profile ...] stop <services>，确保依赖附件（如 teleroute 网络、telemount 卷）的容器被及时停止，避免容器在附件断开后继续运行。源码注释明确解释了这样设计的原因：直接杀掉compose up进程会导致容器 detach 后继续运行一段时间，而其中部分容器依赖即将结束的附件；且在 Windows 上，compose up被中断后甚至完全不会停止容器。

停止前需要了解的前置条件

使用telepresence compose stop前应确认：

1. 项目必须由telepresence compose up启动。stop作为生命周期命令，其操作对象是那些通过 x-tele 扩展 建立了连接和附件的 compose 项目；没有扩展服务的项目会被直接透传给底层docker compose stop（见 run 中len(es) == 0的分支）。
2. 必须存在正在运行的 Telepresence daemon 连接。stop要求mustBeConnected = true；若 daemon 未运行且项目无扩展服务，代码会回退为直接执行docker compose stop以产生符合预期的错误输出（见 run 中的回退逻辑）。
3. 附件（卷）提供者约束：当只停止部分服务时，runCommand 会校验 仍被引用的telemount卷是否由仍在运行范围内的扩展服务提供，否则会报错提示volume ... is provided extended service ..., but that service is not included。

与相关命令的配合

• telepresence compose up：启动项目并建立附件，是stop的对偶命令；
• telepresence compose down：彻底清理——停止并删除容器、结束附件、终止teleroute网络并退出 Telepresence。若只是临时暂停、稍后还要继续开发，用stop更合适；若要完全结束会话，用down；
• telepresence quit：退出客户端时若检测到 compose 项目在运行，会自动代为执行compose down，保证集群侧资源被释放。

完整的x-tele扩展字段（connections、mounts 以及 connect/proxy/ingest/intercept/replace/wiretap 六种服务扩展类型）说明，可继续阅读 docs/reference/compose.md；可实际运行的示例配置位于 examples/compose 目录。

• 云原生
• 开发工具
• 微服务
• 网络