企业官网建设流程全解析

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

telepresence compose create是 Telepresence Docker Compose 扩展体系中的一个核心命令，它在不启动容器的情况下，为 Compose 文件中声明了x-tele扩展的服务创建容器，并完成集群连接、附件（attachment）与代理网络的编排。阅读本文后，你将掌握该命令的完整用法、全部标志参数的含义与适用场景、它与telepresence compose up/down/stop的状态机关系，以及它在 Telepresence 源码中的底层实现机制。

命令概览与定位

telepresence compose系列命令本质上是docker compose的超集：它以 Docker Compose 的 CLI 定义为模板，在原有子命令之上叠加 Telepresence 的x-tele扩展处理逻辑。该命令族注册于 cmd/compose.go，其Short描述为 "Define and run multi-container applications with Telepresence and Docker"，子命令由 compose.GenerateSubCommands 根据内嵌的dc-cli.json声明动态生成。

telepresence compose create对应标准 Docker Compose 的docker compose create子命令，其官方描述为"Creates containers for a service"。核心区别在于：Telepresence 版本会在调用真正的docker compose create之前，先完成以下编排工作：

1. 解析 Compose 项目中各服务的x-tele扩展；
2. 建立指向远程 Kubernetes/OpenShift 集群的连接（connection）；
3. 为扩展服务创建附件（attachment），包括代理、拦截、摄取或替换等行为；
4. 改写 Compose 项目，注入teleroute网络、远程挂载卷（telemount volume）与必要的环境变量；
5. 将改写后的 Compose 文件落盘，并把文件路径与受管卷名保存到 daemon 信息中，再执行docker compose create。

与up的最大差异在于：create只创建容器、不启动它们，因此在所有容器创建完成后，会结束任何已有的附件（attachments）。

基本用法

telepresence compose create [flags] [services]

• [services]为可选的 Compose 服务名列表。当指定了具体服务名时，只会为这些服务创建容器；未指定时作用于 Compose 文件中声明的全部服务。
• 从源码看，服务名列表最终会透传给真正的docker compose进程：transform.go 中runCompose以append(opts, t.config.services...)的方式追加到命令行参数末尾。
• 通过-h, --help可查看该子命令的帮助信息。

全部标志参数详解

telepresence compose create的标志分为三组：通用 Compose 标志、create 专属标志以及 Telepresence 全局标志。以下参数声明与默认值均来自 dc-cli.json 与官方 CLI 参考文档 telepresence_compose_create.md。

Compose 标志（在telepresence compose父命令上）

这些标志在 config.go 中以pflag.FlagSet的方式挂到父命令上，随后由createProject统一转换成传递给docker compose的参数（transform.go）：包括--file、--project-name、--project-directory、--progress、--env-file与 profile 标志。

create 专属标志

其中--scale对应 Docker Compose 的scale类型参数，--pull的policy默认值含义是"遵循 Compose 文件中的pull_policy设置"。

需要注意，--force-recreate与--no-recreate不只是透传给 Docker 的开关，它们还直接影响 Telepresence 的改写行为。在 transform.go 的runCommand中：

• canCreate（初始为selectsAll，即是否选中全部扩展服务）会被--no-recreate=true置为false；
• forceRecreate直接从标志值读取。

当--force-recreate为真时，即使 daemon 信息中已保存了改写后的 Compose 文件，也会重新应用附件并重写该文件（createConfigFile），从而更新 telemount 卷集合；而canCreate为假时，若首次调用未包含全部扩展服务，会直接返回错误the initial invocation of "compose up" or "compose create" must include all extended services。

Telepresence 全局标志

--progress非auto时会被透传为docker compose --progress参数，见 transform.go。

create 在 compose 生命周期中的位置

telepresence compose create是 docs/reference/compose.md 所描述的"状态机"中的关键一环，各命令之间的状态转换如下：

create的典型应用场景是"预编排"：先在 CI 或脚本中以非交互方式（配合-y）把容器与网络拓扑准备好，待后续再up启动，从而把耗时的镜像拉取与容器创建步骤与启动步骤分离。

底层实现：create 的执行链

telepresence compose create的执行可拆解为三个阶段，对应源码中的三个关键函数：

1. 解析扩展与服务选择（newTransformer）

transform.go 中的newTransformer遍历项目内每个服务，若检测到x-tele扩展键（常量extensionKey = "x-tele"，定义于 config.go），则调用parseServiceExtension解析为对应的扩展类型。若命令行指定了[services]而该服务不在其中，selectsAll会被置为false，后续canCreate随之变化。

2. 生成改写后的 Compose 文件（createConfigFile）

createConfigFile 的流程为：

• 收集所有连接（connection）的集群子网，通过teleroute.FindNonConflictingSubnet为 Compose 的默认网络预分配一个不与 Kubernetes 集群子网冲突的 IPAM 子网（configureDefaultNetwork，见 transform.go）；
• applyAttachments把各附件的服务改写（代理替换、卷注入、网络挂载、环境变量）应用到项目模型上，并确保顶层x-tele扩展被序列化回项目中（transform.go）；
• 将改写后的 YAML 写入临时文件（首次，tpc-*.yaml）或覆盖 daemon 信息中已保存的 Compose 文件（重写路径，如--force-recreate）；
• 把 Compose 文件路径与 telemount 卷名列表保存进 daemon 信息（ComposeFile、ComposeVolumes），保证连接关闭时这些卷能被正确清理。

3. 透传执行 docker compose create（runCompose）

runCompose 最终调用本机docker可执行文件，执行docker compose --file <改写后的文件> [compose标志] create [create标志] [services...]。由于create不在up分支中，不会走runAttachedUp的上下文取消清理逻辑，属于"一次性的编排命令"。

这一实现也印证了官方文档对 create 的描述："Creates containers for a service"——Telepresence 只是把容器创建前的集群编排工作全部自动化了。

实操示例

基础用法：为全部服务创建容器

telepresence compose create

仅创建指定服务，且跳过镜像构建

telepresence compose create --no-build api worker

使用显式 Compose 文件与项目名

telepresence compose -f docker-compose.yml -f docker-compose.override.yml \ --project-name myapp \ --profile debug \ create

非交互式预创建（CI 场景）

telepresence compose create -y --quiet-pull --remove-orphans

强制重建并重新应用附件

telepresence compose create --force-recreate --build

按策略拉取并扩展副本数

telepresence compose create --pull always --scale api=3

结合 x-tele 扩展理解 create 的作用对象

create真正编排的对象是 Compose 文件中声明了x-tele扩展的服务。该扩展可以出现在顶层（描述连接与挂载配置）或单个服务上（描述扩展类型），支持的扩展类型包括connect、proxy、ingest、intercept、replace、wiretap，详见 docs/reference/compose.md 的 Service Extensions 章节。例如一个典型配置：

x-tele: connections: - namespace: default services: api: x-tele: type: intercept workload: my-api

执行telepresence compose create时，Telepresence 会为api服务建立附件：共享被拦截容器的环境与卷、注入teleroute网络，并把改写后的配置交给docker compose create落地为容器。这也解释了为何 create 完成后会"结束已有附件"——容器已就绪但未运行，附件所代表的实时关联（拦截、代理）不需要在创建阶段保持。

小结

telepresence compose create在标准 Docker Compose 的create语义之上，增加了 Telepresence 的集群连接、附件编排与 Compose 文件改写能力，是 CI 预编排和"先建容器、后启服务"工作流的首选命令。掌握其标志语义（尤其是--force-recreate/--no-recreate对改写行为的双重影响）与状态机位置，即可安全地将它嵌入本地开发与自动化流水线。

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