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