Dockerfile 自定義鏡像、Docker Compose 編排、Docker 鏡像倉(cāng)庫(kù)這三件事幾乎是每個(gè)后端或運(yùn)維同學(xué)繞不開的一組基礎(chǔ)能力。單看每一個(gè)都不難難的是把它們串成一條順滑的交付鏈路代碼改了鏡像能穩(wěn)定重建本地跑通換臺(tái)機(jī)器也能一鍵起來(lái)鏡像推到倉(cāng)庫(kù)別人拉下來(lái)不會(huì)因?yàn)闃?biāo)簽亂飛而拉錯(cuò)版本。我見(jiàn)過(guò)太多項(xiàng)目卡在中間某一環(huán)——Dockerfile 寫得像流水賬、Compose 文件復(fù)制粘貼改了三個(gè)月沒(méi)人敢動(dòng)、私有倉(cāng)庫(kù)起了一個(gè)卻因?yàn)樽C書問(wèn)題全組改用別的方式傳鏡像。這篇就把這三塊按我實(shí)際踩過(guò)的順序拆開講從分層緩存的底層邏輯到 Compose 的健康檢查寫法再到私有倉(cāng)庫(kù)的 TLS 配置和存儲(chǔ)回收每個(gè)環(huán)節(jié)都給出能直接抄的參數(shù)和命令也會(huì)說(shuō)明我為什么這么選。剛接觸容器的新手可以照著做一遍已經(jīng)在用但總覺(jué)得別扭的老手大概率能在避坑那幾節(jié)找到共鳴。1. 先把三個(gè)東西的邊界理清楚很多人上手就把這三樣?xùn)|西混在一起學(xué)結(jié)果腦子里是一鍋粥。我用一句話概括它們的分工Dockerfile 負(fù)責(zé)造Compose 負(fù)責(zé)組倉(cāng)庫(kù)負(fù)責(zé)存和分發(fā)。造出來(lái)的東西要能被組起來(lái)組起來(lái)的東西要能被別人拿到這三步是一條線上的三個(gè)節(jié)點(diǎn)任何一環(huán)偷懶后面都會(huì)加倍還回來(lái)。1.1 一條鏡像從代碼到運(yùn)行的完整鏈路我把一次完整的交付拆成六步你對(duì)照自己的項(xiàng)目看看斷在哪一步。第一步開發(fā)者本地寫代碼改完提交第二步CI 或者本機(jī)執(zhí)行docker buildDockerfile 逐條指令生成一層層文件系統(tǒng)快照最終產(chǎn)出一個(gè)帶標(biāo)簽的鏡像第三步docker push把鏡像分層推到倉(cāng)庫(kù)注意只有本地不存在的層才會(huì)真正上傳這也是為什么第二次推送往往快得多第四步目標(biāo)機(jī)器docker pull按 manifest 里的 digest 把各層拉下來(lái)組裝第五步Compose 讀取 yaml創(chuàng)建網(wǎng)絡(luò)、掛載卷、按依賴順序起容器第六步健康檢查通過(guò)流量切進(jìn)來(lái)。這條鏈路上有三個(gè)時(shí)間點(diǎn)特別關(guān)鍵構(gòu)建時(shí)的緩存命中率、拉取時(shí)的層復(fù)用率、啟動(dòng)時(shí)的就緒判斷。緩存命中率高構(gòu)建就從幾分鐘降到幾十秒層復(fù)用率高一次發(fā)布只傳改動(dòng)的那幾十兆就緒判斷做對(duì)了滾動(dòng)更新才不會(huì)出現(xiàn)新容器還沒(méi)連上數(shù)據(jù)庫(kù)老容器已經(jīng)被干掉的尷尬。后面所有優(yōu)化本質(zhì)上都是在摳這三個(gè)點(diǎn)。我見(jiàn)過(guò)一個(gè)典型的反面案例某團(tuán)隊(duì)把COPY . .放在 Dockerfile 第二行緊接著才RUN npm install。結(jié)果每次改一行 README整個(gè)依賴安裝層全部失效構(gòu)建時(shí)間穩(wěn)定在四分鐘以上。把這兩行的順序調(diào)過(guò)來(lái)配合.dockerignore構(gòu)建時(shí)間直接掉到二十幾秒。改動(dòng)量不到五行收益卻是幾十倍這就是理解鏈路順序的價(jià)值。1.2 為什么我勸你徹底放棄 docker commit新手最容易走的捷徑是起一個(gè)基礎(chǔ)容器進(jìn)去apt install、改配置、裝依賴折騰滿意了docker commit一下鏡像就有了。第一次這么干會(huì)覺(jué)得特別爽但它埋的雷比省的時(shí)間多得多。最直接的問(wèn)題是不可復(fù)現(xiàn)。三個(gè)月后你需要在這個(gè)鏡像上加一個(gè)包誰(shuí)也不知道當(dāng)初在容器里手敲過(guò)哪些命令是改了/etc/apt/sources.list還是臨時(shí)下過(guò)一個(gè)二進(jìn)制。第二個(gè)問(wèn)題是體積失控commit 會(huì)把容器運(yùn)行期間產(chǎn)生的所有臨時(shí)文件、日志、緩存全部固化進(jìn)去一個(gè)本該 200MB 的鏡像能做到 1.5GB。第三個(gè)問(wèn)題是沒(méi)有分層每次 commit 都是一整層新的推一次倉(cāng)庫(kù)傳幾百兆團(tuán)隊(duì)網(wǎng)速直接被拖垮。Dockerfile 的價(jià)值不在于能構(gòu)建鏡像而在于它是一份可審查、可版本控制、可被他人復(fù)現(xiàn)的構(gòu)建說(shuō)明書。誰(shuí)改了什么、為什么加這個(gè)環(huán)境變量git blame一目了然。所以我的態(tài)度很明確除了臨時(shí)排查問(wèn)題任何時(shí)候都不要用 commit 產(chǎn)出要交付的鏡像。真要臨時(shí)進(jìn)容器調(diào)試用docker exec -it進(jìn)去看完就退別把改動(dòng)當(dāng)成成果。1.3 Compose 的適用邊界什么時(shí)候該上什么時(shí)候別硬上Compose 解決的問(wèn)題是一臺(tái)機(jī)器上多個(gè)容器的協(xié)作關(guān)系。典型場(chǎng)景是應(yīng)用 數(shù)據(jù)庫(kù) 緩存 反向代理四五個(gè)服務(wù)本地開發(fā)、測(cè)試環(huán)境、小規(guī)模單機(jī)部署都用得上。它的好處是把docker run那一長(zhǎng)串參數(shù)固化進(jìn)文件端口、卷、環(huán)境變量、網(wǎng)絡(luò)別名全部聲明式表達(dá)新人克隆倉(cāng)庫(kù)就能跑起來(lái)不用問(wèn)你那個(gè)數(shù)據(jù)庫(kù)密碼是多少。但它有明確的邊界。第一只管單機(jī)。多節(jié)點(diǎn)調(diào)度、跨主機(jī)網(wǎng)絡(luò)、自動(dòng)擴(kuò)縮容這些不是它的職責(zé)硬要往上疊就得引入額外的編排系統(tǒng)。第二沒(méi)有內(nèi)置的滾動(dòng)更新和回滾docker compose up -d是停舊起新中間有短暫中斷對(duì)可用性要求高的服務(wù)得接受這點(diǎn)。第三配置漂移難發(fā)現(xiàn)如果有人docker exec進(jìn)去手改了配置重啟就沒(méi)了這既是缺點(diǎn)也是優(yōu)點(diǎn)。我的判斷標(biāo)準(zhǔn)是單機(jī)、服務(wù)數(shù)量在十個(gè)以內(nèi)、不需要跨節(jié)點(diǎn)容災(zāi)Compose 完全夠用別為了顯得專業(yè)提前上重編排運(yùn)維成本會(huì)反過(guò)來(lái)咬你。等真的出現(xiàn)多機(jī)需求了再遷移那時(shí)候你對(duì)服務(wù)間的依賴關(guān)系已經(jīng)摸得很清楚遷移反而快。1.4 鏡像倉(cāng)庫(kù)不只是存鏡像的地方很多人對(duì)倉(cāng)庫(kù)的理解停留在能 push 能 pull 就行于是起個(gè)最簡(jiǎn)陋的服務(wù)放內(nèi)網(wǎng)。用著用著就出問(wèn)題誰(shuí)都能推 latest某天線上拉到的 latest 和昨天的不一樣磁盤漲到 100% 才發(fā)現(xiàn)沒(méi)人清理出了安全問(wèn)題想查某個(gè)鏡像里到底裝了什么版本的基礎(chǔ)鏡像是哪天的無(wú)從下手。一個(gè)真正可用的倉(cāng)庫(kù)至少要提供四件事訪問(wèn)控制誰(shuí)能推、誰(shuí)能拉、按項(xiàng)目隔離、標(biāo)簽規(guī)范配合 CI 強(qiáng)制約束不允許裸推 latest、存儲(chǔ)治理保留策略 垃圾回收、可追溯鏡像 digest、推送人、推送時(shí)間。前兩項(xiàng)靠流程和倉(cāng)庫(kù)自身能力后兩項(xiàng)靠定時(shí)任務(wù)。這幾件事在單機(jī) registry 上要自己搭在企業(yè)級(jí)方案里通常是現(xiàn)成的。選型的時(shí)候別只看能不能跑起來(lái)要看半年后誰(shuí)來(lái)維護(hù)它。2. Dockerfile把鏡像當(dāng)代碼寫寫 Dockerfile 的正確心態(tài)是寫代碼——它會(huì)被 review、會(huì)被 diff、會(huì)在半年后被修改。所以可讀性、層數(shù)控制、緩存友好度都得在寫的時(shí)候就考慮進(jìn)去而不是等構(gòu)建慢到受不了再回頭重構(gòu)。2.1 分層緩存是理解一切優(yōu)化行為的鑰匙Docker 構(gòu)建鏡像時(shí)每條指令生成一層每層帶一個(gè)基于父層 ID 指令內(nèi)容算出來(lái)的哈希。構(gòu)建時(shí)逐層比對(duì)一旦某層的哈希在本地緩存里存在就直接復(fù)用不再執(zhí)行。注意這里的關(guān)鍵哈希只跟指令文本和父層有關(guān)跟指令執(zhí)行的結(jié)果無(wú)關(guān)。這意味著只要指令字符串變了哪怕只是多一個(gè)空格這層和它之后的所有層全部失效。由此推導(dǎo)出的三條鐵律變化頻率低的指令放前面變化頻率高的放后面把安裝依賴和拷貝源碼徹底分開能用一條RUN干完的事別拆成三條。第三條的原理是每條RUN都是一層層數(shù)多了鏡像的元數(shù)據(jù)開銷變大而且中間產(chǎn)物沒(méi)法在同一條指令內(nèi)清理。舉個(gè)最常見(jiàn)的 Node 項(xiàng)目寫法我會(huì)這樣排FROM node:20-alpine AS base WORKDIR /app # 只拷貝依賴清單源碼變化不影響這一層緩存 COPY package.json package-lock.json ./ RUN npm ci --omitdev npm cache clean --force # 源碼放在最后 COPY . . CMD [node, server.js]npm ci比npm install更適合構(gòu)建場(chǎng)景它嚴(yán)格按 lock 文件安裝結(jié)果確定而且會(huì)先清空 node_modules避免上次殘留污染。--omitdev跳過(guò)開發(fā)依賴npm cache clean --force在同一層里清掉緩存兩者加起來(lái)通常能省一百多兆。對(duì)比一下 Java 項(xiàng)目邏輯完全一樣只是清單文件換成pom.xmlFROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn -B dependency:go-offline COPY src ./src RUN mvn -B clean package -DskipTestsdependency:go-offline這一句是精髓它把依賴提前拉到本地倉(cāng)庫(kù)形成一個(gè)獨(dú)立緩存層。實(shí)測(cè)下來(lái)沒(méi)加這句時(shí)改一行 Java 代碼要重下全部依賴加了之后增量構(gòu)建基本在十秒級(jí)。注意COPY . .之前一定要有.dockerignore否則node_modules、.git、target這些目錄會(huì)被打進(jìn)構(gòu)建上下文光是傳輸上下文就能耗掉幾十秒而且可能覆蓋掉容器內(nèi)剛裝好的依賴。2.2 指令選擇的細(xì)節(jié)賬COPY和ADD的區(qū)別被講爛了但真正要緊的部分是ADD會(huì)偷偷解壓本地 tar 包、會(huì)去拉遠(yuǎn)程 URL這兩個(gè)貼心功能會(huì)讓構(gòu)建行為變得不可預(yù)測(cè)。遠(yuǎn)程 URL 的下載不進(jìn)緩存校驗(yàn)內(nèi)容變了也不會(huì)觸發(fā)重建。所以除非你確實(shí)需要解壓一個(gè)本地壓縮包否則一律用COPY。RUN的寫法有個(gè)流傳很久但其實(shí)是錯(cuò)誤的做法把a(bǔ)pt-get update和apt-get install分成兩條RUN。分開寫的話update 那層會(huì)被緩存很久等你半年后新增一個(gè)包時(shí)install 用的是半年前的索引輕則裝到舊版本重則 404 直接失敗。正確寫法是合并成一條并在末尾清理RUN apt-get update \ apt-get install -y --no-install-recommends curl tzdata \ rm -rf /var/lib/apt/lists/*--no-install-recommends能擋掉一大批推薦包rm -rf必須在同一條指令里執(zhí)行否則刪除動(dòng)作在下一層上一層的大小照樣算進(jìn)鏡像。ENV和ARG常被混用。ARG只在構(gòu)建期有效構(gòu)建完就消失適合傳版本號(hào)、鏡像源地址這類構(gòu)建參數(shù)ENV會(huì)寫進(jìn)鏡像的配置里容器運(yùn)行時(shí)也能讀到適合傳時(shí)區(qū)、語(yǔ)言編碼、運(yùn)行模式。這里有個(gè)安全提醒不要把密鑰、令牌通過(guò)ARG或ENV傳進(jìn)去它們會(huì)留在鏡像歷史里docker history一條命令就能看見(jiàn)。CMD和ENTRYPOINT的 shell 形式與 exec 形式的差異是信號(hào)處理問(wèn)題的根源。寫成CMD node server.jsshell 形式實(shí)際啟動(dòng)的是/bin/sh -c node server.js你的應(yīng)用是 sh 的子進(jìn)程PID 1 是 sh。sh 不會(huì)轉(zhuǎn)發(fā) SIGTERMdocker stop發(fā)信號(hào)后應(yīng)用收不到只能等十秒超時(shí)被 SIGKILL 強(qiáng)殺優(yōu)雅關(guān)閉邏輯全部失效。寫成CMD [node, server.js]exec 形式node 直接是 PID 1信號(hào)正常。EXPOSE只是文檔聲明不實(shí)際開放端口真正映射靠-p或 Compose 的ports。但它是很好的自描述信息建議寫上。HEALTHCHECK后面在 Compose 那節(jié)細(xì)說(shuō)它在鏡像里定義一次所有用這個(gè)鏡像的地方都繼承。2.3 多階段構(gòu)建一個(gè) Java 服務(wù)的體積從 800MB 到 180MB多階段構(gòu)建是 Dockerfile 里收益最大的一招。核心思想編譯環(huán)境臃腫但只在構(gòu)建期需要運(yùn)行環(huán)境要精簡(jiǎn)。用多個(gè)FROM階段最后一個(gè)階段只COPY --from前一個(gè)階段的產(chǎn)物。以 Spring Boot 為例不用多階段時(shí)通常是把 jar 拷進(jìn)一個(gè)帶 JDK 的鏡像動(dòng)輒七八百兆。改成下面這樣FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn -B dependency:go-offline COPY src ./src RUN mvn -B clean package -DskipTests FROM eclipse-temurin:17-jre-alpine WORKDIR /app RUN addgroup -S app adduser -S -G app app COPY --frombuilder /build/target/*.jar app.jar USER app EXPOSE 8080 ENTRYPOINT [java, -XX:MaxRAMPercentage75, -jar, app.jar]最終鏡像只有 JRE 加一個(gè) jar實(shí)測(cè)一般在一百八到兩百二十兆之間取決于依賴多少。里面有幾點(diǎn)值得說(shuō)MaxRAMPercentage75讓 JVM 按容器內(nèi)存限制的百分比估算堆大小比寫死-Xmx更適應(yīng)不同規(guī)格的部署adduser創(chuàng)建非 root 用戶USER切過(guò)去后面第 2.5 節(jié)細(xì)講COPY --frombuilder只搬 jarMaven 的本地倉(cāng)庫(kù)、源碼、編譯中間件一概不帶。前端項(xiàng)目同理構(gòu)建階段用 node 打包出靜態(tài)文件運(yùn)行階段換成反向代理鏡像只把dist目錄拷過(guò)去鏡像能從 1GB 降到 50MB 左右。這種編譯環(huán)境和運(yùn)行環(huán)境徹底分離的思路適用面比想象中廣任何需要編譯產(chǎn)物的語(yǔ)言都能用。2.4 基礎(chǔ)鏡像選型對(duì)照表與 musl 的坑基礎(chǔ)鏡像選錯(cuò)后面要么體積下不來(lái)要么跑起來(lái)就崩。我按常見(jiàn)選項(xiàng)列個(gè)對(duì)照基礎(chǔ)鏡像類型體積量級(jí)優(yōu)點(diǎn)需要注意的地方alpine5–10MB極小攻擊面小用 musl libc某些預(yù)編譯二進(jìn)制跑不了裝包用 apk命令和 apt 不同debian-slim25–40MB兼容性好glibc 完整比 alpine 大一圈包管理器是 apt完整發(fā)行版70–120MB工具齊全調(diào)試方便體積大無(wú)用包多distroless類20–60MB無(wú) shell、無(wú)包管理器安全性高沒(méi)法進(jìn)容器排查日志全靠應(yīng)用輸出scratch0絕對(duì)最小完全空只適合靜態(tài)編譯的二進(jìn)制Alpine 的坑值得單獨(dú)說(shuō)因?yàn)槲也冗^(guò)。它的 C 運(yùn)行庫(kù)是 musl不是廣泛使用的 glibc。純 Go 靜態(tài)編譯的程序、Python 的解釋器都沒(méi)問(wèn)題但某些依賴 glibc 特性的預(yù)編譯二進(jìn)制比如一些原生擴(kuò)展、某些數(shù)據(jù)庫(kù)客戶端放進(jìn)去會(huì)報(bào)not found或者奇怪的符號(hào)錯(cuò)誤排查起來(lái)非常費(fèi)勁因?yàn)閳?bào)錯(cuò)信息完全不指向根因。我的經(jīng)驗(yàn)是不確定就先上 debian-slim等確認(rèn)沒(méi)問(wèn)題再往 alpine 遷。為了省那二十兆搭進(jìn)去半天排查時(shí)間不劃算。distroless適合安全要求高的生產(chǎn)環(huán)境但沒(méi)有 shell 意味著出問(wèn)題時(shí)你沒(méi)法exec進(jìn)去看進(jìn)程、看文件只能靠完善的日志和監(jiān)控。團(tuán)隊(duì)排查能力沒(méi)到那個(gè)水平之前別用。2.5 安全性收尾非 root、只讀、健康檢查鏡像默認(rèn)以 root 運(yùn)行容器內(nèi)進(jìn)程這在單機(jī)開發(fā)環(huán)境問(wèn)題不大但在多租戶或者對(duì)外服務(wù)的場(chǎng)景里是明顯風(fēng)險(xiǎn)點(diǎn)。加一個(gè)普通用戶的成本極低RUN useradd -u 1000 -m -s /bin/bash appuser \ chown -R appuser:appuser /app USER appuser注意chown要在USER之前完成順序反了會(huì)因?yàn)闆](méi)有權(quán)限而失敗。另外創(chuàng)建用戶這一步盡量和后續(xù)的chown合并在同一條指令里避免多一層。時(shí)區(qū)是另一個(gè)高頻問(wèn)題。容器默認(rèn) UTC日志時(shí)間比東八區(qū)差八小時(shí)排查問(wèn)題時(shí)對(duì)時(shí)間戳能對(duì)到懷疑人生。做法是裝tzdata并設(shè)置環(huán)境變量ENV TZAsia/Shanghai LANGC.UTF-8 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezoneLANG也別漏某些應(yīng)用在非 UTF-8 環(huán)境下處理中文會(huì)出亂碼尤其是日志輸出和文件讀寫。HEALTHCHECK健康檢查在鏡像里定義一次即可HEALTHCHECK --interval30s --timeout3s --start-period40s --retries3 \ CMD curl -fsS http://localhost:8080/actuator/health || exit 1start-period很關(guān)鍵它告訴 Docker 在這段時(shí)間內(nèi)的失敗不算數(shù)給應(yīng)用留足啟動(dòng)時(shí)間。沒(méi)有這個(gè)參數(shù)啟動(dòng)慢的 Java 服務(wù)會(huì)被反復(fù)判定為不健康。注意檢查命令用的工具必須在鏡像里存在alpine 下curl默認(rèn)沒(méi)裝要么裝要么換成wget。2.6 .dockerignore 與構(gòu)建上下文.dockerignore是被嚴(yán)重低估的文件。它的作用和.gitignore類似但影響的是發(fā)送給 Docker 守護(hù)進(jìn)程的構(gòu)建上下文。這個(gè)上下文在構(gòu)建開始時(shí)會(huì)被整個(gè)打包傳輸一個(gè)帶node_modules的前端項(xiàng)目上下文輕松幾百兆每次構(gòu)建光傳輸就要幾十秒。我常用的模板.git .gitignore node_modules target build dist *.log logs .env.local .idea .vscode README.md docker-compose*.yml兩個(gè)細(xì)節(jié)一是不要忽略package-lock.json或pom.xml那是構(gòu)建必需的二是如果一個(gè)文件既在.dockerignore里又被COPY引用構(gòu)建會(huì)直接失敗報(bào)file not found很多人排查半天以為是路徑寫錯(cuò)了其實(shí)是忽略了。3. Docker Compose把一組容器當(dāng)一臺(tái)機(jī)器用Compose 文件寫得好不好看一個(gè)標(biāo)準(zhǔn)就夠了新人克隆倉(cāng)庫(kù)docker compose up -d一條命令所有服務(wù)起來(lái)并進(jìn)入可用狀態(tài)不需要看任何文檔。達(dá)不到這個(gè)標(biāo)準(zhǔn)說(shuō)明還有環(huán)境變量、依賴順序或者初始化數(shù)據(jù)沒(méi)聲明清楚。3.1 compose.yaml 的結(jié)構(gòu)骨架新版 Compose 已經(jīng)不需要頂層version字段寫了反而會(huì)收到一條廢棄警告?；竟羌苁沁@樣的services: api: build: context: . dockerfile: Dockerfile image: registry.internal.example.com/team/api:1.4.2 ports: - 8080:8080 environment: TZ: Asia/Shanghai SPRING_PROFILES_ACTIVE: docker env_file: - .env.docker volumes: - app-logs:/app/logs networks: - backend depends_on: db: condition: service_healthy restart: unless-stopped healthcheck: test: [CMD, curl, -fsS, http://localhost:8080/actuator/health] interval: 30s timeout: 3s retries: 3 start_period: 40s db: image: postgres:16-alpine environment: POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - db-data:/var/lib/postgresql/data networks: - backend healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 volumes: app-logs: db-data: networks: backend: driver: bridge幾個(gè)點(diǎn)展開說(shuō)。build和image同時(shí)存在時(shí)docker compose build會(huì)按 Dockerfile 構(gòu)建并打上image指定的標(biāo)簽docker compose pull則直接拉這個(gè)標(biāo)簽。這個(gè)組合在開發(fā)和生產(chǎn)之間切換很方便本地改代碼就 build服務(wù)器上直接 pull。environment和env_file可以并存前者優(yōu)先級(jí)更高。密碼這類敏感信息放env_file里并把該文件加入.gitignore操作用${DB_PASSWORD}變量引用Compose 會(huì)自動(dòng)從同目錄的.env里讀。restart: unless-stopped是我最常用的策略。always的問(wèn)題是手動(dòng)停了也會(huì)被拉起來(lái)調(diào)試時(shí)很煩on-failure遇到正常退出就不重啟有些場(chǎng)景不合適。unless-stopped兼顧兩者崩潰自動(dòng)拉起手動(dòng)停止后保持停止。3.2 depends_on 與 healthcheck 的正確組合這是 Compose 里被誤解最深的一處。很多人以為depends_on: [db]就代表等 db 啟動(dòng)好了再起 api實(shí)際上它只保證容器啟動(dòng)順序db 容器一創(chuàng)建api 容器立刻開始啟動(dòng)此時(shí)數(shù)據(jù)庫(kù)進(jìn)程可能還在初始化、端口根本沒(méi)監(jiān)聽(tīng)。結(jié)果 api 連接失敗重試幾次后放棄日志里一堆連接拒絕。正確做法是配合健康檢查depends_on: db: condition: service_healthy配合 db 服務(wù)上的healthcheck定義Compose 會(huì)等到健康檢查通過(guò)才啟動(dòng)依賴方。pg_isready這類專用探針比curl更準(zhǔn)確因?yàn)樗鼨z查的是數(shù)據(jù)庫(kù)真實(shí)可接受連接的狀態(tài)不只是端口開著。健康檢查的參數(shù)需要根據(jù)服務(wù)特性調(diào)。數(shù)據(jù)庫(kù)這種啟動(dòng)快但初始化慢的interval: 10s、retries: 5大概夠Java 應(yīng)用啟動(dòng)慢start_period: 40s甚至更長(zhǎng)。start_period內(nèi)的失敗不計(jì)數(shù)這是給慢啟動(dòng)服務(wù)的保護(hù)期設(shè)短了會(huì)誤判。還有一個(gè)常見(jiàn)誤解健康檢查通過(guò)只代表進(jìn)程能響應(yīng)探針不代表業(yè)務(wù)邏輯完全就緒。比如應(yīng)用可能探針通了但緩存還沒(méi)預(yù)熱完。這種場(chǎng)景下更靠譜的做法是在應(yīng)用里實(shí)現(xiàn)真正的就緒檢查接口把關(guān)鍵依賴數(shù)據(jù)庫(kù)連接池、配置加載、緩存連接都納入判斷探針打這個(gè)接口。健康檢查的質(zhì)量直接決定編排的可靠性。3.3 網(wǎng)絡(luò)、卷與環(huán)境變量的三層隔離Compose 默認(rèn)會(huì)創(chuàng)建一個(gè)以項(xiàng)目名命名的網(wǎng)絡(luò)所有服務(wù)自動(dòng)加入服務(wù)之間可以直接用服務(wù)名當(dāng)主機(jī)名互訪。這個(gè)默認(rèn)行為很方便但也容易造成全都通的混亂。我的習(xí)慣是顯式定義網(wǎng)絡(luò)并分組networks: frontend: backend: internal: true把數(shù)據(jù)庫(kù)和緩存放backend應(yīng)用同時(shí)加入兩個(gè)網(wǎng)絡(luò)反向代理只加入frontend。internal: true讓這個(gè)網(wǎng)絡(luò)無(wú)法訪問(wèn)外網(wǎng)數(shù)據(jù)庫(kù)完全沒(méi)有對(duì)外出口安全性上一個(gè)臺(tái)階。卷分兩類命名卷和綁定掛載。命名卷由 Docker 管理存在/var/lib/docker/volumes/下適合數(shù)據(jù)庫(kù)數(shù)據(jù)、應(yīng)用日志這類需要持久化但不方便直接編輯的內(nèi)容。綁定掛載直接把宿主機(jī)目錄映射進(jìn)去適合開發(fā)時(shí)掛載源碼實(shí)現(xiàn)熱更新volumes: - ./src:/app/src - ./config:/app/config:ro:ro只讀掛載配置目錄防止容器內(nèi)誤改宿主機(jī)文件。這個(gè)細(xì)節(jié)在多人共用一臺(tái)開發(fā)機(jī)時(shí)尤其重要。環(huán)境變量我按三層管理鏡像內(nèi)置默認(rèn)值ENV寫在不敏感的配置上、Compose 聲明的環(huán)境變量區(qū)分不同環(huán)境的差異項(xiàng)、運(yùn)行時(shí)注入密碼密鑰通過(guò)外部文件或編排平臺(tái)注入絕不進(jìn)倉(cāng)庫(kù)。三層各司其職不會(huì)出現(xiàn)改個(gè)數(shù)據(jù)庫(kù)地址要重新構(gòu)建鏡像這種事。3.4 多環(huán)境覆蓋override 文件與 profilesCompose 支持文件合并compose.yaml加上compose.override.yaml會(huì)自動(dòng)疊加后者優(yōu)先級(jí)更高。這個(gè)機(jī)制天然適合做環(huán)境差異化基礎(chǔ)文件寫通用配置override 寫本機(jī)特定的端口、卷、調(diào)試參數(shù)。# compose.override.yaml本地開發(fā)用加入 .gitignore services: api: volumes: - ./src:/app/src environment: LOG_LEVEL: debug ports: - 8080:8080 - 5005:5005 # 遠(yuǎn)程調(diào)試端口服務(wù)器上不放這個(gè)文件就是生產(chǎn)配置本地開發(fā)放進(jìn)去自動(dòng)獲得熱更新和調(diào)試端口。也可以顯式指定多個(gè)文件docker compose -f compose.yaml -f compose.prod.yaml up -d后者覆蓋前者。profiles解決的是可選服務(wù)的問(wèn)題。比如監(jiān)控組件、數(shù)據(jù)庫(kù)管理工具這些平時(shí)不需要的服務(wù)services: adminer: image: adminer:latest profiles: [tools] ports: - 8081:8080不帶--profile tools啟動(dòng)時(shí)這個(gè)服務(wù)完全不會(huì)被創(chuàng)建不會(huì)浪費(fèi)資源。需要時(shí)docker compose --profile tools up -d臨時(shí)拉起來(lái)。比起注釋掉再取消注釋這種方式干凈太多也不會(huì)因?yàn)橥浉幕貋?lái)而出事。3.5 我常用的命令清單與排查路徑命令不在多在于用對(duì)時(shí)機(jī)。下面這幾個(gè)是我每天都會(huì)碰的命令用途使用時(shí)機(jī)docker compose config展開并校驗(yàn)最終配置改完 yaml 先跑一遍變量沒(méi)解析、語(yǔ)法錯(cuò)都能立刻發(fā)現(xiàn)docker compose up -d --build重建鏡像并后臺(tái)啟動(dòng)改了代碼或 Dockerfile 后docker compose ps查看服務(wù)狀態(tài)和健康情況起完之后確認(rèn)是否全部 healthydocker compose logs -f --tail100 api跟蹤某個(gè)服務(wù)日志排查啟動(dòng)失敗docker compose exec api sh進(jìn)入運(yùn)行中的容器需要看文件、驗(yàn)證網(wǎng)絡(luò)連通性docker compose down -v停止并刪除容器與卷需要徹底清空環(huán)境重來(lái)docker compose up -d --force-recreate強(qiáng)制重建容器配置改了但沒(méi)生效時(shí)docker compose config這個(gè)命令被嚴(yán)重低估。它把變量替換后的最終配置整個(gè)打印出來(lái)很多時(shí)候配置明明改了為什么不生效跑一下就能看到真相——可能是變量名拼錯(cuò)、可能是 override 文件覆蓋了、可能是.env文件位置不對(duì)。排查起不來(lái)的服務(wù)我的固定順序是先docker compose ps看狀態(tài)是 Exit 還是 Restarting再docker compose logs --tail200 服務(wù)名看報(bào)錯(cuò)然后docker compose config確認(rèn)配置沒(méi)被覆蓋最后才考慮進(jìn)容器。絕大多數(shù)問(wèn)題在前兩步就能定位直接鉆容器里翻往往是浪費(fèi)時(shí)間。4. 私有鏡像倉(cāng)庫(kù)從單機(jī) registry 到團(tuán)隊(duì)級(jí)方案鏡像倉(cāng)庫(kù)這塊很多團(tuán)隊(duì)吃過(guò)起步太簡(jiǎn)陋、后來(lái)遷移成本高的虧。我的建議是先想清楚使用規(guī)模和治理需求再?zèng)Q定投入多少。4.1 先想清楚倉(cāng)庫(kù)要解決什么問(wèn)題三類需求對(duì)應(yīng)三種方案。個(gè)人或小團(tuán)隊(duì)內(nèi)網(wǎng)共享幾十個(gè)鏡像兩三個(gè)人推拉一個(gè)單機(jī) registry 就夠了十分鐘能跑起來(lái)維護(hù)成本幾乎為零。團(tuán)隊(duì)級(jí)使用需要按項(xiàng)目隔離權(quán)限、需要知道誰(shuí)推了什么、需要定期清理這時(shí)候得上帶管理界面的方案配置項(xiàng)多但也省心。有合規(guī)或?qū)徲?jì)要求需要鏡像簽名、漏洞掃描、拉取審計(jì)日志那就得選企業(yè)級(jí)套件前期投入大但后面省事。選型時(shí)我最看重的是存儲(chǔ)后端是否可替換。早期的倉(cāng)庫(kù)把數(shù)據(jù)存在本地磁盤用著用著磁盤滿了擴(kuò)容就得停機(jī)遷移。支持對(duì)象存儲(chǔ)的倉(cāng)庫(kù)擴(kuò)容只是改個(gè)配置。這一點(diǎn)在起步時(shí)容易被忽略等數(shù)據(jù)漲到幾百 GB 才發(fā)現(xiàn)遷移就是一次大工程。4.2 十分鐘起一個(gè)可用的私有倉(cāng)庫(kù)單機(jī)方案起步極快services: registry: image: registry:2 ports: - 5000:5000 environment: REGISTRY_STORAGE_DELETE_ENABLED: true volumes: - ./registry-data:/var/lib/registry - ./config.yml:/etc/docker/registry/config.yml:ro restart: unless-stoppedREGISTRY_STORAGE_DELETE_ENABLED這個(gè)環(huán)境變量一定要開否則后面想刪鏡像標(biāo)簽會(huì)直接被拒絕。配置文件里可以追加保留策略和存儲(chǔ)后端storage: filesystem: rootdirectory: /var/lib/registry delete: enabled: true cache: blobdescriptor: inmemory http: addr: :5000起來(lái)之后先給鏡像打上帶倉(cāng)庫(kù)地址的完整標(biāo)簽再推docker tag myapp:1.0.0 192.168.10.20:5000/team/myapp:1.0.0 docker push 192.168.10.20:5000/team/myapp:1.0.0標(biāo)簽的完整格式是倉(cāng)庫(kù)地址/命名空間/鏡像名:版本。這里最容易出的錯(cuò)是忘了加倉(cāng)庫(kù)地址前綴直接docker push myapp:1.0.0會(huì)被推到默認(rèn)的公共倉(cāng)庫(kù)本地私有倉(cāng)庫(kù)里什么都沒(méi)有。4.3 TLS 與 insecure-registries 的正確姿勢(shì)默認(rèn)情況下Docker 客戶端要求倉(cāng)庫(kù)必須走 HTTPS。你用 HTTP 起在 5000 端口push 時(shí)會(huì)看到http: server gave HTTP response to HTTPS client意思很直白客戶端發(fā)的是 HTTPS 請(qǐng)求服務(wù)端回的是 HTTP 明文。兩種解法。生產(chǎn)環(huán)境必須用證書把 CA 證書放到/etc/docker/certs.d/倉(cāng)庫(kù)地址:端口/ca.crt客戶端就會(huì)信任。自簽證書的關(guān)鍵是 SAN 字段必須包含你實(shí)際訪問(wèn)用的地址——很多人簽證書時(shí)只填了域名實(shí)際訪問(wèn)用的是 IP照樣報(bào)x509: certificate is valid for ...。開發(fā)和測(cè)試環(huán)境可以臨時(shí)把倉(cāng)庫(kù)標(biāo)記為不安全倉(cāng)庫(kù)在/etc/docker/daemon.json里加{ insecure-registries: [192.168.10.20:5000] }改完必須重啟 Docker 服務(wù)生效。這里有個(gè)坑insecure-registries只對(duì) HTTP 倉(cāng)庫(kù)有效如果你的倉(cāng)庫(kù)確實(shí)是 HTTPS 但證書不被信任加這個(gè)配置也沒(méi)用得老老實(shí)實(shí)放 CA 證書。我見(jiàn)過(guò)有人在這上面繞了兩小時(shí)一直在反復(fù)重啟 Docker 服務(wù)。注意不要為了圖省事把內(nèi)網(wǎng)所有地址都塞進(jìn)insecure-registries。一旦形成習(xí)慣某天真的需要走加密傳輸時(shí)排查范圍會(huì)大得離譜。4.4 命名、打標(biāo)簽與保留策略標(biāo)簽策略是我見(jiàn)過(guò)最混亂的一環(huán)。典型現(xiàn)場(chǎng)是倉(cāng)庫(kù)里每個(gè)鏡像都有l(wèi)atest、test、v1、v1-new、v1-最終版、v1-真最終版沒(méi)人敢刪任何一個(gè)。半年后想回滾某個(gè)版本發(fā)現(xiàn)根本對(duì)不上哪次發(fā)布。我推行的規(guī)則只有三條。第一latest只在一個(gè)地方使用本地開發(fā)隨手構(gòu)建時(shí)用CI 和發(fā)布流程嚴(yán)禁推latest。第二正式版本用語(yǔ)義化版本號(hào)1.4.2這種配合 git tag能精確對(duì)應(yīng)到某次提交。第三額外打一個(gè) git 短哈希標(biāo)簽方便排查docker tag myapp:1.4.2 192.168.10.20:5000/team/myapp:1.4.2 docker tag myapp:1.4.2 192.168.10.20:5000/team/myapp:sha-a1b2c3d版本號(hào)給人看哈希給機(jī)器查。生產(chǎn)環(huán)境部署時(shí)用 digest 而不是標(biāo)簽這是最穩(wěn)的方式docker pull 192.168.10.20:5000/team/myappsha256:xxxx因?yàn)闃?biāo)簽可以被移動(dòng)同一個(gè)1.4.2今天推的和明天推的可能是兩個(gè)不同的鏡像digest 是內(nèi)容哈希永遠(yuǎn)指向同一份內(nèi)容。這點(diǎn)在出故障回滾時(shí)特別關(guān)鍵——你確定拉回來(lái)的就是當(dāng)初那個(gè)。4.5 存儲(chǔ)回收為什么刪了 tag 磁盤沒(méi)變小這個(gè)問(wèn)題幾乎每個(gè)自建倉(cāng)庫(kù)的人都會(huì)遇到。執(zhí)行了刪除標(biāo)簽的命令curl也返回成功但du -sh一看磁盤占用紋絲不動(dòng)。原因是 Registry 的刪除是兩段式的刪標(biāo)簽只是刪掉了 manifest 的引用底層的 layer 文件blob還在因?yàn)榭赡鼙黄渌麡?biāo)簽共享。要真正回收得跑垃圾回收。Registry 自帶了一個(gè)命令在容器里執(zhí)行docker exec registry /bin/registry garbage-collect \ --delete-untagged /etc/docker/registry/config.yml在這之前必須先刪干凈所有指向無(wú)用 manifest 的標(biāo)簽而且回收過(guò)程最好停寫或只讀因?yàn)椴l(fā)推送可能導(dǎo)致新鏡像的層被誤判為無(wú)引用而清掉。我的做法是每天凌晨跑一次定時(shí)任務(wù)先停掉對(duì)外推送權(quán)限再執(zhí)行回收最后恢復(fù)。聽(tīng)起來(lái)麻煩但比起某天磁盤滿了導(dǎo)致所有構(gòu)建失敗這點(diǎn)麻煩值。保留策略建議按數(shù)量 時(shí)間雙維度控制每個(gè)倉(cāng)庫(kù)保留最近 10 個(gè)版本同時(shí)刪除所有超過(guò) 90 天且非正式版本的標(biāo)簽。只按數(shù)量控制低頻更新的倉(cāng)庫(kù)會(huì)保留很久只按時(shí)間控制高頻更新的倉(cāng)庫(kù)會(huì)積攢太多。5. 實(shí)戰(zhàn)問(wèn)題速查與避坑記錄下面這些幾乎都是我或者身邊同事真實(shí)撞上過(guò)的按階段整理出問(wèn)題時(shí)可以先掃一眼表格。5.1 構(gòu)建階段高頻故障表現(xiàn)象根因處理方式COPY failed: file not found文件被.dockerignore排除或路徑超出構(gòu)建上下文檢查.dockerignore確認(rèn)context目錄包含該文件構(gòu)建越來(lái)越慢改一行代碼就要幾分鐘COPY . .在依賴安裝之前緩存全失效調(diào)整指令順序依賴清單先拷源碼后拷鏡像體積遠(yuǎn)超預(yù)期緩存文件、包管理器索引沒(méi)在同一層清理RUN合并清理命令用多階段構(gòu)建not found或符號(hào)相關(guān)錯(cuò)誤程序跑不起來(lái)Alpine 的 musl libc 與預(yù)編譯二進(jìn)制不兼容換成debian-slim基礎(chǔ)鏡像時(shí)區(qū)不對(duì)日志差八小時(shí)容器默認(rèn) UTC沒(méi)設(shè)TZ裝tzdata設(shè)ENV TZ構(gòu)建時(shí)報(bào)no space left on device本地鏡像和構(gòu)建緩存占滿磁盤docker system prune -af配合--filter until72h磁盤那條多說(shuō)一句docker system prune默認(rèn)不清理正在被容器使用的鏡像加-a才會(huì)清掉所有未使用鏡像加-f免確認(rèn)。執(zhí)行前確認(rèn)沒(méi)有正在跑的重要容器用docker ps看一眼再動(dòng)手。5.2 運(yùn)行與編排階段高頻故障表現(xiàn)象根因處理方式應(yīng)用啟動(dòng)就連不上數(shù)據(jù)庫(kù)depends_on只保證啟動(dòng)順序不等就緒加healthcheckcondition: service_healthydocker stop要等十秒才停CMD用了 shell 形式PID 1 是 sh信號(hào)沒(méi)轉(zhuǎn)發(fā)改成 exec 形式[node,server.js]非 root 用戶寫卷報(bào)permission denied宿主機(jī)目錄屬主與容器內(nèi) UID 不匹配構(gòu)建時(shí)chown或啟動(dòng)時(shí)用user: 1000:1000容器內(nèi)訪問(wèn)localhost連不上另一個(gè)服務(wù)每個(gè)容器有獨(dú)立網(wǎng)絡(luò)棧用服務(wù)名當(dāng)主機(jī)名服務(wù)需在同一網(wǎng)絡(luò)exec format error鏡像架構(gòu)與宿主機(jī)不一致構(gòu)建時(shí)指定--platform linux/amd64改了配置重啟不生效容器被復(fù)用新配置沒(méi)進(jìn)容器docker compose up -d --force-recreateport is already allocated端口被占用ss -lntp查占用進(jìn)程或換端口exec format error這個(gè)在 M 系列芯片的機(jī)器上構(gòu)建、部署到 x86 服務(wù)器時(shí)特別常見(jiàn)報(bào)錯(cuò)信息很短容易誤判成鏡像損壞。構(gòu)建時(shí)加--platform linux/amd64或者用buildx同時(shí)產(chǎn)出多架構(gòu)鏡像能一次性解決。5.3 倉(cāng)庫(kù)階段的三個(gè)經(jīng)典報(bào)錯(cuò)http: server gave HTTP response to HTTPS client——前面說(shuō)過(guò)客戶端用 HTTPS 請(qǐng)求服務(wù)端是明文 HTTP。要么給倉(cāng)庫(kù)配證書要么把地址加進(jìn)insecure-registries并重啟服務(wù)。x509: certificate signed by unknown authority——客戶端不信任倉(cāng)庫(kù)證書。把 CA 證書放到/etc/docker/certs.d/地址/ca.crt。注意目錄名要和訪問(wèn)用的地址完全一致帶端口的話端口不能少192.168.10.20:5000和192.168.10.20是兩個(gè)不同的目錄。manifest unknown或not found——拉取時(shí)找不到對(duì)應(yīng)的標(biāo)簽。要么是標(biāo)簽打錯(cuò)了要么是推送失敗了但命令返回被忽略。用倉(cāng)庫(kù)的 API 列一下現(xiàn)有標(biāo)簽確認(rèn)curl http://地址:5000/v2/命名空間/鏡像名/tags/list能直接看到實(shí)際存在哪些標(biāo)簽比猜測(cè)快得多。5.4 幾條踩出來(lái)的經(jīng)驗(yàn)關(guān)于調(diào)試信息鏡像里裝curl和netstat這類工具體積會(huì)增加十幾兆但排查網(wǎng)絡(luò)問(wèn)題時(shí)能省下大量時(shí)間。如果實(shí)在不想裝進(jìn)生產(chǎn)鏡像可以在構(gòu)建時(shí)開一個(gè)帶工具的 debug 階段出問(wèn)題時(shí)臨時(shí)構(gòu)建那個(gè)階段進(jìn)去看。關(guān)于構(gòu)建速度如果依賴下載慢是網(wǎng)絡(luò)層面的問(wèn)題加構(gòu)建參數(shù)換源比優(yōu)化 Dockerfile 更有效。另外--cache-from配合 CI 緩存能顯著加速把上一次構(gòu)建的鏡像拉下來(lái)當(dāng)緩存源遠(yuǎn)程構(gòu)建時(shí)效果明顯。關(guān)于Compose 文件的可維護(hù)性超過(guò)五個(gè)服務(wù)之后盡量按職責(zé)拆成多個(gè)文件用-f組合。一個(gè)兩百行的 yaml 沒(méi)人愿意改改成三個(gè)七十行的人人敢動(dòng)。另外把公共部分網(wǎng)絡(luò)、時(shí)區(qū)、日志配置用x-開頭的錨點(diǎn)抽出來(lái)復(fù)用能減少大量重復(fù)。關(guān)于倉(cāng)庫(kù)的可用性私有倉(cāng)庫(kù)掛掉的時(shí)候如果所有機(jī)器都依賴它拉鏡像整個(gè)發(fā)布流程就停了。至少保證每臺(tái)機(jī)器本地緩存了最近幾個(gè)可用版本docker image ls里能看到緊急時(shí)可以直接用本地鏡像啟動(dòng)不必等倉(cāng)庫(kù)恢復(fù)。關(guān)于版本管理的心態(tài)我見(jiàn)過(guò)太多人覺(jué)得鏡像倉(cāng)庫(kù)反正內(nèi)網(wǎng)標(biāo)簽隨便打沒(méi)關(guān)系等到要回滾某個(gè)兩周前的版本發(fā)現(xiàn)latest已經(jīng)更新了七次根本找不回來(lái)。標(biāo)簽規(guī)范這件事在只有三個(gè)人的時(shí)候建立成本幾乎為零在三十個(gè)人的時(shí)候推行的阻力大得離譜。早做比什么都強(qiáng)。最后分享一個(gè)我自己一直在用的小習(xí)慣每寫完一個(gè) Dockerfile先用docker build跑兩遍。第一遍看不到什么特別第二遍觀察哪些層顯示CACHED如果只有最后一兩層命中說(shuō)明指令順序還有優(yōu)化空間把變化最頻繁的內(nèi)容再往后挪。這個(gè)動(dòng)作花不到一分鐘但能讓你對(duì)每一層的邊界有肌肉記憶寫第三個(gè) Dockerfile 的時(shí)候順序自然就對(duì)了。