企业官网建设流程全解析

配置文件这三个字，在 Docker 这个圈子里其实是个很笼统的说法。我见过太多人把 Dockerfile 写得干干净净，容器一起就 OOM；也见过 compose 文件里 depends_on 写了一长串服务名，应用照样抢跑报连接拒绝；还有人改完 daemon.json 少了一个逗号，第二天整台机器上几十个容器全部起不来。Docker 的配置文件从来不是一份，而是至少五份，每份管的事情不一样，生效时机也不一样，改错地方比改错内容更浪费时间。这篇就把这五份东西摊开讲清楚：daemon.json 管引擎、Dockerfile 管构建、.dockerignore 管上下文、compose 文件管编排、命令行参数管运行时。看完你至少能做到两件事——知道自己要改的那一项该落在哪份文件里，以及改完之后用哪条命令确认它真的生效了，而不是靠重启大法碰运气。刚上手的朋友可以照着抄作业，已经在生产环境跑容器的朋友，建议重点看第 2 节和第 6 节，那两块踩坑密度最高。

1. 配置文件全景：先搞清楚你改的是哪一层

很多人排查配置问题的第一反应是"我明明改了"，但没想过自己改的那份文件根本管不到出问题的那一层。Docker 的配置是有明确分层边界的，跨界去改，改一百遍也没用。这一节先把地图画出来，后面几节再逐层拆。

1.1 五份配置文件，各管一段路

我把日常打交道的配置入口归成五类，按"从构建到运行"的顺序排：

这里有个特别容易混淆的点：构建期的配置写错了，运行时参数是补救不回来的。比如你在 Dockerfile 里用 shell 形式写了CMD node app.js，容器里的 1 号进程就变成了/bin/sh -c node app.js，你后面加多少运行时参数都没法让应用正确收到 SIGTERM，停止时就只能等超时被强杀。反过来，运行时参数写错了（比如内存给少了），你改 Dockerfile 重新构建也没用。分清这两条线，能省掉一大半无效调试。

1.2 覆盖关系：谁说了算

同一个配置项经常能在好几个地方出现，比如时区、环境变量、资源上限。优先级从高到低大致是：命令行参数 > compose 文件里的服务定义 > 镜像里 Dockerfile 的 ENV/CMD/EXPOSE 默认值。daemon.json 是个例外，它管的是引擎默认值，容器级参数一旦显式指定，就一定盖过它。

举个具体的：daemon.json 里配了"default-ulimits": {"nofile": {"Hard": 65536, "Soft": 65536}}，但你在docker run时加了--ulimit nofile=1024:1024，那容器里就是 1024，引擎默认值不起作用。再比如 Dockerfile 里写了EXPOSE 3000，这只是个元数据声明，不代表端口真的映射出去了，docker run -p不写照样外部访问不到。这些"看起来生效了其实没有"的项，是新手上手阶段最耗时间的坑。

提示：判断某个配置到底生效没有，别看文件，看docker inspect。容器级的看容器 inspect，引擎级的看docker info。文件只是输入，inspect 和 info 才是输出。

2. daemon.json：引擎级配置的取舍细节

daemon.json 是整台机器上所有容器共享的那份配置，改它的影响面最大，也最需要谨慎。我在实际项目里对这份文件的原则是：只放真正需要全局统一的项，能用容器参数解决的绝不写进 daemon.json。原因很简单，全局配置一旦出错，影响的是这台机器上所有容器，排查半径太大。

2.1 一份可以直接用的 daemon.json

下面这份是我在多数自建环境里会用的基线配置，字段不多，但每一项都有明确目的：

{ "data-root": "/data/docker", "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "3" }, "default-ulimits": { "nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 } }, "live-restore": true, "max-concurrent-downloads": 6, "default-address-pools": [ { "base": "172.31.0.0/16", "size": 24 } ] }

第一个字段># 1. 语法先过一遍 python3 -m json.tool /etc/docker/daemon.json > /dev/null && echo "JSON OK" # 2. 重启并看服务状态 systemctl daemon-reload systemctl restart docker systemctl is-active docker # 3. 确认关键项真的进去了 docker info --format '{{.DockerRootDir}}' docker info --format '{{.LoggingDriver}}' docker info --format '{{json .Plugins}}'

