1. 先把启动命令的链路盘清楚镜像默认命令与覆盖语法1.1 一个容器启动时到底执行了什么很多人把容器启动命令简单理解成docker run 后面跟的那一串字符串实际上容器引擎在执行启动时是按照一套固定顺序来组装最终进程的先用镜像的入口点entrypoint再把用户附加的命令参数放到后面最后拼成一条完整命令交给运行时去执行。这个顺序决定了两个很常见的现象。第一你写的启动命令并不总是你说了算如果镜像本身定义了入口点脚本你传入的参数会被当成脚本的参数而不是独立命令。第二即使你不想用镜像默认的启动方式也需要知道有哪些覆盖手段用 --entrypoint 参数可以整体替换入口点而直接写在 docker run 尾部的内容则是追加到入口点之后的参数。从实际排查经验看大部分人栽跟头都栽在以为自己在写命令实际上在写参数。举个典型的例子某个模拟项目X的镜像入口点是一个启动脚本脚本里用 $ 接收外部参数并拼接到应用启动命令中。你直接执行docker run -d 某镜像 /usr/bin/myapp --config/etc/app.conf看起来像是用 /usr/bin/myapp 替换了默认启动实际上入口点脚本仍然在执行只不过把 /usr/bin/myapp 和后面那一串都当作了参数传进去。如果脚本里写的是 exec $ 那最终确实会执行 /usr/bin/myapp如果脚本里只是 echo 或者拼接字符串那应用根本不会按你预期的方式启动。1.2 覆盖入口点不要破坏镜像约定的启动流程有一种情况必须要覆盖入口点调试镜像或临时容器。例如你想进入一个容器里看看文件结构、检查环境变量是否注入成功镜像默认入口点却是启动一个常驻服务你 docker run 进去之后服务起来就把容器占住了根本得不到 shell。这时候我会用docker run -it --rm 某镜像 /bin/sh如果这个命令没有生效多半是镜像的入口点写死了需要显式替换docker run -it --rm --entrypoint /bin/sh 某镜像需要注意--entrypoint 后面不要跟多个参数它只接收一个可执行文件路径剩余的参数照样放在镜像名之后。比如你想用 bash 并且带 -c 参数正确写法是docker run -it --rm --entrypoint /bin/bash 某镜像 -c echo hello因为 --entrypoint 只是把可执行文件换掉-c 和后面字符串都是作为参数追加的。这个细节很容易写错成 --entrypoint /bin/bash -c 这种形式实际上这样会把整串当成一个不存在的路径。我习惯在临时调试时保留 --entrypoint 的覆盖但在业务镜像里尽量不覆盖入口点。因为镜像构建者已经设计好启动流程包括初始化配置、等待依赖、信号处理这些环节直接覆盖入口点相当于跳过整个启动逻辑很容易让容器启动后处于一个半可用状态。1.3 前台进程才是容器的生命线启动命令最终要做的事情是拉起一个前台进程并保持住。容器引擎判定一个容器是否还在运行依据就是启动命令对应的进程是否存活。这个进程一旦退出容器就进入 Exited 状态不管你的服务是不是在后台还有子进程在工作。这个理解有多重要很多新手会把宿主机上常用的后台启动方式带进容器。比如在容器里执行docker run -d 某镜像 sh -c nohup myapp --daemon 命令结束后前台进程是 shsh 执行完立即退出容器立刻停止。即使 myapp 还在容器里跑容器引擎也不会认为容器还活着。反过来很多服务软件默认有前台运行开关。比如常用的反向代理服务有 daemon off 配置一些数据库进程默认在前台运行某些脚本框架需要自己指定 host 和端口监听。这就要求你在写启动命令时特意确认这条命令会不会在启动完成后退出如果会就要想办法让主进程在前台运行。一个简单可靠的做法是把启动脚本写成类似这种形式#!/bin/sh set -e # 做一些前置初始化比如等待数据库就绪 exec /usr/local/bin/myapp --listen0.0.0.0:8080关键是最后一行用 exec 替换当前 shell 进程让应用进程直接成为容器的 1 号进程。这不仅仅是为了前台化还关系到后面要讲的信号处理。2. 启动参数中最容易踩坑的组合restart 策略、端口映射与资源限制2.1 restart 策略不是保险箱它有严格的判定边界启动命令里最常见的参数之一是 --restart。很多人的理解是挂了会自动拉起来但它的判定逻辑比这个更细。no默认值任何退出都不会自动重启。on-failure[:max-retries]进程以非 0 退出码退出时重启最多重试指定次数。always不管退出码是不是 0只要容器停止就重启。unless-stopped和 always 类似但手动停止的容器不会被守护进程在重启时自动拉起。这里有两个容易被忽略的坑。第一on-failure 只看退出码不看具体原因。比如你的应用因为内存不足被系统杀掉退出码可能是一个非 0 值那它就会不断重启如果应用正常完成业务后主动退出并返回 0on-failure 不会重启。第二always 并不是无条件拉起如果你手动 docker stop 一个容器守护进程不会违背你的意愿把它重新启动除非守护进程本身重启了。从实际运维角度看我不建议在启动命令里盲目加 --restart always。对于有状态应用反复重启会带来数据一致性问题对于依赖外部依赖的服务启动时的报错可能根本不是应用自身能恢复的。更合理的做法是配合健康检查来决定是否重启这个后面再说。2.2 端口映射从命令到流量的完整行为端口映射的参数虽然简单但组合起来有不少细节。用 -p 8080:80 表示把宿主机的 8080 端口映射到容器的 80 端口。如果你只写 -p 8080:80那容器启动时监听的是 TCP 的所有地址如果你想限制只映射到某个具体网卡可以写 -p 127.0.0.1:8080:80。还有一个容易被忽略的写法是 -P大写 P 会随机把容器的所有暴露端口映射到宿主机的高位端口。这个适合临时调试不适合生产因为你很难控制最终映射到的端口。在我接触的启动链路问题里端口映射出错最常见的是容器起来了但流量过不去。这一般不是启动命令本身的问题而是没有确认容器内服务是否监听在正确地址上。比如很多框架默认监听 127.0.0.1这样端口映射出去之后宿主机访问容器 IP 的端口是没有响应的。排查时要进入容器用 curl 或 netstat 看一眼监听地址而不是只看映射配置。还要提一下端口冲突的处理。如果你在一个宿主机上频繁启动容器可能会遇到端口被占用导致的启动失败。这类错误信息往往晦涩难懂但本质就是 bind 失败。为了避免在启动命令里铺一堆 -p我在测试环境倾向于用 -P 随机映射用 docker port 命令查实际端口这样能避开大部分冲突。2.3 资源限制启动时预留的参数会影响运行期行为启动命令中还应该尽早考虑资源限制。常见的参数包括 --memory、--cpus、--pids-limit 等。这些参数不只是限制资源上限还决定了后续运维的观测方式。如果启动命令里设置了 --memory 512m容器内应用的内存占用超过限制时可能直接被 OOM 杀死。这时候你去翻系统日志会看到记录但容器本身可能已经反复重启多次。更好的做法是结合 --restart on-failure 和内存限制一起用并且在启动命令里加上 --memory-swap 的说明避免出现物理内存未满但容器频繁被杀的诡异现象。cpu 限制相对温和。--cpus 1.5 表示容器最多使用 1.5 个 CPU 核它不会直接杀死进程只会影响调度。对于依赖 CPU 密集计算的程序要提前测算需要的核数过宽会导致宿主机资源争抢过窄会让容器内应用响应变慢。资源限制这块我给的启动命令示范一般长这样docker run -d \ --name 某应用 \ --restart on-failure:5 \ --memory 512m \ --cpus 0.5 \ -p 127.0.0.1:18080:8080 \ 某镜像注意启动命令的编排顺序习惯上把不变量放前面把本次变更的内容放后面这样便于排查和 diff。3. 生产环境启动命令的进阶设计entrypoint、健康检查与优雅退出3.1 入口点脚本里那些启动前必须做的事情如果业务比较简单启动命令写在 docker run 后面也不是不行。但到了生产环境我更建议把启动逻辑沉淀到镜像的入口点脚本里。因为启动命令越复杂越容易在复制粘贴时出错而入口点脚本是随镜像一起构建、经过测试的。入口点脚本通常承担三件事一是初始化运行环境比如生成配置文件、等待依赖服务就绪二是启动前的校验比如检查环境变量是否完整、目录是否有写权限三是最终启动应用。我见过不少项目把这三件事全塞到 docker run 的 sh -c 参数里最后命令长得无法阅读也失去了版本管理。一个比较稳妥的结构是这样#!/bin/sh set -e # 等待数据库就绪 while ! nc -z 数据库地址 5432; do echo waiting for database... sleep 2 done # 根据环境变量生成配置 envsubst /etc/app.template /etc/app.conf # 启动应用并接管信号 exec /usr/local/bin/app --config /etc/app.conf脚本里的 exec 是重点。没有 exec 的话脚本会以 sh 进程作为容器主进程应用变成它的子进程。容器停止时sh 进程收到退出信号后通常不会主动转发给子进程这就会导致应用被强杀或者出现孤儿进程。用 exec 把应用提到一号进程位置信号才能直达应用。3.2 启动命令与健康检查的配合健康检查healthcheck是启动命令之外很重要的补充。它回答的问题是进程虽然活着但没有正常对外提供服务算不算启动成功从容器引擎的角度进程活着就算 Up但从业务角度一个依赖数据库没连上的应用只是半死不活。我习惯在启动命令里直接附带健康检查docker run -d \ --health-cmdcurl -f http://127.0.0.1:8080/health || exit 1 \ --health-interval10s \ --health-timeout5s \ --health-retries3 \ 某镜像启动后通过 docker inspect 查看健康状态字段能尽快发现应用是否真正就绪。有一个容易踩的坑容器里不一定有 curl 命令。有些精简镜像没有附带 curl健康检查命令会直接失败。这时候要么用镜像自带的工具要么改用 wget或者在编写镜像时预留一个探测用的可执行文件。健康检查一旦失败配合 restart 策略才能形成闭环。我通常的做法是将 restart 设为 on-failure把健康检查命令里探测失败退出 1当作触发条件这样容器在健康检查连续失败后会重启。这个方案比单纯依赖应用进程退出更贴近业务。3.3 优雅退出stop 命令背后的启动参数启动命令还决定了容器停止时的行为。--stop-timeout 控制容器引擎发送停止信号后等待的时间默认值在很多环境中是 10 秒。如果你的应用需要更长时间清理连接或持久化状态要显式增大这个值。还有一个细节是停止信号本身。容器引擎默认发送 SIGTERM然后等超时再发 SIGKILL。应用要正确处理 SIGTERM才能优雅退出。如果应用对 SIGTERM 没有响应那启动命令设计得再好停服时也会出现连接断开、数据丢失。我之前遇到一个案例某模拟项目在停止时总是报container exited with code 137。这个退出码通常是被 SIGKILL 杀掉的表现表面上看是启动命令有问题实际排查后发现是应用没有监听 SIGTERM到了超时时间被 SIGKILL 强杀了。修改方式是应用层注册信号处理同时把 --stop-timeout 调整到 30 秒双管齐下才把退出流程理顺。4. 启动失败时的定位套路从退出码到环境变量的逐层验证4.1 区分创建失败和启动失败容器启动命令相关的问题如果按发生阶段划分一半以上其实是创建阶段就失败了而不是启动阶段。创建失败通常提示在 docker run 那一刻镜像不存在、参数格式错误、端口冲突、存储卷挂载路径不存在等。这类问题比较直接报错信息一般能指向某个具体参数。启动失败则是指容器创建成功但从状态机来看进入了 Exited 或 Restarting。这种情况最典型的表现是docker ps -a 能看到容器但状态不是 Up。我排查这类问题的固定顺序是先看退出码再看日志最后进容器复现。退出码是一个很好的第一判断依据退出码可能含义0进程主动正常退出1应用自身报错退出137被 SIGKILL 杀掉常见于 OOM 或手动强制停止143收到 SIGTERM 后退出常见于优雅退出流程125容器引擎自身启动失败126命令无法执行比如缺少执行权限127命令找不到比如入口点脚本里的程序路径不存在比如看到 127就不要再去折腾应用日志了先去检查启动命令里写的可执行文件路径是否真实存在。有时候镜像版本升级后可执行文件名变了但启动命令还是旧的就会稳定复现 127。4.2 用临时容器隔离变量最小化启动命令排查启动问题最有效的方式是把镜像里预设的东西和你额外注入的东西分开验证。我经常用一个最小化的启动命令来跑同一个镜像docker run --rm 某镜像 true如果这条命令能正常退出码 0说明镜像本身能拉起一个进程问题大概率出在你附加的参数上。然后再逐步加回环境变量、端口映射、卷挂载每加一层就执行一次直到某一步复现启动失败那这一步就是嫌疑最大的。这里有个小技巧在逐步加参数时用 --name 给容器起一个固定名失败后不要急着删先用 docker inspect 看一下 Mounts、Env、Config 这些字段往往能发现注入内容和你预期不一致的地方。比如环境变量里有不可见字符、卷挂载把配置目录覆盖成了空目录这类问题看代码不一定看得出来但看 inspect 输出一目了然。4.3 环境变量和卷挂载是启动命令最常见的杂质启动命令里携带的环境变量和卷挂载是导致启动失败的高发区。环境变量的问题集中在三个方面拼写错误导致应用读取不到值为空导致应用解析异常特殊字符导致应用配置格式错误。卷挂载的问题通常更隐蔽。比如你把宿主机的某个目录挂载到容器内的配置目录如果宿主机目录是空的镜像里原本准备好的默认配置就被覆盖了应用启动时找不到任何配置。另一种常见情况是把文件挂载到了目录上或者反过来导致读取失败。验证环境变量是否注入成功可以临时使用docker run --rm --env-file ./mysettings.env 某镜像 /usr/bin/env这条命令直接打印出容器内的环境变量可以快速确认有没有缺失、有没有多余、值是否符合预期。这类调试用的临时容器跑完就删没有任何副作用。5. 从单命令到编排启动命令的另一种表达方式5.1 容器引擎启动参数与编排字段的对照关系单机容器和编排平台在表达启动配置时名字不一样但底层概念是相通的。理解这套对应关系能把你在 docker run 里的经验平滑迁移过去。--restart 对应 restartPolicy-e 和 --env 对应 env-p 对应 ports但编排平台通常把映射关系和 Service 的端口声明分开-v 和 --mount 对应 volumes--network 对应网络模型但编排平台里的网络配置更抽象--entrypoint 和镜像名后的命令在编排平台里写作 command 和 entrypoint 两个独立字段我觉得最容易出错的是 command 字段的写法。在编排文件里command 可以写成字符串也可以写成列表。写成字符串时平台会按 shell 方式解析写成列表时不会经过 shell所以像 $VAR 这种变量展开就不生效。这个差异和容器启动命令的行为不完全一致刚迁移时很反直觉。5.2 查看正在运行容器的启动参数有时候你手头没有原始的启动命令只有一个在跑的容器。想要知道它是用什么参数启动的可以用 docker inspect。我常提取几个关键字段docker inspect 某容器 --format {{.Config.Entrypoint}} {{.Config.Cmd}} {{.Config.Env}} docker inspect 某容器 --format {{json .HostConfig.RestartPolicy}} docker inspect 某容器 --format {{json .NetworkSettings.Ports}}这样能拿到入口点、命令、环境变量、重启策略和端口映射。注意 inspect 里显示的是当前容器的配置不一定等于当初 docker run 的完整命令行。有些参数在容器运行后会被标准化比如卷挂载的路径格式。如果你想要一个接近原生命令行的视图也有第三方工具能根据容器配置反向组装出 docker run 形式的命令。这类工具只能接近还原不能做到 100% 一致但用来看懂容器怎么启动的已经足够。我在接手别人留下的容器环境时第一件事就是做一次反向还原把启动命令存成文档便于后续统一管理。5.3 启动命令的版本化与可复现性容器启动命令最大的痛点是它没有天然的版本管理。docker run 写在哪里它就在哪里可能是某条文档里的一段代码也可能是某次操作的一个历史记录。一旦环境重建命令的细小差异就会导致行为不一致。我在多个项目里的做法是将所有启动命令收敛到脚本文件或编排文件中。即使只是单机部署也用一份 docker-compose 文件来描述启动配置而不是依赖手写的 docker run。它的好处是启动命令被当作代码管理变更可追溯参数用配置文件组织不会散落在各个历史命令里。这个转移并不复杂。比如把一个 docker run 转换成编排文件的写法services: app: image: 某镜像 restart: on-failure environment: - APP_PORT8080 ports: - 127.0.0.1:18080:8080 healthcheck: test: [CMD, curl, -f, http://127.0.0.1:8080/health] interval: 10s timeout: 5s retries: 3这段配置基本把前面所有启动命令的关键参数都覆盖了并且还能表达健康检查。用文件管理启动配置之后我很少再遇到这个容器当初是怎么跑起来的这种问题了。把启动命令当作一类需要长期维护的工件而不是一次性输入是很重要的思路转变。无论你偏好单机命令还是编排配置我都建议针对每个服务保存一份标准化模板把环境变量、端口、资源限制、健康检查全部显式列出来。这样容器的启动行为才是可预期、可排查、可交接的。
