公司上个月做基础组件容器化迁移，第一批要把 Nacos 3.x 和一套向量检索服务用 Docker Compose 编排起来。我接手之后第一件事，是在一台新初始化的机器上执行docker compose up -d，结果终端甩出来一行冷冰冰的报错：docker: unknown command: docker compose。当时我下意识以为是版本太老，但docker --version显示的是 24.0.x，一点也不老。后来排查下来才发现，这其实是 Docker CLI 插件机制没生效，连带着我意识到一个更大的问题：企业环境里部署 Docker Compose，真正容易踩坑的地方根本不在"怎么写 yaml"，而在环境准备、生产化配置、资源管控和长期运维这几个环节。
这篇文章就按我这次实际推进的顺序来写。我不会整篇堆一堆"最佳实践"的大词，只讲我验证过、踩过、最后调通的东西。如果你贵司也正在从docker run裸命令迁移到 Compose，或者想把跑在测试环境的 Compose 工程真正搬到生产，这篇应该能帮你少走几周弯路。
1. 从 "unknown command" 说起：Compose 环境准备中的三个高频坑
先把这个最经典的报错彻底讲清楚，因为你在公司环境里大概率也会碰到，而且原因往往不是你以为的那个。
1.1 docker-compose 和 docker compose 是两代东西
很多运维老哥还在用docker-compose（带横杠）这个命令，那是 Compose v1 时代的产物，本质是一个用 Python 写的独立二进制。而docker compose（中间有空格）是 Compose v2，它改成了 Docker CLI 的官方插件，不再单独安装一个可执行程序，而是以docker-cli-plugin-docker-compose这个文件的形式放到 Docker CLI 的插件目录里。
这个差异在 Docker 20.10 之后非常明显。新版 Docker 默认只认识插件形式的docker compose，如果你机器上只装了老的docker-compose，输入新命令就会报 unknown command。反过来，如果脚本里还写着docker-compose up，在新版 Docker 上也可能因为找不到 v1 二进制而失败。我见过最多的坑是：一些人两台机器各装各的，混着用，最后 CI 脚本在 A 机器跑通、在 B 机器就跑不通。
1.2 踩到 "docker: unknown command" 的完整排查链路
遇到这个报错，别急着去网上翻一堆apt install的帖子，按下面这条链路五分钟左右就能定位：
第一步，先确认你的 Docker 客户端版本和支持的插件机制：
docker --version docker compose version如果docker compose version同样报 unknown command，说明插件大概率缺失；如果它能输出版本，那问题就变成"为什么命令不能直接执行"——通常是当前 shell 环境变量或 PATH 的问题。
第二步，检查插件是否真的装到了 Docker 可以识别的目录。Docker CLI 会按固定顺序扫描插件目录，常见的有：
/usr/local/lib/docker/cli-plugins /usr/lib/docker/cli-plugins /root/.docker/cli-plugins正常情况下的插件文件长这样：
ls -l /usr/local/lib/docker/cli-plugins/ # 总用量 68340 # -rwxr-xr-x 1 root root 69976000 3月 21 10:22 docker-compose注意文件名必须是docker-compose（没有 .exe 之类后缀），而且要有可执行权限。网上很多教程让你curl -L 下载到/tmp，结果你直接mv到插件目录后没chmod +x，Docker 会静默跳过这个插件，然后继续报 unknown command。
第三步，检查你的 Docker 版本是否够老。Docker 20.10 之前的版本要支持 Compose v2 插件比较费劲，我建议这种老机器直接放弃插件方式，老老实实用 v1 的docker-compose，或者干脆升级 Docker。企业环境里如果你没法轻易重启 docker daemon，升级这条路线要慎重，后面我会讲离线升级的替代方案。
1.3 内网环境与国产 Linux 发行版的安装补充
我们这次的目标机器是麒麟 V10 x86_64，系统是 CentOS 系的底子，但内网完全不能访问外网。这种环境下在线执行apt install docker-compose-plugin或者yum install docker-compose-plugin基本都会失败，因为官方源不一定在里面，第三方源的安全你也不敢信。
我的做法是准备离线安装包。但这里有个容易踩的坑：Docker 的 Compose 插件官方没有单独的 rpm/deb 包，所谓docker-compose-plugin其实是跟随 docker-ce 整套一起发布的。你单独用yum install docker-compose-plugin往往会把一堆依赖带上，反而麻烦。
最稳妥的离线路线是下载 Compose v2 的独立二进制：
# 在有外网的机器上，到 GitHub Releases 页面下载对应架构的包 # 例如 linux-x86_64 版本 curl -L -o docker-compose-linux-x86_64 \ https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-x86_64 chmod +x docker-compose-linux-x86_64 # 拷贝到插件目录 sudo mv docker-compose-linux-x86_64 /usr/local/lib/docker/cli-plugins/docker-compose # 验证 docker compose version这个过程在内网机器上只需要拷贝一次文件，不触碰任何包管理器，依赖问题归零。唯一要注意的是 GitHub Releases 的下载链接偶尔会变，最好先在能联网的机器上验证 URL 有效，再打包进你的部署目录。
版本选择上我建议别追求最新，优先挑企业场景里被验证了半年以上的稳定版。Compose v2.20 之后有一些行为变化（比如对depends_on的语义调整），新版本你在测试环境玩可以，生产环境尽量锁死一个版本，避免后续手滑升级导致行为不一致。
2. 生产可用的 Compose 文件设计：从"能跑"到"敢上线"
环境问题解决后，下一步当然是把服务编排文件写出来。但我要说句实话：网上 90% 的 Compose 示例都是"开发环境能跑"的水平，直接搬到企业环境会出大问题。我自己用下面的几个标准来评判一份 Compose 文件能不能上生产。
2.1 多环境配置：.env 与 env_file 的职责拆清楚
企业里同一个 Compose 工程往往要同时跑在开发、测试、预发、生产四套环境，不可能每套环境都维护一份 yaml。Docker Compose 自己支持变量插值，它读的文件叫.env，作用是往 compose 文件里填变量。而另一个概念env_file是指定容器内部的环境变量文件。这两个东西很容易混，但用途完全不同。
我习惯这样拆分：
.env：只放 compose 层面的变量，比如镜像 tag、对外端口、数据卷路径前缀、项目名。env_file：放应用自己读的环境变量，比如 JVM 参数、数据库连接串、日志级别。- 密钥类信息：绝不进
.env，更不写死在 yaml 里。Compose v2 支持secrets直接挂载到容器文件系统，Docker 19.03 之后建议优先用这种方式。
举个实际的片段：
services: app: image: registry.internal.example.com/app-server:${APP_TAG:-v1.0.0} env_file: - ./config/${ENV:-dev}/app.env secrets: - db_password ... secrets: db_password: file: ./secrets/${ENV:-dev}/db_password这样开发环境不填任何变量也能跑起来，预发环境只需要在启动前指定ENV=staging，生产环境则可以由配置中心下发，避免把敏感信息留在仓库里。你可能会觉得多套了一层配置有点烦，但等你要做灰度、要做同环境多副本的时候，会发现这是救命的设计。
2.2 健康检查与依赖顺序：让 down 掉的服务能自己恢复
企业环境里最恼人的不是服务半夜挂了，而是它挂了你第二天早上才知道。Compose 的restart: always能解决一部分自动拉起的问题，但它不知道服务是否真正"就绪"——MySQL 容器启动了不代表端口能接受连接，Nacos 进程起了不代表集群已经选主完成。
这时候就要用healthcheck。我给团队定的规矩是：所有有状态服务、所有对外提供接口的服务，必须配健康检查，否则不允许合并到主工程的 compose 文件里。
举例，给 MySQL 配健康检查：
services: mysql: image: mysql:8.0 healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-p$$MYSQL_ROOT_PASSWORD"] interval: 10s timeout: 5s retries: 5 start_period: 30s注意两个细节：一是start_period一定要给足，容器从启动到 MySQL 真正能响应请求，有时候要 30 秒以上，这段时间内的失败不应该立刻标记为 unhealthy；二是健康检查命令里的环境变量要用$$转义，否则 Compose 会在宿主机层面就把它展开掉，口令根本传不到容器里。
有了健康检查，depends_on才能真正发挥价值。很多新手以为depends_on会等依赖服务健康再启动自己，实际上 Compose v2 默认只是等依赖服务"容器已启动"而已，并不会等"接口可用"。你在 yaml 里显式声明condition: service_healthy才行：
services: app-server: depends_on: mysql: condition: service_healthy nacos: condition: service_healthy这样 Compose 会等依赖方健康后才启动 app-server，后面你会发现服务宕机重建时，整体可用性比原来瞎等 sleep 好很多。
2.3 网络与数据卷规划：别让所有容器挤在一个默认网络里
开发环境里一个docker compose up拉起所有服务，它们共享一个默认网络，确实省事。但生产里我强烈建议按业务边界拆网络。最简单的做法是用外部网络，让 Compose 工程自己创建的容器加入到一个已经规划好的 overlay 网络里：
docker network create --driver overlay --attachable prod-infra-network对应 compose 文件：
networks: default: name: prod-infra-network external: true这样多个 Compose 工程可以共享同一张网络，A 工程的 Nacos 和 B 工程的业务服务能互相解析服务名，但网络层面可以统一由网络策略管控。如果你有多个环境（dev/staging/prod），一定要避免默认的default网络名称冲突，因为 Compose 默认会把项目名加进去形成唯一网络名，而外部网络不存在这个问题。
数据卷方面，我也做了一次取舍革命。以前贪方便，全部用 bind mount 挂宿主机目录，后来发现跨环境路径不一致、权限混乱、备份策略必须跟着宿主机走，太痛。命名卷（named volume）在这几方面都更干净：
services: nacos: volumes: - nacos-data:/home/nacos/data - nacos-logs:/home/nacos/logs volumes: nacos-data: name: nacos-${ENV:-dev}-data nacos-logs: name: nacos-${ENV:-dev}-logs命名卷的一个额外好处是可以用docker volume create --label把备份策略、存储池配置打进去，配合存储驱动能直接把卷落到企业 NAS 或分布式存储上。bind mount 适合放配置文件、日志目录这种我知道宿主机一定存在的路径，不适合乱挂应用数据。
3. 真实案例：用 Compose 把 Nacos 3.x 和配套服务一起编排起来
光讲原则不过瘾，我把这次迁移过程中真正写出来的一个 Compose 工程拆给大家看，以现在热门的 Nacos 3.x 为主线。
3.1 Nacos 3.x 部署的 Compose 配置
Nacos 3.x 相比 2.x 在模块、配置上都有变化，但好消息是它依然支持通过环境变量覆盖启动参数。我们这次用单机模式先跑起来，但数据目录必须持久化，否则每次重启配置和注册服务数据全没。
services: nacos: image: nacos/nacos-server:v3.0.0 container_name: nacos-server env_file: - ./env/nacos-${ENV:-dev}.env ports: - "8848:8848" - "9848:9848" - "9849:9849" volumes: - nacos-data:/home/nacos/data - nacos-logs:/home/nacos/logs healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8848/nacos/ || exit 1"] interval: 15s timeout: 5s retries: 10 start_period: 40s restart: always networks: - default关于端口要多说一句：8848 是控制台和 HTTP API，9848 是 gRPC 端口，9849 是 9848 的偏移端口。很多人只映射了 8848，结果客户端连接时 Nacos 上报 9848 连不上，又是一轮抓瞎。如果你的客户端和 Nacos 不在同一网络段，这三个端口都要开了。
Nacos 3.x 的镜像对配置文件的管理也细化了。生产环境我推荐把关键参数放到启动环境变量中，例如：
NACOS_AUTH_ENABLE=true：显式开启鉴权，默认是关闭的，内网裸奔很危险。NACOS_AUTH_TOKEN：自定义 token，别用文档里的默认值。MODE=standalone：单机模式测试用，企业集群化部署后面再看集群模式。
start_period: 40s是调过的。Nacos 首次启动要建库建表、初始化缓存，快则 20 秒、慢则 40 秒，健康检查间隔 15 秒的话，第一次检查大概率会失败，但这个失败不能立刻判定它挂了，否则服务端会不断重启它，形成"启动即被杀"的循环。
3.2 模型推理服务的编排思路：容量预估与资源隔离
这次还要一起拉起来的是一套 BGE-M3 embedding 模型推理服务。这类服务有一个特点：模型加载阶段 CPU 和内存都会冲高，但加载完成后日常推理的 CPU 占用反而稳定。你要是不管资源限制，它可能会把宿主机搞到 OOM。
我在编排这类 AI 推理容器时，除了常规的环境变量、模型目录挂载之外，最看重的就是给容器划定明确的 CPU 和内存预算。最终 Compose 文件大概是：
services: bge-m3: image: registry.internal.example.com/bge-m3-server:1.0.0 volumes: - /data/models/bge-m3:/models/bge-m3:ro environment: - MODEL_PATH=/models/bge-m3 - MAX_BATCH_SIZE=64 ports: - "8081:8080" deploy: resources: limits: cpus: "4.0" memory: 8G reservations: cpus: "2.0" memory: 4G healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"] interval: 20s timeout: 5s retries: 5 start_period: 60s注意一个细节：deploy.resources在单机 Compose 下（非 Swarm 模式）也不是空摆设，它会被 Docker 的容器运行时强制执行。limits.memory是硬限制，超过会触发 OOM；reservations是软预留，帮调度器理解这个容器至少需要多少资源。这个设计在共享宿主机上特别重要，免得一个模型加载把旁边的 Nacos 拖死。
4. 资源限制与性能优化：把 CPU、内存和启动时间都管起来
企业环境从来都是多服务混部在一台物理机上，谁都想多压榨一点资源，但谁也都不想被别人连累。这一章我说几个和资源管理相关、并且我在迁移中真正遇到瓶颈的点。
4.1 容器里的 JVM/.NET 运行时为什么 CPU 会异常升高
排查过程中我注意到一个现象：容器内跑的 Java 服务启动后，宿主机top里有几个线程的 CPU 占用很高，甚至持续几分钟降不下来。后来发现是 JVM 在启动阶段做 JIT 编译预热，加上容器感知能力没开全，导致 JVM 以为还是宿主机级别的 CPU 数量，于是开了一堆并行编译线程。
对应的解决办法是两件事：一是给 JVM 传-XX:ActiveProcessorCount=4之类的参数，让它明确知道自己只有 4 个核可用；二是在 Compose 里用healthcheck+deploy.resources.limits把容器 CPU 上限固定下来。
热词里也有人提到.NET Runtime Optimization占用 CPU，这其实是 .NET 运行时在后台做程序集预编译的线程。容器部署 .NET 服务时，这个优化任务同样可能造成启动期 CPU 冲高，解决办法和 JVM 思路一样：让运行时明确感知容器资源边界，同时通过ulimits和资源限制把预编译任务控制在合理水位。具体做法是：
services: dotnet-service: image: registry.internal.example.com/dotnet-svc:2.1.0 deploy: resources: limits: cpus: "2.0" memory: 2G ulimits: nofile: soft: 65536 hard: 65536ulimits里nofile是开源社区里最容易忽略的一项。容器内的进程默认会继承宿主机对文件描述符的软限制，如果太小，高并发下会直接报 too many open files，这问题在裸机上不明显，因为它常常是ulimit -n 65535+，但容器内可能是 1024。手动设成 65536 是标准做法。
4.2 启动速度优化：给健康检查留足start_period
启动慢不一定会导致故障，但一定会导致发布变长、回滚变长，这在企业里就是实打实的成本。很多服务慢不在容器创建，而在应用初始化。JVM 要加载类、Nacos 要跟配置中心同步、模型推理服务要把模型从磁盘读进显存，这些都需要时间。
我优化启动体验的核心思路就一条：把"启动慢"这件事用start_period明确告诉健康检查器，让它在指定时间内不判定服务异常，同时把依赖服务的启动顺序串好。像上面 Nacos 的start_period: 40s、BGE-M3 的start_period: 60s，都是实测后调出来的值。给太短，健康检查会在服务还没起来时就把它标记为 unhealthy 然后反复重启，结果反而更慢；给太长，服务真挂了也要等很久才被拉起来。
实测下来，比原来靠sleep 60硬等的方式快得多，而且更可靠。你可以用这条命令持续观察服务从启动到 healthy 的时间：
docker inspect --format='{{json .State.Health}}' nacos-server看Log数组里的start和end时间戳，能精确到秒，拿这个数据去调start_period比拍脑袋准得多。
4.3 重启策略要谨慎：restart 不是万能的
默认的restart: always确实能保证容器退出后自动拉起，但它有个副作用：如果容器是因为资源 OOM 被 kill 的，它会在几秒钟内又被拉起，然后再次 OOM，形成"反复崩溃重启"的死循环。宿主机 CPU 和内存都会被拖垮。
我的建议是分场景：
- 对于无状态服务，可以
restart: unless-stopped，这样手动 stop 后不会被自动拉起，避免排障时误操作。 - 对于有状态服务，比如 Nacos、数据库，应该先用健康检查兜底，再配置
restart: on-failure:3，连续失败超过 3 次就停下来报警，让值班同学先看日志再决定是否拉起，而不是让机器自己硬扛。
这算是排障文化的问题：让机器自己不断重试，往往掩盖了真实原因。真正的高可用依赖的是监控、告警和可观测性，不是无限重启。
5. 运维阶段最容易忽略的坑：项目名、日志轮转与升级策略
Compose 文件写对了、服务也跑起来了，这只是开始。真正让运维头疼的是接下来几个月的日常维护。这里几个坑我都踩过，逐个说。
5.1 项目名（project name）会决定网络名、卷名和容器名
Compose 默认用工程目录名作为项目名，也就是说你把同一个 Compose 文件放到不同目录下，跑出来的容器、网络、卷名全不一样。如果 CI 或发布脚本里用了固定的容器名或网络名，那换个目录部署就会找不到资源。所以生产环境我强烈建议显式指定项目名，不要依赖目录名推断：
docker compose -p nacos-prod up -d或者在环境变量里设置：
export COMPOSE_PROJECT_NAME=nacos-prod显式指定项目名还有个好处：你可以在同一台机器上并行跑多个相互隔离的环境（比如一套预发、一套金丝雀），只要项目名不同，网络层天然隔离，互不干扰。我在预发环境就用COMPOSE_PROJECT_NAME=nacos-staging跑了一套完整副本，通过外部网络桥接少量端口给测试用，成本极低。
5.2 日志轮转：JSON 日志驱动的大小控制
数据卷持久化你做了、健康检查你配了，但如果日志不管理，磁盘被写满是迟早的事。Compose 默认的日志驱动是 json-file，会无限收集容器日志到宿主机，而且文件大小没有任何上限。我见过一台磁盘 100G 的机器被容器日志三天写满的情况。
在 Compose 服务定义里给每个服务配日志上限：
services: app-server: logging: driver: json-file options: max-size: "10m" max-file: "5"max-size=10m表示单个日志文件到 10MB 就滚动，max-file=5表示保留最近 5 个文件，也就是单容器日志上限 50MB。这个配置对几乎所有容器都适用，不给它配日志上限，等于给磁盘埋了个定时炸弹。如果是企业里有集中的日志采集系统（比如 Kafka + ELK 或 Loki），建议直接把 stdout 接入采集端，宿主机上就不保留日志文件了，驱动可以换gelf或直接用journald。
还有一条命令要提醒：docker system prune很常用，但它默认不会清数据卷，你千万别以为它会把没用的卷一起清掉，反而会让宿主机上堆一堆孤儿卷。要清卷得手动docker volume prune，而且执行前一定确认没有正在使用的服务。
5.3 平滑升级：滚动更新和回滚的 Compose 姿势
生产服务免不了要发新版本，Compose 的更新逻辑比想象中简单，但也有一些细节。最直接的方式是改镜像 tag，然后执行：
docker compose -p app-prod up -dCompose 会比较配置差异，发现镜像变了，会重建对应容器。这里有个常见的坑：如果你没有显式指定镜像 tag，而是写image: xxx:latest，那 Compose 默认不会主动去拉新镜像，因为本地已有 latest 就认为"没变化"。所以生产文件里必须用明确的版本号，比如image: registry.internal.example.com/app-server:v1.0.0，升级时改版本号再 up。
对于多副本场景，用--scale可以做到滚动更新：
docker compose -p app-prod up -d --scale app-server=3配合健康检查，Compose 会创建新的容器，等服务 healthy 后再继续建下一个，整体对流量影响很小。我发现很多团队以为 Compose 做不了滚动更新，其实它是能做基础版本的滚动扩缩容的，只是不如 K8s 那么精细化。如果你的业务规模真的超过两三台机器，再考虑引入编排平台；规模没到那个量级，Compose 的这套手感已经足够顺滑。
回滚也一样简单，把镜像 tag 改成上一个稳定版本号，再docker compose up -d即可。配置文件没有结构性变更时，回滚通常 30 秒内完成，比手动删容器重建快得多。
最后再分享一个实际操作中的体会
这套 Compose 化改造从环境准备、生产配置到资源管控，总共花了大概两周的零碎时间。真正让我觉得值得的，不只是把服务装起来了，而是整个部署过程从"一个人盯着终端敲命令"变成"一条命令可复现、一个文件可审查"。Git 里维护 compose 工程版本，任何人 checkout 下来，只要环境变量给对，就能在十分钟内拉起一整套和线上一致的环境，这个确定性在团队协作里价值极大。
如果你现在也正卡在某台机器上报 unknown command 或者容器时不时重启，先别急着换编排平台。把本章提到的资源限制、健康检查、项目名和日志轮转这四件事做好，你的 Compose 工程至少能在生产环境里稳定跑上半年。最后留个习惯：每次改动 compose 文件后跑一遍docker compose config --quiet，它能帮你第一时间发现 yaml 语法和字段拼写错误，别等到up -d才被报错打脸。