第三条是关键。很多人改完重启，服务是 active，就默认配置生效了，实际上如果文件里写错字段名，引擎会忽略这个字段而不是报错。>FROM node:20-bookworm-slim WORKDIR /app COPY . . # 源码放前面 RUN npm ci # 每次改一行代码，这层就要重装依赖 CMD ["node", "dist/main.js"]

这样写，你改一个注释，依赖就得重装一遍，一次构建多花两分钟。正确写法是把依赖清单单独拷进去：

FROM node:20-bookworm-slim AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build

package.json和锁文件不常变，这一层能长期命中缓存；源码变了只影响COPY . .之后的层。这个改动我每次给项目做构建优化都是第一刀，收益最直接。

还有一个细节：RUN指令尽量合并，但别为了合并把可读性牺牲掉。真正该合并的是那些必须在一个层里完成的关联操作，比如装包之后立刻清理缓存目录：

RUN apt-get update \ && apt-get install -y --no-install-recommends curl ca-certificates \ && rm -rf /var/lib/apt/lists/*

rm -rf /var/lib/apt/lists/*必须和 install 写在同一个RUN里。拆成两条指令，清理发生在下一层，上一层里那几十兆的包索引依然会被打进镜像，等于白删。

3.2 多阶段构建和 .dockerignore 的配合

多阶段构建的价值在于把构建工具链和运行时彻底分开。一个前端项目，构建阶段需要 node、依赖包、源码，运行时只需要一个静态文件目录；一个 Java 项目，构建阶段需要完整的 JDK 和 Maven 仓库，运行时只需要一个 JRE 加一个 jar 包。分开之后镜像体积经常能小一半以上。

FROM node:20-bookworm-slim AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build FROM node:20-bookworm-slim ENV NODE_ENV=production WORKDIR /app RUN groupadd -r app && useradd -r -g app app COPY --from=builder --chown=app:app /app/node_modules ./node_modules COPY --from=builder --chown=app:app /app/dist ./dist USER app EXPOSE 3000 ENTRYPOINT ["node", "dist/main.js"]

注意COPY --from=builder后面的--chown。不写这个，拷过来的文件属主是 root，而你又用USER app降权了，运行时读不到自己的文件，报权限错误。这种问题在构建阶段完全看不出来，只有真正跑起来才暴露。

.dockerignore是配合多阶段构建的另一个必需品。它的作用是在把文件发给构建引擎之前就裁掉不需要的部分。下面这份是我在 Node 项目里的常用模板：

node_modules .git .gitignore dist coverage *.log .env .env.* Dockerfile docker-compose.yml

为什么要写.env？因为构建上下文是会被完整传给引擎的，如果上下文里有密钥文件，哪怕最终没被 COPY 进镜像，也存在泄露风险。别指望"我没 COPY 就没事"。

还有一个实测数据：一个中型前端项目，全量上下文可能有 800MB（主要是node_modules和.git），写好 ignore 之后能压到 10MB 以内。构建开始时那句Sending build context to Docker daemon的耗时，会从十几秒掉到一秒以内。构建机在内网、传输慢的环境里，这个差异更夸张。

3.3 三个常被忽略的指令细节

第一，exec 形式和 shell 形式的区别。ENTRYPOINT ["node", "dist/main.js"]是 exec 形式，进程直接是 node，PID 为 1，能正常接收 SIGTERM 优雅退出；ENTRYPOINT node dist/main.js是 shell 形式，外面套了一层 sh，信号传不到 node，容器停止时只能等--time超时后强杀。这个差别在生产环境的滚动发布里非常明显，表现是每次发版都要多等十几秒。除非你确实需要 shell 来做变量展开，否则一律用 exec 形式。

第二，ARG 和 ENV 的边界。ARG只在构建期存在，构建完就没了；ENV会写进镜像，容器运行时也能读到。所以构建参数（比如内部仓库地址、构建号）用ARG，运行配置（时区、语言、运行模式）用ENV。把密钥类的东西写进ENV尤其危险，因为docker history能把每一层的 ENV 都打出来。

第三，基础镜像别用 latest。latest 是个可变标签，今天拉到的东西明天可能就变了，构建结果不可复现。用具体的版本标签，甚至更稳妥的做法是锁定到版本加小版本号。我踩过一次坑：同一个 Dockerfile 在开发机上构建正常，在构建机上失败，最后查出来是两边基础镜像的 latest 指向不同的小版本，系统库版本不一致导致依赖装不上。从那以后所有基础镜像全部锁版本。

4. docker-compose.yml：编排层配置的语义陷阱

compose 文件语法看着直白，但有几个字段的字面意思和实际行为不一致，属于典型的"看文档以为懂了，跑起来才发现不是那么回事"。这一节重点拆这几个。

4.1 服务定义的最小骨架

services: api: build: context: . dockerfile: Dockerfile args: BUILD_VERSION: "20240115" image: registry.internal.example.local/app/api:20240115 environment: TZ: Asia/Shanghai NODE_ENV: production env_file: - .env.runtime ports: - "127.0.0.1:3000:3000" mem_limit: 1g cpus: 1.5 restart: unless-stopped healthcheck: test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/healthz"] interval: 20s timeout: 3s retries: 3 start_period: 30s depends_on: db: condition: service_healthy db: image: postgres:16-alpine environment: POSTGRES_PASSWORD: ${DB_PASSWORD} healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 3s retries: 5

几个点单独说。version字段在新版 compose 里已经不需要了，写了会有告警，直接删掉更省心。端口映射我习惯写成127.0.0.1:3000:3000，只绑本机回环，外部通过前置网关访问。直接写3000:3000会监听所有网卡，在云主机上等于把服务裸露出去，这是很常见的低级失误。

4.2 healthcheck 和 depends_on 的真实语义

depends_on只保证启动顺序，不保证依赖服务已经能用。这是最容易误解的一条。不写condition的情况下，compose 只是先起 db 再起 api，db 进程起来了但还没初始化完，api 照样连不上。加了condition: service_healthy，才会等健康检查通过再启动下一个服务。

健康检查的参数怎么定，值得算一算。start_period是"宽容期"，这期间内检查失败不计入retries；超过之后，连续失败retries次才标记为 unhealthy。总容忍时间大致是start_period + interval × retries。上面 db 的配置是 30s（默认 start_period 为 0，这里我按 interval × retries 算）——10s × 5 = 50s。也就是说，数据库 50 秒内还没 ready，compose 就会判定它不健康。如果你的数据库首次启动要做数据初始化，这个时间要放宽，否则会出现"健康检查判死、但服务其实只是慢"的误杀。

反过来，interval也别设太小。设成 1s 看着灵敏，实际上每次检查都要起一个进程（CMD形式）或者执行一段脚本，容器多的时候这部分开销不可忽略。10s 到 30s 是比较合理区间。

提示：健康检查的test用CMD形式时，命令在容器内直接执行，不经过 shell，所以不能写管道和重定向。需要 shell 特性就用CMD-SHELL，但要注意它会多一个 sh 进程。

4.3 变量插值和 .env 的优先级

compose 的变量有三个来源：shell 环境变量、.env文件、compose 文件里的env_file指令。前两个是给 compose 文件本身做插值的，第三个是注入到容器里的环境变量，作用对象完全不同，很多人把这两件事混在一起。

优先级上，shell 里已有的环境变量会盖过.env文件里的同名项。这个特性在 CI 里很有用：.env里放本地开发的默认值，CI 里通过环境变量注入真实值，一套文件两边用。但反过来也容易出问题——你改了.env里的值却没生效，很可能是当前 shell 里残留了同名变量，echo $VAR查一下就知道。

env_file指向的文件里的内容会原样注入容器，不参与 compose 文件插值。所以像数据库密码这种只给容器用的值，放env_file更合适；而镜像标签、端口这类需要写进 compose 文件的值，才放.env。

5. 运行时配置：资源、网络、挂载三件套

容器创建之后再改运行时参数是不行的，只能删了重建。所以这三个部分在创建前就要想清楚，尤其是资源限制，给少了服务起不来，给多了宿主机扛不住。

5.1 CPU 和内存参数怎么算

CPU 相关的参数里，--cpus最直观，1.5表示最多用 1.5 个核。它背后对应的是 CFS 的 quota/period 机制：period 默认 100000 微秒（100ms），--cpus 1.5就是把 quota 设成 150000 微秒。也就是说，在每一个 100ms 的周期里，这个容器最多累计运行 150ms 的 CPU 时间——注意是"累计"，多核并行也算在里面。

--cpu-shares是另一套逻辑，它是相对权重，不是上限。两个容器都设成 1024，争抢时平分；一个 1024 一个 512，争抢时按 2:1 分配。没有争抢的时候，cpu-shares完全不影响性能。所以"限流"用--cpus，"保底"用--cpu-shares，这两个别搞混。

内存这边，-m 1g是硬上限，超过就 OOM Kill。--memory-swap的行为要看 cgroup 版本：只设-m不设 swap 时，swap 上限默认是内存的两倍；把--memory-swap显式设成和-m相同的值，表示禁用 swap。生产环境我一般禁用 swap，因为容器用 swap 会导致延迟抖动，问题还特别难复现。

Java 服务这里有个必须注意的点：JDK 10 之前不认容器内存限制，会按宿主机的物理内存去算堆大小，-m 1g的容器里 JVM 可能尝试申请 4G 堆，直接 OOM。现在的做法是显式指定比例：

docker run -d \ --name api \ -m 2g --memory-swap 2g \ --cpus 2 \ -e JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70 -XX:InitialRAMPercentage=40" \ registry.internal.example.local/app/api:20240115

MaxRAMPercentage=70意味着堆上限是容器内存的 70%，也就是 1.4G，剩下的留给元空间、线程栈、直接内存。这个比例别设到 80% 以上，堆外内存一涨就 OOM，而且 OOM 的现场往往看不出是堆的问题。

5.2 网络模式的选择逻辑

默认的 bridge 模式适合绝大多数场景，容器通过 NAT 访问外部，外部通过端口映射访问容器。自定义 bridge 网络比默认 bridge 多一个能力：容器之间可以用服务名互相解析。默认 bridge 上只能用 IP，或者靠--link（已废弃），所以多容器互访一定要建自定义网络。

host模式直接用宿主机网络栈，没有 NAT，性能略好，端口也不用映射。代价是端口冲突会直接暴露，而且容器内看到的网络信息和宿主机完全一样，两个容器不能同时监听同一个端口。我在跑对网络延迟极敏感的服务时会用，普通业务没必要。

none模式就是完全无网络，只有回环。适合纯计算任务，比如批量转码、离线数据处理，能减少攻击面。

一个常见坑是 DNS。容器内的 DNS 默认继承宿主机的/etc/resolv.conf，但宿主机如果配的是本地解析服务（比如127.0.0.53），容器里访问这个地址是访问不到的，因为容器有自己的网络命名空间。表现是容器内能 ping 通 IP 但域名解析失败。解决办法是在创建时显式指定：--dns 8.8.8.8之类，或者在 daemon.json 里配全局 DNS。

5.3 挂载方式与权限映射

挂载有两种：bind mount（直接挂宿主机目录）和 volume（由引擎管理的存储）。选型逻辑很简单：需要你在宿主机上直接看、直接改的文件用 bind mount；纯容器内部数据用 volume。volume 在性能上通常更好（尤其在非 Linux 宿主上），而且不受宿主机目录权限影响。

权限是 bind mount 最常出问题的地方。容器内进程的 UID 和宿主机文件的 UID 对不上，就会 permission denied。我常用的处理方式是在运行参数里显式指定 UID 和 GID：

docker run -d \ --name worker \ -v /data/jobs:/app/jobs \ -u "$(id -u):$(id -g)" \ --read-only \ --tmpfs /tmp:rw,size=256m \ registry.internal.example.local/app/worker:20240115

-u让容器内进程用当前宿主机用户的身份跑，挂载目录的读写权限自然就对上了。--read-only把根文件系统设成只读，配合--tmpfs /tmp给临时文件留个可写空间，能挡掉相当一部分"容器内被写入恶意文件"的风险，而且不影响业务正常运行——真正需要写的目录已经在-v里单独挂出来了。

注意：-v挂载如果宿主路径不存在，Docker 会自动创建一个目录。这会导致一个经典事故：本来想挂一个配置文件/etc/app/config.yml，路径打错了，Docker 创建一个同名空目录挂上去，容器启动时读配置失败，报错信息还特别绕。用--mount type=bind,source=...,target=...语法的话，路径不存在会直接报错，更安全。新项目我一律用--mount。

6. 常见问题与排查技巧实录

配置文件类的问题有个共同特征：报错信息往往指向症状，不指向原因。所以排查靠的不是读报错，而是建立"现象—可能原因—验证命令"的对应关系。下面这张表是我这几年攒下来的，覆盖了八成以上的高频场景。

6.1 高频问题速查表

表格只是索引，真正定位还得靠命令组合。下面这套是我固定的排查动作。

6.2 一套能覆盖多数场景的命令组合

# 1. 容器为什么退出：看状态码和最后时刻的日志 docker inspect --format '{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' <container> docker logs --tail 100 <container> # 2. 容器实际生效的配置：比看文件靠谱 docker inspect --format '{{json .HostConfig}}' <container> | python3 -m json.tool docker inspect --format '{{json .Config.Env}}' <container> | python3 -m json.tool # 3. 资源占用实况 docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}' # 4. 磁盘分布 docker system df -v | head -40 # 5. 引擎级事件流，看容器反复重启的节奏 docker events --filter 'type=container' --since 10m

OOMKilled这个字段特别有用。容器不明原因退出时，先看它是不是 true，如果是，方向立刻就清楚了——不是代码 bug，是内存给少了。这个字段比翻日志快得多，我基本上第一时间就看它。

docker events也值得多用。服务反复重启的时候，日志只能看到每次启动的内容，看不出重启的节奏。events 流里能清楚看到 start、die、start、die 的间隔，间隔固定说明是崩溃重启，间隔递增说明是退避重试，两种情况的排查方向完全不同。

6.3 几个只有踩过才知道的细节

第一，改了 Dockerfile 却没重新构建。compose 里如果同时写了build和image，docker compose up在没有--build的情况下可能直接用本地已有镜像，你的 Dockerfile 改动根本没被应用。表现是"我明明改了"但行为没变。习惯上加--build，或者只写build不写image（代价是每次都会尝试构建）。

第二，时区问题比想象中普遍。基础镜像默认多是 UTC，容器里date一看差八小时，日志时间全对不上。解决方式是在 compose 里统一加TZ环境变量，别指望每个镜像都自带时区数据。有些精简镜像连/usr/share/zoneinfo都没有，只设TZ也不生效，还得装tzdata。这个坑我在至少三个不同项目里遇到过。

第三，容器里的 1 号进程要能处理信号。前面提过 exec 形式，这里补充一个更隐蔽的情况：用 shell 脚本做 entrypoint，脚本里exec忘了写，业务进程就变成了子进程，信号到不了它手上。典型表现是每次停容器都要等满 10 秒然后被 SIGKILL，日志里看不到优雅关闭的记录。写 entrypoint 脚本时，最后一行启动业务务必带exec。

第四，健康检查失败不一定是服务的问题。我遇到过一次健康检查一直 unhealthy，但服务实际可用，最后查出来是健康检查用的curl在精简镜像里根本不存在，命令直接返回非零。健康检查的命令要在目标镜像里验证过再用，别想当然。

第五，docker compose down和down -v的区别要记牢。前者只删容器和网络，数据卷保留；后者连卷一起删。生产环境敲错一次，数据就没了。我在测试环境养成的习惯是down之后手动确认卷还在，再决定要不要清。这个动作慢三秒，能避免很多不可逆的事故。

我个人在实际操作中的体会是，Docker 的配置文件难的不是语法，而是边界感——知道哪一项该写在哪一层，知道改完之后哪个命令能证明它生效了。把这几份文件的职责分清楚，再配上一套固定的验证动作，绝大部分"配置不生效"的问题都会在五分钟内定位到。真正难缠的那些，往往是两份文件互相覆盖造成的，这时候docker inspect看到的实际值，永远比你自己以为的配置更可信。