+
+
+
+ 
+
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Hello, Docker!
+``` + +### 1.1.2 编写 Dockerfile + +在同级目录下创建一个名为 `Dockerfile`（无后缀）的文件： + +```dockerfile +FROM nginx:alpine +COPY index.html /usr/share/nginx/html/index.html +``` + +### 1.1.3 构建镜像 + +打开终端，进入该目录，执行构建命令： + +```bash +$ docker build -t my-hello-world . +``` + +* `docker build`：构建命令 +* `-t my-hello-world`：给镜像起个名字（标签） +* `.`：指定上下文路径为当前目录 + +### 1.1.4 运行容器 + +使用刚才构建的镜像启动一个容器： + +```bash +$ docker run -d -p 8080:80 my-hello-world +``` + +* `docker run`：运行命令 +* `-d`：后台运行 +* `-p 8080:80`：将宿主机的 8080 端口映射到容器的 80 端口 + +### 1.1.5 访问测试 + +打开浏览器访问 [http://localhost:8080](http://localhost:8080)，你应该能看到 “Hello, Docker!”。 + +### 1.1.6 清理 + +停止并删除容器： + +```bash +# 查看正在运行的容器 ID + +$ docker ps + +# 停止容器 + +$ docker stopUbuntu 24.04
特定版本的库"] --> B["运行正常"] + end + subgraph Prod ["生产环境"] + direction TB + C["Python 3.11
Ubuntu 22.04
不同版本的库"] --> D["运行失败！"] + end + A -.->|不一致| C +``` +有了 Docker： + +```mermaid +flowchart LR + subgraph Dev ["开发环境"] + direction TB + A["Docker 镜像
(包含所有依赖)"] --> B["运行正常"] + end + subgraph Prod ["生产环境"] + direction TB + C["同一个镜像
(完全一致)"] --> D["运行正常！"] + end + A == 一致 ==> C +``` + +### 1.2.3 Docker vs 虚拟机 + +很多人第一次接触 Docker 时会问：**“这不就是虚拟机吗？”** 答案是：**不是，而且差别很大。** + +#### 传统虚拟机 + +传统虚拟机技术是虚拟出一套完整的硬件，在其上运行一个完整的操作系统，再在该系统上运行应用： + + + +#### Docker 容器 + +而 Docker 容器内的应用直接运行于宿主的内核，容器内没有自己的内核，也没有进行硬件虚拟： + + + +#### 关键区别 + +| 特性 | Docker 容器 | 传统虚拟机 | +|------|-------------|------------| +| **启动速度** | 秒级 | 分钟级 | +| **资源占用** | MB 级别 | GB 级别 | +| **性能** | 接近原生 | 有明显损耗 | +| **隔离级别** | 进程级隔离 | 完全隔离 | +| **单机数量** | 可运行上千个 | 通常几十个 | + +> 笔者经常用这个类比来解释：虚拟机像是每个应用都住在一栋独立的房子里（有自己的地基、水电系统），而容器像是大家住在同一栋公寓楼里的不同房间（共享地基和水电系统，但各自独立）。 + +### 1.2.4 Docker 的技术基础 + +Docker 使用 [Go 语言](https://golang.google.cn/)开发，基于 Linux 内核的以下技术： + +- **[Namespace](https://en.wikipedia.org/wiki/Linux_namespaces)**：实现资源隔离（进程、网络、文件系统等） +- **[Cgroups](https://zh.wikipedia.org/wiki/Cgroups)**：实现资源限制（CPU、内存、I/O 等） +- **[Union FS](https://en.wikipedia.org/wiki/Union_mount)**：实现分层存储（如 OverlayFS） + +> 如果你对这些底层技术感兴趣，可以阅读本书的[底层实现](../12_implementation/README.md)章节。 + +#### Docker 架构演进 + +Docker 的底层实现经历了多次演进： + +```mermaid +flowchart LR + subgraph Timeline + direction LR + LXC["LXC
(2013)"] --> libcontainer["libcontainer
(2014)"] + libcontainer --> runC["runC
(2015)"] + runC --> containerd["containerd + runC
(现在)"] + runC --> OCI["OCI
标准化"] + end +``` + +- **LXC** (2013)：Docker 最初基于 Linux Containers +- **libcontainer** (2014，Docker 0.9)：Docker 自研的容器运行时 +- **runC**（2015，Docker 1.11 整合）：捐献给 OCI 的标准容器运行时 +- **containerd**：高级容器运行时，管理容器生命周期 + + + +> `runc` 是一个 Linux 命令行工具，用于根据 [OCI 容器运行时规范](https://github.com/opencontainers/runtime-spec)创建和运行容器。 + +> `containerd` 是一个守护程序，它管理容器生命周期，提供了在一个节点上执行容器和管理镜像的最小功能集。 + +### 1.2.5 Docker 的历史与生态 + +**Docker** 最初是 `dotCloud` 公司创始人 [Solomon Hykes](https://github.com/shykes) 在法国期间发起的一个公司内部项目，于 [2013 年 3 月以 Apache 2.0 授权协议开源](https://en.wikipedia.org/wiki/Docker_%28software%29)。 + +Docker 的发展历程： + +- **2013 年 3 月**：开源发布 +- **2013 年底**：dotCloud 公司改名为 Docker, Inc. +- **2015 年**：成立[开放容器联盟 (OCI)](https://opencontainers.org/)，推动容器标准化 +- **至今**：[GitHub 项目](https://github.com/moby/moby)超过 7 万星标 + +Docker 的成功推动了整个容器生态的发展，催生了 Kubernetes、Podman 等众多相关项目。笔者认为，Docker 最大的贡献不仅是技术本身，更是它 **让容器技术从系统管理员的工具变成了每个开发者都能使用的标准工具**。 diff --git a/01_introduction/1.3_why.md b/01_introduction/1.3_why.md new file mode 100644 index 000000000..f49d62ce8 --- /dev/null +++ b/01_introduction/1.3_why.md @@ -0,0 +1,206 @@ +## 1.3 为什么要用 Docker + +在回答 “为什么用 Docker” 之前，笔者想先问一个问题：**你有没有经历过这些场景？** + +### 1.3.1 没有 Docker 的世界 + +在 Docker 出现之前，软件开发和运维面临着诸多棘手的问题。我们先来看看以下三个典型的痛点场景。 + +#### 场景一：“在我电脑上明明能跑” + +```text +周五下午 5:00 +├── 开发者：代码写完了，本地测试通过，提交！🎉 +├── 周一早上 9:00 +│ └── 测试："这个功能在测试环境跑不起来" +└── 开发者："不可能，在我电脑上明明能跑啊……" +``` +笔者统计过，这个问题通常由以下原因导致： + +- Python/Node/Java 版本不一致 +- 依赖库版本不一致 +- 操作系统配置不一致 +- 某些环境变量没有设置 +- “哦，忘了说我本地装了个 XXX” + +#### 场景二：环境配置的噩梦 + +```bash +新同事入职 +├── Day 1：领电脑，配环境 +├── Day 2：继续配环境，遇到问题 +├── Day 3：换种方法配环境 +├── Day 4：问老同事怎么配的，他也忘了 +└── Day 5：终于能跑起来了！但不知道为什么…… +``` + +#### 场景三：服务器迁移的恐惧 + +```bash +运维："我们需要把服务迁移到新服务器" +开发："旧服务器上的配置文档在哪？" +运维："当时是一个已经离职的同事配的……" +所有人：😱 +``` + +### 1.3.2 Docker 如何解决这些问题 + +Docker 的出现为上述问题提供了完美的解决方案。它通过 “一次构建，到处运行” 的核心理念，从根本上改变了软件交付的方式。 + +#### 核心理念：一次构建，到处运行 + +```mermaid +flowchart LR + dev["开发团队"] -->|创建| img["Docker 镜像"] + img -->|测试团队验证| test["测试团队"] + test -- "有问题
反馈修改和更新" --> dev + test -- "没问题
发布" --> prod["生产环境"] +``` + +### 1.3.3 Docker 的核心优势 + +除了解决上述痛点，Docker 还拥有诸多显著的技术优势，包括环境一致性、秒级启动、高效的资源利用等。 + +#### 1. 环境一致性 + +Docker 镜像包含了应用运行所需的大部分用户态依赖：代码、运行时、系统工具、库和默认配置。它不包含宿主机内核，也不能消除 CPU 架构、内核能力、外部服务、网络、卷和运行时配置差异。这意味着： + +- ✅ 开发环境和生产环境可以显著减少差异 +- ✅ 大幅降低 “在我机器上能跑” 的问题 +- ✅ 新人入职，一条命令就能启动开发环境 + +```bash +## 新同事入职第一天 + +$ git clone https://github.com/company/project.git +$ docker compose up + +## 完整的开发环境就准备好了 + +... +``` + +#### 2. 秒级启动 + +传统虚拟机启动需要几分钟（引导操作系统），而 Docker 容器启动通常只需要 **几秒甚至几百毫秒**。 + +笔者实测数据： + +| 启动内容 | 虚拟机 | Docker 容器 | +|---------|--------|-------------| +| 空系统 | ~60 秒 | ~0.5 秒 | +| MySQL | ~90 秒 | ~3 秒 | +| 完整 Web 应用 | ~120 秒 | ~5 秒 | + +这个差异对以下场景尤为重要： + +- **CI/CD 流水线**：每次构建节省几分钟，一天累积下来就是几小时 +- **弹性扩容**：流量高峰时能快速启动更多实例 +- **开发体验**：快速重启服务进行调试 + +#### 3. 资源效率 + +Docker 容器共享宿主机内核，无需为每个应用运行完整的操作系统。以一台 64GB 内存的物理服务器为例： + +- **传统虚拟机方案**：每个虚拟机都需要运行完整的操作系统（每个额外占用如 2GB 内存），产生大量资源开销，实际可用于应用的内存可能只有约 18GB。 +- **Docker 方案**：容器直接共享宿主机系统，只需付出很少的基础开销（OS 及引擎约 4GB），即可将约 60GB 的内存全部用于实际应用。 + +```mermaid +flowchart TD + subgraph VM ["传统虚拟机方案 ❌"] + direction TB + Server1["物理服务器 (64GB 内存)"] + subgraph VMs ["可用应用内存: 约 18GB"] + direction LR + VM1["VM 1: 应用 1
(含 2GB OS)"] + VM2["VM 2: 应用 2
(含 2GB OS)"] + VM3["VM 3: 应用 3
(含 2GB OS)"] + end + Server1 --- VMs + end + + subgraph Docker ["Docker 方案 ✅"] + direction TB + Server2["物理服务器 (64GB 内存)
含约 4GB OS及引擎配置"] + subgraph Containers ["可用应用内存: 约 60GB"] + direction LR + C1["容器 1: 应用 1
(按需分配)"] + C2["容器 2: 应用 2
(按需分配)"] + C3["容器 3: 应用 3
(按需分配)"] + end + Server2 --- Containers + end +``` + +#### 4. 持续交付和部署 + +Docker 完美契合 DevOps 的工作流程： + +```mermaid +flowchart LR + A["代码提交
(Git push)"] --> B["自动构建镜像
(docker build)"] + B --> C["自动测试
(容器内运行测试)"] + C --> D["自动部署
(容器滚动更新)"] +``` +使用 [Dockerfile](../04_image/4.5_build.md) 定义镜像构建过程，使得： + +- 构建过程 **可重复、可追溯** +- 任何人都能从代码重建完全相同的镜像 +- 配合 [GitHub Actions](../21_case_devops/21.2_github_actions.md) 等 CI 系统实现自动化 + +#### 5. 轻松迁移 + +Docker 可以在几乎任何平台上运行： + +- ✅ 本地开发机 (macOS、Windows、Linux) +- ✅ 公有云（AWS、Azure、GCP、阿里云、腾讯云） +- ✅ 私有云和自建数据中心 +- ✅ 边缘设备和 IoT + +**同一个镜像，在任何地方运行结果都一致。** 这让应用迁移变得前所未有的简单。 + +#### 6. 微服务架构的基石 + +现代微服务架构几乎都依赖容器技术。Docker 让你可以： + +- **隔离服务**：每个服务运行在独立容器中，互不干扰 +- **独立扩展**：哪个服务负载高，就单独扩展哪个 +- **独立部署**：更新一个服务不影响其他服务 +- **技术多样**：不同服务可以用不同语言和框架 + +```mermaid +flowchart TD + subgraph Microservices ["微服务架构示例"] + direction TB + subgraph AppLayer ["应用层"] + direction LR + Frontend["前端容器
(Node.js)"] + API["API 容器
(Python)"] + Worker["Worker 容器
(Go)"] + end + Redis["Redis 容器"] + DB["PostgreSQL 容器"] + + Frontend --> API + API --> Redis + API --> DB + Worker --> Redis + Worker --> DB + end +``` + +### 1.3.4 Docker 不适合的场景 + +笔者认为，技术选型要客观。Docker 并非银弹，以下场景可能不太适合： + +- **需要完全隔离的场景**：容器共享宿主机内核，隔离性不如虚拟机。如果需要运行不受信任的代码，虚拟机可能更安全。 +- **需要特殊内核的场景**：容器使用宿主机内核。如果应用需要特定版本的内核或内核模块，可能需要虚拟机。 +- **Windows 原生应用**：虽然 Docker 支持 Windows 容器，但生态不如 Linux 容器成熟。传统 Windows 应用的容器化仍有挑战。 +- **桌面应用**：Docker 主要面向服务端应用。桌面 GUI 应用的容器化虽然可行，但通常得不偿失。 + +### 1.3.5 与传统虚拟机的对比总结 + +关于容器与虚拟机的详细特性对比，请参阅 [1.2.3 Docker vs 虚拟机](1.2_what.md) 中的对比表。总结来说： + +- **性能差异**：虚拟机通常有 5-20% 的性能损耗，而容器接近原生性能。 +- **最佳场景**：Docker 容器适合微服务、CI/CD、开发环境；虚拟机适合多租户、高安全需求场景。 diff --git a/01_introduction/README.md b/01_introduction/README.md new file mode 100644 index 000000000..50ced3668 --- /dev/null +++ b/01_introduction/README.md @@ -0,0 +1,29 @@ +# 第一章 Docker 简介 + +本章将带领你进入 **Docker** 的世界。 + +> **版本提示**：本书内容及示例基于 **Docker Engine v29.x** 及以上版本。值得注意的是，自 Docker Engine v29 起，官方在全新安装场景下 **默认启用 `containerd image store` 作为镜像存储后端**（取代传统 classic store 路径下的 graph driver 体系）。这项底层革新极大增强了 Docker 对多架构镜像（Multi-platform）以及软件供应链安全元数据（Attestations, SBOM, Provenance）的本地支持原生性。 + +## 本章内容 + +* [快速上手](1.1_quickstart.md) + * 通过一个简单的 Web 应用例子，带你快速体验 Docker 的核心流程：构建镜像、运行容器。 + +* [什么是 Docker](1.2_what.md) + * 介绍 Docker 的起源、发展历程以及其背后的核心技术（Cgroups，Namespaces，UnionFS，以及 `containerd` 引擎的演进）。 + * 了解 Docker 是如何改变软件交付方式的。 + +* [为什么要用 Docker](1.3_why.md) + * 对比传统虚拟机技术，阐述 Docker 在启动速度、资源利用率、交付效率等方面的巨大优势。 + * 探讨 Docker 在 DevOps、微服务架构中的关键作用。 + + +## 学习目标 + +通过本章的学习，你将能够： + +1. 理解 Docker 的核心概念与架构。 +2. 明白 Docker 解决了现代软件开发与运维中的哪些痛点。 +3. 建立起对容器技术的初步认知，为后续的实战操作打下基础。 + +好吧，让我们带着问题开始这神奇之旅。 diff --git a/01_introduction/summary.md b/01_introduction/summary.md new file mode 100644 index 000000000..d8e74b0a8 --- /dev/null +++ b/01_introduction/summary.md @@ -0,0 +1,12 @@ +## 本章小结 + +- Docker 是一种轻量级虚拟化技术，核心价值是 **环境一致性** +- 与虚拟机相比，Docker 更轻量、更快速、资源利用率更高 +- Docker 基于 Linux 内核的 Namespace、Cgroups 和 Union FS 技术 +- Docker 推动了容器技术的标准化 (OCI) 和生态发展 + +Docker 的核心价值可以用一句话概括：**让应用的开发、测试、部署保持一致，同时极大提高资源利用效率。** 笔者认为，对于现代软件开发者来说，Docker 已经不是 “要不要学” 的问题，而是 **必备技能**。无论你是前端、后端、运维还是全栈开发者，掌握 Docker 都能让你的工作更高效。 + +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/02_basic_concept/2.1_image.md b/02_basic_concept/2.1_image.md new file mode 100644 index 000000000..7cc1cec7b --- /dev/null +++ b/02_basic_concept/2.1_image.md @@ -0,0 +1,214 @@ +## 2.1 镜像 + +> **版本说明**：本节示例基于 Docker v29.x 编写。示例中使用的镜像标签（如 `ubuntu:24.04`、`nginx:latest`）为演示用途，建议查阅 [Docker Hub](https://hub.docker.com) 或相应镜像的官方页面确认最新可用版本。 + +Docker 镜像作为容器运行的基石，其设计理念和实现机制至关重要。本节将深入探讨镜像的本质、与操作系统的关系、内容构成以及核心的分层存储机制。 + +### 2.1.1 一句话理解镜像 + +> **Docker 镜像是一个只读的模板，包含了运行应用所需的一切：代码、运行时、库、环境变量和配置文件。** 如果用一个类比：**镜像就像是一张光盘或 ISO 文件**。你可以用同一张光盘在不同电脑上安装系统，而光盘本身不会被修改。同样，一个镜像可以创建多个容器，而镜像本身保持不变。 + +### 2.1.2 镜像与操作系统的关系 + +我们都知道，操作系统分为 **内核** 和 **用户空间**： + +```mermaid +flowchart TD + subgraph UserSpace ["用户空间"] + direction TB + App["应用程序、工具、库、配置文件...
（这部分被打包成 Docker 镜像）"] + end + + subgraph KernelSpace ["Linux 内核"] + direction TB + Kernel["容器共享宿主机的内核"] + end + + UserSpace --- KernelSpace +``` +对于 Linux 而言，内核启动后会挂载 `root` 文件系统来提供用户空间支持。**Docker 镜像** 本质上就是一个 `root` 文件系统。 + +例如，官方镜像 `ubuntu:24.04` 包含了一套完整的 Ubuntu 24.04 最小系统的 root 文件系统——但 **不包含 Linux 内核**（因为容器共享宿主机的内核）。 + +### 2.1.3 镜像包含什么？ + +Docker 镜像是一个特殊的文件系统，包含： + +| 内容类型 | 示例 | +|---------|------| +| **程序文件** | 应用二进制文件、Python/Node 解释器 | +| **库文件** | libc、OpenSSL、各种依赖库 | +| **配置文件** | nginx.conf、my.cnf 等 | +| **环境变量** | PATH、LANG 等预设值 | +| **元数据** | 启动命令、暴露端口、数据卷定义 | + +**关键特性**： + +- ✅ 镜像是 **只读** 的 +- ✅ 镜像 **不包含** 动态数据 +- ✅ 镜像构建后 **内容不会改变** + +### 2.1.4 分层存储：镜像的核心设计 + +镜像的分层存储机制是 Docker 最具创新性的特性之一。通过 Union FS 技术，Docker 能够高效地构建和管理镜像。 + +#### 为什么需要分层？ + +笔者认为，分层存储是 Docker 最巧妙的设计之一。 + +假设你有三个应用，都基于 Ubuntu 运行： + +```mermaid +flowchart TD + subgraph Traditional ["传统方式（不分层）总计: 1.5GB ❌"] + direction LR + AppA_Trad["App A
Ubuntu 500MB"] + AppB_Trad["App B
Ubuntu 500MB"] + AppC_Trad["App C
Ubuntu 500MB"] + end + + subgraph DockerLayered ["Docker 分层方式 总计: 620MB ✅"] + direction TB + subgraph Apps ["应用层"] + direction LR + AppA["App A 50MB"] + AppB["App B 30MB"] + AppC["App C 40MB"] + end + Ubuntu["Ubuntu
（共享）500MB"] + + AppA --> Ubuntu + AppB --> Ubuntu + AppC --> Ubuntu + end +``` + +#### 分层是如何工作的？ + +笔者用一个更贴近最佳实践的 Dockerfile 来解释分层： + +```docker +FROM ubuntu:24.04 # 第 1 层：基础系统（约 78MB） +RUN apt-get update && apt-get install -y nginx # 第 2 层：更新索引并安装 nginx +COPY app.conf /etc/nginx/ # 第 3 层：复制配置文件 +``` +这里特意把 `apt-get update` 和 `apt-get install` 放在同一个 `RUN` 里，避免构建缓存导致包索引过期。 + +构建后的镜像结构： + +```mermaid +flowchart TD + Layer3["第 3 层: COPY app.conf (只读)
← 最新添加的层"] + Layer2["第 2 层: nginx 安装文件与包索引 (只读)"] + Layer1["第 1 层: Ubuntu 基础系统 (只读)
← 基础镜像层"] + + Layer3 --> Layer2 --> Layer1 +``` +每一层的特点： + +- **只读**：构建完成后不可修改 +- **可共享**：多个镜像可以共享相同的层 +- **有缓存**：未变化的层不会重新构建 + +#### 分层存储的 “陷阱” + +> ⚠️ **笔者特别提醒**：理解这一点可以帮你避免构建出臃肿的镜像。**关键原理**：每一层的文件变化会被记录，但 **删除操作只是标记，不会真正减小镜像体积**。 + +```docker +## 错误示范 ❌ + +FROM ubuntu:24.04 +RUN apt-get update +RUN apt-get install -y build-essential # 安装编译工具（约 200MB） +RUN make && make install # 编译应用 +RUN apt-get remove build-essential # 试图删除编译工具 + +## 结果：镜像仍然包含 200MB 的编译工具！ +``` +```docker +## 正确做法 ✅ + +FROM ubuntu:24.04 +RUN apt-get update && \ + apt-get install -y build-essential && \ + make && make install && \ + apt-get remove -y build-essential && \ + apt-get autoremove -y && \ + rm -rf /var/lib/apt/lists/* + +## 在同一层完成安装、使用、清理 + +``` + +### 2.1.5 查看镜像的构建历史 + +```bash +## 查看镜像的历史（每层的构建记录） + +$ docker history nginx:latest + +IMAGE CREATED CREATED BY SIZE +a6bd71f48f68 2 weeks ago CMD ["nginx" "-g" "daemon off;"] 0B +
• 共享网络
• 共享文件系统"] + end + + subgraph ContainerProcess ["容器进程 (运行在宿主机内核上)"] + direction TB + C1["• 独立进程空间
• 独立网络环境
• 独立文件系统
• 独立用户空间"] + end +``` +这种隔离主要通过 Linux 内核的 **Namespace** 实现，资源限制通常与 **cgroups** 配合。具体表现为： + +- **进程空间**：容器看不到宿主机上的其他进程。 +- **网络**：在默认网络模式下，容器通常拥有独立的网络命名空间，并可分配独立 IP；使用 `host` 或 `container:` 等模式时则例外。 +- **文件系统**：容器拥有独立的 root 目录。 +- **用户**：默认情况下，容器内的 `root` 仍是 `uid 0`，但通常只拥有受限 capabilities；如果启用 `userns-remap` 或 rootless 等机制，还会进一步映射为宿主机上的低权限用户。 + +### 2.2.3 容器 vs 虚拟机：核心区别 + +很多初学者会混淆容器和虚拟机。笔者用一张图来说明： + +```mermaid +flowchart TD + subgraph VM ["虚拟机 (每个 VM 运行完整 OS)"] + direction TB + subgraph VMApp ["应用层"] + VA[App A] & VB[App B] + end + subgraph VMGuest ["Guest OS (完整系统)"] + G1[Guest OS] & G2[Guest OS] + end + V[Hypervisor] + VMH[Host OS] + VMHW[Hardware] + VMApp --> VMGuest --> V --> VMH --> VMHW + end + + subgraph Container ["容器 (所有容器共享宿主机内核)"] + direction TB + subgraph CApp ["应用层"] + CA[App A] & CB[App B] + end + subgraph CContainer ["隔离层"] + CC1[Container 仅应用] & CC2[Container 仅应用] + end + CE[Docker Engine] + CH[Host OS] + CHW[Hardware] + CApp --> CContainer --> CE --> CH --> CHW + end +``` +| 特性 | 容器 | 虚拟机 | +|------|------|--------| +| **隔离级别** | 操作系统级 (Namespaces/cgroups) | 硬件虚拟化级 (Hypervisor) | +| **启动时间** | 通常更快 | 通常更慢 | +| **资源占用** | 通常更低 | 通常更高 | +| **运行开销** | 通常更接近原生 | 通常有更高虚拟化开销 | +| **内核** | 共享宿主机内核 | 各自独立内核 | + +### 2.2.4 容器的存储层 + +理解容器的存储层机制对于数据的持久化和镜像的优化至关重要。本节将介绍容器的可写层以及 Copy-on-Write 机制。 + +#### 镜像层 + 容器层 + +当容器运行时，Docker 会在镜像的只读层之上创建一个 **可写层**（容器存储层）： + +```mermaid +flowchart TD + ContainerLayer["容器存储层（可读写）
容器运行时创建，记录文件变化"] + ImageLayerN["镜像第 N 层（只读）"] + ImageLayerN1["镜像第 N-1 层（只读）"] + Dots["..."] + ImageLayer1["镜像第 1 层（只读）
基础镜像层"] + + ContainerLayer --> ImageLayerN --> ImageLayerN1 --> Dots --> ImageLayer1 +``` + +#### Copy-on-Write：写时复制 + +当容器需要修改镜像层中的文件时： + +1. Docker 将该文件 **复制** 到容器存储层 +2. 在容器层中进行修改 +3. 原始镜像层保持不变 + +```bash +读取文件：直接从镜像层读取（共享，高效） +修改文件：复制到容器层，然后修改（只有这个容器能看到修改） +``` + +#### ⚠️ 容器存储层的生命周期 + +> **笔者特别强调**：这是新手最容易踩的坑！**容器存储层与容器生命周期绑定。容器删除，数据就没了！** + +```bash +## 创建容器，写入数据 + +$ docker run -it ubuntu bash +root@abc123:/# echo "important data" > /data.txt +root@abc123:/# exit + +## 删除容器 + +$ docker rm abc123 + +## 数据丢了！没有任何办法恢复！ + +``` + +#### 正确的数据持久化方式 + +按照 Docker 最佳实践，容器存储层应该保持 **无状态**。需要持久化的数据应该使用： + +| 方式 | 说明 | 适用场景 | +|------|------|---------| +| **[数据卷 (Volume) ](../08_data/8.1_volume.md)** | Docker 管理的存储 | 数据库、应用数据 | +| **[绑定挂载 (Bind Mount) ](../08_data/8.2_bind-mounts.md)** | 挂载宿主机目录 | 开发时共享代码 | + +```bash +## 使用数据卷（推荐） + +$ docker run -v mydata:/var/lib/mysql mysql + +## 使用绑定挂载 + +$ docker run -v /host/path:/container/path nginx +``` +这些位置的读写 **会跳过容器存储层**，直接写入宿主机，性能更好，也不会随容器删除而丢失。 + +### 2.2.5 容器的生命周期 + +掌握容器的生命周期对于管理和调试 Docker 应用非常重要。如图 2-1 所示，这里先聚焦最常见的创建、运行、暂停、停止和删除流转；Docker CLI 中还可能看到 `restarting`、`removing`、`dead` 等状态。 + +```mermaid +stateDiagram-v2 + direction TB + [*] --> Created : docker create + Created --> Running : docker start + Running --> Stopped : docker stop + Running --> Paused : docker pause + Paused --> Running : docker unpause + + Created --> Deleted : docker rm + Stopped --> Deleted : docker rm + Paused --> Deleted : docker rm + + Deleted --> [*] +``` +图 2-1：容器生命周期状态流转图 + +常用生命周期命令如下： + +```bash +## 创建并启动容器（最常用） + +$ docker run nginx + +## 分步操作 + +$ docker create nginx # 创建容器（不启动） +$ docker start abc123 # 启动容器 + +## 停止容器 + +$ docker stop abc123 # 优雅停止（发送 SIGTERM，等待后发送 SIGKILL） +$ docker kill abc123 # 强制停止（直接发送 SIGKILL） + +## 暂停/恢复（不常用，但有时有用） + +$ docker pause abc123 # 暂停容器内所有进程 +$ docker unpause abc123 # 恢复 + +## 删除容器 + +$ docker rm abc123 # 删除已停止的容器 +$ docker rm -f abc123 # 强制删除运行中的容器 +``` + +### 2.2.6 容器与进程的关系 + +> **核心概念**：容器的生命周期 = 主进程 (PID 1) 的生命周期 + +```bash +## 主进程运行，容器运行 + +## 主进程退出，容器停止 + +``` +这就是为什么： + +```bash +## 这个容器会立即退出（bash 没有输入就退出了） + +$ docker run ubuntu + +## 这个容器会持续运行（官方 nginx 镜像让 nginx 在前台运行） + +$ docker run nginx +``` +官方 `nginx` 镜像默认使用 `nginx -g 'daemon off;'`，让主进程保持在前台运行，这样容器才会持续处于运行状态。 + +详细解释请参考[后台运行](../05_container/5.2_daemon.md)章节。 + +### 2.2.7 容器的隔离性 + +Docker 容器通过以下 Namespace 实现隔离： + +| Namespace | 隔离内容 | 效果 | +|-----------|---------|------| +| **PID** | 进程 ID | 容器内 PID 1 是应用进程，看不到宿主机其他进程 | +| **NET** | 网络 | 独立的网络栈、IP 地址、端口 | +| **MNT** | 文件系统 | 独立的根目录和挂载点 | +| **UTS** | 主机名 | 独立的主机名和域名 | +| **IPC** | 进程间通信 | 独立的信号量、消息队列 | +| **USER** | 用户 | 独立的用户和组 ID | + +> 想深入了解？请阅读[底层实现 - 命名空间](../12_implementation/12.2_namespace.md)。 diff --git a/02_basic_concept/2.3_repository.md b/02_basic_concept/2.3_repository.md new file mode 100644 index 000000000..f4ea474f6 --- /dev/null +++ b/02_basic_concept/2.3_repository.md @@ -0,0 +1,287 @@ +## 2.3 仓库 + +> **版本说明**：本节示例基于 Docker v29.x 和常见镜像版本编写。示例中的版本号（如 `nginx:1.28`、`mysql:8.4`、`mysql:5.7` 等）为演示用途。实际使用时请访问 [Docker Hub 官方页面](https://hub.docker.com) 或相应镜像的发布页确认最新可用版本和标签。 + +Docker Registry 是镜像分发和管理的核心组件。本节将介绍 Registry 的基本概念、公共和私有服务的选择，以及镜像的安全管理。 + +### 2.3.1 一句话理解 Registry + +> **Docker Registry 是存储和分发 Docker 镜像的服务，类似于代码的 GitHub 或包管理的 npm。** + +镜像构建完成后，可以在当前机器上运行。但如果需要在其他服务器上使用这个镜像，就需要一个集中的存储和分发服务——这就是 Docker Registry。 + +### 2.3.2 核心概念 + +要熟练使用 Docker Registry，首先需要理清它与仓库 (Repository)、标签 (Tag) 之间的关系。 + +#### Registry、仓库、标签的关系 + +Docker Registry 中可以包含多个 Repository，每个 Repository 可以包含多个 Tag。如图 2-2 所示，它们之间具有清晰的层级关系。 + +```mermaid +flowchart TB + subgraph Registry ["Docker Registry（如 Docker Hub）"] + direction TB + subgraph RepoNginx ["Repository（仓库）: nginx"] + direction LR + N1(":latest (tag)") + N2(":1.28 (tag)") + N3(":1.26 (tag)") + N4(":alpine (tag)") + N5("...") + N1 ~~~ N2 ~~~ N3 ~~~ N4 ~~~ N5 + end + subgraph RepoMysql ["Repository（仓库）: mysql"] + direction LR + M1(":latest") + M2(":8.0") + M3(":5.7") + M4("...") + M1 ~~~ M2 ~~~ M3 ~~~ M4 + end + RepoNginx ~~~ RepoMysql + end +``` +图 2-2：Registry、Repository 与 Tag 的层级关系 + +相关基本概念具体如下： + +| 概念 | 说明 | 示例 | +|------|------|------| +| **Registry** | 存储镜像的服务 | Docker Hub、ghcr.io | +| **Repository（仓库）** | 同一软件的镜像集合 | `nginx`、`mysql`、`mycompany/myapp` | +| **Tag（标签）** | 仓库内的版本标识 | `latest`、`1.28`、`alpine` | + +#### 镜像的完整名称 + +一个完整的 Docker 镜像名称由 Registry 地址、用户名/组织名、仓库名和标签组成。了解其结构有助于我们更准确地定位镜像。基本格式如下： + +```bash +[registry 地址/][用户名/]仓库名[:标签] +``` +示例： + +```bash +## 完整格式 + +registry.example.com/mycompany/myapp:v1.2.3 +│ │ │ │ +│ │ │ └── 标签 +│ │ └── 仓库名 +│ └── 用户名/组织名 +└── Registry 地址 + +## Docker Hub 官方镜像（省略 registry 和用户名） + +nginx:1.28 +ubuntu:24.04 + +## Docker Hub 用户镜像 + +jwilder/nginx-proxy:latest + +## 其他 Registry + +ghcr.io/username/myapp:v1.0 +us-west1-docker.pkg.dev/my-project/my-repo/myapp:v1.0 +``` +> 💡 **笔者提示**：如果不指定 Registry 地址，默认使用 Docker Hub。如果不指定标签，默认使用 `latest`。 + +### 2.3.3 公共 Registry 服务 + +公共 Registry 服务为开发者提供了便捷的镜像获取途径。其中最著名的是 Docker Hub。 + +#### 默认的 Docker Hub + +[Docker Hub](https://hub.docker.com/) 是最大的公共 Registry，也是 Docker 的默认 Registry。 + +**特点**： + +- 拥有大量[官方镜像](https://hub.docker.com/search?q=&type=image&image_filter=official)（nginx、mysql、redis 等） +- 免费账户可以创建公开仓库 +- 免费个人账户可创建 1 个私有仓库；更高套餐支持更多私有仓库 + +```bash +## 从 Docker Hub 拉取镜像 + +$ docker pull nginx # 官方镜像 +$ docker pull bitnami/redis # 第三方镜像 + +## 推送镜像到 Docker Hub + +$ docker login +$ docker push username/myapp:v1.0 +``` + +#### 其他公共 Registry + +除了 Docker Hub，还有以下几个常见的公共 Registry： + +| Registry | 地址 | 说明 | +|----------|------|------| +| **GitHub Container Registry** | ghcr.io | GitHub 提供，与 GitHub Actions 集成好 | +| **Google Artifact Registry** | LOCATION-docker.pkg.dev | Google Cloud 当前推荐；也支持迁移后的 `gcr.io` 兼容域名 | +| **Quay.io** | quay.io | Red Hat 提供 | +| **阿里云容器镜像服务** | registry.cn-*.aliyuncs.com | 国内访问快 | +| **腾讯云容器镜像服务** | ccr.ccs.tencentyun.com | 国内访问快 | + +Google 的 Container Registry 已废弃并完成下线，当前应优先使用 Artifact Registry；如果已经完成迁移，部分 `gcr.io` 域名请求会被兼容到 Artifact Registry。 + +### 2.3.4 镜像加速器 + +由于网络原因，在国内直接访问 Docker Hub 可能会很慢。可以配置 **镜像加速器** (Registry Mirror) 来加速下载。配置示例如下： + +```jsonc +// /etc/docker/daemon.json +{ + "registry-mirrors": [ + "https://your-accelerator-url" + ] +} +``` +详细配置方法请参考[镜像加速器](../03_install/3.9_mirror.md)章节。 + +> ⚠️ **笔者提醒**：镜像加速器的可用性经常变化，使用前建议先测试是否可用。 + +### 2.3.5 私有 Registry + +出于安全和隐私的考虑，企业往往需要搭建自己的私有 Registry。以下是几种常见的搭建方案。 + +#### 官方 Registry 镜像 + +Docker 官方提供了 [registry](https://hub.docker.com/_/registry/) 镜像，可以快速搭建私有 Registry： + +```bash +## 启动一个本地 Registry + +$ docker run -d -p 5000:5000 --name registry registry:2 + +## 推送镜像到本地 Registry + +$ docker tag myapp:v1.0 localhost:5000/myapp:v1.0 +$ docker push localhost:5000/myapp:v1.0 + +## 从本地 Registry 拉取 + +$ docker pull localhost:5000/myapp:v1.0 +``` + +#### 企业级解决方案 + +官方 Registry 功能较为基础，企业环境常用以下方案： + +| 方案 | 特点 | +|------|------| +| **[Harbor](https://goharbor.io/)** | CNCF 项目，功能全面（用户管理、漏洞扫描、镜像签名）| +| **[Nexus Repository](../06_repository/6.4_nexus3_registry.md)** | 支持多种制品类型（Docker、Maven、npm 等）| +| **云厂商服务** | 阿里云 ACR、腾讯云 TCR、AWS ECR 等 | + +笔者建议： + +- 小团队：可以先用官方 Registry，够用即可 +- 中大型团队：推荐 Harbor，功能完善且开源免费 +- 已使用云服务：直接用云厂商的 Registry 服务更省心 + +### 2.3.6 镜像的推送和拉取 + +掌握镜像的推送 (Push) 和拉取 (Pull) 是使用 Docker Registry 的基本功。 + +#### 完整工作流程 + +如图 2-3 所示，镜像从开发环境构建后推送到 Registry，再由生产环境拉取并运行。 + +```bash +开发者机器 Registry 生产服务器 + │ │ │ + │ docker build │ │ + │ 构建镜像 │ │ + │ │ │ + │ docker push ─────────────▶ │ + │ 推送镜像 │ 存储镜像 │ + │ │ │ + │ │ ◀───────────── docker pull │ + │ │ 拉取镜像 │ + │ │ │ + │ │ docker run │ + │ │ 运行容器 │ +``` +图 2-3：镜像构建、推送与拉取流程 + +#### 常用命令 + +```bash +## 登录 Registry + +$ docker login # 登录 Docker Hub +$ docker login registry.example.com # 登录其他 Registry + +## 拉取镜像 + +$ docker pull nginx:1.28 + +## 标记镜像（准备推送） + +$ docker tag myapp:latest registry.example.com/myteam/myapp:v1.0 + +## 推送镜像 + +$ docker push registry.example.com/myteam/myapp:v1.0 + +## 登出 + +$ docker logout +``` + +### 2.3.7 镜像的安全性 + +在使用公共镜像或维护私有镜像时，安全性是不容忽视的重要环节。 + +#### 使用官方镜像 + +Docker Hub 的[官方镜像](https://hub.docker.com/search?q=&type=image&image_filter=official)（标有 “Official Image” 标识）经过 Docker 团队审核，相对更安全。示例如下： + +```bash +## 官方镜像示例 + +nginx # ✅ 官方 +mysql # ✅ 官方 +redis # ✅ 官方 + +## 第三方镜像（需要自行评估可信度） + +bitnami/redis # ⚠️ 需要评估 +someuser/myapp # ⚠️ 需要评估 +``` + +#### 镜像签名 + +当前更推荐使用 Sigstore / Notation 体系进行镜像签名与验证。`Docker Content Trust (DCT)` 已被正式退役：自 Docker Engine 29.0 起 DCT 已从 Docker CLI 中移除（`docker trust` 子命令不再随 CLI 发布，仅能作为独立插件自行构建；`docker push`、`docker pull`、`docker build`、`docker run` 等命令上的 `--disable-content-trust` 选项虽仍可解析，但已标记为废弃且不再有实际作用），Docker 官方的 Notary v1 服务 `notary.docker.io` 也将于 2026 年 12 月 8 日完全关闭；最早一批 DCT 签名证书自 2025 年 8 月 8 日起已开始过期，Docker 建议镜像发布者迁移到 Sigstore、Notation 等方案。不建议把 DCT 作为新项目方案。 + +> 注意：Cosign 默认会把签名推送回镜像所在仓库，请使用你有推送权限的镜像地址。 + +```bash +## 准备一个你有写权限的镜像地址 +$ export IMAGE=<你的仓库名>/nginx:1.28 +$ docker pull nginx:1.28 +$ docker tag nginx:1.28 $IMAGE +$ docker push $IMAGE + +## 生成签名密钥（会生成 cosign.key / cosign.pub） +$ cosign generate-key-pair + +## 使用 Cosign 签名与验证 +$ cosign sign --key cosign.key $IMAGE +$ cosign verify --key cosign.pub $IMAGE +``` + +#### 漏洞扫描 + +```bash +## 使用 Docker Scout 扫描镜像漏洞 + +$ docker scout cves nginx:latest + +## 使用 Trivy（开源工具） + +$ trivy image nginx:latest +``` diff --git a/02_basic_concept/README.md b/02_basic_concept/README.md new file mode 100644 index 000000000..a7742c54d --- /dev/null +++ b/02_basic_concept/README.md @@ -0,0 +1,15 @@ +# 第二章 基本概念 + +> **版本说明**：本章内容及示例基于 Docker v29.x 编写。镜像标签相关示例请查阅官方文档以确认最新可用版本。 + +**Docker** 包括三个基本概念： + +* **镜像** (`Image`)：Docker 镜像是一个特殊的文件系统，除了提供容器运行时所需的程序、库、资源、配置等文件外，还包含了一些为运行时准备的一些配置参数（如匿名卷、环境变量、用户等）。镜像不包含任何动态数据，其内容在构建之后也不会被改变。 +* **容器** (`Container`)：镜像 (`Image`) 和容器 (`Container`) 的关系，就像是面向对象程序设计中的 `类` 和 `实例` 一样，镜像是静态的定义，容器是镜像运行时的实体。容器可以被创建、启动、停止、删除、暂停等。 +* **仓库** (`Repository`)：镜像构建完成后，可以很容易的在当前宿主机上运行，但是，如果需要在其他服务器上使用这个镜像，我们就需要一个集中的存储、分发镜像的服务，Docker Registry 就是这样的服务。 + +理解了这三个概念，就理解了 **Docker** 的整个生命周期。 + +* [Docker 镜像](2.1_image.md) +* [Docker 容器](2.2_container.md) +* [Docker 仓库](2.3_repository.md) diff --git a/02_basic_concept/summary.md b/02_basic_concept/summary.md new file mode 100644 index 000000000..0bbb89102 --- /dev/null +++ b/02_basic_concept/summary.md @@ -0,0 +1,25 @@ +## 本章小结 + +本章介绍了 Docker 的三个核心概念：镜像、容器和仓库。 + +| 概念 | 要点 | +|------|------| +| **镜像是什么** | 只读的应用模板，包含运行所需的一切 | +| **分层存储** | 多层叠加，共享基础层，节省空间 | +| **只读特性** | 构建后不可修改，保证一致性 | +| **层的陷阱** | 删除操作只是标记，不减小体积 | +| **容器是什么** | 镜像的运行实例，本质是隔离的进程 | +| **容器 vs 虚拟机** | 共享内核，更轻量，但隔离性较弱 | +| **存储层** | 可写层随容器删除而消失 | +| **数据持久化** | 使用 Volume 或 Bind Mount | +| **生命周期** | 与主进程 (PID 1) 绑定 | +| **Registry** | 存储和分发镜像的服务 | +| **仓库 (Repository)** | 同一软件的镜像集合 | +| **标签 (Tag)** | 版本标识，默认为 latest | +| **Docker Hub** | 默认的公共 Registry | +| **私有 Registry** | 企业内部使用，推荐 Harbor | + +现在你已经了解了 Docker 的三个核心概念：[镜像](2.1_image.md)、[容器](2.2_container.md) 和仓库。接下来，让我们开始 [安装 Docker](../03_install/README.md)，动手实践！ +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/03_install/3.10_experimental.md b/03_install/3.10_experimental.md new file mode 100644 index 000000000..de6a805ec --- /dev/null +++ b/03_install/3.10_experimental.md @@ -0,0 +1,33 @@ +## 3.10 开启实验特性 + +一些 docker 命令或功能仅当 **实验特性** 开启时才能使用，请按照以下方法进行设置。 + +### 3.10.1 Docker CLI 的实验特性 + +CLI 的实验特性通常包含仍在开发中的新功能。幸运的是，在较新版本中这些特性已经更加易用。 + +从 `v20.10` 及更高版本开始，Docker CLI 所有实验特性的命令均默认开启，无需再进行配置或设置系统环境变量。 + +### 3.10.2 开启 dockerd 的实验特性 + +编辑 `/etc/docker/daemon.json`，新增如下条目 + +```json +{ + "experimental": true +} +``` + +保存后重启 Docker daemon： + +```bash +$ sudo systemctl restart docker +``` + +然后执行下面的命令验证服务端实验特性已经生效： + +```bash +$ docker version +``` + +若输出中的 `Server` / `Engine` 部分出现 `Experimental: true`，说明 daemon 端实验特性已经启用。 diff --git a/03_install/3.1_ubuntu.md b/03_install/3.1_ubuntu.md new file mode 100644 index 000000000..bf2aa1e86 --- /dev/null +++ b/03_install/3.1_ubuntu.md @@ -0,0 +1,165 @@ +## 3.1 Ubuntu + +Ubuntu 是 Docker 最常用的运行环境之一。本节将介绍如何在 Ubuntu 系统上安装 Docker，并配置国内镜像加速。 + +### 为什么推荐 APT 源安装而不是脚本？ + +虽然 Docker 官方提供了便捷的安装脚本（`get.docker.com`），但笔者在生产环境中**强烈推荐通过 Docker 官方 APT 仓库安装**，原因如下： + +- **版本管理**：通过 APT 仓库安装后，可以像管理其他系统软件包一样升级、回滚和锁定版本 +- **安全更新**：Docker 官方仓库会持续发布新版本和安全修复，适合长期维护 +- **一致性**：团队更容易锁定同一版本，避免“在我的机器上可以运行”的问题 +- **卸载干净**：APT 包管理系统会负责清理所有相关文件，脚本安装的清理往往不够彻底 + +如果你只是想快速尝试 Docker，脚本安装没有问题；但一旦涉及持久运维，APT 源是更成熟的选择。 + +> 警告：切勿在没有配置 Docker APT 源的情况下直接使用 apt 命令安装 Docker。 + +### 3.1.1 准备工作 + +在开始安装之前，我们需要确认系统版本是否满足要求，并清理可能存在的旧版本。 + +#### 系统要求 + +根据 Docker 官方安装文档，当前受支持的 [Ubuntu](https://ubuntu.com/server) 64 位版本包括（具体以官方 [安装文档](https://docs.docker.com/engine/install/ubuntu/) 为准）： + + +* Ubuntu Resolute Raccoon 26.04 (LTS) +* Ubuntu Noble 24.04 (LTS) +* Ubuntu Jammy 22.04 (LTS) + +> **警告**：Ubuntu 20.04 LTS 已不在 Docker 当前支持列表中，不建议用于新部署。对于仍在运行 20.04 的生产系统，应尽快升级到 22.04 LTS 或 24.04 LTS；若短期内无法迁移，可通过 Ubuntu Pro 获取操作系统层面的扩展安全维护（ESM），但这并不改变 Docker 官方支持矩阵。 + +在 Ubuntu LTS 版本上，目前 Docker 支持 amd64、arm64、armhf、ppc64el、s390x 等 5 个平台；而非 LTS 版本支持的平台通常较少。同时，LTS 版本会获得 5 年的升级维护支持，这样的系统会获得更长期的安全保障，因此在生产环境中推荐使用 LTS 版本。 + +#### 卸载旧版本 + +Docker 官方建议先卸载可能冲突的非官方软件包： + +```bash +$ for pkg in docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc; +do + sudo apt remove $pkg; +done +``` + +### 3.1.2 使用 APT 安装 + +先安装基础依赖，并准备 Docker 官方密钥目录： + +```bash +$ sudo apt update + +$ sudo apt install ca-certificates curl +$ sudo install -m 0755 -d /etc/apt/keyrings +``` +如果企业内网已经维护了受信任的软件包镜像，可在后续步骤中替换 `URIs` 的域名；默认建议优先以 Docker 官方仓库为准。 + +为了确认所下载软件包的合法性，需要添加仓库签名密钥： + +```bash +$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +$ sudo chmod a+r /etc/apt/keyrings/docker.asc +``` +然后向 `apt` 添加 Docker 仓库： + +```bash +$ sudo tee /etc/apt/sources.list.d/docker.sources <
(已存在，跳过下载)"] + L2["第2层 be13a9d27eb8
(下载中... 完成)"] + L1["第1层 92dc2a97ff99
(下载中... 完成)"] + L3 --- L2 --- L1 + end +``` +如果本地已有相同的层，Docker 会跳过下载，节省带宽和时间。 + +--- + +### 4.1.3 常用选项 + +`docker pull` 命令支持多种选项来满足不同的下载需求，例如下载所有标签、指定平台架构等。 + +| 选项 | 说明 | 示例 | +|------|------|------| +| `--all-tags, -a` | 拉取所有标签 | `docker pull -a ubuntu` | +| `--platform` | 指定平台架构 | `docker pull --platform linux/arm64 nginx` | +| `--quiet, -q` | 静默模式 | `docker pull -q nginx` | + +#### 指定平台 + +在 Apple Silicon Mac 上拉取 x86 镜像： + +```bash +$ docker pull --platform linux/amd64 nginx +``` +--- + +### 4.1.4 拉取后运行 + +拉取镜像后，可以基于它启动容器： + +```bash +## 拉取镜像 + +$ docker pull ubuntu:24.04 + +## 运行容器 + +$ docker run -it --rm ubuntu:24.04 bash +root@e7009c6ce357:/# cat /etc/os-release +PRETTY_NAME="Ubuntu 24.04 LTS" +... +root@e7009c6ce357:/# exit +``` + +> 本例使用 `ubuntu:24.04` 这样的具体版本标签是最佳实践。若无特殊需求，避免使用 `docker pull ubuntu` 或 `ubuntu:latest`，因为镜像内容可能在某个时刻发生变化。 + +**参数说明**： + +| 参数 | 说明 | +|------|------| +| `-it` | 交互式终端模式 | +| `--rm` | 退出后自动删除容器 | +| `bash` | 启动命令 | + +> 💡 `docker run` 在需要时会自动 `pull` 镜像，因此通常不需要单独执行 `docker pull`。 + +--- + +### 4.1.5 镜像加速 + +从 Docker Hub 下载可能较慢。可以配置镜像加速器： + +```jsonc +// /etc/docker/daemon.json (Linux) +// ~/.docker/daemon.json (Docker Desktop) +{ + "registry-mirrors": [ + "https://your-accelerator-url" + ] +} +``` +配置后重启 Docker： + +```bash +$ sudo systemctl restart docker # Linux + +## 或在 Docker Desktop 中重启 +``` +详见[镜像加速器](../03_install/3.9_mirror.md)章节。 + +--- + +### 4.1.6 验证镜像完整性 + +为了确保下载的镜像没有被篡改且内容一致，我们可以校验镜像的摘要 (Digest)。 + +#### 查看镜像摘要 + +```bash +$ docker images --digests ubuntu +REPOSITORY TAG DIGEST IMAGE ID +ubuntu 24.04 sha256:4bc3ae6596938cb0d9e5ac51a1152ec9dcac2a1c50829c74abd9c4361e321b26 ca2b0f26964c +``` + +#### 使用摘要拉取 + +用摘要拉取可确保获取完全相同的镜像： + +```bash +$ docker pull ubuntu@sha256:4bc3ae6596938cb0d9e5ac51a1152ec9dcac2a1c50829c74abd9c4361e321b26 +``` +> 笔者建议：生产环境使用摘要而非标签，因为标签可能被覆盖，摘要则是不可变的。 + +--- + +### 4.1.7 常见问题 + +在使用 `docker pull` 过程中，可能会遇到下载速度慢、镜像不存在或磁盘空间不足等问题。以下是一些常见问题的排查思路。 + +#### Q：下载速度很慢 + +1. 配置镜像加速器 +2. 检查网络连接 +3. 尝试拉取更小的镜像版本（如 `alpine` 变体） + +#### Q：提示镜像不存在 + +```bash +Error: pull access denied, repository does not exist +``` +可能原因： + +- 镜像名拼写错误 +- 私有镜像未登录（需要 `docker login`） +- 镜像确实不存在 + +#### Q：磁盘空间不足 + +```bash +## 清理未使用的镜像 + +$ docker image prune + +## 清理所有未使用资源 + +$ docker system prune +``` +--- diff --git a/04_image/4.2_list.md b/04_image/4.2_list.md new file mode 100644 index 000000000..b9f1c84c9 --- /dev/null +++ b/04_image/4.2_list.md @@ -0,0 +1,261 @@ +## 4.2 列出镜像 + +在下载了镜像后，我们可以使用 `docker image ls` 命令列出本地主机上的镜像。 + +### 4.2.1 基本用法 + +查看本地已下载的镜像： + +```bash +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE +redis latest 5f515359c7f8 5 days ago 183MB +nginx latest 05a60462f8ba 5 days ago 181MB +ubuntu 24.04 329ed837d508 3 days ago 78MB +ubuntu noble 329ed837d508 3 days ago 78MB +``` +> 💡 `docker images` 是 `docker image ls` 的简写，两者等效。 + +--- + +### 4.2.2 输出字段说明 + +`docker image ls` 命令默认输出的列表包含仓库名、标签、镜像 ID、创建时间和占用空间等信息。 + +| 字段 | 说明 | +|------|------| +| **REPOSITORY** | 仓库名 | +| **TAG** | 标签（版本）| +| **IMAGE ID** | 镜像唯一标识（短 ID，前 12 位）| +| **CREATED** | 创建时间 | +| **SIZE** | 本地占用空间 | + +#### 同一镜像多个标签 + +注意上面的 `ubuntu:24.04` 和 `ubuntu:noble` 拥有相同的 IMAGE ID——它们是同一个镜像的不同标签，只占用一份存储空间。 + +> **版本说明**：`ubuntu:24.04` 是具体版本号，`ubuntu:noble` 是发布代号（Ubuntu 24.04 的代号）。在 Dockerfile 中应优先使用版本号（如 `ubuntu:24.04`）而非发布代号，因为版本号在将来更易理解。 + +--- + +### 4.2.3 理解镜像大小 + +Docker 镜像的大小可能与我们通常理解的文件大小有所不同，这涉及到分层存储的概念。 + +#### 本地大小 vs Hub 显示大小 + +| 位置 | 显示大小 | 说明 | +|------|---------|------| +| Docker Hub | 29MB | 压缩后的网络传输大小 | +| docker image ls | 78MB | 本地解压后的实际大小 | + +#### 实际磁盘占用 + +由于镜像是分层存储，不同镜像可能共享相同的层： + +```bash +ubuntu:24.04 nginx:latest redis:latest + │ │ │ + └───────┬───────┘ │ + ▼ │ + 共享基础层 ◄───────────────────┘ +``` +因此，`docker image ls` 中各镜像大小之和 > 实际磁盘占用。 + +#### 查看实际空间占用 + +```bash +$ docker system df +TYPE TOTAL ACTIVE SIZE RECLAIMABLE +Images 15 3 2.5GB 1.8GB (72%) +Containers 5 2 100MB 80MB (80%) +Local Volumes 8 2 500MB 400MB (80%) +Build Cache 0 0 0B 0B +``` +--- + +### 4.2.4 过滤镜像 + +随着本地镜像数量的增加，我们需要更有效的方式来查找特定的镜像。Docker 提供了多种过滤方式。 + +#### 按仓库名过滤 + +```bash +## 列出所有 ubuntu 镜像 + +$ docker images ubuntu +REPOSITORY TAG IMAGE ID SIZE +ubuntu 24.04 329ed837d508 78MB +ubuntu noble 329ed837d508 78MB +ubuntu 22.04 a1b2c3d4e5f6 72MB +``` + +#### 按仓库名和标签过滤 + +```bash +$ docker images ubuntu:24.04 +REPOSITORY TAG IMAGE ID SIZE +ubuntu 24.04 329ed837d508 78MB +``` + +#### 使用过滤器 --filter + +| 过滤条件 | 说明 | 示例 | +|---------|------|------| +| `dangling=true` | 虚悬镜像 | `-f dangling=true` | +| `before=镜像` | 在某镜像之前创建 | `-f before=nginx:latest` | +| `since=镜像` | 在某镜像之后创建 | `-f since=nginx:latest` | +| `label=key=value` | 按 LABEL 过滤 | `-f label=version=1.0` | +| `reference=pattern` | 按名称模式 | `-f reference='*:latest'` | + +```bash +## 列出 nginx 之后创建的镜像 + +$ docker images -f since=nginx:latest + +## 列出所有带 latest 标签的镜像 + +$ docker images -f reference='*:latest' + +## 列出带特定 LABEL 的镜像 + +$ docker images -f label=maintainer=example@email.com +``` +--- + +### 4.2.5 虚悬镜像 + +仓库名和标签都为 `
+
现在，假设我们非常不喜欢这个欢迎页面，我们希望改成欢迎 Docker 的文字，我们可以使用 `docker exec` 命令进入容器，修改其内容。
@@ -26,14 +31,13 @@ root@3729b97e8226:/# echo 'Hello, Docker!
' > /usr/share/nginx/html/inde root@3729b97e8226:/# exit exit ``` - 我们以交互式终端方式进入 `webserver` 容器，并执行了 `bash` 命令，也就是获得一个可操作的 Shell。 然后，我们用 `Hello, Docker!
` 覆盖了 `/usr/share/nginx/html/index.html` 的内容。 现在我们再刷新浏览器的话，会发现内容被改变了。 -
+
我们修改了容器的文件，也就是改动了容器的存储层。我们可以通过 `docker diff` 命令看到具体的改动。
@@ -56,6 +60,7 @@ A /var/cache/nginx/proxy_temp
A /var/cache/nginx/scgi_temp
A /var/cache/nginx/uwsgi_temp
```
+其中，`A` 表示新增（Added），`C` 表示变更（Changed），`D` 表示删除（Deleted）。
现在我们定制好了变化，我们希望能将其保存下来形成镜像。
@@ -66,8 +71,7 @@ A /var/cache/nginx/uwsgi_temp
```bash
docker commit [选项] <容器ID或容器名> [<仓库名>[:<标签>]]
```
-
-我们可以用下面的命令将容器保存为镜像：
+我们可以用下面的命令将容器保存为镜像。默认情况下，`docker commit` 会在提交时暂停容器进程，以降低数据损坏的风险；如果确实不希望暂停，可以显式指定 `--no-pause`：
```bash
$ docker commit \
@@ -77,19 +81,21 @@ $ docker commit \
nginx:v2
sha256:07e33465974800ce65751acc279adc6ed2dc5ed4e0838f8b86f0c87aa1795214
```
-
其中 `--author` 是指定修改的作者，而 `--message` 则是记录本次修改的内容。这点和 `git` 版本控制相似，不过这里这些信息可以省略留空。
-我们可以在 `docker images` 中看到这个新定制的镜像：
+我们可以在 `docker image ls` 中看到这个新定制的镜像。下面的输出仅为示例，标签、创建时间和大小会随着镜像版本和本地环境不同而变化：
```bash
-$ docker images nginx
+$ docker image ls nginx
REPOSITORY TAG IMAGE ID CREATED SIZE
nginx v2 07e334659748 9 seconds ago 181.5 MB
-nginx 1.11 05a60462f8ba 12 days ago 181.5 MB
-nginx latest e43d811ce2f4 4 weeks ago 181.5 MB```
+nginx 1.30 05a60462f8ba 12 days ago 181.5 MB
+nginx latest e43d811ce2f4 4 weeks ago 181.5 MB
+```
+
+> **版本说明**：上面示例中 `nginx:1.30` 代表 1.30 系列的最新 patch 版本。在实际应用中应根据需求选择确切的版本号，而不是盲目使用 `latest`。
-我们还可以用 `docker history` 具体查看镜像内的历史记录，如果比较 `nginx:latest` 的历史记录，我们会发现新增了我们刚刚提交的这一层。
+我们还可以用 `docker history` 具体查看镜像内的历史记录。例如先执行 `docker history nginx:v2`，再对比 `docker history nginx:latest`，就能看到我们刚刚提交出来的新层。
```bash
$ docker history nginx:v2
@@ -99,30 +105,26 @@ e43d811ce2f4 4 weeks ago /bin/sh -c #(nop) CMD ["nginx" "-g" "da
Hello, Docker!
' > /usr/share/nginx/html/index.html +``` +这个 Dockerfile 很简单，一共就两行。涉及到了两条指令，`FROM` 和 `RUN`。 + +### 4.5.3 FROM 指定基础镜像 + +所谓定制镜像，那一定是以一个镜像为基础，在其上进行定制。就像我们之前运行了一个 `nginx` 镜像的容器，再进行修改一样，基础镜像是必须指定的。而 `FROM` 就是指定 **基础镜像**，因此一个 `Dockerfile` 中 `FROM` 是必备的指令，并且必须是第一条**构建指令**——按官方 Dockerfile 参考，它之前只允许出现 parser 指令、注释和全局作用域的 `ARG`，`ARG` 是唯一能写在 `FROM` 之前的指令（见 [7.7 ARG](../07_dockerfile/7.7_arg.md)）。 + +> **版本号最佳实践**：在 `FROM` 指令中 **务必指定具体版本号**（如 `FROM ubuntu:24.04` 或 `FROM python:3.12-slim`）而非 `FROM ubuntu` 或 `FROM python:latest`。这样可以确保 Dockerfile 在不同时间、不同环境下构建出的镜像内容一致，避免因基础镜像更新导致的不可预期的变化。 + +在 [Docker Hub](https://hub.docker.com/search?q=&type=image&image_filter=official) 上有非常多的高质量的官方镜像，有可以直接拿来使用的服务类的镜像，如 [`nginx`](https://hub.docker.com/_/nginx/)、[`redis`](https://hub.docker.com/_/redis/)、[`mongo`](https://hub.docker.com/_/mongo/)、[`mysql`](https://hub.docker.com/_/mysql/)、[`httpd`](https://hub.docker.com/_/httpd/)、[`php`](https://hub.docker.com/_/php/)、[`tomcat`](https://hub.docker.com/_/tomcat/) 等；也有一些方便开发、构建、运行各种语言应用的镜像，如 [`node`](https://hub.docker.com/_/node)、[`eclipse-temurin`](https://hub.docker.com/_/eclipse-temurin/)、[`python`](https://hub.docker.com/_/python/)、[`ruby`](https://hub.docker.com/_/ruby/)、[`golang`](https://hub.docker.com/_/golang/) 等。可以在其中寻找一个最符合我们最终目标的镜像为基础镜像进行定制。 + +如果没有找到对应服务的镜像，官方镜像中还提供了一些更为基础的操作系统镜像，如 [`ubuntu`](https://hub.docker.com/_/ubuntu/)、[`debian`](https://hub.docker.com/_/debian/)、[`centos`](https://hub.docker.com/_/centos/)、[`fedora`](https://hub.docker.com/_/fedora/)、[`alpine`](https://hub.docker.com/_/alpine/) 等，这些操作系统的软件库为我们提供了更广阔的扩展空间。 + +除了选择现有镜像为基础镜像外，Docker 还存在一个特殊的镜像，名为 `scratch`。这个镜像是虚拟的概念，并不实际存在，它表示一个空白的镜像。 + +```docker +FROM scratch +... +``` +如果你以 `scratch` 为基础镜像的话，意味着你不以任何镜像为基础，接下来所写的指令将作为镜像第一层开始存在。 + +不以任何系统为基础，直接将可执行文件复制进镜像的做法并不罕见，对于 Linux 下静态编译的程序来说，并不需要有操作系统提供运行时支持，所需的一切库都已经在可执行文件里了，因此直接 `FROM scratch` 会让镜像体积更加小巧。使用 [Go 语言](https://golang.google.cn/)开发的应用很多会使用这种方式来制作镜像，这也是有人认为 Go 是特别适合容器微服务架构的语言的原因之一。 + +### 4.5.4 RUN 执行命令 + +`RUN` 指令是用来执行命令行命令的。由于命令行的强大能力，`RUN` 指令在定制镜像时是最常用的指令之一。其格式有两种： + +* *shell* 格式：`RUN <命令>`，就像直接在命令行中输入的命令一样。刚才写的 Dockerfile 中的 `RUN` 指令就是这种格式。 + +```docker +RUN echo 'Hello, Docker!
' > /usr/share/nginx/html/index.html +``` + +* *exec* 格式：`RUN ["可执行文件", "参数1", "参数2"]`，这更像是函数调用中的格式。 + +在会修改文件系统的指令里，`RUN` 是最典型的一类。每一个 `RUN` 的行为，都可以类比为我们刚才手工建立镜像的过程：先基于当前结果启动一个临时构建环境，在其上执行这些命令，再把这一步产生的文件系统变化保存为新的结果层。 + +> **注意** +> +> 每一个 `RUN` 指令都会产生一个新的镜像层。为了减少镜像体积和层数，我们通常会将多个命令合并到一个 `RUN` 指令中执行。 +> +> 更多关于 `RUN` 指令的详细用法、最佳实践（如清理缓存、使用 pipefail 等）及 `Union FS` 的层数限制等内容，请参阅 **[第七章 Dockerfile 指令详解](../07_dockerfile/README.md)** 中的 **[RUN 指令](../07_dockerfile/7.1_run.md)** 小节。 + +要想编写优秀的 `Dockerfile`，必须了解每一条指令的作用和副作用。在 **[第七章 Dockerfile 指令详解](../07_dockerfile/README.md)** 中，我们将对 `COPY`，`ADD`，`CMD`，`ENTRYPOINT` 等指令进行详细讲解。 + +### 4.5.5 构建镜像 + +好了，让我们再回到之前定制的 nginx 镜像的 Dockerfile 来。现在我们明白了这个 Dockerfile 的内容，那么让我们来构建这个镜像吧。 + +在 `Dockerfile` 文件所在目录执行： + +```bash +$ docker build -t nginx:v3 . +``` + +在当前版本的 Docker 中，`docker build` 默认会通过 Buildx 调用 BuildKit，因此你更常看到的是 `[+] Building ...` 这类输出。为了帮助理解“每一步如何形成镜像历史”，下面仍展示一种较容易阅读的经典输出形式： + +```bash +Sending build context to Docker daemon 2.048 kB +Step 1 : FROM nginx + ---> e43d811ce2f4 +Step 2 : RUN echo 'Hello, Docker!
' > /usr/share/nginx/html/index.html + ---> Running in 9cdc27646c7b + ---> 44aa4490ce2c +Removing intermediate container 9cdc27646c7b +Successfully built 44aa4490ce2c +``` +从命令的输出结果中，我们可以清晰地看到镜像的构建过程。在 `Step 2` 中，如同我们之前所说的那样，`RUN` 指令启动了一个容器 `9cdc27646c7b`，执行了所要求的命令，并最后提交了这一层 `44aa4490ce2c`，随后删除了所用到的这个容器 `9cdc27646c7b`。 + +这里我们使用了 `docker build` 命令进行镜像构建。其格式为： + +```bash +docker build [选项] <上下文路径/URL/-> +``` +在这里我们指定了最终镜像的名称 `-t nginx:v3`，构建成功后，我们可以像之前运行 `nginx:v2` 那样来运行这个镜像，其结果会和 `nginx:v2` 一样。 + +### 4.5.6 镜像构建上下文 + +如果注意，会看到 `docker build` 命令最后有一个 `.`。`.` 表示当前目录，而 `Dockerfile` 就在当前目录，因此不少初学者以为这个路径是在指定 `Dockerfile` 所在路径，这么理解其实是不准确的。如果对应上面的命令格式，你可能会发现，这是在指定 **上下文路径**。那么什么是上下文呢？ + +首先要理解 `docker build` 的工作原理。今天的 `docker build` 默认会通过 Buildx 向 BuildKit 后端发起构建请求；无论后端运行在本机还是远端，位置参数指定的都是 **构建上下文**，也就是构建器可以访问到的文件集合。 + +当我们进行镜像构建的时候，并非所有定制都会通过 `RUN` 指令完成，经常还需要把本地文件复制进镜像，比如通过 `COPY` 指令、`ADD` 指令等。因此，构建器必须能够访问这些文件，而它能访问的范围正是你传给 `docker build` 的那个上下文。 + +如果上下文是本地目录，那么这个目录中的文件和子目录就会成为可用输入；如果上下文是远端 Git 仓库或 tar 包，那么构建器会直接获取对应内容。对于本地目录，BuildKit 会按需读取构建过程中真正需要的文件，而不是让 Dockerfile 任意访问宿主机上的任意路径。 + +如果在 `Dockerfile` 中这么写： + +```docker +COPY ./package.json /app/ +``` +这并不是要复制执行 `docker build` 命令所在的目录下的 `package.json`，也不是复制 `Dockerfile` 所在目录下的 `package.json`，而是复制 **上下文 (context)** 目录下的 `package.json`。 + +因此，`COPY` 这类指令中的源文件路径都应该以构建上下文为基准来理解。对于 legacy builder，像 `COPY ../package.json /app` 这样的写法会直接报错；而在 BuildKit 下，前导的越界 `../` 会被剥离并重新解释为上下文内路径。无论是哪种情况，构建器都无法读取上下文之外的宿主机文件；如果真的需要那些文件，应该先把它们放进上下文目录，或重新选择合适的上下文。 + +现在就可以理解刚才的命令 `docker build -t nginx:v3 .` 中的这个 `.`，实际上是在指定上下文目录，而不是单纯指定 `Dockerfile` 所在目录。 + +如果观察 `docker build` 的经典输出，或 BuildKit 输出中的 `transferring context` 提示，我们其实都能看到上下文传输的过程： + +```bash +$ docker build -t nginx:v3 . +Sending build context to Docker daemon 2.048 kB +... +``` +理解构建上下文对于镜像构建是很重要的，避免犯一些不应该的错误。比如有些初学者在发现需要的文件不在上下文里后，干脆把上下文切到硬盘根目录去构建。这样做即使在 BuildKit 下也会让可见上下文变得过大，并且在使用 `COPY . .`、`ADD . /app` 之类写法时，仍可能触发大规模上下文传输，导致构建缓慢甚至失败。这显然是使用错误。 + +一般来说，应该会将 `Dockerfile` 置于一个空目录下，或者项目根目录下。如果该目录下没有所需文件，那么应该把所需文件复制一份过来。如果目录下有些东西确实不希望构建时传给 Docker 引擎，那么可以用 `.gitignore` 一样的语法写一个 `.dockerignore`，该文件是用于剔除不需要作为上下文传递给 Docker 引擎的。 + +那么为什么会有人误以为 `.` 是指定 `Dockerfile` 所在目录呢？这是因为在默认情况下，如果不额外指定 `Dockerfile` 的话，会将上下文目录下的名为 `Dockerfile` 的文件作为 Dockerfile。 + +这只是默认行为，实际上 `Dockerfile` 的文件名并不要求必须为 `Dockerfile`，而且并不要求必须位于上下文目录中，比如可以用 `-f ../Dockerfile.php` 参数指定某个文件作为 `Dockerfile`。 + +当然，一般大家习惯性的会使用默认的文件名 `Dockerfile`，以及会将其置于镜像构建上下文目录中。 + +### 4.5.7 其他 `docker build` 的用法 + +#### 直接用 Git repo 进行构建 + +或许你已经注意到了，`docker build` 还支持从 URL 构建，也就是直接把远端 Git 仓库作为上下文。传统写法可以使用 URL 片段 `#ref:dir`，例如： + +```bash +$ docker build https://github.com/user/myrepo.git#mybranch:docker +``` +这行命令表示：把 Git 仓库作为构建上下文，使用 `mybranch` 分支中的 `docker/` 子目录来构建。在较新的 Buildx 中，也可以改用结构更清晰的查询参数写法，例如 `?branch=mybranch&subdir=docker`。 + +#### 用给定的 tar 压缩包构建 + +```bash +$ docker build http://server/context.tar.gz +``` +如果所给出的 URL 不是个 Git repo，而是个 `tar` 压缩包，那么 Docker 引擎会下载这个包，并自动解压缩，以其作为上下文，开始构建。 + +#### 从标准输入中读取 Dockerfile 进行构建 + +```bash +docker build - < Dockerfile +``` +或 + +```bash +cat Dockerfile | docker build - +``` +如果标准输入传入的是文本文件，则将其视为 `Dockerfile`，并开始构建。这种形式由于直接从标准输入中读取 Dockerfile 的内容，它没有上下文，因此不可以像其他方法那样可以将本地文件 `COPY` 进镜像之类的事情。 + +#### 从标准输入中读取上下文压缩包进行构建 + +```bash +$ docker build - < context.tar.gz +``` +如果发现标准输入的文件格式是 `gzip`、`bzip2` 以及 `xz` 的话，将会将其视为上下文压缩包，直接将其展开，将里面视为上下文，并开始构建。 diff --git a/04_image/4.6_other.md b/04_image/4.6_other.md new file mode 100644 index 000000000..a8aefe8e4 --- /dev/null +++ b/04_image/4.6_other.md @@ -0,0 +1,83 @@ +## 4.6 其他制作镜像的方式 + +除了标准的使用 `Dockerfile` 生成镜像的方法外，由于各种特殊需求和历史原因，还提供了一些其他方法用以生成镜像。 + +### 4.6.1 从 rootfs 压缩包导入 + +格式：`docker import [选项] <文件>|• 基于镜像的只读层
• 添加一层可读写层（容器存储层）"] --> Step3 + Step3["3. 配置网络
• 创建虚拟网卡
• 分配 IP 地址
• 连接到 Docker 网桥"] --> Step4 + Step4["4. 启动容器，执行指定命令"] --> Step5 + Step5["5. 命令执行完毕，容器停止"] +``` + +### 5.1.4 常用启动选项 + +#### 基础选项 + +| 选项 | 说明 | 示例 | +|------|------|------| +| `-d` | 后台运行 (detach)| `docker run -d nginx:latest` | +| `-it` | 交互式终端 | `docker run -it ubuntu:24.04 bash` | +| `--name` | 指定容器名称 | `docker run --name myapp nginx:latest` | +| `--rm` | 退出后自动删除容器 | `docker run --rm ubuntu:24.04 echo hi` | + +#### 端口映射 + +```bash +## 将容器的 80 端口映射到宿主机的 8080 端口 + +$ docker run -d -p 8080:80 nginx:latest + +## 随机映射端口 + +$ docker run -d -P nginx:latest + +## 只绑定到 localhost + +$ docker run -d -p 127.0.0.1:8080:80 nginx:latest +``` + +#### 数据卷挂载 + +```bash +## 挂载命名卷 + +$ docker run -v mydata:/data nginx:latest + +## 挂载宿主机目录 + +$ docker run -v /host/path:/container/path nginx:latest + +## 只读挂载 + +$ docker run -v /host/path:/container/path:ro nginx:latest +``` + +#### 环境变量 + +```bash +## 设置单个环境变量 + +$ docker run -e MYSQL_ROOT_PASSWORD=secret mysql + +## 从文件加载环境变量 + +$ docker run --env-file .env myapp +``` + +#### 资源限制 + +```bash +## 限制内存 + +$ docker run -m 512m nginx:latest + +## 限制 CPU + +$ docker run --cpus=1.5 nginx:latest +``` + +### 5.1.5 启动已终止容器 + +使用 `docker start` 重新启动已停止的容器： + +```bash +## 查看所有容器（包括已停止的） + +$ docker ps -a +CONTAINER ID IMAGE STATUS NAMES +af8bae53bdd3 ubuntu Exited (0) 2 minutes ago myubuntu + +## 重新启动 + +$ docker start myubuntu + +## 启动并附加终端 + +$ docker start -ai myubuntu +``` + +### 5.1.6 容器内进程的特点 + +容器内只运行指定的应用程序及其必需资源： + +```bash +root@ba267838cc1b:/# ps + PID TTY TIME CMD + 1 ? 00:00:00 bash + 11 ? 00:00:00 ps +``` +可见容器中仅运行了 `bash` 进程。这种特点使得 Docker 对资源的利用率极高。 + +> 💡 笔者提示：容器内的 PID 1 进程很重要——它是容器的主进程，该进程退出则容器停止。详见[后台运行](5.2_daemon.md)章节。 + +### 5.1.7 常见问题 + +#### Q：容器启动后立即退出 + +**原因**：主进程执行完毕或无法保持运行 + +```bash +## 这个容器会立即退出（echo 执行完就结束了） + +$ docker run ubuntu:24.04 echo "hello" + +## 解决：使用能持续运行的命令 + +$ docker run -d nginx:latest # nginx 是持续运行的服务 +``` +详细解释见[后台运行](5.2_daemon.md)。 + +#### Q：无法连接容器内的服务 + +**原因**：未正确映射端口 + +```bash +## 错误：没有 -p 参数，外部无法访问 + +$ docker run -d nginx:latest + +## 正确：映射端口 + +$ docker run -d -p 80:80 nginx:latest +``` + +#### Q：容器内修改的文件丢失 + +**原因**：未使用数据卷，数据保存在容器存储层 + +```bash +## 使用数据卷持久化 + +$ docker run -v mydata:/app/data myapp +``` +详见[数据管理](../08_data/README.md)。 diff --git a/05_container/5.2_daemon.md b/05_container/5.2_daemon.md new file mode 100644 index 000000000..60ee952e0 --- /dev/null +++ b/05_container/5.2_daemon.md @@ -0,0 +1,230 @@ +## 5.2 守护态运行 + +在生产环境中，我们通常需要容器持续运行，不受终端关闭的影响。本节将深入讲解如何让容器在后台运行，以及理解容器生命周期的核心概念。 + +### 5.2.1 核心概念：前台 vs 后台 + +当你在终端运行一个程序时，有两种模式： + +- **前台运行**：程序占用当前终端，输出直接显示，关闭终端程序就停止 +- **后台运行**：程序在后台执行，不占用终端，终端关闭也不影响程序 + +Docker 容器默认是 **前台运行** 的。使用 `-d` (detach) 参数可以让容器在后台运行。 + +### 5.2.2 基本使用 + +#### 前台运行：默认 + +```bash +$ docker run ubuntu:24.04 /bin/sh -c "while true; do echo hello world; sleep 1; done" +hello world +hello world +hello world +hello world +``` +容器会把输出的结果 (STDOUT) 打印到宿主机上面。此时： + +- 终端被占用，无法执行其他命令 +- 按 `Ctrl+C` 会终止容器 +- 关闭终端窗口，容器也会停止 + +#### 后台运行：使用 -d 参数 + +```bash +$ docker run -d ubuntu:24.04 /bin/sh -c "while true; do echo hello world; sleep 1; done" +77b2dc01fe0f3f1265df143181e7b9af5e05279a884f4776ee75350ea9d8017a +``` +使用 `-d` 参数后： + +- 容器在后台运行 +- 返回容器的完整 ID +- 终端立即释放，可以继续执行其他命令 +- 输出不会直接显示（需要用 `docker logs` 查看） + +### 5.2.3 深入理解：容器为什么会 “立即退出”？ + +> **这是初学者最常遇到的困惑。** 理解这个问题，你就理解了 Docker 的核心设计理念。 + +很多人尝试这样启动容器： + +```bash +$ docker run -d ubuntu:24.04 +``` +然后用 `docker ps` 查看，发现容器根本不在运行！这是为什么？ + +#### 核心原理：容器的生命周期与主进程绑定 + +```mermaid +flowchart TD + subgraph Lifecycle ["Docker 容器的生命周期 = 容器内 PID 1 进程的生命周期"] + direction LR + Start["主进程启动"] --> Run["容器运行"] + Exit["主进程退出"] --> Stop["容器停止"] + end +``` +当你运行 `docker run -d ubuntu:24.04` 时： + +1. 容器启动 +2. 没有指定命令，默认执行 `/bin/bash` +3. 但没有交互式终端（没有 `-it` 参数），bash 发现没有输入源 +4. bash 立即退出 +5. 主进程退出，容器停止 + +**关键理解**： + +- ❌ `-d` 参数 **不是** 让容器 “一直运行” +- ✅ `-d` 参数是让容器 “在后台运行”，能运行多久取决于主进程 + +#### 常见的 “立即退出” 场景 + +| 场景 | 原因 | 解决方案 | +|------|------|---------| +| `docker run -d ubuntu` | 默认 bash 无输入立即退出 | 指定长期运行的命令 | +| `docker run -d nginx` 后改了配置 | 配置错误导致 nginx 启动失败 | 查看 `docker logs` | +| 自定义镜像容器启动即退 | Dockerfile 的 CMD 执行完毕 | 确保 CMD 是前台进程 | + +### 5.2.4 查看后台容器 + +#### 查看运行中的容器 + +```bash +$ docker container ls +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +77b2dc01fe0f ubuntu:24.04 /bin/sh -c 'while tr 2 minutes ago Up 1 minute agitated_wright +``` + +#### 查看容器输出日志 + +```bash +$ docker container logs 77b2dc01fe0f +hello world +hello world +hello world +... +``` +**实时查看日志**（类似 `tail -f`）： + +```bash +$ docker container logs -f 77b2dc01fe0f +``` + +#### 查看已停止的容器 + +```bash +$ docker container ls -a +``` +加上 `-a` 参数可以看到所有容器，包括已停止的。这对于调试 “容器启动即退出” 的问题非常有用。 + +### 5.2.5 最佳实践 + +#### 1. 长期运行的服务使用 -d + +```bash +## Web 服务器 + +$ docker run -d -p 80:80 nginx:latest + +## 数据库 + +$ docker run -d -p 3306:3306 mysql:8.4 + +## 缓存服务 + +$ docker run -d -p 6379:6379 redis:latest +``` + +> **版本说明**：示例使用常见的标签如 `latest` 或稳定大版本号如 `mysql:8.4`。具体版本可根据需求调整，生产环境建议明确指定版本号（如 `mysql:8.4.4`）而非使用 `latest`。 + +#### 2. 调试时先用前台模式 + +当容器启动有问题时，**去掉 `-d` 参数** 可以直接看到输出和错误： + +```bash +## 有问题的容器，先前台运行看看发生了什么 + +$ docker run myimage:v1.0.0 +``` + +#### 3. 使用 --rm 自动清理 + +对于一次性任务，使用 `--rm` 参数让容器退出后自动删除： + +```bash +$ docker run --rm ubuntu:24.04 echo "Hello, World!" +Hello, World! + +## 容器执行完后自动删除 + +... +``` + +#### 4. 配合日志查看 + +```bash +## 后台启动 + +$ docker run -d --name myapp myimage:v1.0.0 + +## 查看最近 100 行日志 + +$ docker logs --tail 100 myapp + +## 实时跟踪日志 + +$ docker logs -f myapp + +## 查看带时间戳的日志 + +$ docker logs -t myapp +``` + +### 5.2.6 常见问题排查 + +#### Q：容器启动后立即退出 + +1. **查看退出状态码**： + ```bash + $ docker ps -a --filter "name=mycontainer" + # 查看 STATUS 列，如 “Exited (1)” 表示异常退出 + + ``` + +2. **查看容器日志**： + ```bash + $ docker logs mycontainer + ``` + +3. **以交互模式调试**： + ```bash + # /bin/sh 覆盖镜像原本的启动命令，避免容器再次崩溃退出 + # 进入 shell 后可手动执行原启动命令，定位具体报错原因 + $ docker run -it myimage:v1.0.0 /bin/sh + ``` + +#### Q：容器在后台运行但无法访问服务 + +1. **检查端口映射**： + ```bash + $ docker port mycontainer + ``` + +2. **检查容器内服务状态**： + ```bash + $ docker exec mycontainer ps aux + ``` + +#### Q：如何让已经在后台运行的容器回到前台？ + +使用 `docker attach`： + +```bash +$ docker attach mycontainer +``` +> **注意**：`attach` 会连接到容器的主进程。如果主进程不是交互式的，你可能只能看到输出。使用 `Ctrl+P` `Ctrl+Q` 可以安全退出而不停止容器。 + +### 5.2.7 延伸阅读 + +- [进入容器](5.4_attach_exec.md)：如何进入正在运行的容器执行命令 +- [容器日志](../appendix/best_practices.md)：生产环境的日志管理最佳实践 +- [HEALTHCHECK 健康检查](../07_dockerfile/7.12_healthcheck.md)：自动检测容器内服务是否正常 +- [Docker Compose](../11_compose/README.md)：管理多个后台容器的更好方式 diff --git a/05_container/5.3_stop.md b/05_container/5.3_stop.md new file mode 100644 index 000000000..0f829c65b --- /dev/null +++ b/05_container/5.3_stop.md @@ -0,0 +1,229 @@ +## 5.3 终止 + +本节将介绍如何终止一个运行中的容器，以及几种不同的终止方式及其区别。 + +### 5.3.1 终止方式概述 + +终止容器有三种方式： + +| 方式 | 命令 | 说明 | +|------|------|------| +| **优雅停止** | `docker stop` | 先发 SIGTERM，超时后发 SIGKILL | +| **强制停止** | `docker kill` | 直接发 SIGKILL | +| **自动终止** | - | 容器主进程退出时自动停止 | + +--- + +### 5.3.2 docker stop：推荐 + +#### docker stop 基本用法 + +```bash +$ docker stop 容器名或ID +``` + +#### 工作原理 + +```mermaid +flowchart TD + cmd["docker stop mycontainer"] --> A["1. 发送 SIGTERM 信号给容器主进程 (PID 1)"] + A --> B["2. 等待容器优雅退出 (默认 10 秒)"] + B --> C["3. 如果超时仍未退出，发送 SIGKILL 强制终止"] +``` + +#### 自定义超时时间 + +```bash +## 等待 30 秒后强制终止 + +$ docker stop -t 30 mycontainer + +## 立即发送 SIGKILL（相当于 docker kill） + +$ docker stop -t 0 mycontainer +``` + +#### 停止多个容器 + +```bash +## 停止多个指定容器 + +$ docker stop container1 container2 container3 + +## 停止所有运行中的容器 + +$ docker stop $(docker ps -q) +``` +--- + +### 5.3.3 docker kill + +#### 基本用法 + +```bash +$ docker kill 容器名或ID +``` + +#### 与 stop 的区别 + +| 命令 | 信号 | 使用场景 | +|------|------|---------| +| `docker stop` | SIGTERM → SIGKILL | 正常停止，让应用优雅退出 | +| `docker kill` | SIGKILL | 应用无响应，强制终止 | + +#### 发送自定义信号 + +```bash +## 发送 SIGHUP（让进程重新加载配置） + +$ docker kill -s HUP mycontainer + +## 发送 SIGTERM + +$ docker kill -s TERM mycontainer +``` +--- + +### 5.3.4 容器自动终止 + +容器的生命周期与主进程绑定。主进程退出时，容器自动停止： + +```bash +## 主进程是交互式 bash + +$ docker run -it ubuntu bash +root@abc123:/# exit # 退出 bash → 容器停止 + +## 主进程执行完毕 + +$ docker run ubuntu echo "Hello" # echo 执行完 → 容器停止 +``` +--- + +### 5.3.5 查看已停止的容器 + +```bash +$ docker ps -a +CONTAINER ID IMAGE COMMAND STATUS NAMES +ba267838cc1b ubuntu "/bin/bash" Exited (0) 2 minutes ago myubuntu +c5d3a5e8f7b2 nginx "nginx" Up 5 minutes mynginx +``` +**STATUS 字段说明**： + +| 状态 | 说明 | +|------|------| +| `Up X minutes` | 运行中 | +| `Exited (0)` | 正常退出（退出码 0）| +| `Exited (1)` | 异常退出（非零退出码）| +| `Exited (137)` | 被 SIGKILL 终止 (128 + 9)| +| `Exited (143)` | 被 SIGTERM 终止 (128 + 15)| + +--- + +### 5.3.6 重新启动容器 + +#### 启动已停止的容器 + +```bash +$ docker start 容器名或ID + +## 启动并附加终端 + +$ docker start -ai 容器名 +``` + +#### 重启运行中的容器 + +```bash +## 先停止再启动 + +$ docker restart 容器名 + +## 自定义停止超时 + +$ docker restart -t 30 容器名 +``` +--- + +### 5.3.7 生命周期状态图 + +```mermaid +stateDiagram-v2 + direction TB + [*] --> Created : docker create + Created --> Running : docker start + Running --> Stopped : docker stop + Stopped --> Running : docker start + Running --> Paused : docker pause + Paused --> Running : docker unpause + + Created --> Deleted : docker rm + Stopped --> Deleted : docker rm + Paused --> Deleted : docker rm + + Deleted --> [*] +``` +--- + +### 5.3.8 批量操作 + +#### 停止所有容器 + +```bash +$ docker stop $(docker ps -q) +``` + +#### 删除所有已停止的容器 + +```bash +$ docker container prune +``` + +#### 停止并删除所有容器 + +```bash +$ docker stop $(docker ps -q) && docker container prune -f +``` +--- + +### 5.3.9 常见问题 + +#### Q：容器停止很慢 + +原因：应用没有正确处理 SIGTERM 信号，需要等待超时后强制终止。 + +解决方案： + +1. 在应用中正确处理 SIGTERM +2. 使用 `docker stop -t 0` 立即终止 +3. 检查 Dockerfile 中的 `STOPSIGNAL` 配置 + +#### Q：如何让容器优雅退出 + +确保容器主进程正确处理信号： + +```dockerfile +## Dockerfile 示例 + +FROM node:22-alpine +... + +## 使用 exec 形式确保信号能传递给 node 进程 + +CMD ["node", "server.js"] +``` + +> **版本说明**：示例使用 `node:22-alpine`，这是一个精简的 Node.js 22 版本镜像。可根据需求替换为其他版本（如 `node:24-alpine`、`node:latest`）。 + +#### Q：容器无法停止 + +```bash +## 强制终止 + +$ docker kill 容器名 + +## 如果仍无法停止，检查系统资源 + +$ docker inspect 容器名 +``` +--- diff --git a/05_container/5.4_attach_exec.md b/05_container/5.4_attach_exec.md new file mode 100644 index 000000000..2919e1cfc --- /dev/null +++ b/05_container/5.4_attach_exec.md @@ -0,0 +1,278 @@ +## 5.4 进入容器 + +### 5.4.1 为什么需要进入容器 + +使用 `-d` 参数启动容器后，容器在后台运行。以下场景需要进入容器内部操作： + +| 场景 | 示例 | +|------|------| +| **调试问题** | 查看日志、检查配置、排查错误 | +| **临时操作** | 执行数据库迁移、清理缓存 | +| **检查状态** | 查看进程、网络连接、文件系统 | +| **开发测试** | 交互式测试命令、验证环境 | + +### 5.4.2 两种进入方式 + +Docker 提供两种进入容器的命令： + +| 命令 | 推荐程度 | 特点 | +|------|---------|------| +| `docker exec` | ✅ **推荐** | 启动新进程，退出不影响容器 | +| `docker attach` | ⚠️ 谨慎使用 | 附加到主进程，退出可能停止容器 | + +--- + +### 5.4.3 docker exec：推荐 + +#### docker exec 基本用法 + +```bash +## 进入容器并启动交互式 shell + +$ docker exec -it 容器名 /bin/bash + +## 或使用 sh（适用于 Alpine 等精简镜像） + +$ docker exec -it 容器名 /bin/sh +``` + +#### 参数说明 + +| 参数 | 作用 | +|------|------| +| `-i` | 保持标准输入打开 (interactive)| +| `-t` | 分配伪终端 (TTY)| +| `-it` | 两者组合，获得完整交互体验 | +| `-u` | 指定用户（如 `-u root`）| +| `-w` | 指定工作目录 | +| `-e` | 设置环境变量 | + +#### docker exec 示例 + +```bash +## 启动一个后台容器 + +$ docker run -dit --name myubuntu ubuntu +69d137adef7a... + +## 进入容器（交互式 shell） + +$ docker exec -it myubuntu bash +root@69d137adef7a:/# ls +bin boot dev etc home lib ... +root@69d137adef7a:/# exit + +## 容器仍在运行！ + +$ docker ps +CONTAINER ID IMAGE STATUS NAMES +69d137adef7a ubuntu Up 2 minutes myubuntu +``` + +#### 执行单条命令 + +不进入交互模式，直接执行命令： + +```bash +## 查看容器内进程 + +$ docker exec myubuntu ps aux + +## 查看配置文件 + +$ docker exec myubuntu cat /etc/nginx/nginx.conf + +## 以 root 用户执行 + +$ docker exec -u root myubuntu apt update +``` + +#### 只用 -i 不用 -t 的区别 + +```bash +## 只用 -i：可以执行命令，但没有提示符 + +$ docker exec -i myubuntu bash +ls # 输入命令 +bin # 输出结果 +boot +dev +... + +## 用 -it：有完整的终端体验 + +$ docker exec -it myubuntu bash +root@69d137adef7a:/# # 有提示符 +``` +> 💡 通常使用 `-it` 组合。只有在脚本中需要通过管道传入命令时才只用 `-i`。 + +--- + +### 5.4.4 docker attach：谨慎使用 + +#### docker attach 基本用法 + +```bash +$ docker attach 容器名 +``` + +#### 工作原理 + +`attach` 会附加到容器的 **主进程** (PID 1) 的标准输入输出： + +```mermaid +flowchart LR + subgraph Container ["容器"] + direction TB + subgraph Process ["主进程"] + P1["PID 1: /bin/bash
(你的输入直接发送到主进程)"] + end + end + Attach["docker attach"] -->|"附加到这里"| P1 +``` + +#### docker attach 示例 + +```bash +## 启动容器 + +$ docker run -dit --name myubuntu ubuntu +243c32535da7... + +## 附加到容器 + +$ docker attach myubuntu +root@243c32535da7:/# +``` + +#### ⚠️ 重要警告 + +**从 attach 会话中输入 `exit` 或按 `Ctrl+D` 会导致容器停止！** + +```bash +$ docker attach myubuntu +root@243c32535da7:/# exit # 这会停止容器！ + +$ docker ps +CONTAINER ID IMAGE STATUS NAMES +243c32535da7 ubuntu Exited (0) 2 seconds ago myubuntu +``` +**原因**：attach 附加到主进程，退出主进程就等于退出容器。 + +#### 安全退出 attach + +使用 `Ctrl+P` 然后 `Ctrl+Q` 可以从 attach 会话中 **分离**，而不停止容器： + +```bash +$ docker attach myubuntu +root@243c32535da7:/# + +## 按 Ctrl+P 然后 Ctrl+Q + +read escape sequence + +$ docker ps # 容器仍在运行 +CONTAINER ID IMAGE STATUS NAMES +243c32535da7 ubuntu Up 5 minutes myubuntu +``` +--- + +### 5.4.5 exec vs attach 对比 + +| 特性 | docker exec | docker attach | +|------|-------------|---------------| +| **工作方式** | 在容器内启动新进程 | 附加到主进程 | +| **退出影响** | 不影响容器 | 可能停止容器 | +| **多终端** | 可以开多个 | 共享同一个会话 | +| **适用场景** | 调试、临时操作 | 查看主进程输出 | +| **推荐程度** | ✅ 推荐 | ⚠️ 特殊场景使用 | + +```mermaid +flowchart LR + subgraph Exec ["docker exec"] + direction TB + subgraph Container1 ["容器"] + E_PID1["PID 1: nginx"] + E_PID50["PID 50: bash"] + end + NewProc["新进程"] -- 附加到 --> E_PID50 + end + + subgraph Attach ["docker attach"] + direction TB + subgraph Container2 ["容器"] + A_PID1["PID 1: bash"] + end + MainProc["附加到主进程"] --> A_PID1 + end + + note1["退出 bash 不影响 nginx"] + note2["退出 bash 容器停止"] + Container1 -.-> note1 + Container2 -.-> note2 +``` +--- + +### 5.4.6 最佳实践 + +#### 1. 首选 docker exec + +```bash +## 进入容器调试 + +$ docker exec -it myapp bash + +## 查看日志 + +$ docker exec myapp tail -f /var/log/app.log + +## 执行数据库迁移 + +$ docker exec myapp python manage.py migrate +``` + +#### 2. 生产环境避免进入容器 + +笔者建议：生产环境应尽量避免进入容器直接操作，而是通过： + +- 日志系统查看日志（如 `docker logs` 或集中式日志） +- 监控系统查看状态 +- 重新部署而非手动修改 + +#### 3. 无 shell 镜像的处理 + +某些精简镜像（如基于 `scratch` 或 `distroless`）没有 shell： + +```bash +## 这会失败 + +$ docker exec -it myapp bash +OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found + +## 解决方案：使用调试容器（需要 Docker Desktop Pro/Team/Business 订阅） + +$ docker debug myapp +``` +> **注意**：`docker debug` 是 Docker Desktop 4.33+ 提供的功能，需要 Pro、Team 或 Business 订阅。它会附加一个包含常用调试工具（vim、curl、htop 等）的工具箱到目标容器，即使目标镜像基于 `scratch` 也能使用。 +--- + +### 5.4.7 常见问题 + +#### Q：exec 进入后看不到其他终端的操作 + +这是正常的。exec 启动的是独立进程，多个 exec 会话互不影响。 + +#### Q：容器没有 bash + +尝试使用 sh： + +```bash +$ docker exec -it myapp /bin/sh +``` + +#### Q：需要 root 权限 + +```bash +$ docker exec -u root -it myapp bash +``` +--- diff --git a/container/import_export.md b/05_container/5.5_import_export.md similarity index 61% rename from container/import_export.md rename to 05_container/5.5_import_export.md index 4a0a65def..b9f5fd7ca 100644 --- a/container/import_export.md +++ b/05_container/5.5_import_export.md @@ -1,28 +1,33 @@ -##导出和导入容器 +## 5.5 导出和导入 + +当我们需要迁移容器或者备份容器时，可以使用 Docker 的导入和导出功能。本节将介绍这两个命令的使用方法。 + +### 5.5.1 导出容器 -###导出容器 如果要导出本地某个容器，可以使用 `docker export` 命令。 -``` -$ sudo docker ps -a +```bash +$ docker container ls -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -7691a814370e ubuntu:14.04 "/bin/bash" 36 hours ago Exited (0) 21 hours ago test -$ sudo docker export 7691a814370e > ubuntu.tar +7691a814370e ubuntu:24.04 "/bin/bash" 36 hours ago Exited (0) 21 hours ago test +$ docker export 7691a814370e > ubuntu.tar ``` 这样将导出容器快照到本地文件。 -###导入容器快照 +> **版本说明**：导出的容器快照不包含镜像版本历史，导入时可以自定义标签和版本号。 + +### 5.5.2 导入容器快照 + 可以使用 `docker import` 从容器快照文件中再导入为镜像，例如 -``` -$ cat ubuntu.tar | sudo docker import - test/ubuntu:v1.0 -$ sudo docker images -REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + +```bash +$ cat ubuntu.tar | docker import - test/ubuntu:v1.0 +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE test/ubuntu v1.0 9d37a6082e97 About a minute ago 171.3 MB ``` 此外，也可以通过指定 URL 或者某个目录来导入，例如 -``` -$sudo docker import http://example.com/exampleimage.tgz example/imagerepo -``` - -*注：用户既可以使用 `docker load` 来导入镜像存储文件到本地镜像库，也可以使用 `docker import` 来导入一个容器快照到本地镜像库。这两者的区别在于容器快照文件将丢弃所有的历史记录和元数据信息（即仅保存容器当时的快照状态），而镜像存储文件将保存完整记录，体积也要大。此外，从容器快照文件导入时可以重新指定标签等元数据信息。 - +```bash +$ docker import http://example.com/exampleimage.tgz example/imagerepo +``` +*注：用户既可以使用 `docker load` 来导入镜像存储文件到本地镜像库，也可以使用 `docker import` 来导入一个容器快照到本地镜像库。这两者的区别在于容器快照文件将丢弃所有的历史记录和元数据信息（即仅保存容器当时的快照状态），而镜像存储文件将保存完整记录，体积也要大。此外，从容器快照文件导入时可以重新指定标签等元数据信息。* diff --git a/05_container/5.6_rm.md b/05_container/5.6_rm.md new file mode 100644 index 000000000..f6e1233ea --- /dev/null +++ b/05_container/5.6_rm.md @@ -0,0 +1,240 @@ +## 5.6 删除 + +随着容器的创建和停止，系统中会积累大量的容器。本节将介绍如何删除不再需要的容器，以及如何清理所有停止的容器。 + +### 5.6.1 基本用法 + +使用 `docker rm` 删除已停止的容器： + +```bash +$ docker rm 容器名或ID +``` +> 💡 `docker rm` 是 `docker container rm` 的简写，两者等效。 + +--- + +### 5.6.2 删除选项 + +| 选项 | 说明 | 示例 | +|------|------|------| +| 无参数 | 删除已停止的容器 | `docker rm mycontainer` | +| `-f` | 强制删除运行中的容器 | `docker rm -f mycontainer` | +| `-v` | 同时删除关联的匿名卷 | `docker rm -v mycontainer` | + +#### 删除已停止的容器 + +```bash +$ docker rm mycontainer +mycontainer +``` + +#### 强制删除运行中的容器 + +```bash +## 不加 -f 会报错 + +$ docker rm running_container +Error: cannot remove running container + +## 加 -f 强制删除 + +$ docker rm -f running_container +running_container +``` +> ⚠️ 强制删除会向容器发送 SIGKILL 信号，可能导致数据丢失。建议先 `docker stop` 优雅停止。 + +#### 删除容器及其数据卷 + +```bash +## 删除容器时同时删除其匿名卷 + +$ docker rm -v mycontainer +``` +> 注意：只删除匿名卷，命名卷不会被删除。 + +--- + +### 5.6.3 批量删除 + +#### 删除所有已停止的容器 + +```bash +## 方式一：使用 prune 命令（推荐） + +$ docker container prune + +WARNING! This will remove all stopped containers. +Are you sure you want to continue? [y/N] y +Deleted Containers: +abc123... +def456... +Total reclaimed space: 150MB + +## 方式二：不提示确认 + +$ docker container prune -f +``` + +#### 删除所有容器：包括运行中的 + +```bash +## 先停止所有容器，再删除 + +$ docker stop $(docker ps -q) +$ docker rm $(docker ps -aq) + +## 或者直接强制删除 + +$ docker rm -f $(docker ps -aq) +``` + +#### 按条件删除 + +```bash +## 删除所有已退出的容器 + +$ docker rm $(docker ps -aq -f status=exited) + +## 删除名称包含 "test" 的容器 + +$ docker rm $(docker ps -aq -f name=test) + +## 删除 24 小时前创建的容器 + +$ docker container prune --filter "until=24h" +``` +--- + +### 5.6.4 常用过滤条件 + +`docker ps` 的过滤条件可以配合 `rm` 使用： + +| 过滤条件 | 说明 | 示例 | +|---------|------|------| +| `status=exited` | 已退出的容器 | `-f status=exited` | +| `status=created` | 已创建未启动 | `-f status=created` | +| `name=xxx` | 名称匹配 | `-f name=myapp` | +| `ancestor=xxx` | 基于某镜像创建 | `-f ancestor=nginx` | +| `before=xxx` | 在某容器之前创建 | `-f before=mycontainer` | +| `since=xxx` | 在某容器之后创建 | `-f since=mycontainer` | + +#### 示例 + +```bash +## 删除所有基于 nginx 镜像的容器 + +$ docker rm $(docker ps -aq -f ancestor=nginx) + +## 删除所有创建后未启动的容器 + +$ docker rm $(docker ps -aq -f status=created) +``` +--- + +### 5.6.5 容器与镜像的依赖关系 + +> 有容器依赖的镜像无法删除。 + +```bash +## 尝试删除有容器依赖的镜像 + +$ docker image rm nginx +Error: image is being used by stopped container abc123 + +## 需要先删除依赖该镜像的容器 + +$ docker rm abc123 +$ docker image rm nginx +``` +--- + +### 5.6.6 清理策略建议 + +#### 开发环境 + +```bash +## 定期清理已停止的容器 + +$ docker container prune -f + +## 一键清理所有未使用资源 + +$ docker system prune -f +``` + +#### 生产环境 + +```bash +## 使用 --rm 参数运行临时容器 + +$ docker run --rm ubuntu echo "Hello" + +## 容器退出后自动删除 + +## 定期清理（设置保留时间） + +$ docker container prune --filter "until=168h" # 保留 7 天内的 +``` + +#### 完整清理脚本 + +```bash +#!/bin/bash + +## cleanup.sh - Docker 资源清理脚本 + +echo "清理已停止的容器..." +docker container prune -f + +echo "清理未使用的镜像..." +docker image prune -f + +echo "清理未使用的数据卷..." +docker volume prune -f + +echo "清理未使用的网络..." +docker network prune -f + +echo "清理完成！" +docker system df +``` +--- + +### 5.6.7 常见问题 + +#### Q：容器无法删除 + +```bash +Error: container is running +``` +解决：先停止容器，或使用 `-f` 强制删除 + +```bash +$ docker stop mycontainer +$ docker rm mycontainer + +## 或 + +$ docker rm -f mycontainer +``` + +#### Q：删除后磁盘空间没释放 + +可能原因： + +1. 容器的数据卷未删除（使用 `-v` 参数） +2. 镜像未删除 +3. 构建缓存未清理 + +解决： + +```bash +## 查看空间占用 + +$ docker system df + +## 完整清理 + +$ docker system prune -a --volumes +``` +--- diff --git a/05_container/README.md b/05_container/README.md new file mode 100644 index 000000000..52fefdca3 --- /dev/null +++ b/05_container/README.md @@ -0,0 +1,25 @@ +# 第五章 操作容器 + +容器是 Docker 又一核心概念。 + +简单的说，容器是独立运行的一个或一组应用，以及它们的运行态环境。对应的，虚拟机可以理解为模拟运行的一整套操作系统（提供了运行态环境和其他系统环境）和跑在上面的应用。 + +本章将具体介绍如何来管理一个容器，包括创建、启动和停止等。 + +## 版本号说明 + +本章示例涉及多个 Docker 镜像，遵循以下版本号最佳实践： + +- **官方镜像**（如 `ubuntu`、`nginx`、`mysql`）：使用具体大版本号（如 `ubuntu:24.04`、`mysql:8.4`）而非 `latest`，确保示例的可重复性 +- **镜像标签约定**： + - `latest` 或 `v1.0.0` 等：带标签的自定义镜像，示例中指定具体版本 + - `24.04`、`8.4`：官方镜像的稳定版本分支 + - 生产环境建议：**运行/部署**服务镜像时指定确切版本号（如 `nginx:1.28.0`、`mysql:8.4.4`）而非仅大版本号，让每次部署可复现、升级是显式动作。 + （注意这与 [第 7 章](../07_dockerfile/README.md) 对 **Dockerfile 基础镜像** 的建议方向相反：基础镜像用主/次版本号，以便重新构建时自动带上补丁。两者面向的是不同环节。） + +* [启动容器](5.1_run.md) +* [守护态运行](5.2_daemon.md) +* [终止容器](5.3_stop.md) +* [进入容器](5.4_attach_exec.md) +* [导出和导入容器](5.5_import_export.md) +* [删除容器](5.6_rm.md) diff --git a/05_container/summary.md b/05_container/summary.md new file mode 100644 index 000000000..f6fbf4762 --- /dev/null +++ b/05_container/summary.md @@ -0,0 +1,33 @@ +## 本章小结 + +本章介绍了 Docker 容器的启动、停止、进入和删除等核心操作。 + +| 操作 | 命令 | 说明 | +|------|------|------| +| 新建并运行 | `docker run` | 最常用的启动方式 | +| 交互式启动 | `docker run -it` | 用于调试或临时操作 | +| 后台运行 | `docker run -d` | 用于服务类应用 | +| 启动已停止的容器 | `docker start` | 重用已有容器 | +| 优雅停止 | `docker stop` | 先 SIGTERM，超时后 SIGKILL | +| 强制停止 | `docker kill` | 直接 SIGKILL | +| 重启 | `docker restart` | 停止后立即启动 | +| 停止全部 | `docker stop $(docker ps -q)` | 停止所有运行中容器 | +| 进入容器调试 | `docker exec -it 容器名 bash` | 推荐方式 | +| 执行单条命令 | `docker exec 容器名 命令` | 不进入交互模式 | +| 查看主进程输出 | `docker attach 容器名` | 慎用，退出可能停止容器 | +| 删除已停止容器 | `docker rm 容器名` | 需先停止 | +| 强制删除运行中容器 | `docker rm -f 容器名` | 直接删除 | +| 删除容器及匿名卷 | `docker rm -v 容器名` | 同时清理匿名卷 | +| 清理所有已停止容器 | `docker container prune` | 批量清理 | + +### 延伸阅读 + +- [后台运行](5.2_daemon.md)：理解 `-d` 参数和容器生命周期 +- [进入容器](5.4_attach_exec.md)：操作运行中的容器 +- [网络配置](../09_network/README.md)：理解端口映射的原理 +- [数据管理](../08_data/README.md)：数据持久化方案 +- [删除镜像](../04_image/4.3_rm.md)：清理镜像 +- [数据卷](../08_data/8.1_volume.md)：数据卷管理 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/06_repository/6.1_dockerhub.md b/06_repository/6.1_dockerhub.md new file mode 100644 index 000000000..484e43f46 --- /dev/null +++ b/06_repository/6.1_dockerhub.md @@ -0,0 +1,138 @@ +## 6.1 Docker Hub + +### 6.1.1 什么是 Docker Hub + +Docker Hub 是 Docker 的中央镜像仓库，通过它您可以轻松地分享和获取 Docker 镜像。 + + +[Docker Hub](https://hub.docker.com/) 是 Docker 官方维护的公共镜像仓库，也是全球最大的容器镜像库。 + +它提供了： + +- **官方镜像**：由 Docker 官方和软件厂商（如 Nginx，MySQL，Node.js）维护的高质量镜像。 +- **个人/组织仓库**：用户可以上传自己的镜像。 +- **自动构建**：与 GitHub/Bitbucket 集成的历史功能，Docker 已标记为 deprecated，并计划于 2027-04-01 完全退役。 +- **Webhooks**：镜像更新时触发回调。 + +--- + +### 6.1.2 核心功能 + +#### 1. 搜索镜像 + +我们可以通过 `docker search` 命令来查找官方仓库中的镜像，并利用 `docker pull` 命令来将它下载到本地。 + + +除了网页搜索，也可以使用命令行： + +```bash +$ docker search centos +NAME DESCRIPTION STARS OFFICIAL +centos DEPRECATED; The official build of CentOS. 7000+ [OK] +``` +> **技巧**：始终优先使用 `OFFICIAL` 标记为 `[OK]` 的镜像，安全性更有保障。 + +#### 2. 拉取镜像 + +```bash +$ docker pull nginx:alpine +``` + +#### 3. 推送镜像 + +需要先登录： + +```bash +$ docker login + +## 默认情况下，不带其他参数进行 docker login 会自动走 Device Code Web Flow (浏览器认证) +## 若在非交互 CI 环境中，推荐结合 --username 与 --password-stdin 参数使用 + +... +``` +打标签并推送： + +```bash +## 1. 标记镜像 + +$ docker tag myapp:v1 username/myapp:v1 + +## 2. 推送 + +$ docker push username/myapp:v1 +``` +--- + +### 6.1.3 限制与配额 + +#### 镜像拉取限制 + +Docker Hub 对不同类型用户实施拉取速率限制（基于 6 小时周期）： + +| 用户类型 | 限制 | +|---------|------| +| **匿名用户**（未登录）| 每 6 小时 100 次请求 | +| **免费账户**（已登录）| 每 6 小时 200 次请求 | +| **Pro/Team/Business 账户** | 无限制（公平使用政策） | + +> **注意**：Docker 曾计划于 2025 年 4 月调整拉取限制策略，但在 2025 年 2 月宣布取消该计划。目前付费订阅用户享有无限制拉取额度，匿名用户和免费账户的限制保持不变。建议在 CI/CD 环境中始终配置 `docker login` 以获得更高的拉取额度。 + +#### 滥用限流 + +除了上述针对特定账号拉取镜像数量的 Pull Rate Limit 之外，Docker Hub 对所有用户（包含已认证及付费用户）还实施了 **滥用保护限流 (Abuse Rate Limiting)**。它是根据网络出口 IP（IPv4 或 IPv6 /64 子网）计算整体请求频率，阈值动态触发（通常为每分钟数千级别请求）。 + +**两类的差异与排查方法**： + +- **Pull Rate Limit**：针对拉取量达到上限。报错返回 `429 Too Many Requests`，并且 HTTP 返回体/CLI 错误提示中会带有明确的 `toomanyrequests: You have reached your pull rate limit` 提示，常附有账户升级链接。 +- **Abuse Rate Limit**：防范接口频率打击。报错仅返回简化的 `429 Too Many Requests`。这一限流不分付费与否，常发生在“多终端共享出口 IP”的企业局域网或者第三方云 CI 服务（如 GitHub Actions 等）中，即使你已正常配置 `docker login` 也依旧可能触发。 + +> **提示**：如果在 CI/CD 等环境遇到 429 错误，建议： +> 1. 先甄别具体是哪类限流：普通的 pull rate limit 只要在 CI 中配置 `docker login`（并使用有效账号）就能解除匿名限制。 +> 2. 如果是 Abuse 频控导致，应考虑搭建私有仓库作为拉取缓存代理 (Registry pull-through cache)，避免频繁直接请求官方 Hub。 +> 3. 使用国内镜像加速器。 + +--- + +### 6.1.4 安全最佳实践 + +#### 1. 启用 2FA：双因素认证 + +为了保护您的 Docker Hub 账号安全，我们建议采取以下措施。 + + +在 Account Settings -> Security 中启用 2FA，保护账号安全。启用后，CLI 登录需要使用 **Access Token** 而非密码。 + +#### 2. 使用 Access Token + +> **⚠️ 警告**：绝不要在脚本或 CI/CD 系统中，直接使用 `-p` 参数传递密码或 Token（类似 `docker login -p xxx`）！这会导致凭证直接暴露在系统的命令历史、进程列表和终端输出中。 + +1. 在 Docker Hub -> Account Settings -> Security -> Access Tokens 创建 Token (PAT)。 +2. 将 Token 保存在权限受限的本地文件或 CI secret 中，再通过标准输入 (stdin) 传递给 Docker，避免把真实 Token 写进脚本、命令历史或日志： + +```bash +$ chmod 600 "$HOME/.dockerhub-token" +$ cat "$HOME/.dockerhub-token" | docker login --username username --password-stdin +``` + +#### 3. 关注镜像漏洞 + +Docker Hub 提供 Docker Scout 安全扫描功能。官方镜像的漏洞扫描结果对所有用户免费可见。Docker Scout 的持续扫描功能在免费层可以覆盖 1 个私有仓库，付费用户可以扫描更多仓库。在镜像标签页可以看到漏洞扫描结果。 + +--- + +### 6.1.5 Webhooks + +当镜像被推送时，可以自动触发 HTTP 回调（例如通知 CI 系统部署）。 + +**配置方法**： +仓库页面 -> Webhooks -> Create Webhook。 + +--- + +### 6.1.6 自动构建 + +> ⚠️ Docker Hub Automated Builds 已被 Docker 标记为 deprecated，并计划于 2027-04-01 完全退役；新项目应优先使用 GitHub Actions、Buildx 或自有 CI 构建并推送镜像。 + +对于仍在迁移期内的旧仓库，链接 GitHub/Bitbucket 仓库后，当代码有提交或打标签时，Docker Hub 会自动运行构建。不要把它作为新架构的默认方案。 + +--- diff --git a/06_repository/6.2_registry.md b/06_repository/6.2_registry.md new file mode 100644 index 000000000..e6184a4bf --- /dev/null +++ b/06_repository/6.2_registry.md @@ -0,0 +1,127 @@ +## 6.2 私有仓库 + +有时候使用 Docker Hub 这样的公共仓库可能不方便，用户可以创建一个本地仓库供私人使用。 + +本节介绍如何使用本地仓库。 + +[Docker Registry](https://distribution.github.io/distribution/) 是官方提供的工具，可以用于构建私有的镜像仓库。本文示例沿用 [distribution/distribution](https://github.com/distribution/distribution) v2.x 兼容路径；新生产部署应评估 Distribution 3.x，并核对配置路径、迁移说明和生态兼容性。 + +### 6.2.1 安装运行 docker-registry + +#### 容器运行 + +如果您需要搭建私有仓库，可以通过官方提供的 `registry` 镜像快速部署。 + +你可以使用官方 `registry` 镜像来运行。 + +```bash +$ docker run -d -p 127.0.0.1:5000:5000 --restart=always --name registry registry:2 +``` + +> **注意**：这样启动的 registry **没有任何认证、也没有 TLS**，因此这里刻意绑定到 +> `127.0.0.1`，仅供本机实验。不要直接把它绑到 `0.0.0.0` 或内网地址——那等于允许同网段 +> 任意主机匿名推送镜像（镜像投毒：覆盖你的 `latest` 标签，下游全部拉到攻击者的镜像）。 +> 需要多机访问请直接用 [6.3 节](6.3_registry_auth.md) 的 TLS + 认证方案。 + +> **版本说明**：使用 `registry:2` 表示 Docker Registry 2.x 兼容示例。Distribution 3.x 已发布稳定版本；不要直接把本章 v2 配置原样套到 v3 生产环境，升级前应阅读迁移说明并做兼容测试。旧版本 Registry 1.x 已停止维护，不建议使用。 +这将使用官方的 `registry` 镜像来启动私有仓库。默认情况下，仓库会被创建在容器的 `/var/lib/registry` 目录下。你可以通过 `-v` 参数来将镜像文件存放在本地的指定路径。例如下面的例子将上传的镜像放到本地的 `/opt/data/registry` 目录。 + +```bash +$ docker run -d \ + -p 5000:5000 \ + -v /opt/data/registry:/var/lib/registry \ + registry:2 +``` + +### 6.2.2 在私有仓库上传、搜索、下载镜像 + +创建好私有仓库之后，就可以使用 `docker tag` 来标记一个镜像，然后推送它到仓库。例如私有仓库地址为 `127.0.0.1:5000`。 + +先在本机查看已有的镜像。 + +```bash +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE +ubuntu latest ba5877dc9bec 6 weeks ago 192.7 MB +``` +使用 `docker tag` 将 `ubuntu:latest` 这个镜像标记为 `127.0.0.1:5000/ubuntu:latest`。 + +格式为 `docker tag IMAGE[:TAG] [REGISTRY_HOST[:REGISTRY_PORT]/]REPOSITORY[:TAG]`。 + +```bash +$ docker tag ubuntu:latest 127.0.0.1:5000/ubuntu:latest +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE +ubuntu latest ba5877dc9bec 6 weeks ago 192.7 MB +127.0.0.1:5000/ubuntu latest ba5877dc9bec 6 weeks ago 192.7 MB +``` +使用 `docker push` 上传标记的镜像。 + +```bash +$ docker push 127.0.0.1:5000/ubuntu:latest +The push refers to repository [127.0.0.1:5000/ubuntu] +373a30c24545: Pushed +a9148f5200b0: Pushed +cdd3de0940ab: Pushed +fc56279bbb33: Pushed +b38367233d37: Pushed +2aebd096e0e2: Pushed +latest: digest: sha256:fe4277621f10b5026266932ddf760f5a756d2facd505a94d2da12f4f52f71f5a size: 1568 +``` +用 `curl` 查看仓库中的镜像。 + +```bash +$ curl 127.0.0.1:5000/v2/_catalog +{"repositories":["ubuntu"]} +``` +这里可以看到 `{"repositories":["ubuntu"]}`，表明镜像已经被成功上传了。 + +先删除已有镜像，再尝试从私有仓库中下载这个镜像。 + +```bash +$ docker image rm 127.0.0.1:5000/ubuntu:latest + +$ docker pull 127.0.0.1:5000/ubuntu:latest +Pulling repository 127.0.0.1:5000/ubuntu:latest +ba5877dc9bec: Download complete +511136ea3c5a: Download complete +9bad880da3d2: Download complete +25f11f5fb0cb: Download complete +ebc34468f71d: Download complete +2318d26665ef: Download complete + +$ docker image ls +REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE +127.0.0.1:5000/ubuntu latest ba5877dc9bec 6 weeks ago 192.7 MB +``` + +### 6.2.3 配置非 https 仓库地址 + +如果你不想使用 `127.0.0.1:5000` 作为仓库地址，比如想让本网段的其他主机也能把镜像推送到私有仓库。你就得把例如 `192.168.199.100:5000` 这样的内网地址作为私有仓库地址，这时你会发现无法成功推送镜像。 + +这是因为 Docker 默认不允许非 `HTTPS` 方式推送镜像。我们可以通过 Docker 的配置选项来取消这个限制，或者查看下一节配置能够通过 `HTTPS` 访问的私有仓库。 + +> **警告**：下面的 `insecure-registries` 会关闭该地址的 TLS 校验，推送和拉取都是明文、可被中间人篡改；再叠加上 registry 默认无认证，等于把「任意主机可匿名投毒」的仓库开在内网。**仅限隔离的实验网络**，生产一律走 [6.3 节](6.3_registry_auth.md) 的 TLS + 认证。 + +#### Linux + +默认情况下，Docker 强制使用 HTTPS 协议推送镜像。如果您搭建的私有仓库是 HTTP 协议，需要进行如下配置。 + + +对于使用 `systemd` 的系统，请在 `/etc/docker/daemon.json` 中写入如下内容（如果文件不存在请新建该文件） + +```json +{ + "registry-mirrors": [ + "https://docker.your-mirror.example.com" + ], + "insecure-registries": [ + "192.168.199.100:5000" + ] +} +``` +> 注意：该文件必须符合 `json` 规范，否则 Docker 将不能启动。镜像加速器地址请替换为实际可用的源，具体配置参见 [3.9 镜像加速器](../03_install/3.9_mirror.md)。 + +### 6.2.4 其他 + +对于 Docker Desktop for Windows、Docker Desktop for Mac 在设置中的 `Docker Engine` 中进行编辑，增加和上边一样的字符串即可。 diff --git a/06_repository/6.3_registry_auth.md b/06_repository/6.3_registry_auth.md new file mode 100644 index 000000000..757774552 --- /dev/null +++ b/06_repository/6.3_registry_auth.md @@ -0,0 +1,218 @@ +## 6.3 私有仓库高级配置 + +上一节我们搭建了一个具有基础功能的私有仓库，本小节我们来使用 `Docker Compose` 搭建一个拥有权限认证、TLS 的私有仓库。 + +新建一个文件夹，以下步骤均在该文件夹中进行。 + +### 6.3.1 准备站点证书 + +如果你拥有一个域名，国内各大云服务商均提供免费的站点证书。你也可以使用 `openssl` 自行签发证书。 + +这里假设我们将要搭建的私有仓库地址为 `docker.domain.com`，下面我们介绍使用 `openssl` 自行签发 `docker.domain.com` 的站点 SSL 证书。 + +第一步创建 `CA` 私钥。 + +```bash +$ openssl genrsa -out "root-ca.key" 4096 +``` +第二步利用私钥创建 `CA` 根证书请求文件。 + +```bash +$ openssl req \ + -new -key "root-ca.key" \ + -out "root-ca.csr" -sha256 \ + -subj '/C=CN/ST=Shanxi/L=Datong/O=Your Company Name/CN=Your Company Name Docker Registry CA' +``` +> 以上命令中 `-subj` 参数里的 `/C` 表示国家，如 `CN`；`/ST` 表示省；`/L` 表示城市或者地区；`/O` 表示组织名；`/CN` 通用名称。 + +第三步配置 `CA` 根证书，新建 `root-ca.cnf`。 + +```bash +[root_ca] +basicConstraints = critical,CA:TRUE,pathlen:1 +keyUsage = critical, nonRepudiation, cRLSign, keyCertSign +subjectKeyIdentifier=hash +``` +第四步签发根证书。 + +```bash +$ openssl x509 -req -days 3650 -in "root-ca.csr" \ + -signkey "root-ca.key" -sha256 -out "root-ca.crt" \ + -extfile "root-ca.cnf" -extensions \ + root_ca +``` +第五步生成站点 `SSL` 私钥。 + +```bash +$ openssl genrsa -out "docker.domain.com.key" 4096 +``` +第六步使用私钥生成证书请求文件。 + +```bash +$ openssl req -new -key "docker.domain.com.key" -out "site.csr" -sha256 \ + -subj '/C=CN/ST=Shanxi/L=Datong/O=Your Company Name/CN=docker.domain.com' +``` +第七步配置证书，新建 `site.cnf` 文件。 + +```bash +[server] +authorityKeyIdentifier=keyid,issuer +basicConstraints = critical,CA:FALSE +extendedKeyUsage=serverAuth +keyUsage = critical, digitalSignature, keyEncipherment +subjectAltName = DNS:docker.domain.com, IP:127.0.0.1 +subjectKeyIdentifier=hash +``` +第八步签署站点 `SSL` 证书。 + +```bash +$ openssl x509 -req -days 750 -in "site.csr" -sha256 \ + -CA "root-ca.crt" -CAkey "root-ca.key" -CAcreateserial \ + -out "docker.domain.com.crt" -extfile "site.cnf" -extensions server +``` + +配套 demo 中的 [`ssl/README.md`](demo/ssl/README.md) 只保留本地生成证书的占位说明，真实私钥和证书不应提交到仓库。 +这样已经拥有了 `docker.domain.com` 的网站 SSL 私钥 `docker.domain.com.key` 和 SSL 证书 `docker.domain.com.crt` 及 CA 根证书 `root-ca.crt`。 + +新建 `ssl` 文件夹并将 `docker.domain.com.key` `docker.domain.com.crt` `root-ca.crt` 这三个文件移入，删除其他文件。 + +> **安全提示**：这些私钥和证书应在本地或受控部署环境中生成，不要提交进 Git 仓库。示例目录只保留占位说明，运行前请按上面的步骤重新生成。 + +### 6.3.2 配置私有仓库 + +私有仓库默认的配置文件位于 `/etc/docker/registry/config.yml`，我们先在本地编辑 `config.yml`，之后挂载到容器中。 + +```yaml +log: + accesslog: + disabled: true + level: debug + formatter: text + fields: + service: registry + environment: staging +storage: + delete: + enabled: true + cache: + blobdescriptor: inmemory + filesystem: + rootdirectory: /var/lib/registry +auth: + htpasswd: + realm: basic-realm + path: /etc/docker/registry/auth/nginx.htpasswd +http: + addr: :5000 + host: https://docker.domain.com + headers: + X-Content-Type-Options: [nosniff] + http2: + disabled: false + tls: + certificate: /etc/docker/registry/ssl/docker.domain.com.crt + key: /etc/docker/registry/ssl/docker.domain.com.key +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +### 6.3.3 生成 http 认证文件 + +```bash +$ mkdir auth + +$ docker run --rm \ + --entrypoint htpasswd \ + httpd:2.4-alpine \ + -Bbn username password > auth/nginx.htpasswd +``` +> 将上面的 `username` `password` 替换为你自己的用户名和密码。 +> +> **安全提示**：上述命令会将密码明文暴露在 shell 历史记录和进程列表中。生产环境建议使用交互式方式输入密码（不带 `-b` 参数），或通过环境变量/文件传入。 +> 配套 demo 的 [`auth/README.md`](demo/auth/README.md) 仅说明本地生成步骤，生成的 `auth/nginx.htpasswd` 已被忽略，不应提交。 + +> **版本说明**：使用 `httpd:2.4-alpine` 基于 Apache 2.4 的精简镜像。如需其他版本，请指定具体版本号如 `httpd:2.4.58-alpine`；不要用 `latest`（本节下文与 7 章都要求固定版本以保证可重复性）。 + +### 6.3.4 编辑 Docker Compose 配置 + +编辑 `compose.yaml`（或 `docker-compose.yml`）配置如下： + +```yaml +services: + registry: + image: registry:2 + ports: + - "443:5000" + volumes: + - ./:/etc/docker/registry + - registry-data:/var/lib/registry + +volumes: + registry-data: +``` + +本书配套的 `06_repository/demo/` 也采用同样约定：容器内 registry 监听 `:5000`，宿主机通过 `443:5000` 暴露 HTTPS 服务。这样可以避免在容器内占用特权端口，同时仍让客户端使用 `https://docker.domain.com` 访问。 + +> **版本说明**：Compose 配置中明确指定 `registry:2` 版本。生产环境建议固定具体补丁版本（如 `registry:2.8.x`），并在新部署时评估 Distribution 3.x；不要使用 `latest`，以保证部署的可重复性。 + +### 6.3.5 修改 Hosts 文件 + +编辑 `/etc/hosts` + +```bash +127.0.0.1 docker.domain.com +``` + +### 6.3.6 启动 + +```bash +$ docker compose up -d +``` +这样我们就搭建好了一个具有权限认证、TLS 的私有仓库，接下来我们测试其功能是否正常。 + +### 6.3.7 测试私有仓库功能 + +由于自行签发的 CA 根证书不被系统信任，所以我们需要将 CA 根证书 `ssl/root-ca.crt` 移入 `/etc/docker/certs.d/docker.domain.com` 文件夹中。 + +```bash +$ sudo mkdir -p /etc/docker/certs.d/docker.domain.com + +$ sudo cp ssl/root-ca.crt /etc/docker/certs.d/docker.domain.com/ca.crt +``` +登录到私有仓库。 + +```bash +$ docker login docker.domain.com +``` +尝试推送、拉取镜像。 + +```bash +$ docker pull ubuntu:24.04 + +$ docker tag ubuntu:24.04 docker.domain.com/username/ubuntu:24.04 + +$ docker push docker.domain.com/username/ubuntu:24.04 + +$ docker image rm docker.domain.com/username/ubuntu:24.04 + +$ docker pull docker.domain.com/username/ubuntu:24.04 +``` + +> **版本说明**：示例使用 `ubuntu:24.04`，这是仍受 Docker 支持的 LTS 版本（当前最新 LTS 为 26.04）。推送到私有仓库时保持了原有的版本标签，建议生产环境明确指定镜像版本号。 +如果我们退出登录，尝试推送镜像。 + +```bash +$ docker logout docker.domain.com + +$ docker push docker.domain.com/username/ubuntu:24.04 + +no basic auth credentials +``` +发现会提示没有登录，不能将镜像推送到私有仓库中。 + +### 6.3.8 注意事项 + +如果你本机占用了 `443` 端口，你可以配置 [Nginx 代理](https://distribution.github.io/distribution/recipes/nginx/)，这里不再赘述。 diff --git a/06_repository/6.4_nexus3_registry.md b/06_repository/6.4_nexus3_registry.md new file mode 100644 index 000000000..619b2bb08 --- /dev/null +++ b/06_repository/6.4_nexus3_registry.md @@ -0,0 +1,129 @@ +## 6.4 Nexus 3 + +使用 Docker 官方的 Registry 创建的仓库面临一些维护问题。比如某些镜像删除以后空间默认是不会回收的，需要一些命令去回收空间然后重启 Registry。在企业中把内部的一些工具包放入 `Nexus` 中是比较常见的做法，最新版本 `Nexus3.x` 全面支持 Docker 的私有镜像。所以使用 [Nexus 3](https://www.sonatype.com/products/sonatype-nexus-oss-download) 一个软件来管理 `Docker`，`Maven`，`Yum`，`PyPI` 等是一个明智的选择。 + +### 6.4.1 启动 Nexus 容器 + +```bash +$ docker run -d --name nexus3 --restart=always \ + -p 8081:8081 \ + --mount src=nexus-data,target=/nexus-data \ + sonatype/nexus3:3.69.0 +``` + +> **版本说明**：使用 `sonatype/nexus3:3.69.0` 指定稳定的 Nexus 版本。使用具体版本号而非 `latest` 可以避免意外升级带来的不兼容问题。 +首次运行需等待 3-5 分钟，你可以使用 `docker logs nexus3 -f` 查看日志： + +```bash +$ docker logs nexus3 -f + +2021-03-11 15:31:21,990+0000 INFO [jetty-main-1] *SYSTEM org.sonatype.nexus.bootstrap.jetty.JettyServer - +------------------------------------------------- + +Started Sonatype Nexus OSS 3.69.0 + +------------------------------------------------- +``` + +> **版本说明**：上述日志中显示的是 Nexus 3.69 版本的启动日志。具体版本号会随着容器镜像版本而不同。 +如果你看到以上内容，说明 `Nexus` 已经启动成功，你可以使用浏览器打开 `http://YourIP:8081` 访问 `Nexus` 了。 + +首次运行请通过以下命令获取初始密码： + +```bash +$ docker exec nexus3 cat /nexus-data/admin.password + +9266139e-41a2-4abb-92ec-e4142a3532cb +``` +首次启动 Nexus 的默认账号是 `admin`，密码则是上边命令获取到的，点击右上角登录，首次登录需更改初始密码。 + +登录之后可以点击页面上方的齿轮按钮按照下面的方法进行设置。 + +### 6.4.2 创建仓库 + +创建一个私有仓库的方法：`Repository->Repositories` 点击右边菜单 `Create repository` 选择 `docker (hosted)` + +* **Name**：仓库的名称 +* **HTTP**：仓库单独的访问端口（例如：**5001**） +* **Hosted -> Deployment policy**：请选择 **Allow redeploy** 否则无法上传 Docker 镜像。 + +其他的仓库创建方法请各位自己摸索，还可以创建一个 `docker (proxy)` 类型的仓库链接到 DockerHub 上。再创建一个 `docker (group)` 类型的仓库把刚才的 `hosted` 与 `proxy` 添加在一起。主机在访问的时候默认下载私有仓库中的镜像，如果没有将链接到 DockerHub 中下载并缓存到 Nexus 中。 + +### 6.4.3 添加访问权限 + +菜单 `Security->Realms` 把 Docker Bearer Token Realm 移到右边的框中保存。 + +添加用户规则：菜单 `Security->Roles`->`Create role` 在 `Privileges` 选项搜索 docker 把相应的规则移动到右边的框中然后保存。 + +添加用户：菜单 `Security->Users`->`Create local user` 在 `Roles` 选项中选中刚才创建的规则移动到右边的窗口保存。 + +### 6.4.4 NGINX 反向代理配置 + +证书的生成请参见 [私有仓库认证](6.3_registry_auth.md) 里面证书生成一节。 + +NGINX 示例配置如下 + +```nginx +upstream register +{ + server "YourHostName OR IP":5001; #端口为上面添加私有镜像仓库时设置的 HTTP 选项的端口号 + check interval=3000 rise=2 fall=10 timeout=1000 type=http; + check_http_send "HEAD / HTTP/1.0\r\n\r\n"; + check_http_expect_alive http_4xx; +} + +server { + server_name YourDomainName;#如果没有 DNS 服务器做解析，请删除此选项使用本机 IP 地址访问 + listen 443 ssl; + + ssl_certificate key/example.crt; + ssl_certificate_key key/example.key; + + ssl_session_timeout 5m; + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + ssl_prefer_server_ciphers on; + large_client_header_buffers 4 32k; + client_max_body_size 300m; + client_body_buffer_size 512k; + proxy_connect_timeout 600; + proxy_read_timeout 600; + proxy_send_timeout 600; + proxy_buffer_size 128k; + proxy_buffers 4 64k; + proxy_busy_buffers_size 128k; + proxy_temp_file_write_size 512k; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_redirect off; + proxy_set_header X-Real-IP $remote_addr; + proxy_pass http://register; + proxy_read_timeout 900s; + + } + error_page 500 502 503 504 /50x.html; +} +``` + +### 6.4.5 Docker 主机访问镜像仓库 + +如果不启用 SSL 加密可以通过[前面章节](6.2_registry.md)的方法添加非 https 仓库地址到 Docker 的配置文件中然后重启 Docker。 + +使用 SSL 加密以后程序需要访问就不能采用修改配置的方式了。具体方法如下： + +```bash +## REGISTRY_HOST 填你的域名或主机 IP，二者选其一 + +$ REGISTRY_HOST=your-domain-or-host-ip +$ openssl s_client -showcerts -connect "$REGISTRY_HOST":443 /dev/null|openssl x509 -outform PEM >ca.crt +$ cat ca.crt | sudo tee -a /etc/ssl/certs/ca-certificates.crt +$ sudo systemctl restart docker +``` +使用 `docker login $REGISTRY_HOST` 进行测试，用户名密码填写上面 Nexus 中设置的。 diff --git a/06_repository/README.md b/06_repository/README.md new file mode 100644 index 000000000..3c253dd85 --- /dev/null +++ b/06_repository/README.md @@ -0,0 +1,50 @@ +# 第六章 访问仓库 + +仓库 (`Repository`) 是集中存放镜像的地方。 + +一个容易混淆的概念是注册服务器 (`Registry`)。实际上注册服务器是管理仓库的具体服务器，每个服务器上可以有多个仓库，而每个仓库下面有多个镜像。从这方面来说，仓库可以被认为是一个具体的项目或目录。例如对于仓库地址 `docker.io/ubuntu` 来说，`docker.io` 是注册服务器地址，`ubuntu` 是仓库名。 + +大部分时候，并不需要严格区分这两者的概念。 + +## 版本号说明 + +本章涉及的 Registry 和相关工具版本说明： + +- **Docker Registry / CNCF Distribution**：本章示例使用 `registry:2` 兼容路径；新生产部署应评估 Distribution 3.x，并核对配置路径、迁移说明和生态兼容性。已停止维护的 `registry:1` 不建议使用 +- **Nexus 3**：建议指定具体版本（如 `sonatype/nexus3:3.69`）而非 `latest`，避免自动升级带来的兼容性问题 +- **镜像标签规范**： + - 生产环境推送至仓库时应明确指定版本号（如 `myapp:v1.0.0`） + - 避免依赖 `latest` 标签，因为其含义存在歧义且易导致版本混淆 + +## 为什么需要私有仓库？ + +在讨论具体的安装和配置前，让我们先理解：**什么时候你应该建设私有仓库？** + +**开发团队**（有专利代码、不能公开）： + +- 需要私有仓库存储内部镜像 +- 涉及访问控制和审计 +- 强烈推荐使用托管方案（如 Harbor 或云厂商提供的镜像仓库） + +**开源项目或个人学习**： + +- Docker Hub 公开仓库足够 +- 无需自建私有仓库的成本 + +**企业级部署**： + +- 需要高可用、备份、灾难恢复 +- 推荐使用专业级方案（Nexus 3、Harbor）而非简单的 Registry + +本章涵盖的方案从简到复杂： + +- Docker Registry：最小化部署（适合简单场景） +- 私有仓库高级配置：添加认证、HTTPS 等生产必需项 +- Nexus 3：企业级完整解决方案，支持权限管理、备份等 + +## 本章内容 + +* [Docker Hub](6.1_dockerhub.md) +* [私有仓库](6.2_registry.md) +* [私有仓库高级配置](6.3_registry_auth.md) +* [Nexus 3](6.4_nexus3_registry.md) diff --git a/06_repository/demo/auth/README.md b/06_repository/demo/auth/README.md new file mode 100644 index 000000000..c033077e5 --- /dev/null +++ b/06_repository/demo/auth/README.md @@ -0,0 +1,5 @@ +# Generated Authentication File + +Run the `htpasswd` command in section 6.3.3 to generate `nginx.htpasswd` locally before starting the demo registry. + +Do not commit generated password hashes. diff --git a/06_repository/demo/config.yml b/06_repository/demo/config.yml new file mode 100644 index 000000000..086ac0b36 --- /dev/null +++ b/06_repository/demo/config.yml @@ -0,0 +1,35 @@ +version: 0.1 +log: + accesslog: + disabled: true + level: debug + formatter: text + fields: + service: registry + environment: staging +storage: + delete: + enabled: true + cache: + blobdescriptor: inmemory + filesystem: + rootdirectory: /var/lib/registry +auth: + htpasswd: + realm: basic-realm + path: /etc/docker/registry/auth/nginx.htpasswd +http: + addr: :5000 + host: https://docker.domain.com + headers: + X-Content-Type-Options: [nosniff] + http2: + disabled: false + tls: + certificate: /etc/docker/registry/ssl/docker.domain.com.crt + key: /etc/docker/registry/ssl/docker.domain.com.key +health: + storagedriver: + enabled: true + interval: 10s +threshold: 3 diff --git a/06_repository/demo/docker-compose.yml b/06_repository/demo/docker-compose.yml new file mode 100644 index 000000000..ee3dd602c --- /dev/null +++ b/06_repository/demo/docker-compose.yml @@ -0,0 +1,13 @@ + + +services: + registry: + image: registry:2 + ports: + - "443:5000" + volumes: + - ./:/etc/docker/registry + - registry-data:/var/lib/registry + +volumes: + registry-data: diff --git a/06_repository/demo/root-ca.cnf b/06_repository/demo/root-ca.cnf new file mode 100644 index 000000000..b87de32c7 --- /dev/null +++ b/06_repository/demo/root-ca.cnf @@ -0,0 +1,4 @@ +[root_ca] +basicConstraints = critical,CA:TRUE,pathlen:1 +keyUsage = critical, nonRepudiation, cRLSign, keyCertSign +subjectKeyIdentifier=hash diff --git a/06_repository/demo/site.cnf b/06_repository/demo/site.cnf new file mode 100644 index 000000000..608538b1f --- /dev/null +++ b/06_repository/demo/site.cnf @@ -0,0 +1,7 @@ +[server] +authorityKeyIdentifier=keyid,issuer +basicConstraints = critical,CA:FALSE +extendedKeyUsage=serverAuth +keyUsage = critical, digitalSignature, keyEncipherment +subjectAltName = DNS:docker.domain.com, IP:127.0.0.1 +subjectKeyIdentifier=hash diff --git a/06_repository/demo/ssl/.gitignore b/06_repository/demo/ssl/.gitignore new file mode 100644 index 000000000..7c9d611b5 --- /dev/null +++ b/06_repository/demo/ssl/.gitignore @@ -0,0 +1,3 @@ +* +!.gitignore +!README.md diff --git a/06_repository/demo/ssl/README.md b/06_repository/demo/ssl/README.md new file mode 100644 index 000000000..1f1a95b9f --- /dev/null +++ b/06_repository/demo/ssl/README.md @@ -0,0 +1,5 @@ +# Generated TLS Files + +Run the certificate steps in section 6.3.1 to generate `docker.domain.com.key`, `docker.domain.com.crt`, and `root-ca.crt` locally before starting the demo registry. + +Do not commit generated private keys or certificates. diff --git a/06_repository/summary.md b/06_repository/summary.md new file mode 100644 index 000000000..4df17128b --- /dev/null +++ b/06_repository/summary.md @@ -0,0 +1,18 @@ +## 本章小结 + +本章介绍了 Docker Hub 的使用、私有仓库的搭建以及 Nexus 3 等企业级方案。 + +| 功能 | 说明 | +|------|------| +| **官方镜像** | 优先使用的基础镜像 | +| **拉取限制** | 匿名 100 次/6h，登录 200 次/6h | +| **安全** | 推荐开启 2FA 并使用 Access Token | +| **自动化** | 支持 Webhooks 和自动构建 | + +### 延伸阅读 + +- [私有仓库](6.2_registry.md)：搭建自己的 Registry +- [镜像加速器](../03_install/3.9_mirror.md)：加速下载 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/07_dockerfile/7.10_workdir.md b/07_dockerfile/7.10_workdir.md new file mode 100644 index 000000000..7c6f8fc69 --- /dev/null +++ b/07_dockerfile/7.10_workdir.md @@ -0,0 +1,185 @@ +## 7.10 WORKDIR 指定工作目录 + +### 7.10.1 基本语法 + +```docker +WORKDIR <工作目录路径> +``` +`WORKDIR` 指定后续指令的工作目录。如果目录不存在，Docker 会自动创建。 + +--- + +### 7.10.2 基本用法 + +```docker +WORKDIR /app + +RUN pwd # 输出 /app +RUN echo "hello" > world.txt # 创建 /app/world.txt +COPY . . # 复制到 /app/ +``` +--- + +### 7.10.3 为什么需要 WORKDIR + +#### 常见错误 + +```docker +## ❌ 错误：cd 在下一个 RUN 中无效 + +RUN cd /app +RUN echo "hello" > world.txt # 文件在根目录！ +``` + +#### 原因分析 + +```dockerfile +RUN cd /app + ↓ +启动容器 → cd /app（仅内存变化）→ 提交镜像层 → 容器销毁 + │ + ↓ 工作目录未改变！ +RUN echo "hello" > world.txt + ↓ +启动新容器（工作目录在 /）→ 创建 /world.txt +``` +每个 RUN 都在新容器中执行，**前一个 RUN 的内存状态（包括工作目录）不会保留**。 + +#### 正确做法 + +```docker +## ✅ 正确：使用 WORKDIR + +WORKDIR /app +RUN echo "hello" > world.txt # 创建 /app/world.txt +``` +--- + +### 7.10.4 相对路径 + +WORKDIR 支持相对路径，基于上一个 WORKDIR： + +```docker +WORKDIR /a +WORKDIR b +WORKDIR c + +RUN pwd # 输出 /a/b/c +``` +--- + +### 7.10.5 使用环境变量 + +```docker +ENV APP_HOME=/app +WORKDIR $APP_HOME + +RUN pwd # 输出 /app +``` +--- + +### 7.10.6 多阶段构建中的 WORKDIR + +```docker +## 构建阶段 +## 建议使用 node:22 或 node: 等具体版本标签，避免使用 latest + +FROM node:22 AS builder +WORKDIR /build +COPY package*.json ./ +RUN npm install +COPY . . +RUN npm run build + +## 生产阶段 +## 建议使用 nginx:alpine 或其他具体版本 + +FROM nginx:alpine +WORKDIR /usr/share/nginx/html +COPY --from=builder /build/dist . +``` +--- + +### 7.10.7 最佳实践 + +#### 1. 尽早设置 WORKDIR + +```docker +# 建议使用 node:22 等主/次版本号标签 +FROM node:22 +WORKDIR /app # 尽早设置 + +COPY package*.json ./ +RUN npm install +COPY . . +CMD ["node", "server.js"] +``` + +#### 2. 使用绝对路径 + +```docker +## ✅ 推荐：绝对路径，意图明确 + +WORKDIR /app + +## ⚠️ 避免：相对路径可能造成混淆 + +WORKDIR app +``` + +#### 3. 不要用 RUN cd + +```docker +## ❌ 避免 + +RUN cd /app && echo "hello" > world.txt + +## ✅ 推荐 + +WORKDIR /app +RUN echo "hello" > world.txt +``` + +#### 4. 适时重置 WORKDIR + +```docker +WORKDIR /app + +## ... 应用相关操作 ... + +WORKDIR /data + +## ... 数据相关操作 ... + +... +``` +--- + +### 7.10.8 与其他指令的关系 + +| 指令 | WORKDIR 的影响 | +|------|---------------| +| `RUN` | 在 WORKDIR 中执行命令 | +| `CMD` | 在 WORKDIR 中启动 | +| `ENTRYPOINT` | 在 WORKDIR 中启动 | +| `COPY` | 相对目标路径基于 WORKDIR | +| `ADD` | 相对目标路径基于 WORKDIR | + +```docker +WORKDIR /app + +RUN pwd # /app +COPY . . # 复制到 /app +CMD ["./start.sh"] # /app/start.sh +``` +--- + +### 7.10.9 运行时覆盖 + +使用 `-w` 参数覆盖工作目录： + +```bash +$ docker run -w /tmp myimage pwd +/tmp +``` +--- diff --git a/07_dockerfile/7.11_user.md b/07_dockerfile/7.11_user.md new file mode 100644 index 000000000..a1d13683f --- /dev/null +++ b/07_dockerfile/7.11_user.md @@ -0,0 +1,270 @@ +## 7.11 USER 指定当前用户 + +### 7.11.1 基本语法 + +```docker +USER <用户名>[:<用户组>] +USER
日志文件
上传文件"] + end + Result1["容器删除 = 数据丢失"] + Container1 ~~~ Result1 + end + + subgraph UseVolume ["使用 VOLUME："] + direction TB + Container2["容器存储层
（只读/无状态）"] + subgraph Volume ["数据卷"] + Data["持久化数据 (安全)"] + end + Container2 --> Volume + Result2["容器删除，数据保留"] + Volume ~~~ Result2 + end +``` +--- + +### 7.8.3 基本用法 + +#### 定义单个卷 + +```docker +FROM mysql:8.4 +VOLUME /var/lib/mysql +``` + +#### 定义多个卷 + +```docker +FROM myapp +VOLUME ["/data", "/logs", "/config"] +``` +--- + +### 7.8.4 VOLUME 的行为 + +#### 1. 自动创建匿名卷 + +如果运行时未指定挂载，Docker 会自动创建匿名卷： + +```bash +$ docker run mysql:8.4 +$ docker volume ls +DRIVER VOLUME NAME +local a1b2c3d4e5f6... # 自动创建的匿名卷 +``` + +#### 2. 可被命名卷覆盖 + +```bash +## 使用命名卷替代匿名卷 + +$ docker run -v mysql_data:/var/lib/mysql mysql:8.4 +``` + +#### 3. 可被 Bind Mount 覆盖 + +```bash +## 使用宿主机目录替代 + +$ docker run -v /my/data:/var/lib/mysql mysql:8.4 +``` +--- + +### 7.8.5 VOLUME 在构建时的特殊行为 + +> ⚠️ **重要**：`VOLUME` 之后再写入该目录的构建语义取决于 builder。legacy builder 会丢弃这些修改；BuildKit 会保留。但运行容器时，一旦该路径挂载了卷，卷会遮蔽镜像内同路径的内容。 + +```docker +FROM ubuntu +VOLUME /data + +## ⚠️ legacy builder 会丢弃；BuildKit 会保留，但运行时挂载卷会遮蔽它 + +RUN echo "hello" > /data/test.txt +``` +**原因**：旧 builder 会在构建过程中为该目录创建临时匿名卷，后续写入发生在临时卷中；BuildKit 则会把修改保留在镜像层。为了避免不同 builder 下出现不同结果，也为了避免运行时卷遮蔽镜像内初始化数据，不要把必须存在的初始化文件写在 `VOLUME` 之后。 + +#### 正确做法 + +```docker +FROM ubuntu + +## ✅ 先写入文件 + +RUN mkdir -p /data && echo "hello" > /data/test.txt + +## 再声明 VOLUME + +VOLUME /data +``` +--- + +### 7.8.6 常见使用场景 + +#### 数据库持久化 + +```docker +# 建议使用 postgres:16 等具体版本标签，避免 latest，具体版本号根据数据库兼容性需求选择 +FROM postgres:16 +VOLUME /var/lib/postgresql/data +``` + +#### 日志目录 + +```docker +FROM nginx +VOLUME /var/log/nginx +``` + +#### 上传文件目录 + +```docker +FROM myapp +VOLUME /app/uploads +``` +--- + +### 7.8.7 查看 VOLUME 定义 + +```bash +## 查看镜像定义的 VOLUME + +$ docker inspect mysql:8.4 --format '{{json .Config.Volumes}}' | jq +{ + "/var/lib/mysql": {} +} + +## 查看容器挂载的卷 + +$ docker inspect mycontainer --format '{{json .Mounts}}' | jq +``` +--- + +### 7.8.8 VOLUME vs docker run -v + +| 特性 | Dockerfile VOLUME | docker run -v | +|------|-------------------|---------------| +| **定义时机** | 镜像构建时 | 容器运行时 | +| **默认行为** | 创建匿名卷 | 可指定命名卷或路径 | +| **灵活性** | 低（固定路径）| 高（可任意指定）| +| **适用场景** | 定义必须持久化的路径 | 灵活的数据管理 | + +--- + +### 7.8.9 在 Compose 中 + +在 Compose 中配置如下： + +```yaml +services: + db: + # 建议使用 postgres:16 或其他具体版本，避免 latest + image: postgres:16 + volumes: + # 命名卷（推荐） + + - postgres_data:/var/lib/postgresql/data + # Bind Mount + + - ./init.sql:/docker-entrypoint-initdb.d/init.sql + +volumes: + postgres_data: # 声明命名卷 +``` +--- + +### 7.8.10 安全注意事项 + +#### 匿名卷可能导致数据丢失 + +```bash +## 使用 --rm 运行的容器，匿名卷会在容器删除时一起删除 + +$ docker run --rm mysql:8.4 + +## 容器停止后，数据丢失！ + +... +``` +**解决**：始终使用命名卷 + +```bash +$ docker run -v mysql_data:/var/lib/mysql mysql:8.4 +``` +--- + +### 7.8.11 最佳实践 + +#### 1. 定义必须持久化的路径 + +```docker +## 数据库必须使用卷 + +FROM postgres:16 +VOLUME /var/lib/postgresql/data +``` + +#### 2. 不要在 VOLUME 后修改目录 + +```docker +## ❌ 避免 + +VOLUME /app/data +RUN cp init-data.json /app/data/ + +## ✅ 正确 + +RUN mkdir -p /app/data && cp init-data.json /app/data/ +VOLUME /app/data +``` + +#### 3. 文档中说明 VOLUME 用途 + +```docker +## 持久化用户上传的文件 + +VOLUME /app/uploads + +## 持久化数据库数据 + +VOLUME /var/lib/mysql +``` +--- diff --git a/07_dockerfile/7.9_expose.md b/07_dockerfile/7.9_expose.md new file mode 100644 index 000000000..82599fa88 --- /dev/null +++ b/07_dockerfile/7.9_expose.md @@ -0,0 +1,206 @@ +## 7.9 EXPOSE 暴露端口 + +### 7.9.1 基本语法 + +```docker +EXPOSE <端口> [<端口>/<协议>...] +``` +`EXPOSE` 声明容器运行时提供服务的端口。这是一个 **文档性质的声明**，告诉使用者容器会监听哪些端口。 + +--- + +### 7.9.2 基本用法 + +```docker +## 声明单个端口 + +EXPOSE 80 + +## 声明多个端口 + +EXPOSE 80 443 + +## 声明 TCP 和 UDP 端口 + +EXPOSE 80/tcp +EXPOSE 53/udp +``` +--- + +### 7.9.3 EXPOSE 的作用 + +#### 1. 文档说明 + +告诉镜像使用者，容器将在哪些端口提供服务： + +```docker +## 使用者一看就知道这是 web 应用 + +EXPOSE 80 443 +``` +```bash +## 查看镜像暴露的端口 + +$ docker inspect nginx --format '{{.Config.ExposedPorts}}' +map[80/tcp:{}] +``` + +#### 2. 配合 -P 使用 + +使用 `docker run -P` 时，Docker 会自动映射 EXPOSE 的端口到宿主机随机端口： + +```docker +## Dockerfile + +EXPOSE 80 +``` +```bash +$ docker run -P nginx +$ docker port $(docker ps -q) +80/tcp -> 0.0.0.0:32768 +``` +--- + +### 7.9.4 EXPOSE vs -p + +| 特性 | EXPOSE | -p | +|------|--------|-----| +| **位置** | Dockerfile | docker run 命令 | +| **作用** | 声明/文档 | 实际端口映射 | +| **是否必需** | 否 | 是（外部访问时）| +| **映射发生时** | 不发生 | 运行时发生 | + +```mermaid +flowchart TD + Expose["EXPOSE 80
仅声明意图"] + Run["docker run -p
实际端口映射
宿主机 ←→ 容器"] + Expose ~~~ Run +``` + +#### 没有 EXPOSE 也能 -p + +```docker +## 即使没有 EXPOSE，也可以使用 -p + +FROM nginx + +## 没有 EXPOSE + +... +``` +```bash +## 仍然可以映射端口 + +$ docker run -p 8080:80 mynginx +``` +--- + +### 7.9.5 常见误解 + +#### 误解：EXPOSE 会打开端口 + +```docker +## ❌ 错误理解：这不会让容器可从外部访问 + +EXPOSE 80 +``` +EXPOSE 不会： + +- 自动进行端口映射 +- 让服务可从外部访问 +- 在容器启动时开启端口监听 + +EXPOSE 只是元数据声明。容器是否实际监听该端口，取决于容器内的应用。 + +#### 正确理解 + +```docker +## Dockerfile + +FROM nginx +EXPOSE 80 # 1. 声明：这个容器会在 80 端口提供服务 +``` +```bash +## 运行：需要 -p 才能从外部访问 + +$ docker run -p 8080:80 nginx # 2. 映射：宿主机 8080 → 容器 80 +``` +--- + +### 7.9.6 最佳实践 + +#### 1. 总是声明应用使用的端口 + +```docker +## Web 服务 + +FROM nginx +EXPOSE 80 443 + +## 数据库 + +FROM postgres +EXPOSE 5432 + +## Redis + +FROM redis +EXPOSE 6379 +``` + +#### 2. 使用明确的协议 + +```docker +## 默认是 TCP + +EXPOSE 80 + +## 明确指定 UDP + +EXPOSE 53/udp + +## 同时支持 TCP 和 UDP + +EXPOSE 53/tcp 53/udp +``` + +#### 3. 与应用实际端口保持一致 + +```docker +## ✅ 好：EXPOSE 与应用端口一致 + +ENV PORT=3000 +EXPOSE 3000 +CMD ["node", "server.js"] + +## ❌ 差：EXPOSE 与应用端口不一致（误导） + +EXPOSE 80 +CMD ["node", "server.js"] # 实际监听 3000 +``` +--- + +### 7.9.7 使用环境变量 + +```docker +ARG PORT=80 +EXPOSE $PORT +``` +--- + +### 7.9.8 在 Compose 中 + +在 Compose 中配置如下： + +```yaml +services: + web: + build: . + ports: + - "8080:80" # 映射端口（类似 -p） + expose: + - "80" # 仅声明（类似 EXPOSE） +``` +`expose` 在 Compose 中仅用于容器间通信的文档说明，不进行端口映射。 + +--- diff --git a/07_dockerfile/README.md b/07_dockerfile/README.md new file mode 100644 index 000000000..cf5e94a25 --- /dev/null +++ b/07_dockerfile/README.md @@ -0,0 +1,98 @@ +# 第七章 Dockerfile 指令详解 + +## 什么是 Dockerfile + +Dockerfile 是一个文本文件，其内包含了一条条的 **指令 (Instruction)**，每一条指令构建一层，因此每一条指令的内容，就是描述该层应当如何构建。 + +在[第四章](../04_image/README.md)中，我们通过 `docker commit` 学习了镜像的构成。但是，手动 `commit` 只能作为临时修补，并不适合作为生产环境镜像的构建方式。 + +使用 Dockerfile 构建镜像有以下优势： + +* **自动化**：可以通过 `docker build` 命令自动构建镜像。 +* **可重复性**：由于 Dockerfile 是文本文件，可以确保每次构建的结果一致。 +* **版本控制**：Dockerfile 可以纳入版本控制系统（如 Git），便于追踪变更。 +* **透明性**：任何人都可以通过阅读 Dockerfile 了解镜像的构建过程。 + +## Dockerfile 编写哲学 + +在深入每个指令的细节之前，笔者想强调一个至关重要的原则：**Dockerfile 不是脚本，而是镜像的“设计图”**。这个区别决定了你如何思考每条指令的作用。 + +相比编写 Bash 脚本的思维（“按顺序执行这些命令”），Dockerfile 的思维应该是（“这一层镜像应该如何构建，下一层如何分层”）。这个思维转变会影响你的决策： + +- **合并命令**：一个 `RUN apt-get update && apt-get install ...` 应该写在一起，而不是分开成多个 `RUN` 指令，因为它们是同一个“层”的逻辑 +- **选择合适的指令**：`COPY` vs `ADD`、`CMD` vs `ENTRYPOINT` 这些选择不是随意的，而是根据镜像分层的语义来决定的 +- **优化镜像大小**：最后才清理缓存、删除临时文件，让这些“瘦身”操作在同一层完成 + +这个章节将详细介绍各个指令。在学习指令语法时，请始终思考：“这个指令为什么要以这样的方式工作？如果我是 Docker，我应该如何设计它？” + +## Dockerfile 基本结构 + +Dockerfile 一般分为四部分：基础镜像信息、维护者信息、镜像操作指令和容器启动时执行指令。 + +可运行 `docker buildx build --check` 校验的[完整 Dockerfile 示例](../examples/validated/dockerfile/Dockerfile)与配套 `index.html` 保存在仓库中。它使用 `scratch`，因此结构检查不会解析远程基础镜像元数据。下面的围栏与该文件由测试强制保持一致。 + + +```dockerfile +FROM scratch + +COPY index.html /index.html +``` + +### 指令详解 + +本章将详细讲解 Dockerfile 中的各个指令： + +* [RUN 执行命令](7.1_run.md) +* [COPY 复制文件](7.2_copy.md) +* [ADD 更高级的复制文件](7.3_add.md) +* [CMD 容器启动命令](7.4_cmd.md) +* [ENTRYPOINT 入口点](7.5_entrypoint.md) +* [ENV 设置环境变量](7.6_env.md) +* [ARG 构建参数](7.7_arg.md) +* [VOLUME 定义匿名卷](7.8_volume.md) +* [EXPOSE 暴露端口](7.9_expose.md) +* [WORKDIR 指定工作目录](7.10_workdir.md) +* [USER 指定当前用户](7.11_user.md) +* [HEALTHCHECK 健康检查](7.12_healthcheck.md) +* [ONBUILD 为他人作嫁衣裳](7.13_onbuild.md) +* [LABEL 为镜像添加元数据](7.14_label.md) +* [SHELL 指令](7.15_shell.md) + +### 高级特性 + +本章还将介绍 Dockerfile 的高级特性： + +* [多阶段构建](7.17_multistage_builds.md) +* [多阶段构建实战：Laravel 应用](7.18_multistage_builds_laravel.md) + +### 参考与最佳实践 + +此外，我们还将介绍 Dockerfile 的最佳实践和常见问题。 + +* [参考文档](7.16_references.md) + +## 使用 Dockerfile 构建镜像 + +构建镜像的基本命令格式为： + +```bash +docker build [选项] <上下文路径/URL/-> +``` +例如，在 Dockerfile 所在目录执行： + +```bash +docker build -t my-image:1.0 . +``` + +### 关于版本号最佳实践 + +本章中的 Dockerfile 示例使用的基础镜像标签遵循以下原则： + +- **通用标签**（如 `ubuntu:24.04`、`alpine`、`nginx`）：保持原样，无需修改 +- **基础镜像版本号**（如 `node:22`、`python:3.12`）：使用主或次版本号而非完整版本号（patch），这样可以自动获取最新的补丁版本，确保获得安全更新。 + （这条只针对 **Dockerfile 的基础镜像**；部署一个服务镜像时反而应钉死确切版本，见 [第 5 章](../05_container/README.md)。） +- **避免**：不建议使用 `latest` 标签和完整的 patch 版本号（如 `20.10.0`）作为基础镜像，因为这会导致构建的不可重现性或安全风险 + +读者在使用这些示例时，应根据实际生产环境需求选择合适的版本号。 + +更多关于 `docker build` 的用法，我们在实战中会结合具体指令进行演示。 diff --git a/07_dockerfile/multistage_example/laravel/.dockerignore b/07_dockerfile/multistage_example/laravel/.dockerignore new file mode 100644 index 000000000..8516a3a06 --- /dev/null +++ b/07_dockerfile/multistage_example/laravel/.dockerignore @@ -0,0 +1,17 @@ +.idea/ +.git/ + +vendor/ + +node_modules/ + +public/js/ +public/css/ +public/mix-manifest.json + +yarn-error.log + +bootstrap/cache/* +storage/ + +# 自行添加其他需要排除的文件，例如 .env.* 文件 diff --git a/07_dockerfile/multistage_example/laravel/Dockerfile b/07_dockerfile/multistage_example/laravel/Dockerfile new file mode 100644 index 000000000..495f14bad --- /dev/null +++ b/07_dockerfile/multistage_example/laravel/Dockerfile @@ -0,0 +1,56 @@ +FROM node:22-alpine AS frontend + +COPY package.json /app/ + +RUN set -x ; cd /app \ + && npm install --registry=https://registry.npmmirror.com + +COPY webpack.mix.js webpack.config.js tailwind.config.js /app/ +COPY resources/ /app/resources/ + +RUN set -x ; cd /app \ + && touch artisan \ + && mkdir -p public \ + && npm run production + +FROM composer:2 AS composer + +COPY database/ /app/database/ +COPY composer.json composer.lock /app/ + +RUN set -x ; cd /app \ + && composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ \ + && composer install \ + --ignore-platform-reqs \ + --no-interaction \ + --no-plugins \ + --no-scripts \ + --prefer-dist + +FROM php:8.3-fpm-alpine AS laravel + +ARG LARAVEL_PATH=/app/laravel + +COPY --from=composer /app/vendor/ ${LARAVEL_PATH}/vendor/ +COPY . ${LARAVEL_PATH} +COPY --from=frontend /app/public/js/ ${LARAVEL_PATH}/public/js/ +COPY --from=frontend /app/public/css/ ${LARAVEL_PATH}/public/css/ +COPY --from=frontend /app/public/mix-manifest.json ${LARAVEL_PATH}/public/mix-manifest.json + +RUN set -x ; cd ${LARAVEL_PATH} \ + && mkdir -p storage \ + && mkdir -p storage/framework/cache \ + && mkdir -p storage/framework/sessions \ + && mkdir -p storage/framework/testing \ + && mkdir -p storage/framework/views \ + && mkdir -p storage/logs \ + && chown -R www-data:www-data storage \ + && chmod -R 775 storage \ + && php artisan package:discover + +FROM nginx:1.28-alpine AS nginx + +ARG LARAVEL_PATH=/app/laravel + +COPY laravel.conf /etc/nginx/conf.d/ +COPY --from=laravel ${LARAVEL_PATH}/public ${LARAVEL_PATH}/public diff --git a/07_dockerfile/multistage_example/laravel/laravel.conf b/07_dockerfile/multistage_example/laravel/laravel.conf new file mode 100644 index 000000000..c600fbb88 --- /dev/null +++ b/07_dockerfile/multistage_example/laravel/laravel.conf @@ -0,0 +1,18 @@ +server { + listen 80 default_server; + root /app/laravel/public; + index index.php index.html; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ .*\.php(\/.*)*$ { + fastcgi_pass laravel:9000; + include fastcgi.conf; + + # fastcgi_connect_timeout 300; + # fastcgi_send_timeout 300; + # fastcgi_read_timeout 300; + } +} diff --git a/07_dockerfile/summary.md b/07_dockerfile/summary.md new file mode 100644 index 000000000..182031179 --- /dev/null +++ b/07_dockerfile/summary.md @@ -0,0 +1,48 @@ +## 本章小结 + +本章详细介绍了 Dockerfile 的所有核心指令，以下是各指令要点的速查表。 + +| 指令 | 作用 | 关键要点 | +|------|------|---------| +| **FROM** | 指定基础镜像 | 必须是第一条构建指令；只有全局 `ARG` 能写在它之前 | +| **RUN** | 在新层执行命令 | 合并命令、清理缓存以减小体积 | +| **COPY** | 复制文件 | 优先使用，支持 `--from` | +| **ADD** | 更高级的复制 | 自动解压 tar；公开远程 artifact 应配合 `--checksum` | +| **CMD** | 容器启动默认命令 | 可被 `docker run` 参数覆盖 | +| **ENTRYPOINT** | 容器入口点 | 固定启动命令，CMD 作为默认参数 | +| **ENV** | 设置环境变量 | 构建时 + 运行时均生效 | +| **ARG** | 构建参数 | 仅构建时生效，FROM 后需重新声明 | +| **VOLUME** | 定义匿名卷 | 运行时挂载会遮蔽镜像内目录；构建后续写入语义依赖 builder | +| **EXPOSE** | 声明端口 | 仅文档作用，不自动映射 | +| **WORKDIR** | 指定工作目录 | 替代 `RUN cd`，目录不存在会自动创建 | +| **USER** | 指定运行用户 | 用户必须已存在，推荐 gosu | +| **HEALTHCHECK** | 健康检查 | 支持 starting/healthy/unhealthy 状态 | +| **ONBUILD** | 延迟执行指令 | 只继承一次，不可级联 | +| **LABEL** | 添加元数据 | 推荐 OCI 标准标签，替代 MAINTAINER | +| **SHELL** | 更改默认 shell | 推荐 `["/bin/bash", "-o", "pipefail", "-c"]` | + +### 生产镜像快速检查清单 + +在将镜像推向生产之前，建议逐条过一遍以下清单： + +- [ ] 基础镜像选择了最小化版本（如 `alpine`、`distroless`） +- [ ] 使用了[多阶段构建](7.17_multistage_builds.md)，最终镜像不含编译工具链 +- [ ] 以非 root 用户运行（`USER` 指令） +- [ ] `COPY` 优先于 `ADD`，且仅复制必要文件 +- [ ] `RUN` 指令合并了 `apt-get update && install && rm -rf /var/lib/apt/lists/*` +- [ ] 设置了 `HEALTHCHECK` +- [ ] 使用了 `.dockerignore` 排除 `.git`、`node_modules` 等无关文件 +- [ ] 镜像标签使用了具体版本号或 commit hash，而非 `latest` + +> 更完整的编写指南见[附录：Dockerfile 最佳实践](../appendix/best_practices.md)。 + +### 延伸阅读 + +- [使用 Dockerfile 定制镜像](../04_image/4.5_build.md)：Dockerfile 入门 +- [多阶段构建](7.17_multistage_builds.md)：优化镜像大小 +- [Dockerfile 最佳实践](../appendix/best_practices.md)：编写指南 +- [安全](../18_security/README.md)：容器安全实践 +- [Compose 模板文件](../11_compose/11.5_compose_file.md)：Compose 中的配置 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/08_data/8.1_volume.md b/08_data/8.1_volume.md new file mode 100644 index 000000000..0992f6879 --- /dev/null +++ b/08_data/8.1_volume.md @@ -0,0 +1,361 @@ +## 8.1 数据卷 + +### 8.1.1 为什么需要数据卷 + +容器的存储层有一个关键问题：**容器删除后，数据就没了**。 + +```mermaid +flowchart LR + Run[容器运行] --> Write[写入数据] + Write --> Delete[容器删除] + Delete -->|数据都在容器 writable 层| Lost[DATA LOST! ❌] +``` +数据卷 (Volume) 解决了这个问题，它的生命周期独立于容器。 + +--- + +### 8.1.2 数据卷的特性 + +| 特性 | 说明 | +|------|------| +| **持久化** | 容器删除后数据仍然保留 | +| **共享** | 多个容器可以挂载同一个数据卷 | +| **即时生效** | 对数据卷的修改立即可见 | +| **不影响镜像** | 数据卷中的数据不会打包进镜像 | +| **性能更好** | 绕过 UnionFS，直接读写 | + +--- + +### 8.1.3 数据卷 vs 容器存储层 + +#### 容器存储层：不推荐存储重要数据 + +```mermaid +graph TD + subgraph Container [容器] + Writable[容器存储层
Writable] + Image[镜像层
ReadOnly] + Writable --- Image + end + + Lifecycle[生命周期 = 容器生命周期] -.-> Container + Delete[容器删除] -->|导致| DataLost[数据丢失 ❌] +``` + +#### 数据卷：推荐 + +```mermaid +graph TD + subgraph Container [容器] + AppDir["/app/data"] + end + + subgraph Volume [数据卷 my-data] + Data[持久化数据] + end + + AppDir == 挂载 ==> Volume + Delete[容器删除] -.->|不会影响| Volume +``` +--- + +### 8.1.4 数据卷基本操作 + +#### 创建数据卷 + +```bash +$ docker volume create my-vol +``` + +#### 列出所有数据卷 + +```bash +$ docker volume ls +DRIVER VOLUME NAME +local my-vol +local postgres_data +local redis_data +``` + +#### 查看数据卷详情 + +```bash +$ docker volume inspect my-vol +[ + { + "CreatedAt": "2026-01-15T10:00:00Z", + "Driver": "local", + "Labels": {}, + "Mountpoint": "/var/lib/docker/volumes/my-vol/_data", + "Name": "my-vol", + "Options": {}, + "Scope": "local" + } +] +``` +**关键字段**： + +- `Mountpoint`：数据卷在宿主机上的实际存储位置 +- `Driver`：存储驱动（默认 local，也可以用第三方驱动） + +--- + +### 8.1.5 挂载数据卷 + +#### 方式一：--mount：推荐 + +```bash +$ docker run -d \ + --name web \ + --mount source=my-vol,target=/usr/share/nginx/html \ + nginx +``` +**参数说明**： + +| 参数 | 说明 | +|------|------| +| `source` | 数据卷名称（不存在会自动创建）| +| `target` | 容器内挂载路径 | +| `readonly` | 可选，只读挂载 | + +#### 方式二：-v：简写 + +```bash +$ docker run -d \ + --name web \ + -v my-vol:/usr/share/nginx/html \ + nginx +``` +**格式**：`-v 数据卷名:容器路径[:选项]` + +#### 两种方式对比 + +| 特性 | --mount | -v | +|------|---------|-----| +| 语法 | 键值对，更清晰 | 冒号分隔，更简洁 | +| **数据卷 (Volume)** 挂载行为 | 卷不存在会自动创建，与 `-v` 结果一致 | 卷不存在会自动创建 | +| **绑定挂载 (Bind Mount)** 行为 | ⭐**宿主机路径不存在会报错**，不会自动创建 | 宿主机路径不存在会 **自动创建为目录** | +| 推荐程度 | ✅ 推荐（更明确安全，避免误创建）| 常用（更简洁）| + +> **提示**：官方更推荐使用 `--mount`。除了语法格式可读性更好之外，最重要的行为差异发生在 **绑定挂载 (Bind Mount)** 时：如果挂载的宿主机源路径尚未存在，`-v` 会擅自将其自动创建为一个空目录；而 `--mount` 则会严格检查并直接报错。这能有效避免因路径拼写错误而在宿主机上留下垃圾目录（以及导致的容器访问空目录问题）。而对于本节的 **数据卷 (Volume)** 挂载而言，两者在目标指定的卷不存在时皆会自动创建卷，产生的结果是 **完全一致** 的。 + +#### 只读挂载 + +```bash +## --mount 方式 + +$ docker run -d \ + --mount source=my-vol,target=/data,readonly \ + nginx + +## -v 方式 + +$ docker run -d \ + -v my-vol:/data:ro \ + nginx +``` +--- + +### 8.1.6 使用场景示例 + +#### 场景一：数据库持久化 + +```bash +## 创建数据卷 + +$ docker volume create postgres_data + +## 启动 PostgreSQL，数据存储在数据卷中 + +$ docker run -d \ + --name postgres \ + -e POSTGRES_PASSWORD=secret \ + -v postgres_data:/var/lib/postgresql/data \ + postgres:16 # 确保与环境兼容的 PostgreSQL 版本 + +## 即使删除容器，数据仍然保留 + +$ docker rm -f postgres + +## 重新启动，数据还在 + +$ docker run -d \ + --name postgres \ + -e POSTGRES_PASSWORD=secret \ + -v postgres_data:/var/lib/postgresql/data \ + postgres:16 # 确保与环境兼容的 PostgreSQL 版本 +``` + +#### 场景二：多容器共享数据 + +```bash +## 创建共享数据卷 + +$ docker volume create shared-data + +## 容器 A 写入数据 + +$ docker run -d --name writer \ + -v shared-data:/data \ + alpine sh -c "while true; do date >> /data/log.txt; sleep 5; done" + +## 容器 B 读取数据 + +$ docker run --rm \ + -v shared-data:/data \ + alpine cat /data/log.txt +``` + +#### 场景三：配置文件持久化 + +```bash +## 将 nginx 配置存储在数据卷中 + +$ docker run -d \ + -v nginx-config:/etc/nginx/conf.d \ + -v nginx-logs:/var/log/nginx \ + -p 80:80 \ + nginx +``` +--- + +### 8.1.7 数据卷管理 + +#### 删除数据卷 + +```bash +## 删除指定数据卷 + +$ docker volume rm my-vol + +## 删除容器时同时删除数据卷 + +$ docker rm -v container_name +``` + +#### 清理未使用的数据卷 + +```bash +## 查看未被任何容器使用的数据卷 + +$ docker volume ls -f dangling=true + +## 删除所有未使用的数据卷 + +$ docker volume prune + +## 强制删除（不提示确认） + +$ docker volume prune -f +``` +> ⚠️ **注意**：数据卷不会自动垃圾回收。长期运行的系统应定期清理无用数据卷。 + +--- + +### 8.1.8 数据卷备份与恢复 + +#### 备份数据卷 + +```bash +## 使用临时容器挂载数据卷，打包备份 + +$ docker run --rm \ + -v my-vol:/source:ro \ + -v $(pwd):/backup \ + alpine tar czf /backup/my-vol-backup.tar.gz -C /source . +``` +**原理**： + +1. 创建临时容器 +2. 挂载要备份的数据卷到 `/source` +3. 挂载当前目录到 `/backup` +4. 使用 tar 打包 + +#### 恢复数据卷 + +```bash +## 创建新数据卷 + +$ docker volume create my-vol-restored + +## 解压备份到新数据卷 + +$ docker run --rm \ + -v my-vol-restored:/target \ + -v $(pwd):/backup:ro \ + alpine tar xzf /backup/my-vol-backup.tar.gz -C /target +``` + +#### 备份脚本示例 + +```bash +#!/bin/bash + +## backup-volume.sh + +VOLUME_NAME=$1 +BACKUP_DIR=${2:-/backups} +TIMESTAMP=$(date +%Y%m%d_%H%M%S) + +docker run --rm \ + -v ${VOLUME_NAME}:/source:ro \ + -v ${BACKUP_DIR}:/backup \ + alpine tar czf /backup/${VOLUME_NAME}_${TIMESTAMP}.tar.gz -C /source . + +echo "Backed up ${VOLUME_NAME} to ${BACKUP_DIR}/${VOLUME_NAME}_${TIMESTAMP}.tar.gz" +``` +--- + +### 8.1.9 数据卷 vs 绑定挂载 + +Docker 有两种主要的数据持久化方式： + +| 特性 | 数据卷 (Volume) | 绑定挂载 (Bind Mount) | +|------|----------------|---------------------| +| **管理方式** | Docker 管理 | 用户管理 | +| **存储位置** | `/var/lib/docker/volumes/` | 任意宿主机路径 | +| **可移植性** | 更好 | 依赖宿主机路径 | +| **适用场景** | 生产数据持久化 | 开发时同步代码 | +| **备份** | 需要工具 | 直接访问文件 | + +```bash +## 数据卷 + +$ docker run -v mydata:/app/data nginx + +## 绑定挂载 + +$ docker run -v /host/path:/app/data nginx +``` +详见[绑定挂载](8.2_bind-mounts.md)章节。 + +--- + +### 8.1.10 常见问题 + +#### Q：如何知道容器使用了哪些数据卷？ + +```bash +$ docker inspect container_name --format '{{json .Mounts}}' | jq +``` + +#### Q：数据卷的数据在哪里？ + +```bash +## 查看数据卷详情 + +$ docker volume inspect my-vol + +## Mountpoint 字段显示实际路径 + +"Mountpoint": "/var/lib/docker/volumes/my-vol/_data" +``` +> ⚠️ **注意**：不建议直接修改 Mountpoint 中的文件，应通过容器操作。 + +#### Q：如何在不同机器间迁移数据卷？ + +1. 在源机器备份：`docker run --rm -v mydata:/data -v $(pwd):/backup alpine tar czf /backup/data.tar.gz -C /data .` +2. 传输 tar.gz 文件 +3. 在目标机器恢复 + +--- diff --git a/08_data/8.2_bind-mounts.md b/08_data/8.2_bind-mounts.md new file mode 100644 index 000000000..4a97cb68a --- /dev/null +++ b/08_data/8.2_bind-mounts.md @@ -0,0 +1,292 @@ +## 8.2 挂载主机目录 + +### 8.2.1 什么是绑定挂载 + +Bind Mount（绑定挂载）将 **Docker daemon 所在主机** 上的目录或文件直接挂载到容器中。容器可以读写这台主机上的文件系统。 + +```mermaid +flowchart LR + subgraph Host ["宿主机"] + Dir1["/home/user/code/"] + end + + subgraph Container ["容器"] + Dir2["/usr/share/nginx/html/"] + end + + Dir1 <-->|Bind Mount| Dir2 +``` +目录结构（同一份文件）： +```text +/home/user/code/ (或 /usr/share/nginx/html/) +├── index.html +├── style.css +└── app.js +``` +--- + +### 8.2.2 Bind Mount vs Volume + +| 特性 | Bind Mount | Volume | +|------|------------|--------| +| **数据位置** | 宿主机任意路径 | Docker 管理的目录 | +| **路径指定** | 必须是绝对路径 | 卷名 | +| **可移植性** | 依赖宿主机路径 | 更好（Docker 管理）| +| **性能** | 依赖宿主机文件系统 | 优化的存储驱动 | +| **适用场景** | 开发环境、配置文件 | 生产数据持久化 | +| **备份** | 直接访问文件 | 需要通过 Docker | + +#### 选择建议 + +| 需求 | 推荐方案 | +|------|----------| +| 开发时同步代码 | Bind Mount | +| 持久化数据库数据 | Volume | +| 共享配置文件 | Bind Mount | +| 容器间共享数据 | Volume | +| 备份方便 | Bind Mount（直接访问）| +| 生产环境 | Volume | + +--- + +### 8.2.3 基本语法 + +#### 使用 `--mount`：推荐 + +```bash +$ docker run -d \ + --mount type=bind,source=/宿主机路径,target=/容器路径 \ + nginx +``` + +#### 使用 `-v`：简写 + +```bash +$ docker run -d \ + -v /宿主机路径:/容器路径 \ + nginx +``` + +#### 两种语法对比 + +| 特性 | --mount | -v | +|------|---------|-----| +| 语法 | 键值对，更清晰 | 冒号分隔，更简洁 | +| 路径不存在时 | 直接报错 (Fail Fast) | 静默自动创建 **目录** | +| 推荐程度 | ✅ 推荐 | 常用 | + +> **⚠️ 陷阱**：如果不小心挂载了一个不存在的主机路径，使用 `-v` 会在 **daemon 主机** 上静默创建一个空目录。对于本地 Docker Desktop 用户，这个主机通常就是本机；对于远程 daemon，这个主机就是远程机器。这也是 Docker 官方更推荐使用 `--mount` 的原因：它会直接报错，避免因路径拼写错误而挂错位置。 + +--- + +### 8.2.4 使用场景 + +#### 场景一：开发环境代码同步 + +```bash +## 将本地代码目录挂载到容器 + +$ docker run -d \ + -p 8080:80 \ + --mount type=bind,source=$(pwd)/src,target=/usr/share/nginx/html \ + nginx + +## 修改本地文件，容器内立即生效（热更新） + +$ echo "Hello" > src/index.html + +## 浏览器刷新即可看到变化 + +... +``` + +#### 场景二：配置文件挂载 + +```bash +## 挂载自定义 nginx 配置 + +$ docker run -d \ + --mount type=bind,source=/path/to/nginx.conf,target=/etc/nginx/nginx.conf,readonly \ + nginx +``` + +#### 场景三：日志收集 + +```bash +## 将容器日志输出到宿主机目录 + +$ docker run -d \ + --mount type=bind,source=/var/log/myapp,target=/app/logs \ + myapp +``` + +#### 场景四：共享 SSH 密钥 + +只读挂载可以防止容器修改主机密钥，但不能防止容器读取并外传密钥。只有在镜像完全可信、密钥作用域很窄且可随时轮换时，才考虑这种做法。更稳妥的方式是使用 SSH agent socket 转发、一次性 deploy key，或在 CI/构建场景中使用 BuildKit `--ssh`。 + +```bash +## 挂载 SSH 密钥（只读） + +$ docker run --rm -it \ + --mount type=bind,source=$HOME/.ssh,target=/root/.ssh,readonly \ + alpine ssh user@remote +``` +--- + +### 8.2.5 只读挂载 + +防止容器修改宿主机文件： + +```bash +## --mount 语法 + +$ docker run -d \ + --mount type=bind,source=/config,target=/app/config,readonly \ + myapp + +## -v 语法 + +$ docker run -d \ + -v /config:/app/config:ro \ + myapp +``` +容器内尝试写入会报错： + +```bash +$ touch /app/config/new.txt +touch: /app/config/new.txt: Read-only file system +``` +--- + +### 8.2.6 挂载单个文件 + +```bash +## 挂载 bash 历史记录 + +$ docker run --rm -it \ + --mount type=bind,source=$HOME/.bash_history,target=/root/.bash_history \ + ubuntu bash + +## 挂载自定义配置文件 + +$ docker run -d \ + --mount type=bind,source=/path/to/my.cnf,target=/etc/mysql/my.cnf \ + mysql +``` +> ⚠️ **注意**：挂载单个文件时，如果宿主机上的文件被编辑器替换（而非原地修改），容器内仍是旧文件的 inode。建议重启容器或挂载目录。 + +--- + +### 8.2.7 查看挂载信息 + +```bash +$ docker inspect mycontainer --format '{{json .Mounts}}' | jq +``` +输出： + +```json +[ + { + "Type": "bind", + "Source": "/home/user/code", + "Destination": "/app", + "Mode": "", + "RW": true, + "Propagation": "rprivate" + } +] +``` +| 字段 | 说明 | +|------|------| +| `Type` | 挂载类型 (bind)| +| `Source` | 宿主机路径 | +| `Destination` | 容器内路径 | +| `RW` | 是否可读写 | +| `Propagation` | 挂载传播模式 | + +--- + +### 8.2.8 常见问题 + +#### Q：路径不存在报错 + +```bash +$ docker run --mount type=bind,source=/not/exist,target=/app nginx +docker: Error response from daemon: invalid mount config for type "bind": +bind source path does not exist: /not/exist +``` +**解决**：确保源路径存在。若你确实需要自动创建目录，可改用 `-v`，但要先确认创建位置就是你想要的主机路径。 + +#### Q：权限问题 + +容器内用户可能无权访问挂载的文件： + +```bash +## 方法1：确保宿主机文件权限允许容器用户访问 + +$ chmod -R 755 /path/to/data + +## 方法2：以 root 运行容器 + +$ docker run -u root ... + +## 方法3：使用相同的 UID + +$ docker run -u $(id -u):$(id -g) ... +``` + +#### Q：macOS/Windows 性能问题 + +在 Docker Desktop 上，Bind Mount 性能通常不如 Volume，因为数据需要在宿主机文件系统和 Linux VM 之间同步： + +```bash +## 使用 :cached 或 :delegated 提高性能（macOS，仅 Docker Desktop 4.5 及更早版本） + +$ docker run -v /host/path:/container/path:cached myapp +``` +| 选项 | 说明 | +|------|------| +| `:cached` | 宿主机权威，容器读取可能延迟 | +| `:delegated` | 容器权威，宿主机读取可能延迟 | +| `:consistent` | 默认，完全一致（最慢）| + +> **注意**：Docker Desktop 4.6+ 默认使用 VirtioFS 文件共享引擎，上述 `:cached`/`:delegated` 选项已被静默忽略。如需优化文件同步性能，请参考 Docker Desktop 的 [Synchronized file shares](https://docs.docker.com/desktop/features/synchronized-file-sharing/) 功能。 + +--- + +### 8.2.9 最佳实践 + +#### 1. 开发环境使用 Bind Mount + +```bash +## 代码热更新 + +$ docker run -v "$(pwd)":/app -w /app -p 3000:3000 node:22 npm run dev +``` + +#### 2. 生产环境使用 Volume + +```bash +## 数据持久化 + +$ docker run -v mysql_data:/var/lib/mysql mysql +``` + +#### 3. 配置文件使用只读挂载 + +```bash +$ docker run -v /config/nginx.conf:/etc/nginx/nginx.conf:ro nginx +``` + +#### 4. 注意路径安全 + +```bash +## ❌ 危险：挂载根目录或敏感目录 + +$ docker run -v /:/host ... + +## ✅ 只挂载必要的目录 + +$ docker run -v /app/data:/data ... +``` +--- diff --git a/08_data/8.3_tmpfs.md b/08_data/8.3_tmpfs.md new file mode 100644 index 000000000..3d15c8410 --- /dev/null +++ b/08_data/8.3_tmpfs.md @@ -0,0 +1,39 @@ +## 8.3 tmpfs 挂载 + +`tmpfs` 挂载会把数据放在内存中，而不是写入容器可写层或数据卷。它只适用于 Linux 语义的容器环境，适合需要快速读写但不要求持久化的数据。 + +### 8.3.1 适用场景 + +- 临时缓存 +- 会话数据 +- 不希望落盘的敏感中间文件 + +### 8.3.2 基本用法 + +使用 `--mount` 语法（推荐）： + +```bash +$ docker run --mount type=tmpfs,destination=/run,tmpfs-size=67108864,tmpfs-mode=1770 nginx +``` +也可以使用 `--tmpfs` 简写语法： + +```bash +$ docker run --tmpfs /run:size=64m nginx +``` +> **注意**：`--tmpfs` 更适合简单场景；如果你希望显式描述挂载点、大小和权限，`--mount type=tmpfs,...` 的可读性更好，也更便于后续维护。 + +### 8.3.3 注意事项 + +- 容器停止后，`tmpfs` 数据会丢失。 +- `tmpfs` 占用宿主机内存，建议显式限制大小。 +- 不适合需要持久化的数据。 +- `tmpfs` 不适合多个容器共享同一份数据，也不适合当作跨重启的缓存层。 +- 在内存压力较高时，部分数据可能受系统交换机制影响，因此不要把 `tmpfs` 当作绝对不会落盘的安全边界。 + +### 8.3.4 与 Volume / Bind Mount 对比 + +| 类型 | 数据位置 | 持久化 | 典型用途 | +|------|---------|-------|---------| +| Volume | Docker 管理目录 | 是 | 数据库、长期业务数据 | +| Bind Mount | 宿主机指定目录 | 是 | 开发联调、配置文件共享 | +| tmpfs | 内存 | 否 | 高速临时数据、敏感临时文件 | diff --git a/08_data/README.md b/08_data/README.md new file mode 100644 index 000000000..5d222cc3b --- /dev/null +++ b/08_data/README.md @@ -0,0 +1,15 @@ +# 第八章 数据管理 + +如图 8-1 所示，Docker 数据管理主要围绕三类挂载方式展开。 + +
+ 
+
172.18.0.2"] -- "DNS: 'db' → 172.18.0.3" --> DB["db
172.18.0.3"] + end +``` + +### 9.3.5 常用网络命令 + +以下是 Docker 网络管理中常用的命令： + +```bash +## 列出网络 + +$ docker network ls + +## 创建网络 + +$ docker network create mynet + +## 查看网络详情 + +$ docker network inspect mynet + +## 连接容器到网络 + +$ docker network connect mynet mycontainer + +## 断开网络连接 + +$ docker network disconnect mynet mycontainer + +## 删除网络 + +$ docker network rm mynet + +## 清理未使用的网络 + +$ docker network prune +``` +--- + +> **🔥 踩坑实录** +> +> 一个新手开发者通过 `docker compose` 部署了两个容器化服务：服务 A 和服务 B。他在服务 A 的代码中尝试用 `localhost:3000` 访问服务 B，结果始终连接超时。这个错误非常隐蔽——在本地单机开发时看不出问题，因为他可能在同一个进程中测试。排查时他错误地认为是防火墙或网络配置问题。实际原因是：每个容器都有独立的网络命名空间，`localhost` 在容器内部只指向容器自己，不是宿主机也不是其他容器。正确的做法是使用 Compose 自动创建的服务名作为主机名：`http://service-b:3000`。Compose 会自动在网络中注册服务名的 DNS，这样容器间通信才能正确解析。改动仅需一行代码，问题随之消失。 diff --git a/09_network/9.4_container_linking.md b/09_network/9.4_container_linking.md new file mode 100644 index 000000000..59344e720 --- /dev/null +++ b/09_network/9.4_container_linking.md @@ -0,0 +1,61 @@ +## 9.4 容器互联 + +容器之间的网络通信是 Docker 网络的核心功能之一。本节介绍容器互联的几种方式。 + +### 9.4.1 同一网络内的容器 + +同一自定义网络内的容器可以直接通过容器名通信，这是推荐的容器互联方式： + +```bash +## 创建网络 + +$ docker network create app-net + +## 启动应用和数据库 + +$ docker run -d --name redis --network app-net redis +$ docker run -d --name app --network app-net myapp + +## app 容器中可以用 redis:6379 连接 Redis + +... +``` + +### 9.4.2 连接到多个网络 + +一个容器可以同时连接到多个网络，这对于需要跨网络通信的中间件容器特别有用： + +```bash +## 启动容器 + +$ docker run -d --name multi-net-container --network frontend nginx + +## 再连接到另一个网络 + +$ docker network connect backend multi-net-container + +## 查看容器的网络 + +$ docker inspect multi-net-container --format '{{json .NetworkSettings.Networks}}' +``` + +### 9.4.3 ⚠️ --link 已废弃 + +`--link` 是 Docker 早期用于容器互联的方式，**已经被废弃**，不建议在新项目中使用。请使用自定义网络替代： + +```bash +## 旧方式（不推荐） + +$ docker run --link db:database myapp + +## 新方式（推荐） + +$ docker network create mynet +$ docker run --network mynet --name db postgres +$ docker run --network mynet --name app myapp +``` +使用自定义网络的优势在于： + +- 原生支持 DNS 解析 +- 不需要在容器启动时显式声明依赖 +- 更灵活，可以动态 connect/disconnect diff --git a/09_network/9.5_port_mapping.md b/09_network/9.5_port_mapping.md new file mode 100644 index 000000000..e9d35848e --- /dev/null +++ b/09_network/9.5_port_mapping.md @@ -0,0 +1,138 @@ +## 9.5 外部访问容器 + +容器运行在自己的隔离网络环境中（通常是 Bridge 模式）。为了让外部网络访问容器内的服务，我们需要将容器的端口映射到宿主机的端口。 + +### 9.5.1 为什么要映射端口 + +容器的网络访问规则如下： + +- **容器之间**：可以通过 IP 或容器名（自定义网络）互通。 +- **宿主机访问容器**：原生 Linux 环境下可按网络配置访问容器 IP；Docker Desktop 上不能依赖容器 IP，应通过端口映射、容器名（容器间）或 `host.docker.internal` 等机制访问。 +- **外部网络访问容器**：❌ 默认无法直接访问。 + +为了让外部（如你的浏览器、其他局域网机器）访问容器内的服务，我们需要将容器的端口 **映射** 到宿主机的端口。 + +```mermaid +flowchart TD + User["外部用户 (Browser)"] --> Host["宿主机 (localhost:8080)"] + Host --> Proxy["Docker Proxy
端口映射 (8080 -> 80)"] + Proxy --> Container["容器 (端口: 80)"] +``` +--- + +### 9.5.2 端口映射方式 + +Docker 提供了多种方式来指定端口映射。 + +#### 1. 指定映射 + +使用 `-p <宿主机端口>:<容器端口>` 格式： + +```bash +## 将宿主机的 8080 端口映射到容器的 80 端口 + +$ docker run -d -p 8080:80 nginx +``` +此时访问 `http://localhost:8080` 即可看到 Nginx 页面。 + +**多种格式**： + +| 格式 | 含义 | 示例 | +|------|------|------| +| `ip:hostPort:containerPort` | 绑定指定 IP 的特定端口 | `-p 127.0.0.1:8080:80`（仅 IPv4 本机访问）| +| `ip::containerPort` | 绑定指定 IP 的随机端口 | `-p 127.0.0.1::80` | +| `hostPort:containerPort` | 绑定所有地址（通常包括 `0.0.0.0` 和 `[::]`）的特定端口 | `-p 8080:80`（默认）| +| `containerPort` | 绑定所有地址的随机端口 | `-p 80` | + +#### 2. 随机映射 + +如果不关心宿主机使用哪个端口，可以使用随机映射。使用 `-P`（大写）参数，Docker 会把 Dockerfile 中 `EXPOSE` 指令暴露的所有端口发布到宿主机的随机高位端口。具体落在哪个端口，取决于宿主机当前可用的临时端口范围。 + +```bash +$ docker run -d -P nginx +``` +查看映射结果： + +```bash +$ docker ps +CONTAINER ID PORTS +abc123456 0.0.0.0:49153->80/tcp +``` +此时 Nginx 被映射到了宿主机的一个随机高位端口，例如 `49153`。 + +--- + +### 9.5.3 查看端口映射 + +可以使用以下命令查看容器的端口映射： + +#### docker port + +运行 `docker port` 可以查看到指定容器的端口映射情况： + +```bash +$ docker port mycontainer +80/tcp -> 0.0.0.0:8080 +80/tcp -> [::]:8080 +``` + +#### docker ps + +运行 `docker ps` 可以查看到所有容器的端口映射列表： + +```bash +$ docker ps +CONTAINER ID IMAGE PORTS NAMES +abc123456 nginx 0.0.0.0:8080->80/tcp web +``` +--- + +### 9.5.4 最佳实践与安全 + +在配置端口映射时，需要注意以下安全事项： + +#### 1. 限制监听 IP + +默认情况下，`-p 8080:80` 会监听所有可用地址，常见输出包括 `0.0.0.0:8080` 和 `[::]:8080`。这意味着任何人只要能连接你的宿主机 IP，就能访问该服务。 + +如果不希望对外暴露（例如数据库服务），应绑定到回环地址。IPv4 使用 `127.0.0.1`，IPv6 使用 `[::1]`： + +```bash +## 仅允许本机访问 + +$ docker run -d -p 127.0.0.1:3306:3306 mysql +$ docker run -d -p '[::1]:3306:3306' mysql +``` + +#### 2. 避免端口冲突 + +如果宿主机 8080 已经被占用了，容器将无法启动。 + +**解决**： + +- 更换宿主机端口：`-p 8081:80` +- 让 Docker 自动分配：`-p 80` + +#### 3. UDP 映射 + +默认是 TCP 协议。如果要映射 UDP 服务（如 DNS，Syslog）： + +```bash +$ docker run -d -p 53:53/udp dns-server +``` +--- + +### 9.5.5 实现原理 + +Docker 使用 `docker-proxy` 进程（用户态）或 `iptables` DNAT 规则（内核态）来实现端口转发。 + +当流量到达宿主机端口时，iptables 规则将其目标地址修改为容器 IP 并转发： + +```bash +## 简化的 iptables 逻辑 + +iptables -t nat -A DOCKER -p tcp --dport 8080 -j DNAT --to-destination 172.17.0.2:80 +``` +这也是为什么你在容器内部看到的访问来源 IP 通常是网关 IP（如 172.17.0.1），而不是真实的外部 Client IP（除非使用 host 网络模式）。 + +--- diff --git a/09_network/9.6_network_isolation.md b/09_network/9.6_network_isolation.md new file mode 100644 index 000000000..55bf97b51 --- /dev/null +++ b/09_network/9.6_network_isolation.md @@ -0,0 +1,79 @@ +## 9.6 网络隔离 + +Docker 网络提供了天然的隔离能力，不同网络之间的容器默认无法通信。这是 Docker 网络安全的重要基础。 + +### 9.6.1 网络隔离原理 + +不同网络之间默认隔离，容器只能与同一网络中的容器直接通信： + +```bash +## 创建两个网络 + +$ docker network create frontend +$ docker network create backend + +## 容器 A 在 frontend + +$ docker run -d --name web --network frontend nginx + +## 容器 B 在 backend + +$ docker run -d --name db --network backend postgres + +## web 无法直接访问 db（不同网络） + +$ docker exec web ping db +ping: db: Name or service not known +``` + +### 9.6.2 安全优势 + +这种隔离机制带来以下安全优势： + +| 场景 | 说明 | +|------|------| +| **前后端分离** | 前端容器无法直接访问数据库网络 | +| **微服务隔离** | 不同微服务组可以使用不同网络 | +| **多租户** | 不同租户的容器在不同网络中完全隔离 | +| **最小权限** | 容器只能访问必要的网络资源 | + +### 9.6.3 跨网络通信 + +如果确实需要某个容器跨网络通信，可以将其同时连接到多个网络： + +```bash +## 创建一个中间件容器，连接到两个网络 + +$ docker run -d --name api --network frontend myapi +$ docker network connect backend api + +## 现在 api 容器既可以访问 frontend 中的 web，也可以访问 backend 中的 db +``` +这种方式让你可以精确控制哪些容器可以跨网络通信，遵循最小权限原则。 + +### 9.6.4 典型网络架构 + +一个典型的多层应用网络架构如下： + +```mermaid +graph TD + subgraph FrontendNet ["frontend 网络"] + LB["负载均衡器"] + Web1["Web 服务器 1"] + Web2["Web 服务器 2"] + end + + subgraph BackendNet ["backend 网络"] + API["API 服务器"] + DB["数据库"] + Cache["Redis 缓存"] + end + + LB --> Web1 + LB --> Web2 + Web1 -.-> API + Web2 -.-> API + API --> DB + API --> Cache +``` +在这种架构中，API 服务器同时连接到 `frontend` 和 `backend` 网络，充当两个网络之间的桥梁。负载均衡器和 Web 服务器无法直接访问数据库，增强了安全性。 diff --git a/09_network/9.7_advanced_networking.md b/09_network/9.7_advanced_networking.md new file mode 100644 index 000000000..99d8f8fa3 --- /dev/null +++ b/09_network/9.7_advanced_networking.md @@ -0,0 +1,211 @@ +## 9.7 容器网络高级特性 + +本节聚焦 Docker 自身可见的高级网络能力：Overlay 网络、服务发现和 DNS 解析。更偏 Kubernetes 编排网络的概念，如 CNI 和 NetworkPolicy，不在本章展开。 + +### 9.7.1 Overlay 网络原理与配置 + +Overlay 网络在现有网络基础上建立虚拟网络，允许容器跨宿主机通信。它是 Swarm 场景下的核心网络驱动之一。 + +#### Overlay 网络工作原理 + +Overlay 网络通过隧道封装技术（通常是 VXLAN）将容器网络流量封装在宿主机物理网络的 UDP 数据包中传输。Docker overlay 网络默认使用 `4789/udp` 作为数据通道端口，同时 Swarm 控制面与节点通信还需要相应开放 `2377/tcp`、`7946/tcp` 和 `7946/udp`。 + +```text +容器 A (192.168.0.2) + ↓ +veth 对 + ↓ +br-net (网桥) + ↓ +Docker 引擎 (VXLAN 封装) + ↓ +物理网络 (172.16.0.0/24) + ↓ +Docker 引擎 (VXLAN 解封装) + ↓ +br-net (网桥) + ↓ +veth 对 + ↓ +容器 B (192.168.0.3，不同宿主机) +``` + +#### 创建和使用 Overlay 网络 + +Overlay 网络依赖 Swarm。若要让独立容器加入 overlay 网络，需要把网络创建为 `attachable`。 + +```bash +# 初始化 Swarm +docker swarm init + +# 创建 attachable overlay 网络 +docker network create --driver overlay \ + --attachable \ + --subnet 192.168.0.0/24 \ + --opt com.docker.network.driver.mtu=1450 \ + my-overlay-net + +# 验证网络创建 +docker network ls +docker network inspect my-overlay-net + +# 在 Swarm 服务中使用 overlay 网络 +docker service create --name web \ + --network my-overlay-net \ + --replicas 3 \ + nginx # 确保与环境兼容的 Nginx 版本 + +# 单机环境下也可以让普通容器加入 attachable overlay 网络 +docker run -d --name container1 --network my-overlay-net busybox sleep 1d +docker run -d --name container2 --network my-overlay-net busybox sleep 1d + +# 测试跨容器通信 +docker exec container1 ping -c 1 container2 +``` + +#### Overlay 网络性能优化 + +```bash +# 调整 MTU（Maximum Transmission Unit）避免分片 +# VXLAN 开销 50 字节，物理 MTU 1500 时建议设置为 1450 +docker network create --driver overlay \ + --attachable \ + --opt com.docker.network.driver.mtu=1450 \ + optimized-overlay + +# 启用 IP 地址管理（IPAM）自定义 +docker network create --driver overlay \ + --attachable \ + --subnet 10.0.9.0/24 \ + --aux-address "my-router=10.0.9.2" \ + my-custom-overlay +``` + +### 9.7.2 容器 DNS 解析机制 + +Docker 内置 DNS 服务器，但 DNS 解析涉及多个层面的配置。 + +#### DNS 解析流程 + +```text +容器应用 (dig www.example.com) + ↓ +容器内 /etc/resolv.conf (127.0.0.11:53) + ↓ +Docker 内嵌 DNS 服务器 (127.0.0.11) + ↓ +用户自定义 DNS 或宿主机 /etc/resolv.conf + ↓ +外部 DNS 服务器 (8.8.8.8 等) + ↓ +DNS 响应 → 容器缓存 → 应用 +``` + +#### 配置容器 DNS + +**在运行时指定 DNS：** + +```bash +# 单个容器 +docker run -d \ + --dns 8.8.8.8 \ + --dns 1.1.1.1 \ + --dns-search example.com \ + nginx # 确保与环境兼容的 Nginx 版本 + +# DNS 选项 +docker run -d \ + --dns-option ndots:2 \ + --dns-option timeout:1 \ + --dns-option attempts:3 \ + nginx # 确保与环境兼容的 Nginx 版本 + +# 查看容器 DNS 配置 +docker exec
192.168.1.100] + docker0[docker0 网桥
172.17.0.1] + + subgraph Containers + subgraph ContainerA [容器 A] + eth0_A[eth0
172.17.0.2] + end + subgraph ContainerB [容器 B] + eth0_B[eth0
172.17.0.3] + end + end + + eth0 <--> docker0 + docker0 <--> eth0_A + docker0 <--> eth0_B + end + + Internet((互联网)) <--> eth0 +``` +本章将详细介绍 Docker 网络配置的各个方面。 + +## 本章内容 + +* [配置 DNS](9.1_dns.md) +* [网络类型](9.2_network_types.md) +* [自定义网络](9.3_custom_network.md) +* [容器互联](9.4_container_linking.md) +* [外部访问容器](9.5_port_mapping.md) +* [网络隔离](9.6_network_isolation.md) +* [高级网络配置](9.7_advanced_networking.md) diff --git a/09_network/summary.md b/09_network/summary.md new file mode 100644 index 000000000..d7a4ac9cf --- /dev/null +++ b/09_network/summary.md @@ -0,0 +1,27 @@ +## 本章小结 + +本章介绍了 Docker 网络配置的各个方面： + +| 概念 | 要点 | +|------|------| +| **DNS 配置** | 自定义网络支持嵌入式 DNS，可通过容器名解析 | +| **网络类型** | bridge（默认）、host、none、overlay、macvlan | +| **自定义网络** | 推荐使用，支持容器名 DNS 解析和更好的隔离 | +| **容器互联** | 同一自定义网络内容器可直接通过容器名通信 | +| **端口映射** | `-p 宿主机端口:容器端口` 暴露服务到外部 | +| **网络隔离** | 不同网络默认隔离，增强安全性 | +| **--link** | 已废弃，使用自定义网络替代 | + +### 延伸阅读 + +- [配置 DNS](9.1_dns.md)：自定义 DNS 设置 +- [网络类型](9.2_network_types.md)：Bridge、Host、None 等网络模式 +- [自定义网络](9.3_custom_network.md)：创建和管理自定义网络 +- [容器互联](9.4_container_linking.md)：容器间通信方式 +- [端口映射](9.5_port_mapping.md)：高级端口配置 +- [网络隔离](9.6_network_isolation.md)：网络安全与隔离策略 +- [EXPOSE 指令](../07_dockerfile/7.9_expose.md)：在 Dockerfile 中声明端口 +- [Compose 网络](../11_compose/11.5_compose_file.md)：Compose 中的网络配置 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/10_buildx/10.1_buildkit.md b/10_buildx/10.1_buildkit.md new file mode 100644 index 000000000..0c25dc9bf --- /dev/null +++ b/10_buildx/10.1_buildkit.md @@ -0,0 +1,154 @@ +## 10.1 BuildKit + +**BuildKit** 是下一代的镜像构建组件，在 [moby/buildkit](https://github.com/moby/buildkit) 开源。 + +> **重要**：自 Docker 23 起，BuildKit 已成为 **默认稳定构建器**，无需手动启用。Docker Engine 29 在新安装场景中进一步将 containerd image store 设为默认，提升多平台镜像、SBOM/Provenance 等 OCI 元数据能力。 + +目前，Docker Hub 自动构建已经支持 BuildKit，具体请参考 [docker-practice/docker-hub-buildx](https://github.com/docker-practice/docker-hub-buildx)。 + +### 10.1.1 `Dockerfile` 新增指令详解 + +BuildKit 引入了多项新指令，旨在优化构建缓存和安全性。以下将详细介绍这些指令的用法。 + +使用 BuildKit 后，我们可以使用下面几个新的 `Dockerfile` 指令来加快镜像构建。 + +要使用最新的 Dockerfile 语法特性，建议在 Dockerfile 开头添加语法指令： + +```docker +# syntax=docker/dockerfile:1 + +``` +这将使用最新的稳定版语法解析器，确保你可以使用所有最新特性。 + +#### `RUN --mount=type=cache` + +目前，几乎所有的程序都会使用依赖管理工具，例如 `Go` 中的 `go mod`、`Node.js` 中的 `npm` 等等，当我们构建一个镜像时，往往会重复的从互联网中获取依赖包，难以缓存，大大降低了镜像的构建效率。 + +例如一个前端工程需要用到 `npm`： + +```docker +FROM node:alpine AS builder + +WORKDIR /app + +COPY package.json /app/ + +RUN npm i --registry=https://registry.npmmirror.com \ + && rm -rf ~/.npm + +COPY src /app/src + +RUN npm run build + +FROM nginx:alpine + +COPY --from=builder /app/dist /app/dist +``` +使用多阶段构建，构建的镜像中只包含了目标文件夹 `dist`，但仍然存在一些问题，当 `package.json` 文件变动时，`RUN npm i && rm -rf ~/.npm` 这一层会重新执行，变更多次后，生成了大量的中间层镜像。 + +为解决这个问题，可以把包管理器的下载缓存挂载到构建步骤中，例如 npm 的 `/root/.npm`。注意：`type=cache` 只能作为性能优化，不能成为构建正确性的前提。缓存目录可能被并发构建改写，也可能被 GC 清理，所以不要把 `node_modules`、编译产物等必须存在的内容只放在 cache mount 里。 + +`BuildKit` 提供了 `RUN --mount=type=cache` 指令，可以实现上边的设想。 + +```docker +# syntax=docker/dockerfile:1 + +FROM node:alpine AS builder + +WORKDIR /app + +COPY package.json /app/ + +RUN --mount=type=cache,target=/root/.npm,id=npm_cache \ + npm install --registry=https://registry.npmmirror.com + +COPY src /app/src + +RUN npm run build + +FROM nginx:alpine + +COPY --from=builder /app/dist /app/dist +``` + +第一个 `RUN` 指令执行后，`id` 为 `npm_cache` 的缓存文件夹挂载到了 `/root/.npm`，后续构建可复用下载缓存。 + +第二个 `RUN` 指令执行时，`node_modules` 已经作为上一层真实写入到 builder 阶段的文件系统中，构建不依赖缓存目录内容。 + +最后使用 `COPY --from=builder` 将上一阶段产生的文件复制到最终镜像。跨阶段复制构建产物应使用 `COPY --from`；如果只是临时读取上一阶段文件，可使用 `RUN --mount=type=bind,from=builder,source=/app/dist,target=/tmp/dist,ro`。 + +上面的 `Dockerfile` 中 `--mount=type=cache,...` 中指令作用如下： + +|Option |Description| +|---------------------|-----------| +|`id` | `id` 设置一个标志，以便区分缓存。| +|`target`（必填项） | 缓存的挂载目标文件夹。| +|`ro`,`readonly` | 只读，缓存文件夹不能被写入。 | +|`sharing` | 有 `shared` `private` `locked` 值可供选择。`sharing` 设置当一个缓存被多次使用时的表现，由于 `BuildKit` 支持并行构建，当多个步骤使用同一缓存时（同一 `id`）会发生冲突。`shared` 表示多个步骤可以同时读写，`private` 表示当多个步骤使用同一缓存时，每个步骤使用不同的缓存，`locked` 表示当一个步骤完成释放缓存后，后一个步骤才能继续使用该缓存。| +|`from` | 缓存来源（构建阶段），不填写时为空文件夹。| +|`source` | 来源的文件夹路径。| + +#### `RUN --mount=type=bind` + +该指令可以将一个镜像（或上一构建阶段）的文件挂载到指定位置。 + +```docker +# syntax=docker/dockerfile:1 + +RUN --mount=type=bind,from=php:alpine,source=/usr/local/bin/docker-php-entrypoint,target=/docker-php-entrypoint \ + cat /docker-php-entrypoint +``` + +#### `RUN --mount=type=tmpfs` + +该指令可以将一个 `tmpfs` 文件系统挂载到指定位置。 + +```docker +# syntax=docker/dockerfile:1 + +RUN --mount=type=tmpfs,target=/temp \ + mount | grep /temp +``` + +#### `RUN --mount=type=secret` + +该指令可以将一个文件（例如密钥）挂载到指定位置。 + +```docker +# syntax=docker/dockerfile:1 + +RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \ + test -s /root/.aws/credentials && echo "credentials mounted" +``` +```bash +$ docker build -t test --secret id=aws,src=$HOME/.aws/credentials . +``` + +#### `RUN --mount=type=ssh` + +该指令可以挂载 `ssh` 密钥。 + +```docker +# syntax=docker/dockerfile:1 + +FROM alpine +RUN apk add --no-cache openssh-client +RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts +RUN --mount=type=ssh ssh git@gitlab.com | tee /hello +``` +```bash +$ eval $(ssh-agent) +$ ssh-add ~/.ssh/id_rsa +(Input your passphrase here) +$ docker build -t test --ssh default=$SSH_AUTH_SOCK . +``` + +### 10.1.2 使用 `docker compose build` 与 BuildKit + +Docker Compose 同样支持 BuildKit，这使得多服务应用的构建更加高效。 + +自 Docker 23 起，BuildKit 已默认启用，无需额外配置。如果使用旧版本，可设置 `DOCKER_BUILDKIT=1` 环境变量启用。 + +### 10.1.3 官方文档 + +* https://docs.docker.com/reference/dockerfile/ diff --git a/10_buildx/10.2_buildx.md b/10_buildx/10.2_buildx.md new file mode 100644 index 000000000..fa3117689 --- /dev/null +++ b/10_buildx/10.2_buildx.md @@ -0,0 +1,61 @@ +## 10.2 使用 buildx 构建镜像 + +### 10.2.1 使用 + +Buildx 的使用非常直观，绝大多数情况下可以替代 `docker build` 命令。 + +你可以直接使用 `docker buildx build` 命令构建镜像。 + +```bash +$ docker buildx build . +[+] Building 8.4s (23/32) + => ... +``` +Buildx 使用 [BuildKit 引擎](10.1_buildkit.md)进行构建，支持许多新的功能，具体参考 [Buildkit](10.1_buildkit.md) 一节。 + +需要注意的是，默认 `docker` driver 会把构建结果加载到本地镜像存储；使用 `docker-container`、remote、cloud 等 builder 时，如未指定 `--load`、`--push` 或 `--output`，结果通常只保留在构建缓存中。 + +#### 构建前检查 + +Buildx 0.15 起支持构建检查：常规构建会默认检查 Dockerfile 与构建参数；如果只想做检查而不真正构建，可以使用 `--check`： + +```bash +$ docker buildx build --check . +``` +这适合作为 CI 的快速门禁：普通构建中的检查告警默认不会让构建失败，但 `--check` 发现问题会以非零状态退出；需要把告警提升为错误时，可在 Dockerfile 顶部配合 `# check=error=true`。 + +#### 使用 `bake` + +`docker buildx bake` 是一个高级构建命令，支持从 HCL、JSON 或 Compose 文件中定义构建目标，实现复杂的流水线构建。 + +```bash +## 从 Compose 文件构建所有服务 + +$ docker buildx bake + +## 仅构建指定目标 + +$ docker buildx bake web +``` + +#### 生成 SBOM + +Buildx 支持在构建时直接生成 SBOM (Software Bill of Materials)，这对于软件供应链安全至关重要。 + +```bash +$ docker buildx build --sbom=true -t myimage . +``` +该命令会把 SBOM 作为构建 attestation 附加到构建结果中；BuildKit 默认使用 SPDX SBOM attestation。需要 CycloneDX 文件时，可使用 Syft、Docker Scout 等工具另行生成或转换。 + +> **⚠️ 注意与失败模式**： +> 要使 SBOM（或其他 attestation 元数据）成功附着并可见，对底层的存储格式有前置要求：默认的 classic image store 不支持 manifest list/index 这种存放 attestation 的结构。 +> +> 如果只简单运行上述命令，你可能会面临 **“命令成功执行，但本地镜像中看不到 SBOM”** 的体会落差。 +> +> **正确的解决路径有两条**： +> 1. **推送到远端仓库**：使用 `docker buildx build --sbom=true --push -t myimage:tag` 时，SBOM 会正确保存到远端仓库。远端 OCI 兼容的镜像仓库能够完整存储这些元数据。 +> 2. **启用 containerd image store**：在 Docker 守护进程中启用 `containerd image store` 特性（Docker 29+，新安装场景默认启用，Docker Desktop 上也更容易直接使用），可以在本地查看和管理 SBOM 等 attestation 元数据。 + +### 10.2.2 官方文档 + +* [Docker buildx 命令文档](https://docs.docker.com/reference/cli/docker/buildx/) diff --git a/10_buildx/10.3_multi-arch-images.md b/10_buildx/10.3_multi-arch-images.md new file mode 100644 index 000000000..2cb3da827 --- /dev/null +++ b/10_buildx/10.3_multi-arch-images.md @@ -0,0 +1,129 @@ +## 10.3 使用 buildx 构建多种系统架构支持的 Docker 镜像 + +Docker 镜像可以支持多种系统架构，这意味着你可以在 `x86_64`、`arm64` 等不同架构的机器上运行同一个镜像。这是通过一个名为 “manifest list”（或称为 “fat manifest”）的文件来实现的。 + +### 10.3.1 Manifest List 是什么？ + +为了理解多架构镜像的原理，我们需要先了解 Manifest List 的概念。 + +Manifest list 是一个包含了多个指向不同架构镜像的 manifest 的文件。当你拉取一个支持多架构的镜像时，Docker 会自动根据你当前的系统架构选择并拉取对应的镜像。 + +例如，官方的 `hello-world` 镜像就支持多种架构。你可以使用 `docker manifest inspect` 命令来查看它的 manifest list： + +```bash +$ docker manifest inspect hello-world +{ + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 525, + "digest": "sha256:80852a401a974d9e923719a948cc5335a0a4435be8778b475844a7153a2382e5", + "platform": { + "architecture": "amd64", + "os": "linux" + } + }, + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 525, + "digest": "sha256:3adea81344be1724b383d501736c3852939b33b3903d02474373700b25e5d6e3", + "platform": { + "architecture": "arm", + "os": "linux", + "variant": "v5" + } + }, + // ... more architectures + ] +} +``` + +### 10.3.2 使用 `docker buildx` 构建多架构镜像 + +`docker buildx` 是构建多架构镜像的最佳实践工具，它屏蔽了底层的复杂性，提供了一键构建多架构镜像的能力。 + +在 Docker 19.03+ 版本中，`docker buildx` 是推荐的用于构建多架构镜像的工具。它使用 `BuildKit` 作为后端，可以大大简化构建过程（Docker 23+ 默认启用 BuildKit）。 + +#### 新建 `builder` 实例 + +首先，你需要创建一个新的 `builder` 实例，因为它支持同时为多个平台构建。 + +```bash +$ docker buildx create --name mybuilder --use +$ docker buildx inspect --bootstrap +``` + +#### 构建和推送 + +使用 `docker buildx build` 命令并指定 `--platform` 参数，可以同时构建支持多种架构的镜像。`--push` 参数会将构建好的镜像和 manifest list 推送到 Docker 仓库。 + +```dockerfile +## Dockerfile + +FROM --platform=$TARGETPLATFORM alpine + +RUN uname -a > /os.txt + +CMD cat /os.txt +``` +```bash +$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t your-username/multi-arch-image . --push +``` +构建完成后，你就可以在不同架构的机器上拉取并运行 `your-username/multi-arch-image` 这个镜像了。 + +#### 架构相关的构建参数 + +在 `Dockerfile` 中，你可以使用一些预定义的构建参数来根据目标平台定制构建过程： + +* `TARGETPLATFORM`：构建镜像的目标平台，例如 `linux/amd64`。 +* `TARGETOS`：目标平台的操作系统，例如 `linux`。 +* `TARGETARCH`：目标平台的架构，例如 `amd64`。 +* `TARGETVARIANT`：目标平台的变种，例如 `v7`。 +* `BUILDPLATFORM`：构建环境的平台。 +* `BUILDOS`：构建环境的操作系统。 +* `BUILDARCH`：构建环境的架构。 +* `BUILDVARIANT`：构建环境的变种。 + +例如，你可以这样编写 `Dockerfile` 来拷贝特定架构的二进制文件： + +```dockerfile +FROM scratch + +ARG TARGETOS +ARG TARGETARCH + +COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist + +ENTRYPOINT ["/dist"] +``` + +### 10.3.3 使用 `docker manifest`：底层工具 + +除了 `docker buildx`，我们也可以直接操作 Manifest List 来手动组合不同架构的镜像。 + +`docker manifest` 是一个更底层的命令，可以用来创建、检查和推送 manifest list。虽然 `docker buildx` 在大多数情况下更方便，但了解 `docker manifest` 仍然有助于理解其工作原理。 + +#### 创建 manifest list + +```bash +## 首先，为每个架构构建并推送镜像 + +$ docker buildx build --platform linux/amd64 -t your-username/my-app:amd64 . --push +$ docker buildx build --platform linux/arm64 -t your-username/my-app:arm64 . --push + +## 然后，创建一个 manifest list，将它们组合在一起 + +$ docker manifest create your-username/my-app:latest \ + your-username/my-app:amd64 \ + your-username/my-app:arm64 + +## 最后，推送 manifest list + +$ docker manifest push your-username/my-app:latest +``` + +#### 检查 manifest list + +你可以使用 `docker manifest inspect` 来查看一个 manifest list 的详细信息，如上文所示。 diff --git a/10_buildx/README.md b/10_buildx/README.md new file mode 100644 index 000000000..f6c5394fa --- /dev/null +++ b/10_buildx/README.md @@ -0,0 +1,16 @@ +# 第十章 Docker Buildx + +Docker Buildx 是一个 docker CLI 插件，其扩展了 docker 命令，支持 [Moby BuildKit](10.1_buildkit.md) 提供的功能。提供了与 docker build 相同的用户体验，并增加了许多新功能。 + +> Buildx 需要 Docker v23.0+（该版本起 BuildKit 成为默认构建引擎）。推荐使用 Docker v29 及以上版本以获得最完整的 Buildx 功能支持。 + +## 本章内容 + +本章将详细介绍 Docker Buildx 的使用，包括： + +* [使用 BuildKit 构建镜像](10.1_buildkit.md) +* [使用 Buildx 构建镜像](10.2_buildx.md) +* [构建多种系统架构支持的 Docker 镜像](10.3_multi-arch-images.md) + +> **供应链安全与存储后端前瞻**：现代软件供应链中，镜像来源证明（Provenance，在 BuildKit 中默认以 `mode=min` 添加）和软件物料清单（SBOM，可通过 `--sbom=true` 显式开启）已经成为极其重要的构建产出。这些 Attestations 数据会作为 manifest 附着在 **镜像索引 (Image Index)** 上。 +> 正是基于此诉求，自 Docker Engine 29 起在**新安装场景**默认启用的 `containerd image store` 提供对 Image Index 的完美本地支持能力，解决了传统经典存储后端（Classic Store）无法有效处理带 Attestations 镜像索引的瓶颈。这使得你可以利用 `docker buildx imagetools inspect` 等手段，甚至做到无需拉取完整镜像内容即可在 Registry 或本地高效校验镜像的安全元数据。 diff --git a/10_buildx/summary.md b/10_buildx/summary.md new file mode 100644 index 000000000..cbd5b4d1d --- /dev/null +++ b/10_buildx/summary.md @@ -0,0 +1,23 @@ +## 本章小结 + +Docker Buildx 是 Docker 构建系统的重要进化，提供了高效、安全且支持多平台的镜像构建能力。 + +| 概念 | 要点 | +|------|------| +| **BuildKit** | 下一代构建引擎，Docker 23+ 默认启用 | +| **缓存挂载** | `RUN --mount=type=cache` 加速依赖安装 | +| **Secret 挂载** | `RUN --mount=type=secret` 安全传递密钥 | +| **buildx build** | 替代 `docker build`，支持更多构建功能 | +| **构建检查** | `--check` 可在不执行构建的情况下检查 Dockerfile 与构建参数 | +| **多架构构建** | `--platform` 参数一键构建多种架构镜像 | +| **Manifest List** | 多架构镜像的索引文件 | +| **SBOM** | 通过 `--sbom=true` 生成软件物料清单 | + +### 延伸阅读 + +- [Dockerfile 指令详解](../07_dockerfile/README.md)：Dockerfile 编写基础 +- [多阶段构建](../07_dockerfile/7.17_multistage_builds.md)：优化镜像体积 +- [Dockerfile 最佳实践](../appendix/best_practices.md)：编写高效 Dockerfile +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/11_compose/11.1_introduction.md b/11_compose/11.1_introduction.md new file mode 100644 index 000000000..a6099b15c --- /dev/null +++ b/11_compose/11.1_introduction.md @@ -0,0 +1,39 @@ +## 11.1 简介 + +`Compose` 项目是 Docker 官方的开源项目，负责实现对 Docker 容器的快速编排。从功能上看，跟 `OpenStack` 中的 `Heat` 十分类似。 + +其代码目前在 [docker/compose 仓库](https://github.com/docker/compose) 上开源。 + +`Compose` 定位是 “定义和运行多个 Docker 容器的应用 (Defining and running multi-container Docker applications)”，其前身是开源项目 Fig。 + +通过第一部分中的介绍，我们知道使用一个 `Dockerfile` 模板文件，可以让用户很方便的定义一个单独的应用容器。然而，在日常工作中，经常会碰到需要多个容器相互配合来完成某项任务的情况。例如要实现一个 Web 项目，除了 Web 服务容器本身，往往还需要再加上后端的数据库服务容器，甚至还包括负载均衡容器等。 + +`Compose` 恰好满足了这样的需求。它允许用户通过一个单独的 `compose.yaml`（历史默认名也常见为 `docker-compose.yml`）模板文件（YAML 格式）来定义一组相关联的应用容器为一个项目 (project)。 + +### 11.1.1 概述 + +Docker Compose 让用户能够以声明式方式定义和管理多容器应用。它的核心价值在于：用一个 YAML 文件取代一连串手动的 `docker run` 命令，使得复杂应用的启动、停止和重建变得一键可达。 + +对于开发团队而言，Compose 解决了三个关键问题：环境一致性（“在我机器上能跑”的问题）、服务依赖管理（确保数据库在应用之前启动）、以及开发-测试-生产的配置差异管理（通过 `compose.override.yaml` 实现多环境适配）。 + +### 11.1.2 模板文件规范 + +Compose 模板文件采用 YAML 格式，扩展名为 `.yml` 或 `.yaml`。 + +> **注意**：Compose Specification 的顶层 `version` 字段仅用于向后兼容，当前已标记为 obsolete。新文件建议直接省略该字段。 + +Docker Compose 默认使用 `compose.yaml`，也兼容 `compose.yml`、`docker-compose.yaml`、`docker-compose.yml` 等文件名。 + +`Compose` 中有两个重要的概念： + +* 服务 (`service`)：一个应用的容器，实际上可以包括若干运行相同镜像的容器实例。 + +* 项目 (`project`)：由一组关联的应用容器组成的一个完整业务单元，在 Compose 文件中定义。 + +`Compose` 的默认管理对象是项目，通过子命令对项目中的一组容器进行便捷地生命周期管理。 + +`Compose` 项目早期由 Python 编写，称为 Docker Compose V1。 + +现在的 Docker Compose V2 是一个 Go 语言编写的 Docker CLI 插件（当前版本号已演进至 v5.x 系列，以避免与旧 Compose 文件格式版本混淆）。Docker Desktop 默认包含它；在 Linux 上，也可以将它作为独立的 CLI 插件安装后直接通过 `docker compose` 命令使用。它提供了更快的性能和更好的集成体验。 + +只要所操作的平台支持 Docker API，就可以在其上利用 `Compose` 来进行编排管理。 diff --git a/11_compose/11.2_install.md b/11_compose/11.2_install.md new file mode 100644 index 000000000..d5dcff0c3 --- /dev/null +++ b/11_compose/11.2_install.md @@ -0,0 +1,50 @@ +## 11.2 安装与卸载 + +`Compose` 是 Docker 官方的开源项目，负责实现本地或单机多容器应用的快速编排。跨主机集群编排应使用 Swarm、Kubernetes 或云厂商托管服务。 + +当前的 Compose 以 `docker compose` 子命令的形式提供。Docker Desktop 在 macOS、Windows 和 Linux 上默认包含它；如果你已经在 Linux 上单独安装了 Docker Engine 和 Docker CLI，也可以再安装 Compose CLI 插件。 + +### 11.2.1 Linux + +在 Linux 上，默认建议通过 Docker 官方软件仓库安装 Compose CLI 插件，这样可以随系统包管理器更新。 + +Ubuntu / Debian： + +```bash +$ sudo apt-get update +$ sudo apt-get install docker-compose-plugin +``` + +Fedora / CentOS / RHEL 兼容发行版： + +```bash +$ sudo dnf install docker-compose-plugin +``` + +如果是离线环境、需要锁定特定版本，或包管理器暂不覆盖你的架构，可以从 Docker 官方发布页手工安装。手工安装不会自动更新；下载 URL 中的版本号和架构（如 `x86_64`、`aarch64`）需要按目标机器替换。 + +```bash +$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} +$ mkdir -p $DOCKER_CONFIG/cli-plugins +$ curl -SL https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose +$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose +``` + +### 11.2.2 测试安装 + +```bash +$ docker compose version +Docker Compose version v5.x.x +``` + +### 11.2.3 卸载 + +如果是仓库方式安装，使用包管理器卸载；如果是二进制包方式安装，删除二进制文件即可。 + +```bash +$ sudo apt-get remove docker-compose-plugin +# 或 +$ sudo dnf remove docker-compose-plugin + +$ rm $DOCKER_CONFIG/cli-plugins/docker-compose +``` diff --git a/11_compose/11.3_usage.md b/11_compose/11.3_usage.md new file mode 100644 index 000000000..f7173800b --- /dev/null +++ b/11_compose/11.3_usage.md @@ -0,0 +1,121 @@ +## 11.3 使用 + +本节将通过一个具体的 Web 应用案例，介绍 Docker Compose 的基本概念和常用操作。 + +### 11.3.1 术语 + +首先介绍几个术语。 + +* 服务 (`service`)：一个应用容器，实际上可以运行多个相同镜像的实例。 + +* 项目 (`project`)：由一组关联的应用容器组成的一个完整业务单元。 + +可见，一个项目可以由多个服务（容器）关联而成，`Compose` 面向项目进行管理。 + +### 11.3.2 准备示例 + +下面创建一个由 `web` 和 `redis` 组成的简单示例项目。 + +#### 应用代码 + +新建文件夹，在该目录中编写 `app.py` 文件 + +```python +from flask import Flask +from redis import Redis + +app = Flask(__name__) +redis = Redis(host='redis', port=6379) + +@app.route('/') +def hello(): + count = redis.incr('hits') + return 'Hello World! 该页面已被访问 {} 次。\n'.format(count) + +if __name__ == "__main__": + app.run(host="0.0.0.0", debug=True) +``` + +#### Dockerfile + +编写 `Dockerfile` 文件，内容为 + +```docker +FROM python:3.12-alpine +COPY . /code +WORKDIR /code +RUN pip install redis flask +CMD ["python", "app.py"] +``` + +#### compose.yaml + +编写 `compose.yaml` 文件，这是 Compose 推荐使用的主模板文件（也兼容 `docker-compose.yml` 等历史文件名）。 + +```yaml +services: + web: + build: . + ports: + - "5000:5000" + + redis: + image: "redis:alpine" +``` + +### 11.3.3 启动与验证 + +#### 启动项目 + +```bash +$ docker compose up +``` +此时访问本地 `5000` 端口，每次刷新页面，计数就会加 1。 + +按下 `Ctrl-C` 停止项目。 + +#### 后台运行与停止 + +```bash +$ docker compose up -d +$ docker compose stop +``` + +#### 查看日志 + +```bash +$ docker compose logs -f +``` + +#### 进入服务 + +```bash +$ docker compose exec redis sh +/data # redis-cli +127.0.0.1:6379> get hits +"9" +``` + +### 11.3.4 常用命令 + +#### 构建与重建 + +```bash +$ docker compose build +$ docker compose start +``` + +#### 运行一次性命令 + +```bash +$ docker compose run web python app.py +``` + +#### 验证与清理 + +```bash +$ docker compose config +$ docker compose down +``` + +> 💡 `docker compose down` 默认会删除容器和网络，但 **保留数据卷**。如需同时删除数据卷，请使用 `docker compose down -v`。 diff --git a/11_compose/11.4_commands.md b/11_compose/11.4_commands.md new file mode 100644 index 000000000..8a423e839 --- /dev/null +++ b/11_compose/11.4_commands.md @@ -0,0 +1,342 @@ +## 11.4 命令说明 + +Docker Compose 提供了丰富的命令来管理项目和容器。本节将详细介绍这些命令的使用格式和常用选项。 + +### 何时用哪个命令：场景化指南 + +在学习具体命令前，让我们从使用场景出发，这样可以帮助你更快地找到需要的命令： + +**项目启动与停止**： + +- `docker compose up`：第一次启动项目，拉取镜像、创建容器 +- `docker compose start`：启动已停止的容器（项目已存在） +- `docker compose stop`：优雅地停止容器（不删除容器） +- `docker compose down`：完全清理，删除容器和网络（开发时常用） + +**调试与查看**： + +- `docker compose ps`：查看项目中的容器状态 +- `docker compose logs`：查看容器日志（排查问题的第一步） +- `docker compose exec`：进入正在运行的容器执行命令 + +**构建与更新**： + +- `docker compose build`：重新构建镜像（修改 Dockerfile 后） +- `docker compose pull`：更新所有镜像到最新版本 + +**配置验证**： + +- `docker compose config`：验证 docker-compose.yml 格式是否正确 + +### 11.4.1 命令对象与格式 + +对于 Compose 来说，大部分命令的对象既可以是项目本身，也可以指定为项目中的服务或者容器。如果没有特别的说明，命令对象将是项目，这意味着项目中所有的服务都会受到命令影响。 + +执行 `docker compose [COMMAND] --help` 或者 `docker compose help [COMMAND]` 可以查看具体某个命令的使用格式。 + +`docker compose` 命令的基本的使用格式是 + +```bash +docker compose [-f=
应用"] + Port8000[":8000"] + Django ~~~ Port8000 + end + + subgraph DB ["db 服务"] + direction TB + Postgres["PostgreSQL
数据库"] + end + + Django -- ":5432" --> Postgres + end + + Browser["localhost:8000
（浏览器访问）"] + Port8000 --> Browser +``` +图 11-1：Django + PostgreSQL 的 Compose 架构 + +**关键点**： + +- `web` 服务运行 Django 应用，对外暴露 8000 端口 +- `db` 服务运行 PostgreSQL 数据库，只在内部网络可访问 +- 两个服务通过 Docker Compose 自动创建的网络相互通信 +- `web` 服务可以通过服务名 `db` 访问数据库（Docker 内置 DNS） + +### 11.6.2 准备工作 + +创建一个项目目录并进入： + +```bash +$ mkdir django-docker && cd django-docker +``` +我们需要创建三个文件：`Dockerfile`、`requirements.txt` 和 `compose.yaml`。 + +### 11.6.3 步骤 1：创建 Dockerfile + +```docker +FROM python:3.12-slim + +## 防止 Python 缓冲 stdout/stderr，让日志实时输出 + +ENV PYTHONUNBUFFERED=1 + +## 设置工作目录 + +WORKDIR /code + +## 先复制依赖文件，利用 Docker 缓存加速构建 + +COPY requirements.txt /code/ + +## 安装依赖 + +RUN pip install --no-cache-dir -r requirements.txt + +## 复制项目代码 + +COPY . /code/ +``` +**逐行解释**： + +| 指令 | 作用 | 为什么这样写 | +|------|------|-------------| +| `FROM python:3.12-slim` | 基础镜像 | `slim` 版本比完整版小很多，但包含运行 Python 所需的一切 | +| `ENV PYTHONUNBUFFERED=1` | 关闭输出缓冲 | 让 `print()` 和日志立即显示，便于调试 | +| `WORKDIR /code` | 设置工作目录 | 后续命令都在此目录执行 | +| `COPY requirements.txt` 在前 | 分层复制 | 只有 requirements.txt 变化时才重新安装依赖，加速构建 | +| `--no-cache-dir` | 不缓存 pip 下载 | 减小镜像体积 | + +> 💡 **笔者建议**：总是将变化频率低的文件先复制，变化频率高的后复制。这样可以最大化利用 Docker 的构建缓存。 + +### 11.6.4 步骤 2：创建 requirements.txt + +```txt +Django>=5.0,<6.0 +psycopg[binary]>=3.1,<4.0 +gunicorn>=21.0,<22.0 +``` +**依赖说明**： + +| 包名 | 作用 | +|------|------| +| `Django` | Web 框架 | +| `psycopg[binary]` | PostgreSQL 数据库驱动（推荐使用 psycopg 3）| +| `gunicorn` | 生产环境 WSGI 服务器（可选，开发时可不用）| + +### 11.6.5 步骤 3：创建 compose.yaml + +配置如下： + +```yaml +services: + db: + image: postgres:16 + environment: + POSTGRES_DB: django_db + POSTGRES_USER: django_user + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U django_user -d django_db"] + interval: 5s + timeout: 5s + retries: 5 + + web: + build: . + command: python manage.py runserver 0.0.0.0:8000 + volumes: + - .:/code + ports: + - "8000:8000" + depends_on: + db: + condition: service_healthy + environment: + # settings.py 直接读取 POSTGRES_PASSWORD，必须传入 web 容器 + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + DATABASE_URL: postgres://django_user:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/django_db + +volumes: + postgres_data: +``` +**配置详解**： + +#### db 服务 + +db 服务配置如下： + +```yaml +db: + image: postgres:16 # 使用官方 PostgreSQL 16 镜像 + environment: + POSTGRES_DB: django_db # 创建的数据库名 + POSTGRES_USER: django_user # 数据库用户 + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} # 数据库密码经环境变量注入，不写明文 + volumes: + - postgres_data:/var/lib/postgresql/data # 持久化数据 + healthcheck: # 健康检查，确保数据库就绪 + test: ["CMD-SHELL", "pg_isready -U django_user -d django_db"] + interval: 5s +``` +> ⚠️ **笔者提醒**：`volumes` 配置很重要！没有它，每次容器重启数据都会丢失。笔者见过不少新手因为忘记这一步，导致开发数据全部丢失。 + +#### web 服务 + +web 服务配置如下： + +```yaml +web: + build: . # 从当前目录的 Dockerfile 构建 + command: python manage.py runserver # 启动 Django 开发服务器 + volumes: + - .:/code # 挂载代码目录，支持热更新 + ports: + - "8000:8000" # 映射端口 + depends_on: + db: + condition: service_healthy # 等待数据库健康后再启动 +``` +**关键配置说明**： + +| 配置项 | 作用 | 笔者建议 | +|--------|------|---------| +| `volumes: .:/code` | 代码挂载 | 开发时必备，修改代码无需重新构建镜像 | +| `depends_on` + `healthcheck` | 启动顺序 | 确保数据库就绪后 Django 才启动，避免连接错误 | +| `environment` | 环境变量 | 推荐用环境变量管理配置，避免硬编码 | + +### 11.6.6 步骤 4：创建 Django 项目 + +运行以下命令创建新的 Django 项目： + +```bash +$ docker compose run --rm web django-admin startproject mysite . +``` +**命令解释**： + +- `docker compose run`：运行一次性命令 +- `--rm`：命令执行后删除临时容器 +- `web`：在 web 服务环境中执行 +- `django-admin startproject mysite .`：在当前目录创建 Django 项目 + +生成的目录结构： + +```bash +django-docker/ +├── compose.yaml +├── Dockerfile +├── requirements.txt +├── manage.py +└── mysite/ + ├── __init__.py + ├── settings.py + ├── urls.py + ├── asgi.py + └── wsgi.py +``` +> 💡 **Linux 用户注意**：如果遇到权限问题，执行 `sudo chown -R $USER:$USER .` + +### 11.6.7 步骤 5：配置数据库连接 + +修改 `mysite/settings.py`，配置数据库连接： + +```python +import os + +DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.postgresql', + 'NAME': os.environ.get('POSTGRES_DB', 'django_db'), + 'USER': os.environ.get('POSTGRES_USER', 'django_user'), + 'PASSWORD': os.environ['POSTGRES_PASSWORD'], + 'HOST': 'db', # Docker Compose 服务名 + 'PORT': 5432, + } +} + +## 允许的主机（开发环境） + +ALLOWED_HOSTS = ['*'] +``` + +生产环境优先使用 Docker Compose secrets 或外部密钥管理；即使是本地示例，也不要把固定密码写进 Compose 文件或 Django 默认值中。 + +**为什么 HOST 是 `db` 而不是 `localhost`？** + +在 Docker Compose 中，各服务通过服务名相互访问。Docker 内置的 DNS 会将 `db` 解析为 db 服务容器的 IP 地址。这是 Docker Compose 的核心功能之一。 + +### 11.6.8 步骤 6：启动应用 + +```bash +$ docker compose up +``` +你会看到： + +1. 首先构建 web 镜像（第一次运行） +2. 启动 db 服务，等待健康检查通过 +3. 启动 web 服务 + +```bash +db-1 | PostgreSQL init process complete; ready for start up. +db-1 | LOG: database system is ready to accept connections +web-1 | Watching for file changes with StatReloader +web-1 | Starting development server at http://0.0.0.0:8000/ +``` +打开浏览器访问 `http://localhost:8000`，可以看到 Django 欢迎页面！ + +### 11.6.9 常用开发命令 + +在另一个终端窗口执行： + +```bash +## 执行数据库迁移 + +$ docker compose exec web python manage.py migrate + +## 创建超级用户 + +$ docker compose exec web python manage.py createsuperuser + +## 进入 Django shell + +$ docker compose exec web python manage.py shell + +## 进入 PostgreSQL 命令行 + +$ docker compose exec db psql -U django_user -d django_db +``` +> 💡 笔者建议使用 `exec` 而不是 `run`。`exec` 在已运行的容器中执行命令，`run` 会创建新容器。 + +### 11.6.10 常见问题排查 + +#### Q1：数据库连接失败 + +**错误信息**：`django.db.utils.OperationalError: could not connect to server` **可能原因与解决方案**： + +| 原因 | 解决方案 | +|------|---------| +| 数据库还没启动完成 | 使用 `depends_on` + `healthcheck` | +| HOST 配置错误 | 确保使用服务名 `db` 而不是 `localhost` | +| 网络未创建 | 运行 `docker compose down` 后重新 `up` | + +```bash +## 调试：检查数据库是否正常运行 + +$ docker compose ps +$ docker compose logs db +``` + +#### Q2：代码修改没有生效 + +**可能原因**： + +1. **开发服务器没有自动重载**：确保使用 `runserver` 而不是 `gunicorn` +2. **Volume 挂载问题**：检查 `compose.yaml` 中的 volumes 配置 +3. **缓存问题**：尝试 `docker compose restart web` + +#### Q3：权限问题 + +```bash +## 如果容器内创建的文件 root 用户所有 + +$ sudo chown -R $USER:$USER . +``` + +### 11.6.11 开发 vs 生产：关键差异 + +笔者特别提醒，本节的配置是 **开发环境** 配置。生产环境需要以下调整： + +| 配置项 | 开发环境 | 生产环境 | +|--------|---------|---------| +| **Web 服务器** | `runserver` | `gunicorn` + Nginx | +| **DEBUG** | `True` | `False` | +| **密码管理** | 环境变量注入（如本节 `${POSTGRES_PASSWORD:?}`） | 使用 Docker Secrets 或外部密钥管理 | +| **Volume** | 挂载代码目录 | 代码直接 COPY 进镜像 | +| **ALLOWED_HOSTS** | `['*']` | 具体域名 | + +**生产环境 Compose 文件示例**： + +```yaml +## compose.prod.yaml + +services: + web: + build: . + command: gunicorn mysite.wsgi:application --bind 0.0.0.0:8000 + # 不挂载代码，使用镜像内的代码 + + environment: + DEBUG: 'False' + ALLOWED_HOSTS: 'example.com,www.example.com' + # ... + +``` + +### 11.6.12 延伸阅读 + +- [Compose 模板文件详解](11.5_compose_file.md)：深入理解 Compose 文件的所有配置项 +- [使用 WordPress](11.8_wordpress.md)：另一个 Compose 实战案例 +- [Dockerfile 最佳实践](../appendix/best_practices.md)：构建更小、更安全的镜像 +- [数据管理](../08_data/README.md)：Volume 和数据持久化详解 diff --git a/11_compose/11.7_rails.md b/11_compose/11.7_rails.md new file mode 100644 index 000000000..5acf6e261 --- /dev/null +++ b/11_compose/11.7_rails.md @@ -0,0 +1,290 @@ +## 11.7 实战 Rails + +> 本小节内容适合 Ruby 开发人员阅读。 + +> **版本说明**：本示例使用以下镜像版本： +> - Ruby：3.2（可替换为其他 3.x 版本） +> - PostgreSQL：16（可替换为其他 16.x、15.x 等版本） +> - Rails：~> 7.1（可根据项目需求调整） + +本节使用 Docker Compose 配置并运行一个 **Rails + PostgreSQL** 应用。 + +### 11.7.1 架构概览 + +如图 11-2 所示，Rails 与 PostgreSQL 在同一 Compose 网络中协同工作。 + +```mermaid +flowchart TD + subgraph Network ["Docker Compose 网络"] + direction LR + subgraph Web ["web 服务"] + direction TB + Rails["Rails
应用"] + Port3000[":3000"] + Rails ~~~ Port3000 + end + + subgraph DB ["db 服务"] + direction TB + Postgres["PostgreSQL
数据库"] + end + + Rails -- ":5432" --> Postgres + end + + Browser["localhost:3000"] + Port3000 --> Browser +``` +图 11-2：Rails + PostgreSQL 的 Compose 架构 + +### 11.7.2 准备工作 + +创建项目目录： + +```bash +$ mkdir rails-docker && cd rails-docker +``` +需要创建三个文件：`Dockerfile`、`Gemfile` 和 `compose.yaml`。 + +### 11.7.3 步骤 1：创建 Dockerfile + +```docker +FROM ruby:3.2 + +## 安装系统依赖 + +RUN apt-get update -qq && \ + apt-get install -y build-essential libpq-dev nodejs && \ + rm -rf /var/lib/apt/lists/* + +## 设置工作目录 + +WORKDIR /myapp + +## 先复制 Gemfile，利用缓存加速构建 + +COPY Gemfile /myapp/Gemfile +COPY Gemfile.lock /myapp/Gemfile.lock +RUN bundle install + +## 复制应用代码 + +COPY . /myapp +``` +**配置说明**： + +| 指令 | 作用 | +|------|------| +| `build-essential` | 编译原生扩展所需 | +| `libpq-dev` | PostgreSQL 客户端库 | +| `nodejs` | Rails Asset Pipeline 需要 | +| 先复制 Gemfile | 只有依赖变化时才重新 `bundle install` | + +### 11.7.4 步骤 2：创建 Gemfile + +创建一个初始的 `Gemfile`，稍后会被 `rails new` 覆盖： + +```ruby +source 'https://rubygems.org' +gem 'rails', '~> 7.1' +``` +创建空的 `Gemfile.lock`： + +```bash +$ touch Gemfile.lock +``` + +### 11.7.5 步骤 3：创建 compose.yaml + +配置如下。下面为了本地练习使用环境变量占位；不要把真实数据库密码写进 `compose.yaml`、`.env` 或 Git，生产环境应使用 Compose secrets、Rails credentials 或平台密钥管理。 + +```yaml +services: + db: + image: postgres:16 + environment: + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 5s + timeout: 5s + retries: 5 + + web: + build: . + command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b '0.0.0.0'" + volumes: + - .:/myapp + ports: + - "3000:3000" + depends_on: + db: + condition: service_healthy + environment: + DATABASE_URL: postgres://postgres:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/myapp_development + +volumes: + postgres_data: +``` +**配置详解**： + +| 配置项 | 说明 | +|--------|------| +| `rm -f tmp/pids/server.pid` | 清理上次异常退出留下的 PID 文件 | +| `volumes: .:/myapp` | 挂载代码目录，支持热更新 | +| `depends_on` + `condition` | 等待数据库健康检查通过后再启动 | +| `DATABASE_URL` | Rails 12-factor 风格的数据库配置 | + +### 11.7.6 步骤 4：生成 Rails 项目 + +使用 `docker compose run` 生成项目骨架： + +```bash +$ docker compose run --rm web rails new . --force --database=postgresql --skip-bundle +``` +**命令解释**： + +- `--rm`：执行后删除临时容器 +- `--force`：覆盖已存在的文件 +- `--database=postgresql`：配置使用 PostgreSQL +- `--skip-bundle`：暂不安装依赖（稍后统一安装） + +生成的目录结构： + +```bash +$ ls +Dockerfile Gemfile Rakefile config lib tmp +Gemfile.lock README.md app config.ru log vendor +compose.yaml bin db public + +``` +> ⚠️ **Linux 用户**：如遇权限问题，执行 `sudo chown -R $USER:$USER .` + +### 11.7.7 步骤 5：重新构建镜像 + +由于生成了新的 Gemfile，需要重新构建镜像以安装完整依赖： + +```bash +$ docker compose build +``` + +### 11.7.8 步骤 6：配置数据库连接 + +修改 `config/database.yml`： + +```yaml +default: &default + adapter: postgresql + encoding: unicode + pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %> + url: <%= ENV['DATABASE_URL'] %> + +development: + <<: *default + +test: + <<: *default + database: myapp_test + +production: + <<: *default +``` +> 💡 使用 `DATABASE_URL` 环境变量配置数据库，符合 12-factor 应用原则，便于在不同环境间切换。 + +### 11.7.9 步骤 7：启动应用 + +```bash +$ docker compose up +``` +输出示例： + +```bash +db-1 | PostgreSQL init process complete; ready for start up. +db-1 | LOG: database system is ready to accept connections +web-1 | => Booting Puma +web-1 | => Rails 7.1.0 application starting in development +web-1 | => Run `bin/rails server --help` for more startup options +web-1 | Puma starting in single mode... +web-1 | * Listening on http://0.0.0.0:3000 +``` + +### 11.7.10 步骤 8：创建数据库 + +在另一个终端执行： + +```bash +$ docker compose exec web rails db:create +Created database 'myapp_development' +Created database 'myapp_test' +``` +访问 http://localhost:3000 查看 Rails 欢迎页面。 + +### 11.7.11 常用开发命令 + +```bash +## 数据库迁移 + +$ docker compose exec web rails db:migrate + +## Rails 控制台 + +$ docker compose exec web rails console + +## 运行测试 + +$ docker compose exec web rails test + +## 生成脚手架 + +$ docker compose exec web rails generate scaffold Post title:string body:text + +## 进入容器 Shell + +$ docker compose exec web bash +``` + +### 11.7.12 常见问题 + +#### Q：数据库连接失败 + +检查 `DATABASE_URL` 环境变量格式是否正确，确保 db 服务已启动： + +```bash +$ docker compose ps +$ docker compose logs db +``` + +#### Q：server.pid 文件导致启动失败 + +错误信息：`A server is already running` + +已在 command 中添加 `rm -f tmp/pids/server.pid` 处理。如仍有问题： + +```bash +$ docker compose exec web rm -f tmp/pids/server.pid +``` + +#### Q：Gem 安装失败 + +可能需要更新 bundler 或清理缓存： + +```bash +$ docker compose run --rm web bundle update +``` + +### 11.7.13 开发 vs 生产 + +| 配置项 | 开发环境 | 生产环境 | +|--------|---------|---------| +| Rails 服务器 | Puma（开发模式）| Puma + Nginx | +| 代码挂载 | 使用 volumes | 代码打包进镜像 | +| 静态资源 | 动态编译 | 预编译 (`rails assets:precompile`) | +| 数据库密码 | 明文配置 | 使用 Secrets 管理 | + +### 11.7.14 延伸阅读 + +- [使用 Django](11.6_django.md)：Python Web 框架实战 +- [Compose 模板文件](11.5_compose_file.md)：配置详解 +- [数据管理](../08_data/README.md)：数据持久化 diff --git a/11_compose/11.8_wordpress.md b/11_compose/11.8_wordpress.md new file mode 100644 index 000000000..5620faf9b --- /dev/null +++ b/11_compose/11.8_wordpress.md @@ -0,0 +1,235 @@ +## 11.8 实战 WordPress + +> **版本说明**：本示例使用以下镜像版本： +> - MySQL：8.4（可替换为其他 8.x 版本，或使用 MariaDB 替代） +> - WordPress：latest（建议在生产环境指定具体版本，如 6.x） + +WordPress 是全球最流行的内容管理系统 (CMS)。使用 Docker Compose 可以在几分钟内搭建一个包含数据库、Web 服务和持久化存储的本地练习/单机演示环境。 + +--- + +### 11.8.1 项目结构 + +```bash +wordpress/ +├── compose.yaml +├── .env # 非敏感环境变量（如版本、端口） +├── secrets/ # 本地密钥文件，生产环境应由密钥管理系统提供 +│ ├── db_root_password.txt +│ └── db_password.txt +└── nginx/ # 可选：反向代理配置 + └── nginx.conf +``` +--- + +### 11.8.2 编写 `compose.yaml` + +这是一个可运行的单机最小配置，不是完整生产安全基线。正式部署前应固定镜像版本、放在反向代理/TLS 后面、限制公开端口、配置备份与监控，并按 WordPress 与插件生命周期做升级测试。 + +```yaml +services: + # 数据库服务 + + db: + image: mysql:8.4 + container_name: wordpress_db + restart: always + command: + # 启用原生密码认证（MySQL 8.4 默认禁用，旧版 WP 兼容性需要） + + - --mysql-native-password=ON + - --character-set-server=utf8mb4 + - --collation-server=utf8mb4_unicode_ci + environment: + MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password + MYSQL_DATABASE: wordpress + MYSQL_USER: wordpress + MYSQL_PASSWORD_FILE: /run/secrets/db_password + secrets: + - db_root_password + - db_password + volumes: + - db_data:/var/lib/mysql + networks: + - wp_net + + # WordPress 服务 + + wordpress: + # 示例保留 latest 以便读者快速体验；生产环境请固定到经过测试的明确版本标签 + image: wordpress:latest + container_name: wordpress_app + restart: always + ports: + # 本机调试入口；生产环境请通过反向代理发布 HTTPS + - "127.0.0.1:8000:80" + environment: + WORDPRESS_DB_HOST: db:3306 + WORDPRESS_DB_USER: wordpress + WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password + WORDPRESS_DB_NAME: wordpress + secrets: + - db_password + volumes: + - wp_data:/var/www/html + # 增加上传文件大小限制 + + - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini + depends_on: + - db + networks: + - wp_net + +volumes: + db_data: # 数据库持久化 + wp_data: # WordPress 文件(插件/主题/上传)持久化 + +networks: + wp_net: + +secrets: + db_root_password: + file: ./secrets/db_root_password.txt + db_password: + file: ./secrets/db_password.txt +``` +--- + +### 11.8.3 配置文件详解 + +#### 1. 密钥文件 + +不要把数据库密码写入 `compose.yaml`、`.env`、命令行或 Git。Compose 官方建议敏感值使用 secrets；本地练习可用只读密钥文件模拟： + +```bash +mkdir -p secrets +printf '%s\n' 'somestrongrootpassword' > secrets/db_root_password.txt +printf '%s\n' 'somestronguserpassword' > secrets/db_password.txt +chmod 600 secrets/*.txt +``` + +把 `secrets/` 加入 `.gitignore`。生产环境应改用平台密钥管理能力，而不是把真实密码放在项目目录。 + +#### 2. 数据持久化 + +我们定义了两个命名卷： + +- `db_data`：确保 MySQL 容器重建后数据不丢失 +- `wp_data`：保存 WordPress 的核心文件、插件、主题和上传的媒体文件 + +#### 3. PHP 配置优化 + +默认的 WordPress 镜像上传文件限制较小（通常 2MB）。创建 `uploads.ini`： + +```ini +file_uploads = On +memory_limit = 256M +upload_max_filesize = 64M +post_max_size = 64M +max_execution_time = 600 +``` +--- + +### 11.8.4 启动与运行 + +1. 启动服务： + +```bash +$ docker compose up -d +``` + +2. 访问安装界面： + 打开浏览器访问 `http://localhost:8000` + +3. 查看日志： + +```bash +$ docker compose logs -f +``` +--- + +### 11.8.5 生产环境最佳实践 + +#### 1. 数据库备份 + +不要只依赖 Volume。建议定期备份数据库： + +```bash +## 导出 SQL + +$ docker compose exec -T db sh -c 'tmp=$(mktemp) && printf "[client]\nuser=wordpress\npassword=%s\n" "$(cat /run/secrets/db_password)" > "$tmp" && mysqldump --defaults-extra-file="$tmp" wordpress; rc=$?; rm -f "$tmp"; exit "$rc"' > backup.sql +``` +或者添加一个自动备份容器： + +```yaml + backup: + image: tiredofit/db-backup + volumes: + - ./backups:/backup + environment: + # tiredofit/db-backup 4.x 起按 DB01_ 前缀配置备份任务，并原生支持 _FILE 读密 + - DB01_TYPE=mysql + - DB01_HOST=db + - DB01_NAME=wordpress + - DB01_USER=wordpress + - DB01_PASS_FILE=/run/secrets/db_password + - DB01_BACKUP_INTERVAL=1440 # 每天备份一次（单位：分钟） + secrets: + - db_password + depends_on: + - db + networks: + - wp_net +``` + +#### 2. 使用 Nginx 反向代理 + +在生产环境中，不要直接暴露 WordPress 端口，而是通过 Nginx 进行反向代理并配置 SSL。 + +#### 3. 使用 Redis 缓存 + +WordPress 支持 Redis 缓存以提高性能。 + +```yaml + redis: + image: redis:alpine + restart: always + networks: + - wp_net +``` +在 WordPress 容器环境变量中添加： +```yaml + # 官方 wordpress 镜像只把固定的一组 WORDPRESS_* 变量写进 wp-config.php， + # 其中并没有 Redis 相关项；Redis Object Cache 插件读的是 PHP 常量 WP_REDIS_HOST， + # 因此要通过 WORDPRESS_CONFIG_EXTRA 注入 + WORDPRESS_CONFIG_EXTRA: | + define('WP_REDIS_HOST', 'redis'); +``` +并安装 Redis Object Cache 插件。 + +--- + +### 11.8.6 常见问题 + +#### Q：数据库连接错误 + +**现象**：访问页面显示 “Error establishing a database connection”。**排查**： + +1. 检查 `docker compose logs wordpress` +2. 确认 `secrets/db_password.txt` 的内容正确，且与数据库初始化时使用的密码一致（改密码后需要重建 db 数据卷） +3. 确认 `WORDPRESS_DB_HOST` 也是 `db`（服务名） +4. MySQL 8.4 可能需要几秒钟启动，WordPress 会自动重试，稍等片刻即可。 + +#### Q：无法上传大文件 + +**解决**：确保挂载了 `uploads.ini` 配置，并且重启了容器： +```bash +$ docker compose restart wordpress +``` +--- + +### 11.8.7 延伸阅读 + +- [Compose 模板文件](11.5_compose_file.md)：深入了解配置项 +- [数据卷](../08_data/8.1_volume.md)：理解数据持久化 +- [Docker Hub WordPress](https://hub.docker.com/_/wordpress)：官方镜像文档 diff --git a/11_compose/11.9_lnmp.md b/11_compose/11.9_lnmp.md new file mode 100644 index 000000000..60ab23e86 --- /dev/null +++ b/11_compose/11.9_lnmp.md @@ -0,0 +1,38 @@ +## 11.9 实战 LNMP + +### 什么是 LNMP + +LNMP 是一个经典的 Web 应用栈，由以下四个开源软件组合而成： + +- **L**：Linux（操作系统） +- **N**：Nginx（Web 服务器） +- **M**：MySQL（数据库服务器） +- **P**：PHP（脚本语言） + +这个组合被广泛用于构建高性能的 Web 应用。 + +### 使用 Docker Compose 部署 LNMP + +本项目的维护者 [khs1994](https://github.com/khs1994) 的开源项目 [khs1994-docker/lnmp](https://github.com/khs1994-docker/lnmp) 使用 Docker Compose 搭建了一套完整的 LNMP 环境。 + +### 参考项目 + +该项目中包含的服务： + +- **Nginx**：Web 服务器，用于处理 HTTP 请求 +- **MySQL/MariaDB**：关系型数据库服务 +- **PHP-FPM**：PHP 处理器，与 Nginx 通过 Fast CGI 协议通信 +- **Redis**：可选的内存缓存服务（用于会话或缓存） + +### 学习资源 + +各位开发者可以参考该项目在以下场景中运行 LNMP： + +- Docker 容器化部署 +- Kubernetes 集群编排 +- 开发环境快速搭建 +- 生产环境配置参考 + +项目地址：[khs1994-docker/lnmp](https://github.com/khs1994-docker/lnmp) + +通过该项目，你可以学习到如何使用 Docker Compose 定义多个相互关联的服务，以及如何在容器化环境中管理应用的生命周期。 diff --git a/11_compose/README.md b/11_compose/README.md new file mode 100644 index 000000000..299eb20b2 --- /dev/null +++ b/11_compose/README.md @@ -0,0 +1,32 @@ +# 第十一章 Docker Compose + +`Docker Compose` 是 Docker 官方编排 (Orchestration) 项目之一，负责快速定义和启动本地或单机多容器应用。跨主机集群编排应交给 Swarm、Kubernetes 或云厂商托管服务。 + +> ⚠️ **重要提示：Compose V1 已停止支持** +> +> 早期基于 Python 编写的 Compose V1（命令为 `docker-compose`）已于 2023 年中正式停止支持。现已全面升级为基于 Go 编写的 Compose V2，作为 Docker CLI 的官方插件提供（命令为 `docker compose`，中间为空格）。本书强烈推荐且后续章节均以 V2 为核心标准进行讲解。 + +## Docker Compose 解决什么问题？ + +在学习 Compose 之前，笔者想强调它的真正价值。假设你正在开发一个微服务应用——前端、后端、数据库三个服务。如果你用 Docker 容器分别运行它们，你会遇到这些问题： + +1. **启动顺序**：需要先启数据库，再启后端，最后启前端 +2. **网络连接**：三个容器需要能彼此通信 +3. **卷挂载**：本地代码需要映射到容器内 +4. **环境变量**：每个服务的配置需要逐个设置 + +使用 `docker run` 逐个启动的话，需要记住 3 条复杂的命令。而 **Docker Compose 的核心价值就是用一个 YAML 文件来定义整个应用**，然后一条命令 `docker compose up` 启动所有服务。这是 Compose 被广泛采用的原因——它极大地简化了本地开发和测试的复杂性。 + +**谁应该学 Compose？** 任何使用 Docker 进行本地开发的人，以及需要快速部署多容器应用的团队。 + +本章将介绍 `Compose` 项目情况以及安装和使用。 + +* [简介](11.1_introduction.md) +* [安装与卸载](11.2_install.md) +* [使用](11.3_usage.md) +* [命令说明](11.4_commands.md) +* [Compose 模板文件](11.5_compose_file.md) +* [实战 Django](11.6_django.md) +* [实战 Rails](11.7_rails.md) +* [实战 WordPress](11.8_wordpress.md) +* [实战 LNMP](11.9_lnmp.md) diff --git a/11_compose/demo/app/Dockerfile b/11_compose/demo/app/Dockerfile new file mode 100644 index 000000000..135dfbac5 --- /dev/null +++ b/11_compose/demo/app/Dockerfile @@ -0,0 +1,5 @@ +FROM python:3.12-alpine +COPY . /code +WORKDIR /code +RUN pip install redis flask +CMD ["python", "app.py"] diff --git a/11_compose/demo/app/app.py b/11_compose/demo/app/app.py new file mode 100644 index 000000000..f0dfc2080 --- /dev/null +++ b/11_compose/demo/app/app.py @@ -0,0 +1,13 @@ +from flask import Flask +from redis import Redis + +app = Flask(__name__) +redis = Redis(host='redis', port=6379) + +@app.route('/') +def hello(): + count = redis.incr('hits') + return 'Hello World! 该页面已被访问 {} 次。\n'.format(count) + +if __name__ == "__main__": + app.run(host="0.0.0.0", debug=True) diff --git a/11_compose/demo/app/docker-compose.yml b/11_compose/demo/app/docker-compose.yml new file mode 100644 index 000000000..b8f08374f --- /dev/null +++ b/11_compose/demo/app/docker-compose.yml @@ -0,0 +1,10 @@ + +services: + + web: + build: . + ports: + - "5000:5000" + + redis: + image: "redis:alpine" diff --git a/11_compose/demo/django/.gitignore b/11_compose/demo/django/.gitignore new file mode 100644 index 000000000..dfb0c8960 --- /dev/null +++ b/11_compose/demo/django/.gitignore @@ -0,0 +1,2 @@ +django_example +manage.py diff --git a/11_compose/demo/django/Dockerfile b/11_compose/demo/django/Dockerfile new file mode 100644 index 000000000..86ae43cab --- /dev/null +++ b/11_compose/demo/django/Dockerfile @@ -0,0 +1,21 @@ +FROM python:3.12-slim + +## 防止 Python 缓冲 stdout/stderr，让日志实时输出 + +ENV PYTHONUNBUFFERED=1 + +## 设置工作目录 + +WORKDIR /code + +## 先复制依赖文件，利用 Docker 缓存加速构建 + +COPY requirements.txt /code/ + +## 安装依赖 + +RUN pip install --no-cache-dir -r requirements.txt + +## 复制项目代码 + +COPY . /code/ diff --git a/11_compose/demo/django/docker-compose.yml b/11_compose/demo/django/docker-compose.yml new file mode 100644 index 000000000..3c46f6396 --- /dev/null +++ b/11_compose/demo/django/docker-compose.yml @@ -0,0 +1,34 @@ + +services: + + db: + image: postgres:16 + environment: + POSTGRES_DB: django_db + POSTGRES_USER: django_user + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U django_user -d django_db"] + interval: 5s + timeout: 5s + retries: 5 + + web: + build: . + command: python manage.py runserver 0.0.0.0:8000 + volumes: + - .:/code + ports: + - "8000:8000" + depends_on: + db: + condition: service_healthy + environment: + # 与书中 11.6 节一致：settings.py 从环境变量读取数据库密码 + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + DATABASE_URL: postgres://django_user:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/django_db + +volumes: + postgres_data: diff --git a/11_compose/demo/django/requirements.txt b/11_compose/demo/django/requirements.txt new file mode 100644 index 000000000..96c90f622 --- /dev/null +++ b/11_compose/demo/django/requirements.txt @@ -0,0 +1,3 @@ +Django>=5.0,<6.0 +psycopg[binary]>=3.1,<4.0 +gunicorn>=21.0,<22.0 diff --git a/11_compose/demo/wordpress/README.md b/11_compose/demo/wordpress/README.md new file mode 100644 index 000000000..d446b8f90 --- /dev/null +++ b/11_compose/demo/wordpress/README.md @@ -0,0 +1,18 @@ +# WordPress Compose 示例 + +本示例使用 Docker Compose secrets 管理数据库密码，启动前需要先创建密钥文件（参见书中 11.8 节）： + +```bash +mkdir -p secrets +printf '%s\n' 'somestrongrootpassword' > secrets/db_root_password.txt +printf '%s\n' 'somestronguserpassword' > secrets/db_password.txt +chmod 600 secrets/*.txt +``` + +然后启动： + +```bash +docker compose up -d +``` + +注意：`secrets/` 目录不要提交到版本库；生产环境应改用平台的密钥管理能力。 diff --git a/11_compose/demo/wordpress/docker-compose.yml b/11_compose/demo/wordpress/docker-compose.yml new file mode 100644 index 000000000..d55bdd32d --- /dev/null +++ b/11_compose/demo/wordpress/docker-compose.yml @@ -0,0 +1,65 @@ +services: + # 数据库服务 + + db: + image: mysql:8.4 + container_name: wordpress_db + restart: always + command: + # 启用原生密码认证（MySQL 8.4 默认禁用，旧版 WP 兼容性需要） + + - --mysql-native-password=ON + - --character-set-server=utf8mb4 + - --collation-server=utf8mb4_unicode_ci + environment: + MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password + MYSQL_DATABASE: wordpress + MYSQL_USER: wordpress + MYSQL_PASSWORD_FILE: /run/secrets/db_password + secrets: + - db_root_password + - db_password + volumes: + - db_data:/var/lib/mysql + networks: + - wp_net + + # WordPress 服务 + + wordpress: + # 示例保留 latest 以便读者快速体验；生产环境请固定到经过测试的明确版本标签 + image: wordpress:latest + container_name: wordpress_app + restart: always + ports: + # 本机调试入口；生产环境请通过反向代理发布 HTTPS + - "127.0.0.1:8000:80" + environment: + WORDPRESS_DB_HOST: db:3306 + WORDPRESS_DB_USER: wordpress + WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password + WORDPRESS_DB_NAME: wordpress + secrets: + - db_password + volumes: + - wp_data:/var/www/html + # 增加上传文件大小限制 + + - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini + depends_on: + - db + networks: + - wp_net + +volumes: + db_data: # 数据库持久化 + wp_data: # WordPress 文件(插件/主题/上传)持久化 + +networks: + wp_net: + +secrets: + db_root_password: + file: ./secrets/db_root_password.txt + db_password: + file: ./secrets/db_password.txt diff --git a/11_compose/demo/wordpress/uploads.ini b/11_compose/demo/wordpress/uploads.ini new file mode 100644 index 000000000..0f0134da2 --- /dev/null +++ b/11_compose/demo/wordpress/uploads.ini @@ -0,0 +1,5 @@ +file_uploads = On +memory_limit = 256M +upload_max_filesize = 64M +post_max_size = 64M +max_execution_time = 600 diff --git a/11_compose/summary.md b/11_compose/summary.md new file mode 100644 index 000000000..f7d229263 --- /dev/null +++ b/11_compose/summary.md @@ -0,0 +1,24 @@ +## 本章小结 + +Docker Compose 是管理多容器应用的利器，通过 YAML 文件声明式地定义服务、网络和数据卷。 + +| 概念 | 要点 | +|------|------| +| **核心概念** | 服务 (service) 和项目 (project) | +| **配置文件** | `compose.yaml`（推荐）或 `docker-compose.yml` | +| **版本** | Compose V2 为 Go 编写的 CLI 插件，通过 `docker compose` 使用 | +| **启动** | `docker compose up -d` 启动所有服务 | +| **停止** | `docker compose down` 停止并移除容器 | +| **查看状态** | `docker compose ps` 查看服务状态 | +| **查看日志** | `docker compose logs` 查看服务日志 | +| **模板文件** | 支持 `services`、`networks`、`volumes` 等顶级配置 | + +### 延伸阅读 + +- [Compose 模板文件](11.5_compose_file.md)：详细模板语法参考 +- [Compose 命令说明](11.4_commands.md)：完整命令列表 +- [网络配置](../09_network/README.md)：Docker 网络基础 +- [数据管理](../08_data/README.md)：数据卷管理 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/12_implementation/12.1_arch.md b/12_implementation/12.1_arch.md new file mode 100644 index 000000000..051d3b3ab --- /dev/null +++ b/12_implementation/12.1_arch.md @@ -0,0 +1,143 @@ +## 12.1 基本架构 + +Docker 的架构设计简洁而高效，主要由客户端和服务端两部分组成。 + +### 12.1.1 核心架构图 + +Docker 采用了 **C/S（客户端/服务端）** 架构。Client 向 Daemon 发送请求，Daemon 负责构建、运行和分发容器。 + +```mermaid +graph LR + C1["客户端"] -->|docker run| D["dockerd
守护进程"] + C1 -->|docker pull| D + D -->|管理| C2["Containers
容器"] + D -->|管理| C3["Images
镜像"] +``` +--- + +### 12.1.2 组件详解 + +Docker 的内部架构如同洋葱一样分层，每一层专注解决特定问题： + +#### 1. Docker CLI：客户端 + +用户与 Docker 交互的主要方式。它将用户命令（如 `docker run`）转换为 API 请求发送给 dockerd。 + +#### 2. Dockerd：守护进程 + +Docker 的大脑。 + +- 监听 API 请求 +- 管理 Docker 对象（镜像、容器、网络、卷） +- 编排下层组件完成工作 + +#### 3. Containerd：高级运行时 + +行业标准的容器运行时（CNCF 毕业项目）。 + +- 管理容器的完整生命周期（启动、停止） +- 镜像拉取与存储 +- **不包含** 复杂的与容器无关的功能（如构建、API） +- Kubernetes 也可以直接使用 containerd（跳过 Docker） + +#### 4. Runc：低级运行时 + +用于创建和运行容器的 CLI 工具。 + +- 直接与内核交互 (Namespaces，Cgroups) +- 遵循 OCI (Open Container Initiative) 规范 +- **主要职责**：根据配置启动一个容器，然后退出（将控制权交给容器进程） + +#### 5. Shim + +每个容器都有一个 shim 进程。 + +- **解耦**：允许 dockerd 重启而不影响容器运行 +- **保持 IO**：维持容器的标准输入输出 +- **状态汇报**：向 containerd 汇报容器退出状态 + +--- + +### 12.1.3 容器启动流程 + +当执行 `docker run -d nginx` 时，内部发生了什么？ + +```mermaid +flowchart TD + U["用户"] + K["docker run -d nginx"] + D["Dockerd"] + C["Containerd"] + B["OCI Bundle"] + S["Containerd-shim"] + R["Runc"] + P["容器进程
nginx"] + E["退出"] + + U -->|1. REST API| D + D -->|2. gRPC| C + C -->|3. 准备镜像和 Bundle| B + C -->|4. 启动 Shim| S + S -->|5. 执行| R + R -->|6. 创建 Namespaces 和 Cgroups| P + R -->|7. 进程退出| E + S -->|8. 监控 IO 和退出| P +``` + +1. **CLI** 发送请求给 **Dockerd** +2. **Dockerd** 解析请求，调用 **Containerd** +3. **Containerd** 准备镜像，转换为 OCI Bundle +4. **Containerd** 创建 **Shim** 进程 +5. **Shim** 调用 **Runc** +6. **Runc** 与系统内核交互，创建 Namespaces 和 Cgroups +7. **Runc** 启动 nginx 进程后退出 +8. **Shim** 接管容器 IO 和生命周期监控 + +--- + +### 12.1.4 Docker Engine v29.x 变化 + +从 Docker Engine v29.x 开始，架构进一步简化和标准化： + +- **Containerd 镜像存储 (Image Store)**：在 v29.x 的新安装场景中默认启用。Docker 直接使用 Containerd 的镜像管理能力，不再维护自己的一套 graphdriver。 + - **优势**：多平台镜像支持更好，可保存 SBOM/Provenance 等 attestations，并可使用 containerd snapshotters 的 lazy pulling 等能力。 +- **实验性 nftables 支持**：随着主流 Linux 发行版逐步弃用 iptables，Docker v29.x 引入了实验性 nftables 后端。启用方式为 `dockerd --firewall-backend=nftables`，可直接创建 nftables 规则而无需依赖 iptables-nft 转换层。生产环境请谨慎使用。 + +--- + +### 12.1.5 Docker Desktop 架构 + +在 macOS 和 Windows 上，因为内核差异，架构稍微复杂： + +```mermaid +flowchart TD + subgraph HostOS ["MacOS / Windows"] + CLI["Docker CLI"] + subgraph LinuxVM ["Linux VM (虚拟机)"] + Engine["Dockerd <--> Containerd <--> Runc"] + end + CLI -- "(Socket 映射)" --> Engine + end +``` + +- 使用轻量级虚拟机 (Apple Virtualization / WSL 2) 运行 Linux 内核 +- 文件挂载 (Bind Mount) 需要跨越 VM 边界（这也是文件 I/O 慢的原因） +- 网络端口需要从宿主机转发到 VM + +--- + +### 12.1.6 总结 + +| 组件 | 角色 | 关键职责 | +|------|------|----------| +| **CLI** | 指挥官 | 发送指令，展示结果 | +| **Dockerd** | 大管家 | API 接口，整体调度 | +| **Containerd** | 经理 | 容器生命周期，镜像管理 | +| **Shim** | 监工 | 保持 IO，允许无守护进程重启 | +| **Runc** | 工人 | 真正干活（创建容器），干完就走 | + +### 12.1.7 延伸阅读 + +- [命名空间](./12.2_namespace.md)：Runc 如何隔离容器 +- [控制组](./12.3_cgroups.md)：Runc 如何限制资源 +- [联合文件系统](./12.4_ufs.md)：镜像如何存储 diff --git a/12_implementation/12.2_namespace.md b/12_implementation/12.2_namespace.md new file mode 100644 index 000000000..bb0b81318 --- /dev/null +++ b/12_implementation/12.2_namespace.md @@ -0,0 +1,299 @@ +## 12.2 命名空间 + +命名空间是 Linux 内核一个强大的特性。每个容器都有自己单独的命名空间，运行在其中的应用都像是在独立的操作系统中运行一样。命名空间保证了容器之间彼此互不影响。 + +### 12.2.1 什么是 Namespace + +> **Namespace 是 Linux 内核提供的资源隔离机制，它让容器内的进程仿佛运行在独立的操作系统中。** Namespace 是容器技术的核心基础之一。它回答了一个关键问题：**如何让一个进程 “以为” 自己独占整个系统？** + +```mermaid +flowchart LR + subgraph Host ["宿主机视角"] + direction TB + H1["PID 1: systemd"] + H2["PID 2: sshd"] + H3["PID 3: dockerd"] + H4["PID 1234: nginx"] + H5["PID 1235: nginx worker"] + end + + subgraph Container ["容器内视角"] + direction TB + C1["PID 1: nginx
← 容器认为自己是 PID 1"] + C2["PID 2: nginx worker"] + end + + H4 -. "（实际是宿主机的 1234）" .- C1 +``` + +### 12.2.2 Namespace 的类型 + +Linux 内核（5.6+）共提供 8 种 Namespace。Docker 容器默认启用其中的 PID、NET、MNT、UTS、IPC（在 cgroup v2 主机上还包括 Cgroup）；USER Namespace 默认**不**启用，需要通过 `daemon.json` 的 `userns-remap` 显式开启（详见第 18.1 节），Time Namespace 则未被使用： + +| Namespace | 隔离内容 | 容器中的效果 | +|-----------|---------|-------------| +| **PID** | 进程 ID | 容器内 PID 从 1 开始，看不到其他容器和宿主机进程 | +| **NET** | 网络栈 | 独立的网卡、IP 地址、端口、路由表 | +| **MNT** | 挂载点 | 独立的文件系统视图，自己的根目录 | +| **UTS** | 主机名 | 独立的主机名和域名 | +| **IPC** | 进程间通信 | 独立的信号量、消息队列、共享内存 | +| **USER** | 用户/组 ID | 容器内的 root 可以映射为宿主机的普通用户（默认不启用，需 `userns-remap` 显式开启）| +| **Cgroup** | Cgroup 根目录 | 隔离 cgroup 层级视图 (Linux 4.6+)| +| **Time** | 系统时钟 | 隔离 CLOCK_MONOTONIC 和 CLOCK_BOOTTIME (Linux 5.6+)| + +--- + +### 12.2.3 PID Namespace + +PID Namespace 负责进程 ID 的隔离，使得容器内的进程彼此不可见。 + +#### PID 的作用 + +隔离进程 ID，让每个容器有自己的进程编号空间。 + +#### PID 隔离效果 + +```bash +## 宿主机上查看进程 + +$ ps aux | grep nginx +root 12345 0.0 0.1 nginx: master process +root 12346 0.0 0.1 nginx: worker process + +## 容器内查看进程 + +$ docker exec mycontainer ps aux +PID USER COMMAND + 1 root nginx: master process ← 在容器内是 PID 1 + 2 root nginx: worker process +``` + +#### PID 关键点 + +- 容器内的 PID 1 进程特殊重要——它是容器的主进程，退出则容器停止 +- 容器内无法看到宿主机或其他容器的进程 +- 宿主机可以看到所有容器内的进程（但 PID 不同） + +--- + +### 12.2.4 NET Namespace + +NET Namespace 负责网络栈的隔离，包括网卡、路由表和 iptables 规则等。 + +#### NET 的作用 + +隔离网络栈，每个容器拥有独立的网络环境。 + +#### NET 隔离效果 + +```mermaid +flowchart LR + subgraph Host ["宿主机"] + direction TB + H1["eth0: 192.168.1.10
端口 80 可用"] + H2["docker0: 172.17.0.1"] + end + + subgraph Container ["容器"] + direction TB + C1["eth0: 172.17.0.2
端口 80 可用"] + C2["(veth pair 连接)"] + end + + H2 <--> C2 +``` + +#### NET 关键点 + +- 每个容器有独立的网卡、IP、路由表、iptables 规则 +- 多个容器可以监听相同端口（如都监听 80） +- Docker 使用 veth pair 连接容器网络和宿主机网桥 + +--- + +### 12.2.5 MNT Namespace + +MNT Namespace 负责文件系统挂载点的隔离，确保容器看到独立的文件系统视图。 + +#### MNT 的作用 + +隔离文件系统挂载点，每个容器有自己的根目录。 + +#### MNT 隔离效果 + +```bash +宿主机文件系统： 容器内看到的： +/ / ← 容器的根目录 +├── bin/ ├── bin/ +├── home/ ├── home/ +├── var/ ├── var/ +│ └── lib/ │ └── lib/ +│ └── docker/ │ +│ └── overlay2/ │ +│ └── merged/ ────┼─── 这个目录成为容器的 / +└── ... └── ... +``` + +#### 与 chroot 的区别 + +| 特性 | chroot | MNT Namespace | +|------|--------|---------------| +| 安全性 | 可以逃逸 | 更安全 | +| 挂载隔离 | 无 | 完全隔离 | +| /proc/mounts | 共享 | 独立 | + +--- + +### 12.2.6 UTS Namespace + +UTS Namespace 主要用于隔离主机名和域名。 + +#### UTS 的作用 + +隔离主机名和域名，让每个容器可以有自己的主机名。 + +#### UTS 隔离效果 + +```bash +## 宿主机 + +$ hostname +my-server + +## 容器内 + +$ docker run --hostname mycontainer ubuntu hostname +mycontainer +``` +UTS = “UNIX Time-sharing System”，是历史遗留的名称。 + +--- + +### 12.2.7 IPC Namespace + +IPC Namespace 用于隔离进程间通信资源，如 System V IPC 和 POSIX 消息队列。 + +#### IPC 的作用 + +隔离 System V IPC 和 POSIX 消息队列。 + +#### 隔离的资源 + +- 信号量 (semaphores) +- 消息队列 (message queues) +- 共享内存 (shared memory) + +#### IPC 关键点 + +- 同一容器内的进程可以通过 IPC 通信 +- 不同容器的进程无法通过 IPC 通信（除非显式共享） + +--- + +### 12.2.8 USER Namespace + +USER Namespace 允许将容器内的用户 ID 映射到宿主机的不同用户 ID。 + +#### USER 的作用 + +隔离用户和组 ID，实现权限隔离。 + +#### USER 隔离效果 + +```mermaid +flowchart LR + subgraph Container ["容器内"] + direction TB + C1["UID 0 (root)"] + C2["UID 1 (daemon)"] + end + + subgraph Host ["宿主机"] + direction TB + H1["UID 100000
← 非特权用户"] + H2["UID 100001"] + end + + C1 -- 映射 --> H1 + C2 -- 映射 --> H2 +``` + +#### 安全意义 + +容器内的 root 用户可以映射为宿主机上的普通用户，即使容器被突破，攻击者在宿主机上也只有普通权限。 + +> 💡 笔者建议：生产环境建议启用 User Namespace，增强安全性。 + +--- + +### 12.2.9 动手实验：体验 Namespace + +使用 `unshare` 命令可以在不使用 Docker 的情况下体验 Namespace： + +#### 实验 1：UTS Namespace + +```bash +## 创建新的 UTS namespace 并启动 shell + +$ sudo unshare --uts /bin/bash + +## 修改主机名（只影响这个 namespace） + +$ hostname container-test +$ hostname +container-test + +## 退出后查看宿主机主机名（未改变） + +$ exit +$ hostname +my-server +``` + +#### 实验 2：PID Namespace + +```bash +## 创建新的 PID 和 MNT namespace + +$ sudo unshare --pid --mount --fork /bin/bash + +## 挂载新的 /proc + +$ mount -t proc proc /proc + +## 查看进程（只能看到当前 shell） + +$ ps aux +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.0 0.0 8960 4516 pts/0 S 10:00 0:00 /bin/bash +root 8 0.0 0.0 10072 3200 pts/0 R+ 10:00 0:00 ps aux +``` + +#### 实验 3：NET Namespace + +```bash +## 创建新的网络 namespace + +$ sudo unshare --net /bin/bash + +## 查看网络接口（只有 lo） + +$ ip addr +1: lo:
占用所有
内存和 CPU"] + B["容器 B、C 饥饿"] + end + end + + subgraph Limit ["有 cgroups 限制"] + direction TB + subgraph HostRes2 ["宿主机资源"] + direction LR + C_A["A
1GB
2核"] + C_B["B
1GB
1核"] + C_C["C
1GB
1核"] + end + end +``` +--- + +### 12.3.2 cgroups 的历史 + +| 时间 | 事件 | +|------|------| +| 2006 | Google 工程师提出 “process containers” 概念 | +| 2007 | 为避免与 Linux 容器概念混淆，更名为 “control groups” (cgroups) | +| 2008 | Linux 2.6.24（2008 年 1 月）正式合并 cgroups v1 | +| 2016 | Linux 4.5 引入 cgroups v2 | +| 现在 | Docker 在宿主机支持 cgroups v2 时会自动使用 v2，否则回退到 v1 | + +--- + +### 12.3.3 cgroups 可以限制的资源 + +| 资源类型 | 子系统 | 说明 | +|---------|--------|------| +| **CPU** | `cpu`, `cpuset` | CPU 使用时间和核心分配 | +| **内存** | `memory` | 内存使用上限和 swap | +| **块设备 I/O** | `blkio` | 磁盘读写速度限制 | +| **网络** | `net_cls`, `net_prio` | 网络带宽优先级 | +| **进程数** | `pids` | 限制进程/线程数量 | + +--- + +### 12.3.4 Docker 中的资源限制 + +Docker 提供了丰富的参数来配置容器的资源限制，主要包括内存、CPU、磁盘 I/O 等。 + +#### 内存限制 + +```bash +## 限制容器最多使用 512MB 内存 + +$ docker run -m 512m myapp + +## 限制内存 + swap + +$ docker run -m 512m --memory-swap 1g myapp + +## 软限制（超过时警告，不会 OOM Kill） + +$ docker run --memory-reservation 256m myapp +``` +| 参数 | 说明 | +|------|------| +| `-m` / `--memory` | 硬限制（超过会 OOM Kill）| +| `--memory-swap` | 内存 + swap 总限制 | +| `--memory-reservation` | 软限制（内存竞争时生效）| +| `--oom-kill-disable` | 禁用 OOM Killer（谨慎使用）| + +#### CPU 限制 + +```bash +## 限制使用 1.5 个 CPU 核心 + +$ docker run --cpus=1.5 myapp + +## 限制使用 CPU 0 和 1 + +$ docker run --cpuset-cpus="0,1" myapp + +## 设置 CPU 使用权重（相对值，默认 1024） + +$ docker run --cpu-shares=512 myapp +``` +| 参数 | 说明 | +|------|------| +| `--cpus` | 限制 CPU 核心数（如 1.5）| +| `--cpuset-cpus` | 绑定到特定 CPU 核心 | +| `--cpu-shares` | CPU 时间片权重（相对值）| +| `--cpu-period` / `--cpu-quota` | 精细控制 CPU 配额 | + +#### 磁盘 I/O 限制 + +```bash +## 限制设备写入速度为 10MB/s + +$ docker run --device-write-bps /dev/sda:10mb myapp + +## 限制设备读取速度 + +$ docker run --device-read-bps /dev/sda:10mb myapp + +## 限制 IOPS + +$ docker run --device-write-iops /dev/sda:100 myapp +``` + +#### 进程数限制 + +```bash +## 限制最多 100 个进程 + +$ docker run --pids-limit=100 myapp +``` +--- + +### 12.3.5 查看容器资源使用 + +```bash +## 实时监控所有容器的资源使用 + +$ docker stats +CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O +abc123 web 0.50% 45.5MiB / 512MiB 8.89% 1.2kB / 0B 0B / 0B +def456 db 2.30% 256MiB / 1GiB 25.00% 5.6kB / 3.2kB 4.1MB / 2.3MB + +## 查看特定容器 + +$ docker stats mycontainer + +## 查看容器的 cgroup 配置 + +$ docker inspect mycontainer --format '{{json .HostConfig}}' | jq +``` +--- + +### 12.3.6 资源限制的效果 + +#### 内存超限 + +```bash +## 启动限制 100MB 内存的容器 + +$ docker run -m 100m stress --vm 1 --vm-bytes 200M + +## 容器会被 OOM Killer 杀死 + +$ docker ps -a +CONTAINER ID STATUS NAMES +abc123 Exited (137) 5 seconds ago hopeful_darwin + +## 137 = 128 + 9，表示被 SIGKILL（9） 杀死 + +... +``` + +#### CPU 限制验证 + +```bash +## 不限制 CPU + +$ docker run --rm stress --cpu 4 + +## 占满所有 CPU + +## 限制为 1 个核心 + +$ docker run --rm --cpus=1 stress --cpu 4 + +## 只能使用约 100% CPU（1 个核心） + +... +``` +--- + +### 12.3.7 cgroups v1 vs v2 + +| 特性 | cgroups v1 | cgroups v2 | +|------|-----------|-----------| +| 层级结构 | 多层级（每个资源单独）| 统一层级 | +| 管理复杂度 | 复杂 | 简化 | +| 资源分配 | 基于层级 | 基于子树 | +| PSI（压力监控）| ❌ | ✅ | +| rootless 容器 | 部分支持 | 完整支持 | + +#### Docker 对 cgroups v2 的支持 + +Docker 20.10+ 开始支持 cgroups v2（如果系统支持），提供更好的性能和资源隔离。cgroup 驱动可以通过 Docker 守护进程配置文件 `/etc/docker/daemon.json` 的 `exec-opts` 配置项指定： + +```json +{ + "exec-opts": ["native.cgroupdriver=systemd"] +} +``` + +`native.cgroupdriver` 仅支持 `systemd` 和 `cgroupfs` 两个取值；若不指定，cgroup v1 主机默认使用 `cgroupfs`，带 systemd 的 cgroup v2 主机默认使用 `systemd`。重启 Docker 守护进程后生效。 + +#### 检查系统使用的版本 + +```bash +## 查看 cgroup 版本 + +$ mount | grep cgroup +cgroup2 on /sys/fs/cgroup type cgroup2 (rw,nosuid,nodev,noexec,relatime) + +## 如果显示 cgroup2 表示 v2 + +## 或者 + +$ cat /proc/filesystems | grep cgroup +nodev cgroup +nodev cgroup2 +``` +--- + +### 12.3.8 在 Compose 中设置限制 + +在 Compose 中设置限制配置如下： + +```yaml +services: + web: + image: nginx + deploy: + resources: + limits: + cpus: '0.5' + memory: 512M + reservations: + cpus: '0.25' + memory: 256M +``` +--- + +### 12.3.9 最佳实践 + +在使用 Cgroups 限制资源时，遵循一些最佳实践可以避免潜在的问题。 + +#### 1. 始终设置内存限制 + +```bash +## 防止 OOM 影响宿主机 + +$ docker run -m 1g myapp +``` + +#### 2. 为关键应用设置 CPU 保证 + +```bash +$ docker run --cpus=2 --cpu-shares=2048 critical-app +``` + +#### 3. 监控资源使用 + +```bash +## 配合 Prometheus + cAdvisor 监控 + +$ docker run -d --name cadvisor \ + -v /:/rootfs:ro \ + -v /var/run:/var/run:ro \ + -v /sys:/sys:ro \ + -v /var/lib/docker:/var/lib/docker:ro \ + ghcr.io/google/cadvisor +``` +--- diff --git a/12_implementation/12.4_ufs.md b/12_implementation/12.4_ufs.md new file mode 100644 index 000000000..c96fa2357 --- /dev/null +++ b/12_implementation/12.4_ufs.md @@ -0,0 +1,217 @@ +## 12.4 联合文件系统 + +联合文件系统 (UnionFS) 是 Docker 镜像分层存储的基础，它允许将多个目录挂载为同一个虚拟文件系统。 + +### 12.4.1 什么是联合文件系统 + +联合文件系统 (UnionFS) 是一种 **分层、轻量级** 的文件系统，它将多个目录 “联合” 挂载到同一个虚拟目录，形成一个统一的文件系统视图。 + +> **核心思想**：将多个只读层叠加，最上层可写，形成完整的文件系统。 + +```mermaid +flowchart TD + ContainerFS["容器看到的文件系统
/bin /etc /lib /usr /var /app /data"] + UnionFS["UnionFS 联合挂载"] + + ContainerLayer["容器层 (读写) : /app/data/log.txt (新写入)"] + ImageLayer3["镜像层3 (只读) : /app/app.py"] + ImageLayer2["镜像层2 (只读) : /usr/local/bin/python"] + ImageLayer1["镜像层1 (只读) : /bin /etc /lib (基础系统)"] + + ContainerFS --> UnionFS + UnionFS --> ContainerLayer --> ImageLayer3 --> ImageLayer2 --> ImageLayer1 +``` +--- + +### 12.4.2 为什么 Docker 使用联合文件系统 + +Docker 选择联合文件系统作为其存储驱动，主要基于以下几个核心优势。 + +#### 1. 镜像分层复用 + +```mermaid +flowchart TD + Nginx["nginx:alpine"] --> Alpine["alpine:3.19 (共享基础层)"] + MyApp["myapp:latest"] --> Alpine +``` +多个镜像共享相同的底层，节省磁盘空间。 + +#### 2. 快速构建 + +每个 Dockerfile 指令创建一层，只有变化的层需要重建： + +```docker +FROM node:22 # 层1：基础镜像 +COPY package.json ./ # 层2：依赖定义 +RUN npm install # 层3：安装依赖 +COPY . . # 层4：应用代码 +``` +代码变化时，只需重建层 4，层 1-3 使用缓存。 + +#### 3. 容器启动快 + +容器启动时不需要复制镜像，只需： + +1. 在镜像层上创建一个薄的可写层 +2. 联合挂载所有层 + +--- + +### 12.4.3 Copy-on-Write：写时复制 + +当容器修改只读层中的文件时： + +```mermaid +flowchart LR + subgraph Before ["修改前"] + direction TB + B_C["容器层 (空)"] + B_I["镜像层
/etc/nginx.conf"] + end + + subgraph After ["修改后"] + direction TB + A_C["容器层
/etc/nginx.conf ← 复制到容器层后修改"] + A_I["镜像层
/etc/nginx.conf (原文件仍在，但被遮蔽)"] + end + B_C --- B_I + A_C --- A_I +``` +**流程**： + +1. 从只读层读取文件 +2. 复制到容器的可写层 +3. 在可写层中修改 +4. 后续读取使用可写层的版本 + +--- + +### 12.4.4 Docker 支持的存储驱动 + +Docker 的存储驱动经历了从早期各式各样的机制（如 aufs, devicemapper），到被广泛使用的现代经典 graph driver (`overlay2`)，再到当下（Engine v29.x 及以后）**在新安装场景中默认启用的 containerd 镜像存储引擎（containerd image store）** 的演进。 + +| 存储后端 / 驱动 | 核心特性说明 | 推荐程度 | +|---------|------|---------| +| **containerd image store**|（v29.x 新一代默认后端，新装默认）基于 containerd 的 snapshotters，原生支持 OCI image index、多架构镜像与 Attestations 构建溯源元数据存储；启用 `userns-remap` 时不可用。 | ✅**强烈推荐（现代默认）** | +| **overlay2**|（经典 Graph Driver）传统架构下的现代 Linux 默认驱动，性能优秀，但在处理复杂溯源元数据（索引）时受限。 | ✅**推荐（主要后备）** | +| **aufs** | 早期默认，已从现代 Docker Engine 移除 | 历史资料 | +| **btrfs**/**zfs** | 使用原生稳定文件系统快照能力 | 特定场景 | +| **devicemapper** | 块设备级存储，已从现代 Docker Engine 移除 | 历史资料 | +| **vfs** | 不使用 CoW，每层完整复制 | 仅测试 | + +#### Classic Graph Drivers 与 Snapshotters 的核心差异 + +传统模型（如 `overlay2`）将镜像拉取解包的过程由 Docker 的 graph drivers 处理。而新的 `containerd image store` 则将这一职责彻底下放给了 `containerd` 自身的 `snapshotters`（底层在 Linux 发行版通常依然利用操作系统的 overlayfs）。这种架构改变带来了： + +1. 本地免拉取查看多平台镜像 index manifest 与 attestations (SBOM、Provenance)。 +2. 允许 Docker 使用 containerd snapshotters 管理镜像层，便于与现代 OCI 生态能力对齐。它不表示 kubelet/containerd 会自动复用 Docker 本地镜像；Kubernetes 镜像分发仍应以 registry、镜像拉取策略和运行时配置为准。 + +#### 查看当前存储驱动与后端 + +```bash +## 查看默认存储驱动 +$ docker info | grep "Storage Driver" +Storage Driver: overlay2 + +## 在 Engine v29.x 中，可以通过如下输出验证是否开启了 containerd 镜像后端： +$ docker info -f '{{ .DriverStatus }}' +[[driver-type io.containerd.snapshotter.v1]] +``` +--- + +### 12.4.5 overlay2 工作原理 + +在经典 graph driver 体系下，overlay2 仍是 Linux 上的主要推荐驱动；Docker Engine 29 新安装场景默认走 containerd image store/snapshotter。 + +```mermaid +flowchart TD + Merged["merged (合并视图)
容器看到的完整文件系统"] + OverlayFS["OverlayFS"] + + Upper["upper
(容器层)
读写"] + Lower2["lower2
(镜像层)
只读"] + Lower1["lower1
(基础层)
只读"] + + Merged --> OverlayFS + OverlayFS --> Upper + OverlayFS --> Lower2 + OverlayFS --> Lower1 +``` + +- **lowerdir**：只读的镜像层（可以有多个） +- **upperdir**：可写的容器层 +- **workdir**：OverlayFS 的工作目录 +- **merged**：联合挂载后的视图 + +#### 文件操作行为 + +| 操作 | 行为 | +|------|------| +| **读取** | 从上到下查找第一个匹配的文件 | +| **创建** | 在 upper 层创建 | +| **修改** | 如果在 lower 层，先复制到 upper 层再修改 | +| **删除** | 在 upper 层创建 whiteout 文件标记删除 | + +--- + +### 12.4.6 查看镜像层 + +```bash +## 查看镜像的层信息 + +$ docker history nginx:alpine +IMAGE CREATED CREATED BY SIZE +a6eb2a334a9f 2 weeks ago CMD ["nginx" "-g" "daemon off;"] 0B +
完全隔离（性能损耗）"] + direction TB + Guest["Guest OS"] + Hyper["Hypervisor
<-- 隔离边界"] + Host["Host OS"] + Guest --> Hyper --> Host + end + + subgraph Container ["容器安全模型：
进程隔离（轻量但需加固）"] + direction TB + Proc["容器进程
(共享内核)"] + Mech["Namespace <-- 隔离边界
Cgroups
Capabilities"] + Proc --> Mech + end +``` + +## 本章内容 + +本章涵盖 Docker 安全的多个层面，从内核隔离机制到运行时防护和供应链安全。 + +* [内核命名空间](18.1_kernel_ns.md) + * 命名空间的安全意义、User Namespace 与提权防护。 + +* [控制组](18.2_control_group.md) + * 通过 Cgroups 限制容器资源使用，防止资源耗尽攻击。 + +* [服务端防护](18.3_daemon_sec.md) + * Docker 守护进程的安全配置与网络访问控制。 + +* [内核能力机制](18.4_kernel_capability.md) + * Linux Capabilities 的细粒度权限控制。 + +* [其他安全特性](18.5_other_feature.md) + * 镜像安全（漏洞扫描、签名验证）、运行时安全（非 root 运行、只读文件系统、Seccomp、AppArmor）、Dockerfile 安全实践、软件供应链安全（SBOM、SLSA）。 + +* [镜像安全](18.6_image_security.md) + * 容器镜像的安全扫描、漏洞检测与签名验证。 + +## 安全扫描清单 + +部署前检查： + +| 检查项 | 命令/方法 | +|--------|----------| +| 漏洞扫描 | `docker scout cves` 或 `trivy` | +| 非 root 运行 | 检查 Dockerfile 中的 `USER` | +| 资源限制 | 检查 `-m`, `--cpus` 参数 | +| 只读文件系统 | 检查 `--read-only` | +| 无特权模式 | 确认没有 `--privileged` | +| 最小能力 | 检查 `--cap-drop=all` | +| 网络隔离 | 检查网络配置 | +| 敏感信息 | 确认无硬编码密码 | diff --git a/18_security/summary.md b/18_security/summary.md new file mode 100644 index 000000000..440f23e74 --- /dev/null +++ b/18_security/summary.md @@ -0,0 +1,18 @@ +## 本章小结 + +Docker 的安全性依赖于多层隔离机制的协同工作，同时需要用户遵循最佳实践。本章涵盖的核心安全维度包括： + +| 维度 | 关键措施 | +|------|---------| +| **内核隔离** | Namespace 隔离进程/网络/文件系统，Cgroups 限制资源使用 | +| **权限控制** | 非 root 运行、`--cap-drop ALL` 最小能力集、`--read-only` 只读根文件系统 | +| **镜像安全** | 使用可信基础镜像、定期扫描漏洞（Trivy / Snyk）、启用 Sigstore / Notation / Registry 原生签名验证；DCT 仅作为遗留迁移对象 | +| **运行时防护** | Seccomp 系统调用过滤、AppArmor / SELinux 强制访问控制 | +| **网络隔离** | 自定义 bridge 网络隔离容器通信、限制容器对宿主机网络的访问 | + +总体来看，Docker 容器还是十分安全的，特别是在容器内不使用 root 权限来运行进程的话。 + +另外，用户可以使用现有工具，比如 [Apparmor](https://docs.docker.com/engine/security/apparmor/)，[Seccomp](https://docs.docker.com/engine/security/seccomp/)，SELinux，GRSEC 来增强安全性；甚至自己在内核中实现更复杂的安全机制。 +--- + +> 📝 **发现错误或有改进建议？** 欢迎提交 [Issue](https://github.com/yeasy/docker_practice/issues) 或 [PR](https://github.com/yeasy/docker_practice/pulls)。 diff --git a/19_observability/19.1_prometheus.md b/19_observability/19.1_prometheus.md new file mode 100644 index 000000000..e880c0f0e --- /dev/null +++ b/19_observability/19.1_prometheus.md @@ -0,0 +1,267 @@ +## 19.1 Prometheus + +Prometheus 和 Grafana 是目前最流行的开源监控组合，前者负责数据采集与存储，后者负责数据可视化。 + +[Prometheus](https://prometheus.io/) 是一个开源的系统监控和报警工具包。它受 Google Borgmon 的启发，由 SoundCloud 在 2012 年创建。 + +### 19.1.1 架构简介 + +Prometheus 的主要组件包括： + +* **Prometheus Server**：核心组件，负责收集和存储时间序列数据。 +* **Exporters**：负责向 Prometheus 暴露监控数据（如 Node Exporter，cAdvisor）。 +* **Alertmanager**：处理报警发送。 +* **Pushgateway**：用于支持短生命周期的 Job 推送数据。 + +### 19.1.2 快速部署 + +我们可以使用 Docker Compose 快速部署一套 Prometheus + Grafana 监控环境。 + +本节示例使用了： + +* `node-exporter`：采集宿主机指标（CPU、内存、磁盘、网络等）。 +* `cAdvisor`：采集容器指标（容器 CPU/内存/网络 IO、文件系统等）。 + +在生产环境中，建议将 Prometheus 的数据目录做持久化，并显式配置数据保留周期。 + +#### 1. 准备配置文件 + +创建 `prometheus.yml`： + +```yaml +global: + scrape_interval: 15s + +scrape_configs: + - job_name: 'prometheus' + static_configs: + - targets: ['localhost:9090'] + + - job_name: 'node-exporter' + static_configs: + - targets: ['node-exporter:9100'] + + - job_name: 'cadvisor' + static_configs: + - targets: ['cadvisor:8080'] + +rule_files: + - /etc/prometheus/rules.yml +``` + +#### 2. 编写 Docker Compose 文件 + +创建 `compose.yaml`（或 `docker-compose.yml`）。下面示例使用的是相对较新的稳定版本。**镜像版本提示**：本示例中 Prometheus、Grafana、node-exporter、cAdvisor 的版本号仅为参考。生产环境部署前，请查阅以下官方资源确认最新推荐版本： +- [Prometheus 官方文档](https://prometheus.io/docs/prometheus/latest/installation/) +- [Grafana 官方发布](https://grafana.com/grafana/download) +- [node-exporter 发布页](https://github.com/prometheus/node_exporter/releases) +- [cAdvisor 发布页](https://github.com/google/cadvisor/releases) + +```yaml +services: + prometheus: + image: prom/prometheus:v3.11.2 + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml + - ./rules.yml:/etc/prometheus/rules.yml + - prometheus_data:/prometheus + ports: + - "127.0.0.1:9090:9090" + command: + - --config.file=/etc/prometheus/prometheus.yml + - --storage.tsdb.path=/prometheus + - --storage.tsdb.retention.time=15d + networks: + - monitoring + + grafana: + image: grafana/grafana:13.0.1 + ports: + - "127.0.0.1:3000:3000" + environment: + - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:?set GRAFANA_ADMIN_PASSWORD} + networks: + - monitoring + depends_on: + - prometheus + + node-exporter: + image: prom/node-exporter:v1.11.1 + ports: + - "127.0.0.1:9100:9100" + networks: + - monitoring + + cadvisor: + image: ghcr.io/google/cadvisor:v0.56.2 + ports: + - "127.0.0.1:8080:8080" + volumes: + - /:/rootfs:ro + - /var/run:/var/run:ro + - /sys:/sys:ro + - /var/lib/docker/:/var/lib/docker:ro + networks: + - monitoring + +networks: + monitoring: + +volumes: + prometheus_data: +``` + +#### 3. 启动服务 + +```bash +$ docker compose up -d +``` +启动后，访问以下地址： + +* Prometheus: `http://localhost:9090` +* Grafana：`http://localhost:3000`（账号为 `admin`，密码来自 `GRAFANA_ADMIN_PASSWORD`） + +> 安全提示：cAdvisor 需要读取宿主机 `/sys`、`/var/run`、Docker 数据目录等路径才能采集容器指标；即使是只读挂载，也会暴露宿主机和容器元数据。只在受控监控节点使用，并把 Prometheus、Grafana、cAdvisor 端口绑定到本机或受保护网络。 + +### 19.1.3 配置 Grafana 面板 + +1. 在 Grafana 中添加 Prometheus 数据源，URL 填写 `http://prometheus:9090`。 +2. 导入现成的 Dashboard 模板，例如 [Node Exporter Full](https://grafana.com/grafana/dashboards/1860) (ID：1860) 和 [Docker Container](https://grafana.com/grafana/dashboards/193) (ID：193)。 + +这样，你就拥有了一个直观的容器监控大屏。 + +### 19.1.4 生产要点与告警闭环 + +完成部署后，建议补齐以下生产要点。 + +#### 指标采集的“最小闭环” + +1. 在 Prometheus 页面打开 **Status -> Targets**，确认 `prometheus`、`node-exporter`、`cadvisor` 的 `State` 均为 `UP`。 +2. 在 **Graph** 中尝试查询： + + * `up` + * `rate(container_cpu_usage_seconds_total[5m])` + +3. 在 Grafana Dashboard 中重点关注： + + * 宿主机 CPU/Load/内存/磁盘 + * 容器 CPU/内存使用率、容器重启次数 + +如果你发现“面板为空”，通常不是 Grafana 的问题，而是 Prometheus 没抓到数据或查询标签与 Dashboard 不匹配。 + +#### 常见问题排查 + +* **Target down**：检查容器网络是否互通，端口是否暴露到同一网络，以及 exporter 是否在容器内正常监听。 +* **cAdvisor 无数据或报错**：确认挂载了 Docker 目录与宿主机的 `/sys`、`/var/run` 等路径，并确保宿主机上 Docker 运行正常。 +* **指标缺失**：确认你的 Docker/内核版本与 cAdvisor 兼容；对于 containerd 等运行时，采集方式会不同。 + +#### 关键指标速查：节点/容器 + +在生产环境排障时，建议优先关注下面几类指标，并在 Grafana 面板中建立对应的常用视图。 + +* **节点 CPU 使用率**：`100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)` +* **节点内存使用率**：`(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100` +* **节点磁盘空间使用率**：`(1 - (node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"})) * 100` +* **容器 CPU**：`sum by (namespace, pod, container) (rate(container_cpu_usage_seconds_total[5m]))` +* **容器内存**：`sum by (namespace, pod, container) (container_memory_working_set_bytes)` + +说明：不同采集路径的 label 命名不同。Docker Compose 中独立部署的 cAdvisor 常见容器标签是 `name`；Kubernetes kubelet 的 `/metrics/cadvisor` 中，`container_cpu_usage_seconds_total` 等稳定指标使用 `container`、`pod`、`namespace`。如果查询为空，先直接查询 `container_cpu_usage_seconds_total` 样本并在 Prometheus 图形界面查看实际 label，不要假设存在 `container_name`。 + +#### Targets down 排错清单 + +当 **Status -> Targets** 出现 `DOWN` 时，建议按以下顺序排查： + +1. **网络连通性**：Prometheus 容器是否能解析并访问目标（同一 Docker network、DNS、端口）。 +2. **端口/路径**：确认 exporter 监听端口与 Prometheus 配置一致；必要时在 Prometheus 容器内 `curl http://node-exporter:9100/metrics`。 +3. **权限/挂载**：cAdvisor 需要访问宿主机 `/sys`、`/var/lib/docker` 等挂载路径，缺失会导致指标不全或报错。 +4. **时间问题**：宿主机与容器时间偏差过大可能导致“数据看起来断档”，需要检查 NTP/时区配置。 +5. **目标本身异常**：确认 exporter 容器是否在重启，查看 `docker logs`。 + +#### Alertmanager 告警建议 + +生产环境建议引入 Alertmanager 做告警聚合与路由，并在 Prometheus 中配置 `alerting` 与 `rule_files`。 + +为了保持“最小告警闭环”，建议至少覆盖两类告警： + +* **采集链路告警**：例如 `up == 0`，用于发现 exporter 或网络故障。 +* **资源风险告警**：例如节点磁盘空间不足，用于提前发现容量风险。 + +##### 1. 准备告警规则文件 + +创建 `rules.yml`： + +```yaml +groups: + - name: docker_practice + rules: + - alert: PrometheusTargetDown + expr: up == 0 + for: 2m + labels: + severity: warning + annotations: + summary: "Prometheus 抓取目标不可达" + description: "Job={{ $labels.job }}, Instance={{ $labels.instance }}" + + - alert: HostDiskSpaceLow + expr: | + (node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"}) < 0.10 + for: 10m + labels: + severity: critical + annotations: + summary: "磁盘可用空间不足" + description: "Instance={{ $labels.instance }}, Mountpoint={{ $labels.mountpoint }}" +``` +说明：这里的规则是“可用空间低于 10%”的阈值告警，并非“未来 24 小时写满”的预测。生产环境建议针对特定文件系统与挂载点做更精确的过滤。 + +##### 2. 配置 Prometheus 加载规则并接入 Alertmanager + +修改 `prometheus.yml`，增加： + +```yaml +rule_files: + - /etc/prometheus/rules.yml + +alerting: + alertmanagers: + - static_configs: + - targets: ["alertmanager:9093"] +``` +并在 Compose 中挂载规则文件。 + +##### 3. 部署 Alertmanager + +创建 `alertmanager.yml`： + +```yaml +route: + receiver: default + +receivers: + - name: default + webhook_configs: + - url: http://example.com/webhook +``` +再在 `compose.yaml` 增加服务： + +```yaml + alertmanager: + image: prom/alertmanager:v0.32.0 + volumes: + - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml + ports: + - "9093:9093" + networks: + - monitoring +``` +生产环境中，建议将告警发送到可追踪的渠道（如 IM 机器人、事件平台、工单系统），并在告警中附带 Dashboard 链接与排障入口，避免告警成为噪声。 + +#### 建议的文件清单 + +为了避免示例难以复现，建议在同一目录下准备以下文件： + +* `compose.yaml`：Prometheus、Grafana、exporters、Alertmanager 的部署文件 +* `prometheus.yml`：Prometheus 抓取配置与告警配置 +* `rules.yml`：告警规则 +* `alertmanager.yml`：告警路由与接收器配置 diff --git a/19_observability/19.2_elk.md b/19_observability/19.2_elk.md new file mode 100644 index 000000000..1405e8a33 --- /dev/null +++ b/19_observability/19.2_elk.md @@ -0,0 +1,208 @@ +## 19.2 ELK 套件 + +ELK (Elasticsearch，Logstash，Kibana) 是目前业界最流行的开源日志解决方案。而在容器领域，由于 Fluentd 更加轻量级且对容器支持更好，EFK (Elasticsearch，Fluentd，Kibana) 组合也变得非常流行。 + +### 19.2.1 方案架构 + +我们将采用以下架构： + +1. **Docker Container**：容器将日志输出到标准输出 (stdout/stderr)。 +2. **Fluentd**：作为 Docker 的 Logging Driver 或运行为守护容器，收集容器日志。 +3. **Elasticsearch**：存储从 Fluentd 接收到的日志数据。 +4. **Kibana**：从 Elasticsearch 读取数据并进行可视化展示。 + +### 19.2.2 部署流程 + +我们将使用 Docker Compose 来一键部署整个日志堆栈。 + +#### 1. 编写 Compose 文件 + +1. 编写 `compose.yaml`（或 `docker-compose.yml`）配置如下。**版本提示**：本示例使用 Elasticsearch 9.x、Kibana 9.x、Fluentd 等组件的特定版本号，仅作为参考。生产环境部署前，请查阅 [Elastic 官方文档](https://www.elastic.co/docs/) 和 [Fluentd 官方文档](https://docs.fluentd.org/) 确认最新版本与配置兼容性。 + +```yaml +services: + elasticsearch: + image: docker.elastic.co/elasticsearch/elasticsearch:9.4.0 + container_name: elasticsearch + environment: + - "discovery.type=single-node" + - "xpack.security.enabled=false" + - "ES_JAVA_OPTS=-Xms512m -Xmx512m" + ports: + - "9200:9200" + volumes: + - es_data:/usr/share/elasticsearch/data + networks: + - logging + + kibana: + image: docker.elastic.co/kibana/kibana:9.4.0 + container_name: kibana + environment: + - ELASTICSEARCH_HOSTS=http://elasticsearch:9200 + ports: + - "5601:5601" + networks: + - logging + + fluentd: + # elasticsearch8 插件通过 REST API 与 ES 9.x 兼容 + image: fluent/fluentd-kubernetes-daemonset:v1.17-debian-elasticsearch8-1 + container_name: fluentd + environment: + - "FLUENT_ELASTICSEARCH_HOST=elasticsearch" + - "FLUENT_ELASTICSEARCH_PORT=9200" + - "FLUENT_ELASTICSEARCH_SCHEME=http" + - "FLUENT_UID=0" + ports: + - "24224:24224" + - "24224:24224/udp" + volumes: + - ./fluentd/conf:/fluentd/etc + networks: + - logging + +volumes: + es_data: + +networks: + logging: +``` + +#### 2. 配置 Fluentd + +创建 `fluentd/conf/fluent.conf`： + +```ini +
+
+
+
+
+
+
+
+
+
diff --git a/_images/swarm.png b/_images/swarm.png
deleted file mode 100644
index 4af7b271a..000000000
Binary files a/_images/swarm.png and /dev/null differ
diff --git a/_images/tencent-cloud-container-service.png b/_images/tencent-cloud-container-service.png
new file mode 100644
index 000000000..31a981b43
Binary files /dev/null and b/_images/tencent-cloud-container-service.png differ
diff --git a/_images/ubuntu-logo.jpg b/_images/ubuntu-logo.jpg
new file mode 100644
index 000000000..4138fab12
Binary files /dev/null and b/_images/ubuntu-logo.jpg differ
diff --git a/_layouts/website/page.html b/_layouts/website/page.html
deleted file mode 100644
index cabab1bde..000000000
--- a/_layouts/website/page.html
+++ /dev/null
@@ -1,12 +0,0 @@
-{% extends template.self %}
-
-{% block head %}
- {{ super() }}
-
-{% endblock %}
diff --git a/_local/.bashrc_docker b/_local/.bashrc_docker
deleted file mode 100644
index ed0df3ca1..000000000
--- a/_local/.bashrc_docker
+++ /dev/null
@@ -1,49 +0,0 @@
-# Some useful commands to use docker.
-# Author: yeasy@github
-# Created:2014-09-25
-
-alias docker-pid="sudo docker inspect --format '{{.State.Pid}}'"
-alias docker-ip="sudo docker inspect --format '{{ .NetworkSettings.IPAddress }}'"
-
-#the implementation refs from https://github.com/jpetazzo/nsenter/blob/master/docker-enter
-function docker-enter() {
- #if [ -e $(dirname "$0")/nsenter ]; then
- #Change for centos bash running
- if [ -e $(dirname '$0')/nsenter ]; then
- # with boot2docker, nsenter is not in the PATH but it is in the same folder
- NSENTER=$(dirname "$0")/nsenter
- else
- # if nsenter has already been installed with path notified, here will be clarified
- NSENTER=$(which nsenter)
- #NSENTER=nsenter
- fi
- [ -z "$NSENTER" ] && echo "WARN Cannot find nsenter" && return
-
- if [ -z "$1" ]; then
- echo "Usage: `basename "$0"` CONTAINER [COMMAND [ARG]...]"
- echo ""
- echo "Enters the Docker CONTAINER and executes the specified COMMAND."
- echo "If COMMAND is not specified, runs an interactive shell in CONTAINER."
- else
- PID=$(sudo docker inspect --format "{{.State.Pid}}" "$1")
- if [ -z "$PID" ]; then
- echo "WARN Cannot find the given container"
- return
- fi
- shift
-
- OPTS="--target $PID --mount --uts --ipc --net --pid"
-
- if [ -z "$1" ]; then
- # No command given.
- # Use su to clear all host environment variables except for TERM,
- # initialize the environment variables HOME, SHELL, USER, LOGNAME, PATH,
- # and start a login shell.
- #sudo $NSENTER "$OPTS" su - root
- sudo $NSENTER --target $PID --mount --uts --ipc --net --pid su - root
- else
- # Use env to clear all host environment variables.
- sudo $NSENTER --target $PID --mount --uts --ipc --net --pid env -i $@
- fi
- fi
-}
diff --git a/_local/docker_manual_waitfish.pdf b/_local/docker_manual_waitfish.pdf
deleted file mode 100644
index add8577a3..000000000
Binary files a/_local/docker_manual_waitfish.pdf and /dev/null differ
diff --git a/_local/pull_all.sh b/_local/pull_all.sh
deleted file mode 100644
index 8240c0802..000000000
--- a/_local/pull_all.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/sh
-
-# This script will update all local images
-# See: https://github.com/yeasy/docker_practice/blob/master/_local/pull_all.sh
-# Usage: pull_all
-# Author: yeasy@github
-# Create: 2014-09-23
-
-for image in `sudo docker images|grep -v "REPOSITORY"|grep -v "
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Navigation Menu
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {{ message }}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Mac/Win: 启动 Docker Desktop | +| `permission denied while trying to connect to the Docker daemon socket` | 当前用户无权访问 Docker socket | 临时使用 `sudo docker ...`，或确认风险后执行 `sudo usermod -aG docker $USER` 并重新登录；`docker` 用户组等同授予 root 级权限，安全要求较高的环境优先评估 Rootless mode | +| `manifest for ... not found: manifest unknown` | 镜像 tag 不存在 | 检查 Docker Hub 该镜像是否存在该 tag，或拼写是否正确 | +| `connection refused` (pull image) | 网络不通或镜像源无法访问 | 检查网络，配置[镜像加速器](../../03_install/3.9_mirror.md) | +| `Bind for 0.0.0.0:8080 failed: port is already allocated` | 端口被占用 | 检查占用端口的进程 (`lsof -i:8080`) 并杀掉，或换个端口映射 (`-p 8081:80`) | +| `exec user process caused "exec format error"` | 架构不匹配（如在 x86 上跑 ARM 镜像）| 使用 `docker buildx` 构建多架构镜像，或拉取对应架构的镜像 | +| `standard_init_linux.go:211: exec user process caused "no such file or directory"` | 找不到解释器或依赖库 | 检查 `ENTRYPOINT`/`CMD` 脚本开头的 shebang (`#!/bin/sh` vs `#!/bin/bash`)，或确认二进制文件是否依赖缺失（Alpine 常见缺少 glibc）| +| `iptables: No chain/target/match by that name` | 防火墙规则缺失或冲突 | 重启 Docker 服务重置 iptables 链: `sudo systemctl restart docker` | +| 容器内无法访问外网 | DNS 配置或转发问题 | 检查 `/etc/docker/daemon.json` 中的 DNS 配置 | diff --git a/appendix/glossary.md b/appendix/glossary.md new file mode 100644 index 000000000..694e467a5 --- /dev/null +++ b/appendix/glossary.md @@ -0,0 +1,82 @@ +## 附录七：术语表 + +本附录整理了本书中常见的一些专业术语及其解释。 + +## A + +* **Alpine**：一个轻量级的 Linux 发行版，常作为基础镜像用于构建体积较小的 Docker 镜像。 +* **API (Application Programming Interface)**：应用程序编程接口，Docker Daemon 提供 RESTful API 供客户端或外部程序与之交互。 + +## B + +* **Base Image（基础镜像）**：没有父镜像的镜像，通常是操作系统的最小安装集合（如 `ubuntu` 或 `alpine`）。 +* **BuildKit**：Docker 下一代的构建引擎，提供了更高的构建性能、更好的缓存处理和并发构建支持。 +* **Buildx**：Docker CLI 的一个插件，扩展了构建功能，支持 BuildKit 的所有高级特性，例如多系统架构镜像构建。 + +## C + +* **Cgroups (Control Groups)**：控制组，Linux 内核特性，用于限制、记录、隔离进程组使用的物理资源（如 CPU、内存、磁盘 I/O 等）。 +* **Cluster（集群）**：一组协同工作的节点（如主机、虚拟机等），在容器领域常指 Kubernetes 集群。 +* **Compose (Docker Compose)**：用于定义和运行多容器 Docker 应用程序的工具，通过 YAML 文件配置应用服务。 +* **Container（容器）**：镜像的运行实例，带有额外的可写文件层，具有独立性。 +* **Containerd**：行业标准的容器运行时，核心功能是管理宿主机上容器的生命周期（创建、启动、停止、销毁）。 + +## D + +* **Daemon（守护进程）**：Docker 的后台守护进程，负责接收和处理 Docker API 请求，并管理镜像、容器、网络和数据卷等对象。 +* **Docker**：开源的应用容器引擎，让开发者可以打包应用程序及其依赖包到一个可移植的容器中，然后发布到任何流行的 Linux 或 Windows 机器上。 +* **Docker Desktop**：包含 Docker Engine、Docker CLI 客户端、Docker Compose 和 Kubernetes 等的桌面应用程序，适用于 macOS 和 Windows。 +* **Docker Hub**：Docker 官方的公共镜像仓库服务，提供容器镜像的存储和分发。 +* **Dockerfile**：包含用于组合镜像的命令的文本文件，Docker 通过读取 `Dockerfile` 中的指令即可自动完成镜像构建。 + +## E + +* **Etcd**：一个高可用、强一致性的分布式键值存储系统，常用于容器集群（如 Kubernetes）的服务发现和状态配置管理。 + +## I + +* **Image（镜像）**：Docker 镜像是一个只读模板，带有创建 Docker 容器的说明。 + +## K + +* **Kubernetes (K8s)**：开源的容器编排引擎，用于自动化容器化应用程序的部署、扩展和管理。 + +## L + +* **Layer（镜像层）**：Docker 镜像由多个只读层叠合而成，每一层通常代表 Dockerfile 中的一条指令的操作结果，通过联合文件系统（UFS）叠加在一起形成完整的文件系统。 + +## M + +* **Multistage Build（多阶段构建）**：Dockerfile 中的特性，允许在同一个 Dockerfile 中使用多个 `FROM` 语句，从一个阶段复制所需的构建产物到另一个阶段，从而大幅减小最终镜像的体积。 + +## N + +* **Namespace（命名空间）**：Linux 内核特性，用于隔离各种系统资源，如进程、网络、挂载点等，使容器看起来就像是一个独立的操作系统。 +* **Node（节点）**：容器集群（如 Kubernetes）中的一台工作机器，可以是物理机或虚拟机。 + +## O + +* **OCI (Open Container Initiative)**：开放容器规范，由多家行业领头企业共同制定的容器运行时和镜像格式的行业标准。 +* **Orchestration（编排）**：自动化部署、管理、扩展和网络配置容器的系统和技术（如 Kubernetes）。 + +## P + +* **Pod**：Kubernetes 中最小的、可部署的计算单元，包含一个或多个紧密相关的容器，共享相同的网络命名空间和存储。 +* **Prometheus**：开源的系统监控和告警工具包，广泛应用于云原生的监控体系中。 + +## R + +* **Registry（注册服务器）**：提供 Docker 镜像下载和上传等存储分发服务的服务器。 +* **Repository（仓库）**：集中存放某个应用的所有镜像的地方，通常由镜像名定义。一个 Registry 中可以包含多个 Repository。 + +## S + +* **Swarm (Docker Swarm)**：Docker 原生的集群和编排管理工具，可将多个 Docker 主机组合成一个统一的虚拟 Docker 主机池。维护节点时通常将节点可用性设为 `Drain`，这只影响 Swarm service 调度，不会停止该节点上独立运行的容器。 + +## U + +* **UFS (Union File System)**：联合文件系统，一种分层、轻量级并且高性能的文件系统，它支持对文件系统的修改一层层叠加。 + +## V + +* **Volume（数据卷）**：专为绕过联合文件系统而设计的特殊目录，用于实现容器数据的持久化，或在多个容器之间提供文件共享。 diff --git a/appendix/learning_roadmap.md b/appendix/learning_roadmap.md new file mode 100644 index 000000000..94bb5fa53 --- /dev/null +++ b/appendix/learning_roadmap.md @@ -0,0 +1,875 @@ +## 附录八：Docker 学习路线图与知识体系 + +本附录为学习者提供清晰的学习路线、知识点依赖关系、认证指南和常见面试题，帮助快速成长为 Docker 和 DevOps 专家。 + +### 学习阶段划分 + +Docker 学习可分为四个递进阶段，每个阶段都有明确的学习目标和时间投入。 + +#### 第一阶段：基础入门（0-2 周） + +**学习目标：** + +- 理解容器化的基本概念 +- 能够运行、管理基本的容器 +- 了解镜像和仓库的基本操作 + +**核心内容：** +```text +Docker 简介 +├── 为什么需要 Docker +├── 容器 vs 虚拟机 vs 云计算 +└── Docker 的三大核心概念 + ├── 镜像（Image） + ├── 容器（Container） + └── 仓库（Repository） + +基础命令 +├── docker run / create / start / stop / rm +├── docker ps / logs / exec / inspect +├── docker pull / push / tag +└── docker build -t + +Docker 安装配置 +├── Linux 平台安装 +├── macOS 和 Windows 安装 +├── 镜像加速器配置 +└── 权限和用户配置 +``` +**学习资源：** + +- [官方教程](https://docs.docker.com/get-started/) +- 本书第 1-3 章：入门篇基础概念 +- [Docker CLI 参考](https://docs.docker.com/reference/cli/docker/) + +**时间投入：** + +- 理论学习：3-4 小时 +- 实操练习：8-10 小时 +- 总计：2 周 + +**验证学习成果：** +```bash +# 完成以下任务说明基础入门完成 +1. 运行官方 nginx 镜像，访问 http://localhost +2. 使用 docker exec 进入容器修改首页 +3. 提交修改为新镜像 +4. 推送镜像到 Docker Hub（需创建账户） +``` + +#### 第二阶段：核心开发（2-6 周） + +**学习目标：** + +- 掌握 Dockerfile 编写 +- 能够构建自己的应用镜像 +- 理解数据管理和网络配置 +- 熟悉 Docker Compose 编排 + +**核心内容：** +```text +Dockerfile 指令详解 +├── FROM / RUN / COPY / ADD +├── WORKDIR / ENV / ARG +├── EXPOSE / CMD / ENTRYPOINT +├── VOLUME / USER / HEALTHCHECK +└── 最佳实践和性能优化 + ├── 分层缓存机制 + ├── 减少镜像体积 + ├── 多阶段构建 + └── 安全最佳实践 + +容器数据管理 +├── 数据卷（Volume） +│ ├── 命名卷 +│ ├── 匿名卷 +│ └── 卷挂载最佳实践 +├── 绑定挂载（Bind Mount） +│ ├── 宿主机路径映射 +│ └── 权限和隔离 +└── tmpfs 挂载 + └── 临时文件系统 + +容器网络 +├── 网络类型 +│ ├── bridge（默认） +│ ├── host +│ ├── overlay +│ └── macvlan +├── 端口映射 +├── 容器互联 +├── DNS 配置 +└── 自定义网络 + +Docker Compose +├── compose.yml/docker-compose.yml 编写 +├── services 定义 +├── volumes 配置 +├── networks 配置 +├── 依赖关系 +├── 环境变量 +└── 命令操作 + ├── up / down / ps / logs + ├── exec / run + └── build / push +``` +**学习资源：** + +- 本书第 4-11 章：进阶篇 +- [Docker 官方最佳实践](https://docs.docker.com/build/building/best-practices/) +- [Dockerfile 参考](https://docs.docker.com/reference/dockerfile/) + +**时间投入：** + +- 理论学习：8-10 小时 +- 实操练习：30-40 小时（多个实战项目） +- 总计：4-6 周 + +**项目实战：** +```text +项目 1: Python Web 应用（Flask/Django） +- 编写多阶段 Dockerfile +- 使用 Compose 配置数据库 +- 实现热重载开发环境 + +项目 2: Node.js 微服务 +- 优化镜像大小 +- 配置 Compose 多个服务 +- 设置网络和环境变量 + +项目 3: 数据库容器化 +- PostgreSQL/MySQL 配置 +- 数据持久化 +- 备份恢复策略 +``` + +#### 第三阶段：生产优化（6-12 周） + +**学习目标：** + +- 掌握容器安全最佳实践 +- 理解性能监控和优化 +- 学会容器编排（Kubernetes 基础） +- 熟悉 CI/CD 集成 + +**核心内容：** +```text +容器安全 +├── 镜像安全 +│ ├── 漏洞扫描（Trivy/Grype/Snyk） +│ ├── 镜像签名和验证（Cosign） +│ ├── SBOM 生成和管理 +│ └── 供应链安全 +├── 运行时安全 +│ ├── 用户和权限 +│ ├── Linux 能力机制 +│ ├── AppArmor 和 SELinux +│ ├── Rootless 容器 +│ └── 安全的 Docker socket 访问 +└── 宿主机安全 + ├── API 访问控制 + ├── TLS 认证 + └── 审计日志 + +性能监控和优化 +├── 监控指标体系 +│ ├── CPU / 内存 / 网络 / I/O +│ └── 应用级指标 +├── 监控工具 +│ ├── docker stats +│ ├── cAdvisor +│ ├── Prometheus +│ └── Grafana +├── 性能优化 +│ ├── 镜像大小优化 +│ ├── 内存和 CPU 限制 +│ ├── OOM 诊断和处理 +│ └── 网络性能优化 +└── 日志管理 + ├── 日志驱动配置 + ├── ELK Stack + └── 日志聚合 + +容器编排基础 +├── Kubernetes 核心概念 +│ ├── Pod / Deployment / Service +│ ├── ConfigMap / Secret +│ └── 健康检查和自动恢复 +├── 容器执行环境 +│ ├── containerd +│ ├── CRI-O +│ └── Docker +├── 网络插件 +│ ├── CNI 标准 +│ ├── Calico / Flannel / Cilium +│ └── 网络策略 +└── 存储和有状态应用 + ├── PV / PVC + ├── StorageClass + └── StatefulSet + +CI/CD 集成 +├── GitHub Actions +│ ├── 镜像构建和推送 +│ ├── 安全扫描 +│ └── 自动化测试 +├── GitLab CI +├── Jenkins Docker 集成 +└── Drone + +生态工具 +├── Buildx（多架构构建） +├── Skopeo（镜像管理） +├── Podman（替代方案） +└── Buildah（镜像构建） +``` +**学习资源：** + +- 本书第 12-21 章：深入篇和实战篇 +- [Kubernetes 官方文档](https://kubernetes.io/docs/) +- [CNCF 学习路线](https://landscape.cncf.io/) + +**时间投入：** + +- 理论学习：15-20 小时 +- 实操练习：60-80 小时（多个生产级项目） +- 总计：6-12 周 + +**项目实战：** +```text +项目 1: 安全镜像构建流程 +- 集成 Trivy 扫描 +- 镜像签名和验证 +- 生成 SBOM 文档 + +项目 2: 完整监控栈 +- 搭建 Prometheus + Grafana +- 配置告警规则 +- 性能数据采集和分析 + +项目 3: CI/CD 流程 +- GitHub Actions 或 GitLab CI 配置 +- 自动化镜像构建 +- 安全扫描和合规检查 +- 自动化部署到 Kubernetes + +项目 4: Kubernetes 集群部署 +- 本地 K3s/Kind 集群 +- 部署有状态应用 +- 配置持久化存储 +``` + +#### 第四阶段：专家深造（12+ 周） + +**学习目标：** + +- 掌握 Kubernetes 高级特性 +- 理解容器运行时底层实现 +- 能够设计和优化大规模容器平台 +- 贡献开源社区 + +**核心内容：** +```text +Kubernetes 高级特性 +├── 集群管理 +│ ├── 节点管理和驱逐 +│ ├── 集群自动扩缩容 +│ └── 节点亲和性和污点容忍 +├── 存储编排 +│ ├── 动态存储配置 +│ ├── 有状态应用管理（StatefulSet） +│ └── 备份和灾难恢复 +├── 服务网格（Service Mesh） +│ ├── Istio / Linkerd / Cilium +│ ├── 流量管理 +│ └── 可观测性增强 +├── 安全和多租户 +│ ├── RBAC（角色访问控制） +│ ├── Network Policy 深入 +│ ├── Pod Security Policy +│ └── 准入控制器（Admission Controller） +└── 性能和扩展性 + ├── 大规模集群优化 + ├── 自定义 Operator + └── 集群联邦 + +容器运行时底层 +├── Linux 内核机制 +│ ├── Namespace 详解 +│ ├── Cgroup v1 和 v2 +│ ├── OverlayFS 和 UnionFS +│ └── SELinux 和 AppArmor +├── 容器运行时 +│ ├── containerd 源码阅读 +│ ├── runc 实现 +│ ├── gVisor 和 Kata +│ └── Firecracker +└── OCI 标准 + ├── Image Spec + └── Runtime Spec + +DevOps 工程化 +├── 大规模集群管理 +│ ├── Helm / Kustomize +│ ├── GitOps（Flux / ArgoCD） +│ └── 配置管理 +├── 灾难恢复和高可用 +│ ├── 多集群部署 +│ ├── 故障转移 +│ └── 备份策略 +├── 成本优化 +│ ├── 资源申请和限制 +│ ├── 自动扩缩容 +│ └── 成本监控 +└── 团队协作 + ├── GitFlow 工作流 + ├── 代码审查 + └── 文档和最佳实践传播 +``` +**贡献机会：** + +- [Kubernetes](https://github.com/kubernetes/kubernetes) +- [Cilium](https://github.com/cilium/cilium) +- [Prometheus](https://github.com/prometheus/prometheus) +- [Docker/Moby](https://github.com/moby/moby) + +### 知识点依赖关系 + +```text +基础概念 (Week 0-2) +├── 容器 vs 虚拟机 +├── Docker 三大概念 +└── 基础命令 + ↓ +Dockerfile 和镜像构建 (Week 2-4) +├── Dockerfile 指令 +├── 多阶段构建 +└── 镜像优化 + ↓ ↓ ↓ +数据管理 ← 网络配置 ← Docker Compose (Week 4-6) +├── Volume ├── Bridge ├── YAML 编写 +├── Bind Mount├── Overlay ├── 多容器编排 +└── tmpfs └── 自定义网络└── 开发工作流 + ↓ ↓ ↓ + └─────────────────────────┘ + 实战项目开发 (Week 6-10) + ├── Web 应用容器化 + ├── 数据库容器化 + ├── 微服务架构 + └── 本地开发环境 + ↓ +容器安全 ← 性能优化 ← 监控和日志 (Week 10-14) +├── 镜像扫描 ├── 大小优化 ├── Prometheus +├── 漏洞管理 ├── 内存优化 ├── Grafana +├── 镜像签名 ├── CPU 优化 └── ELK Stack +└── SBOM └── 诊断工具 + ↓ ↓ ↓ + └─────────────────────┘ + 安全生产环境 (Week 14-18) + ├── CI/CD 流程 + ├── 镜像仓库 + ├── 日志集中 + └── 告警系统 + ↓ +Kubernetes 基础 (Week 18-24) +├── Pod / Service / Deployment +├── 资源管理 +├── 存储管理 +└── 网络策略 + ↓ +Kubernetes 进阶 (Week 24-36) +├── StatefulSet / DaemonSet +├── Operator 开发 +├── 集群管理 +└── 服务网格 + ↓ +企业级平台设计 (Week 36+) +├── 多集群管理 +├── GitOps 工作流 +├── 成本优化 +└── 开源贡献 +``` + +### 推荐学习资源 + +#### 官方文档 + +| 资源 | URL | 推荐程度 | +|------|-----|--------| +| Docker 官方文档 | [docs.docker.com](https://docs.docker.com) | ⭐⭐⭐⭐⭐ | +| Docker Hub | [hub.docker.com](https://hub.docker.com) | ⭐⭐⭐⭐⭐ | +| Kubernetes 官方 | [kubernetes.io/docs](https://kubernetes.io/docs) | ⭐⭐⭐⭐⭐ | +| CNCF 景观 | [landscape.cncf.io](https://landscape.cncf.io) | ⭐⭐⭐⭐ | + +#### 在线课程 + +- **Udemy**：Docker 和 Kubernetes 完整课程（70-100 小时） +- **Linux Academy**：Linux 和容器管理 +- **A Cloud Guru**：AWS/Azure 容器服务 +- **Pluralsight**：Docker 和容器生态系统 + +#### 书籍推荐 + +- 《Docker 深入浅出》- 本书的原版 +- 《Kubernetes 权威指南》- 深入 Kubernetes 的必读书 +- 《容器技术核心技术与应用》- 理解底层实现 +- 《SRE Google 运维之道》- 生产环境最佳实践 + +#### 博客和社区 + +- [Docker 官方博客](https://www.docker.com/blog/) +- [Kubernetes 官方博客](https://kubernetes.io/blog/) +- [CNCF 博客](https://www.cncf.io/blog/) +- [DZone Cloud Architecture](https://dzone.com/cloud-architecture) + +### 认证指南 + +#### Docker 认证 + +**Docker Certified Associate (DCA)** + +考试信息： + +- 题目数：55 道 +- 时间限制：90 分钟 +- 及格分数：73%（约 41 道题） +- 费用：$199 USD +- 有效期：2 年 + +考试内容比例： +```text +镜像和仓库（20%） +- 镜像构建和管理 +- 镜像层和缓存 +- 私有仓库配置 + +容器运行（15%） +- 容器生命周期 +- 资源限制 +- 容器隔离 + +网络（15%） +- 网络驱动 +- 容器通信 +- 端口映射 + +存储（10%） +- Volume 管理 +- 数据持久化 +- 绑定挂载 + +编排（20%） +- Docker Compose +- Docker Swarm 基础 + +安全（15%） +- 用户和权限 +- 密钥管理 +- 镜像安全 +- 守护进程安全 + +和日志（5%） +- Logging drivers +- 事件处理 +``` +准备建议： +```bash +# 1. 学习本书第 1-11 章（基础到中级） +# 2. 完成 20+ 个实战项目 +# 3. 参考官方学习指南 +# 参考 Docker 官方学习入口：https://www.docker.com/resources/ + +# 4. 模拟考试 +- Linux Academy DCA 练习题 +- Whizlabs DCA 模拟考试 + +# 5. 重点掌握的命令 +docker build / push / pull / tag +docker run / exec / logs / inspect / ps +docker volume / network / service +docker compose up / down / logs / ps +docker stats / events / inspect +``` + +#### Kubernetes 认证 + +**认证路径：** + +1. **CKA - Certified Kubernetes Administrator** + - 难度：高 + - 时间：3 小时（实操） + - 费用：$395 + - 内容：集群安装、管理、故障排查 + +2. **CKAD - Certified Kubernetes Application Developer** + - 难度：中 + - 时间：2 小时（实操） + - 费用：$395 + - 内容：应用开发和部署 + +3. **CKS - Certified Kubernetes Security Specialist** + - 难度：很高 + - 时间：2 小时（实操） + - 费用：$395 + - 内容：安全最佳实践 + +### 常见面试题与答案要点 + +#### 基础概念面试题 + +**Q1: Docker 容器和虚拟机有什么区别？** + +A（要点）： +```text +虚拟机： +- 完整的操作系统环境（GB 级） +- 启动时间：分钟级 +- 隔离级别：完全硬件隔离 +- 性能开销：高（5-20%） + +容器： +- 共享内核，包含应用和依赖（MB 级） +- 启动时间：秒级 +- 隔离级别：进程级隔离（Namespace/Cgroup） +- 性能开销：低（1-5%） + +总结：容器更轻量、更快、密度更高 +``` +**Q2: 什么是 Docker 镜像？它如何存储的？** + +A（要点）： +```text +镜像本质： +- 只读的文件系统快照 +- 分层存储结构 +- 每一层是前一层的增量 + +存储方式： +- Union FS：多个只读层 + 一个可写层 +- 每个 RUN/COPY/ADD 指令创建一层 +- 层之间通过 diff 增量存储，节省空间 + +优点： +- 共享基础层减少存储 +- 层级缓存加快构建 +- 支持高效分发 +``` +**Q3: 容器如何实现隔离？** + +A（要点）： +```text +技术手段： +1. Namespace（资源隔离）： + - PID Namespace：进程隔离 + - Network Namespace：网络隔离 + - Mount Namespace：文件系统隔离 + - UTS Namespace：主机名隔离 + - IPC Namespace：进程间通信隔离 + +2. Cgroup（资源限制）： + - 限制 CPU 使用 + - 限制内存使用 + - 限制磁盘 I/O + - 限制网络带宽 + +3. Linux 能力机制（权限控制）： + - 削减不必要的 root 权限 + - 限制容器能力 + +4. SELinux / AppArmor（强制访问控制） +``` + +#### Dockerfile 面试题 + +**Q4: 如何优化 Docker 镜像大小？** + +A（要点）： +```text +1. 选择合适的基础镜像： + scratch < alpine:3.21 < python:3.14-slim < python:3.14 + +2. 多阶段构建： + - 构建阶段只保留编译工具 + - 运行阶段只包含最终二进制 + - 典型场景：Go、Node.js、Java + +3. 清理包管理器缓存： + apt-get clean && rm -rf /var/lib/apt/lists/* + yum clean all && rm -rf /var/cache/yum + pip install --no-cache-dir + +4. 合并 RUN 指令： + 减少镜像层数 + +5. 使用 .dockerignore： + 排除不必要的构建上下文 + +6. 去除调试符号： + Go: -ldflags="-w -s" + C/C++: strip binary + +7. 压缩资源： + gzip 静态文件，压缩图片 +``` +**Q5: CMD 和 ENTRYPOINT 有什么区别？** + +A（要点）： +```text +CMD： +- 定义容器默认命令 +- 容器运行时可被覆盖：docker run image_name custom_cmd +- 可以有多个 CMD，只有最后一个生效 + +ENTRYPOINT： +- 定义容器的可执行程序 +- 容器运行时参数追加而非覆盖 +- 与 CMD 配合使用 + +推荐用法： +ENTRYPOINT ["python", "app.py"] +CMD ["--port", "8000"] + +# 运行 docker run image --debug 会执行： +# python app.py --debug +``` + +#### 网络和存储面试题 + +**Q6: Docker 网络驱动的区别？** + +A（要点）： +```text +Bridge（默认）： +- 虚拟网桥，容器间通过网桥通信 +- 支持端口映射 +- 隔离性好，性能适中 + +Host： +- 使用宿主机网络栈 +- 性能最优，隔离性最差 +- 容器端口直接映射到宿主机 + +Overlay： +- 跨主机通信，基于 VXLAN +- Docker overlay 网络默认使用 UDP 4789 传输数据 +- Swarm 标准；Kubernetes 通常由 CNI 插件实现跨主机网络 +- 性能略低，支持分布式 + +macvlan： +- 容器获得 MAC 地址 +- 表现为物理机，性能好 +- 用于物理网络集成 + +None： +- 无网络，完全隔离 +``` +**Q7: Volume 和 Bind Mount 有什么区别？** + +A（要点）： +```text +Volume： +- Docker 管理，存储位置：/var/lib/docker/volumes/ +- 跨平台兼容，隔离性好 +- 支持驱动，可扩展 +- 推荐在生产环境使用 + +Bind Mount： +- 宿主机管理，任意位置 +- 跨平台兼容性一般 +- 性能好，用于开发环境 +- 权限管理复杂 + +tmpfs： +- 内存文件系统，不持久化 +- 用于临时文件、敏感数据 +- 性能最好，重启丢失 +``` + +#### 安全和生产面试题 + +**Q8: 如何提高 Docker 安全性？** + +A（要点）： +```text +镜像安全： +- 使用官方镜像或可信镜像源 +- 定期扫描漏洞（Trivy/Grype） +- 镜像签名验证（Cosign） +- 生成和管理 SBOM + +容器运行： +- 以非 root 用户运行 +- 使用 read-only 文件系统 +- 限制 Linux 能力 +- 使用 AppArmor 或 SELinux + +宿主机安全： +- 启用 TLS 认证 API +- 不暴露 /var/run/docker.sock +- 使用 Rootless 容器 +- 定期更新 Docker + +网络安全： +- 使用自定义网络隔离 +- 配置网络策略 +- 限制出入站流量 +``` +**Q9: 容器被 OOM 杀死，如何诊断和解决？** + +A（要点）： +```text +诊断： +1. 检查容器是否被 OOM 杀死： + docker inspect
HA Webpage Visit Results
#"+ str(request[pair][1]) +": "+str(request[pair][0])+ " requests " + "from <"+guest+"> to WebServer <"+pair[1]+">
") - else: - file.write("#"+ str(request[pair][1]) +": "+str(request[pair][0])+ " requests " + "from <"+guest+"> to WebServer <"+pair[1]+">
") - file.write(" "); - file.close() - pickle.dump(request,open("pickle_data.txt","w")) - -if __name__ == '__main__': - try: - ServerClass = BaseHTTPServer.HTTPServer - Protocol = "HTTP/1.0" - addr = len(sys.argv) < 2 and "0.0.0.0" or sys.argv[1] - port = len(sys.argv) < 3 and 80 or int(sys.argv[2]) - HandlerClass.protocol_version = Protocol - httpd = ServerClass((addr, port), HandlerClass) - sa = httpd.socket.getsockname() - print "Serving HTTP on", sa[0], "port", sa[1], "..." - httpd.serve_forever() - except: - exit() -``` - -#### index.html -生成一个临时的 `index.html` 文件，其内容会被 index.py 更新。 -```bash -$ touch index.html -``` - -#### Dockerfile -生成一个 Dockerfile，内容为 -```bash -FROM python:2.7 -WORKDIR /code -ADD . /code -EXPOSE 80 -CMD python index.py -``` - -### haproxy 目录 -在其中生成一个 `haproxy.cfg` 文件，内容为 -```bash -global - log 127.0.0.1 local0 - log 127.0.0.1 local1 notice - -defaults - log global - mode http - option httplog - option dontlognull - timeout connect 5000ms - timeout client 50000ms - timeout server 50000ms - -listen stats - bind 0.0.0.0:70 - stats enable - stats uri / - -frontend balancer - bind 0.0.0.0:80 - mode http - default_backend web_backends - -backend web_backends - mode http - option forwardfor - balance roundrobin - server weba weba:80 check - server webb webb:80 check - server webc webc:80 check - option httpchk GET / - http-check expect status 200 -``` -### docker-compose.yml -编写 docker-compose.yml 文件，这个是 Compose 使用的主模板文件。内容十分简单，指定 3 个 web 容器，以及 1 个 haproxy 容器。 - -```bash -weba: - build: ./web - expose: - - 80 - -webb: - build: ./web - expose: - - 80 - -webc: - build: ./web - expose: - - 80 - -haproxy: - image: haproxy:latest - volumes: - - ./haproxy:/haproxy-override - - ./haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro - links: - - weba - - webb - - webc - ports: - - "80:80" - - "70:70" - expose: - - "80" - - "70" -``` - -### 运行 compose 项目 -现在 compose-haproxy-web 目录长成下面的样子。 -```bash -compose-haproxy-web -├── docker-compose.yml -├── haproxy -│ └── haproxy.cfg -└── web - ├── Dockerfile - ├── index.html - └── index.py -``` -在该目录下执行 `docker-compose up` 命令，会整合输出所有容器的输出。 -``` -$sudo docker-compose up -Recreating composehaproxyweb_webb_1... -Recreating composehaproxyweb_webc_1... -Recreating composehaproxyweb_weba_1... -Recreating composehaproxyweb_haproxy_1... -Attaching to composehaproxyweb_webb_1, composehaproxyweb_webc_1, composehaproxyweb_weba_1, composehaproxyweb_haproxy_1 -``` - -此时访问本地的 80 端口，会经过 haproxy 自动转发到后端的某个 web 容器上，刷新页面，可以观察到访问的容器地址的变化。 - -访问本地 70 端口，可以查看到 haproxy 的统计信息。 - -当然，还可以使用 consul、etcd 等实现服务发现，这样就可以避免手动指定后端的 web 容器了，更为灵活。 diff --git a/compose/wordpress.md b/compose/wordpress.md deleted file mode 100644 index e3d05f400..000000000 --- a/compose/wordpress.md +++ /dev/null @@ -1,87 +0,0 @@ -## 使用 Wordpress -Compose 让 Wordpress 运行在一个独立的环境中很简易。 - -[安装](install.md) Compose ，然后下载 Wordpress 到当前目录： - -``` -wordpress.org/latest.tar.gz | tar -xvzf - -``` -这将会创建一个叫 wordpress 目录，你也可以重命名成你想要的名字。在目录里面，创建一个 `Dockerfile` 文件，定义应用的运行环境： - -``` -FROM orchardup/php5 -ADD . /code -``` -以上内容告诉 Docker 创建一个包含 PHP 和 Wordpress 的镜像。更多关于如何编写 Dockerfile 文件的信息可以查看 [镜像创建](../image/create.md#利用 Dockerfile 来创建镜像) 和 [Dockerfile 使用](../dockerfile/README.md)。 - - -下一步，`docker-compose.yml` 文件将开启一个 web 服务和一个独立的 MySQL 实例： - -``` -web: - build: . - command: php -S 0.0.0.0:8000 -t /code - ports: - - "8000:8000" - links: - - db - volumes: - - .:/code -db: - image: orchardup/mysql - environment: - MYSQL_DATABASE: wordpress -``` -要让这个应用跑起来还需要两个文件。 -第一个，`wp-condocker-compose.php` ，它是一个标准的 Wordpress 配置文件，有一点需要修改的是把数据库的配置指向 `db` 容器。 - -``` -) -``` -通过这个 PID，就可以连接到这个容器： -``` -$ nsenter --target $PID --mount --uts --ipc --net --pid -``` -下面给出一个完整的例子。 -``` -$ sudo docker run -idt ubuntu -243c32535da7d142fb0e6df616a3c3ada0b8ab417937c853a9e1c251f499f550 -$ sudo docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -243c32535da7 ubuntu:latest "/bin/bash" 18 seconds ago Up 17 seconds nostalgic_hypatia -$ PID=$(docker-pid 243c32535da7) -10981 -$ sudo nsenter --target 10981 --mount --uts --ipc --net --pid -root@243c32535da7:/# -``` -更简单的，建议大家下载 -[.bashrc_docker](https://github.com/yeasy/docker_practice/raw/master/_local/.bashrc_docker)，并将内容放到 .bashrc 中。 -``` -$ wget -P ~ https://github.com/yeasy/docker_practice/raw/master/_local/.bashrc_docker; -$ echo "[ -f ~/.bashrc_docker ] && . ~/.bashrc_docker" >> ~/.bashrc; source ~/.bashrc -``` -这个文件中定义了很多方便使用 Docker 的命令，例如 `docker-pid` 可以获取某个容器的 PID；而 `docker-enter` 可以进入容器或直接在容器内执行命令。 -``` -$ echo $(docker-pidDocker 实践指南
+ + diff --git a/examples/validated/github-actions/validate.yml b/examples/validated/github-actions/validate.yml new file mode 100644 index 000000000..b3089d5bd --- /dev/null +++ b/examples/validated/github-actions/validate.yml @@ -0,0 +1,43 @@ +name: Validate container examples + +on: + push: + branches: + - master + pull_request: + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + + - name: Install pinned validators + env: + KUBECONFORM_VERSION: "0.8.0" + KUBECONFORM_SHA256: "9bc2bffbf71f261128533edaf912153948b7ff238f9a531ae6d34466ec287883" + ACTIONLINT_VERSION: "1.7.12" + ACTIONLINT_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8" + run: | + mkdir -p "$RUNNER_TEMP/bin" + curl -fsSL --retry 3 \ + "https://github.com/yannh/kubeconform/releases/download/v${KUBECONFORM_VERSION}/kubeconform-linux-amd64.tar.gz" \ + -o "$RUNNER_TEMP/kubeconform.tar.gz" + echo "${KUBECONFORM_SHA256} $RUNNER_TEMP/kubeconform.tar.gz" | sha256sum -c - + tar xzf "$RUNNER_TEMP/kubeconform.tar.gz" -C "$RUNNER_TEMP/bin" kubeconform + + curl -fsSL --retry 3 \ + "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" \ + -o "$RUNNER_TEMP/actionlint.tar.gz" + echo "${ACTIONLINT_SHA256} $RUNNER_TEMP/actionlint.tar.gz" | sha256sum -c - + tar xzf "$RUNNER_TEMP/actionlint.tar.gz" -C "$RUNNER_TEMP/bin" actionlint + echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" + + - name: Validate canonical examples + run: python3 tools/test_examples.py --require-tools diff --git a/examples/validated/kubernetes/schemas/README.md b/examples/validated/kubernetes/schemas/README.md new file mode 100644 index 000000000..9a735a9b2 --- /dev/null +++ b/examples/validated/kubernetes/schemas/README.md @@ -0,0 +1,17 @@ +# Kubernetes schema provenance + +- schema set: `v1.31.0-standalone-strict` +- upstream: [`yannh/kubernetes-json-schema`](https://github.com/yannh/kubernetes-json-schema) +- upstream commit: `5e4d7a8ff7c9d783a27cf08ab2ba54a7dd8b8d03` +- source paths: `v1.31.0-standalone-strict/deployment-apps-v1.json` and `v1.31.0-standalone-strict/service-v1.json` +- vendoring transformation: append one POSIX terminal newline; JSON content is otherwise unchanged + +Upstream SHA-256 before newline normalization: + +- `deployment-apps-v1.json`: `3e3008f66a5f68cee3984485ac1892dbedc7f072b3a87064116bab294874e99e` +- `service-v1.json`: `f489d6102675238b913898caf6fef6f472403950fc9e5895ef718f3c4f1c4351` + +Committed SHA-256 used by the offline validator: + +- `deployment-apps-v1.json`: `d3b29ff1d1f202e33b9f0d3c9a2b777a4f45d5ff8210285e62e2c7bef1d09057` +- `service-v1.json`: `314be70ae72a72233561ed3dbeeba71e64cf84004ab611ca1727d5384bf400ed` diff --git a/examples/validated/kubernetes/schemas/v1.31.0-standalone-strict/deployment-apps-v1.json b/examples/validated/kubernetes/schemas/v1.31.0-standalone-strict/deployment-apps-v1.json new file mode 100644 index 000000000..4ccf670f6 --- /dev/null +++ b/examples/validated/kubernetes/schemas/v1.31.0-standalone-strict/deployment-apps-v1.json @@ -0,0 +1,10975 @@ +{ + "description": "Deployment enables declarative updates for Pods and ReplicaSets.", + "properties": { + "apiVersion": { + "description": "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + "type": [ + "string", + "null" + ], + "enum": [ + "apps/v1" + ] + }, + "kind": { + "description": "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + "type": [ + "string", + "null" + ], + "enum": [ + "Deployment" + ] + }, + "metadata": { + "description": "ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.", + "properties": { + "annotations": { + "additionalProperties": { + "type": [ + "string", + "null" + ] + }, + "description": "Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations", + "type": [ + "object", + "null" + ] + }, + "creationTimestamp": { + "description": "Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "deletionGracePeriodSeconds": { + "description": "Number of seconds allowed for this object to gracefully terminate before it will be removed from the system. Only set when deletionTimestamp is also set. May only be shortened. Read-only.", + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "deletionTimestamp": { + "description": "Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "finalizers": { + "description": "Must be empty before the object is deleted from the registry. Each entry is an identifier for the responsible component that will remove the entry from the list. If the deletionTimestamp of the object is non-nil, entries in this list can only be removed. Finalizers may be processed and removed in any order. Order is NOT enforced because it introduces significant risk of stuck finalizers. finalizers is a shared field, any actor with permission can reorder it. If the finalizer list is processed in order, then this can lead to a situation in which the component responsible for the first finalizer in the list is waiting for a signal (field value, external system, or other) produced by a component responsible for a finalizer later in the list, resulting in a deadlock. Without enforced ordering finalizers are free to order amongst themselves and are not vulnerable to ordering changes in the list.", + "items": { + "type": [ + "string", + "null" + ] + }, + "type": [ + "array", + "null" + ], + "x-kubernetes-list-type": "set", + "x-kubernetes-patch-strategy": "merge" + }, + "generateName": { + "description": "GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server.\n\nIf this field is specified and the generated name exists, the server will return a 409.\n\nApplied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency", + "type": [ + "string", + "null" + ] + }, + "generation": { + "description": "A sequence number representing a specific generation of the desired state. Populated by the system. Read-only.", + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "labels": { + "additionalProperties": { + "type": [ + "string", + "null" + ] + }, + "description": "Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels", + "type": [ + "object", + "null" + ] + }, + "managedFields": { + "description": "ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like \"ci-cd\". The set of fields is always in the version that the workflow used when modifying the object.", + "items": { + "description": "ManagedFieldsEntry is a workflow-id, a FieldSet and the group version of the resource that the fieldset applies to.", + "properties": { + "apiVersion": { + "description": "APIVersion defines the version of this resource that this field set applies to. The format is \"group/version\" just like the top-level APIVersion field. It is necessary to track the version of a field set because it cannot be automatically converted.", + "type": [ + "string", + "null" + ] + }, + "fieldsType": { + "description": "FieldsType is the discriminator for the different fields format and version. There is currently only one possible value: \"FieldsV1\"", + "type": [ + "string", + "null" + ] + }, + "fieldsV1": { + "description": "FieldsV1 stores a set of fields in a data structure like a Trie, in JSON format.\n\nEach key is either a '.' representing the field itself, and will always map to an empty set, or a string representing a sub-field or item. The string will follow one of these four formats: 'f:Hello, Docker!
' > /usr/share/nginx/html/index.html -``` - -这个 Dockerfile 很简单，一共就两行。涉及到了两条指令，`FROM` 和 `RUN`。 - -### FROM 指定基础镜像 - -所谓定制镜像，那一定是以一个镜像为基础，在其上进行定制。就像我们之前运行了一个 `nginx` 镜像的容器，再进行修改一样，基础镜像是必须指定的。而 `FROM` 就是指定**基础镜像**，因此一个 `Dockerfile` 中 `FROM` 是必备的指令，并且必须是第一条指令。 - -在 Docker Hub (Hello, Docker!
' > /usr/share/nginx/html/index.html -``` - -* *exec* 格式：`RUN ["可执行文件", "参数1", "参数2"]`，这更像是函数调用中的格式。 - -既然 `RUN` 就像 Shell 脚本一样可以执行命令，那么我们是否就可以像 Shell 脚本一样把每个命令对应一个 RUN 呢？比如这样： - -```Dockerfile -FROM debian:jessie - -RUN apt-get update -RUN apt-get install -y gcc libc6-dev make -RUN wget -O redis.tar.gz "http://download.redis.io/releases/redis-3.2.5.tar.gz" -RUN mkdir -p /usr/src/redis -RUN tar -xzf redis.tar.gz -C /usr/src/redis --strip-components=1 -RUN make -C /usr/src/redis -RUN make -C /usr/src/redis install -``` - -之前说过，Dockerfile 中每一个指令都会建立一层，`RUN` 也不例外。每一个 `RUN` 的行为，就和刚才我们手工建立镜像的过程一样：新建立一层，在其上执行这些命令，执行结束后，`commit` 这一层的修改，构成新的镜像。 - -而上面的这种写法，创建了 7 层镜像。这是完全没有意义的，而且很多运行时不需要的东西，都被装进了镜像里，比如编译环境、更新的软件包等等。结果就是产生非常臃肿、非常多层的镜像，不仅仅增加了构建部署的时间，也很容易出错。 -这是很多初学 Docker 的人常犯的一个错误。 - -*Union FS 是有最大层数限制的，比如 AUFS，曾经是最大不得超过 42 层，现在是不得超过 127 层。* - -上面的 `Dockerfile` 正确的写法应该是这样： - -```Dockerfile -FROM debian:jessie - -RUN buildDeps='gcc libc6-dev make' \ - && apt-get update \ - && apt-get install -y $buildDeps \ - && wget -O redis.tar.gz "http://download.redis.io/releases/redis-3.2.5.tar.gz" \ - && mkdir -p /usr/src/redis \ - && tar -xzf redis.tar.gz -C /usr/src/redis --strip-components=1 \ - && make -C /usr/src/redis \ - && make -C /usr/src/redis install \ - && rm -rf /var/lib/apt/lists/* \ - && rm redis.tar.gz \ - && rm -r /usr/src/redis \ - && apt-get purge -y --auto-remove $buildDeps -``` - -首先，之前所有的命令只有一个目的，就是编译、安装 redis 可执行文件。因此没有必要建立很多层，这只是一层的事情。因此，这里没有使用很多个 `RUN` 对一一对应不同的命令，而是仅仅使用一个 `RUN` 指令，并使用 `&&` 将各个所需命令串联起来。将之前的 7 层，简化为了 1 层。在撰写 Dockerfile 的时候，要经常提醒自己，这并不是在写 Shell 脚本，而是在定义每一层该如何构建。 - -并且，这里为了格式化还进行了换行。Dockerfile 支持 Shell 类的行尾添加 `\` 的命令换行方式，以及行首 `#` 进行注释的格式。良好的格式，比如换行、缩进、注释等，会让维护、排障更为容易，这是一个比较好的习惯。 - -此外，还可以看到这一组命令的最后添加了清理工作的命令，删除了为了编译构建所需要的软件，清理了所有下载、展开的文件，并且还清理了 `apt` 缓存文件。这是很重要的一步，我们之前说过，镜像是多层存储，每一层的东西并不会在下一层被删除，会一直跟随着镜像。因此镜像构建时，一定要确保每一层只添加真正需要添加的东西，任何无关的东西都应该清理掉。 - -很多人初学 Docker 制作出了很臃肿的镜像的原因之一，就是忘记了每一层构建的最后一定要清理掉无关文件。 - -### 构建镜像 - -好了，让我们再回到之前定制的 nginx 镜像的 Dockerfile 来。现在我们明白了这个 Dockerfile 的内容，那么让我们来构建这个镜像吧。 - -在 `Dockerfile` 文件所在目录执行： - -```bash -$ docker build -t nginx:v3 . -Sending build context to Docker daemon 2.048 kB -Step 1 : FROM nginx - ---> e43d811ce2f4 -Step 2 : RUN echo 'Hello, Docker!
' > /usr/share/nginx/html/index.html - ---> Running in 9cdc27646c7b - ---> 44aa4490ce2c -Removing intermediate container 9cdc27646c7b -Successfully built 44aa4490ce2c -``` - -从命令的输出结果中，我们可以清晰的看到镜像的构建过程。在 `Step 2` 中，如同我们之前所说的那样，`RUN` 指令启动了一个容器 `9cdc27646c7b`，执行了所要求的命令，并最后提交了这一层 `44aa4490ce2c`，随后删除了所用到的这个容器 `9cdc27646c7b`。 - -这里我们使用了 `docker build` 命令进行镜像构建。其格式为： - -```bash -docker build [选项] <上下文路径/URL/-> -``` - -在这里我们指定了最终镜像的名称 `-t nginx:v3`，构建成功后，我们可以像之前运行 `nginx:v2` 那样来运行这个镜像，其结果会和 `nginx:v2` 一样。 - -### 镜像构建上下文（Context） - -如果注意，会看到 `docker build` 命令最后有一个 `.`。`.` 表示当前目录，而 `Dockerfile` 就在当前目录，因此不少初学者以为这个路径是在指定 `Dockerfile` 所在路径，这么理解其实是不准确的。如果对应上面的命令格式，你可能会发现，这是在指定**上下文路径**。那么什么是上下文呢？ - -首先我们要理解 `docker build` 的工作原理。Docker 在运行时分为 Docker 引擎（也就是服务端守护进程）和客户端工具。Docker 的引擎提供了一组 REST API，被称为 [Docker Remote API](https://docs.docker.com/engine/reference/api/docker_remote_api/)，而如 `docker` 命令这样的客户端工具，则是通过这组 API 与 Docker 引擎交互，从而完成各种功能。因此，虽然表面上我们好像是在本机执行各种 `docker` 功能，但实际上，一切都是使用的远程调用形式在服务端（Docker 引擎）完成。也因为这种 C/S 设计，让我们操作远程服务器的 Docker 引擎变得轻而易举。 - -当我们进行镜像构建的时候，并非所有定制都会通过 `RUN` 指令完成，经常会需要将一些本地文件复制进镜像，比如通过 `COPY` 指令、`ADD` 指令等。而 `docker build` 命令构建镜像，其实并非在本地构建，而是在服务端，也就是 Docker 引擎中构建的。那么在这种客户端/服务端的架构中，如何才能让服务端获得本地文件呢？ - -这就引入了上下文的概念。当构建的时候，用户会指定构建镜像上下文的路径，`docker build` 命令得知这个路径后，会将路径下的所有内容打包，然后上传给 Docker 引擎。这样 Docker 引擎收到这个上下文包后，展开就会获得构建镜像所需的一切文件。 - -如果在 `Dockerfile` 中这么写： - -```Dockerfile -COPY ./package.json /app/ -``` - -这并不是要复制执行 `docker build` 命令所在的目录下的 `package.json`，也不是复制 `Dockerfile` 所在目录下的 `package.json`，而是复制 **上下文（context）** 目录下的 `package.json`。 - -因此，`COPY` 这类指令中的源文件的路径都是*相对路径*。这也是初学者经常会问的为什么 `COPY ../package.json /app` 或者 `COPY /opt/xxxx /app` 无法工作的原因，因为这些路径已经超出了上下文的范围，Docker 引擎无法获得这些位置的文件。如果真的需要那些文件，应该将它们复制到上下文目录中去。 - -现在就可以理解刚才的命令 `docker build -t nginx:v3 .` 中的这个 `.`，实际上是在指定上下文的目录，`docker build` 命令会将该目录下的内容打包交给 Docker 引擎以帮助构建镜像。 - -如果观察 `docker build` 输出，我们其实已经看到了这个发送上下文的过程： - -```bash -$ docker build -t nginx:v3 . -Sending build context to Docker daemon 2.048 kB -... -``` - -理解构建上下文对于镜像构建是很重要的，避免犯一些不应该的错误。比如有些初学者在发现 `COPY /opt/xxxx /app` 不工作后，于是干脆将 `Dockerfile` 放到了硬盘根目录去构建，结果发现 `docker build` 执行后，在发送一个几十 GB 的东西，极为缓慢而且很容易构建失败。那是因为这种做法是在让 `docker build` 打包整个硬盘，这显然是使用错误。 - -一般来说，应该会将 `Dockerfile` 至于一个空目录下，或者项目根目录下。如果该目录下没有所需文件，那么应该把所需文件复制一份过来。如果目录下有些东西确实不希望构建时传给 Docker 引擎，那么可以用 `.gitignore` 一样的语法写一个 `.dockerignore`，该文件是用于剔除不需要作为上下文传递给 Docker 引擎的。 - -那么为什么会有人误以为 `.` 是指定 `Dockerfile` 所在目录呢？这是因为在默认情况下，如果不额外指定 `Dockerfile` 的话，会将上下文目录下的名为 `Dockerfile` 的文件作为 Dockerfile。 - -这只是默认行为，实际上 `Dockerfile` 的文件名并不要求必须为 `Dockerfile`，而且并不要求必须位于上下文目录中，比如可以用 `-f ../Dockerfile.php` 参数指定某个文件作为 `Dockerfile`。 - -当然，一般大家习惯性的会使用默认的文件名 `Dockerfile`，以及会将其置于镜像构建上下文目录中。 - -### 其它 `docker build` 的用法 - -#### 直接用 Git repo 进行构建 - -或许你已经注意到了，`docker build` 还支持从 URL 构建，比如可以直接从 Git repo 中构建： - -```bash -$ docker build https://github.com/twang2218/gitlab-ce-zh.git#:8.14 -docker build https://github.com/twang2218/gitlab-ce-zh.git\#:8.14 -Sending build context to Docker daemon 2.048 kB -Step 1 : FROM gitlab/gitlab-ce:8.14.0-ce.0 -8.14.0-ce.0: Pulling from gitlab/gitlab-ce -aed15891ba52: Already exists -773ae8583d14: Already exists -... -``` - -这行命令指定了构建所需的 Git repo，并且指定默认的 `master` 分支，构建目录为 `/8.14/`，然后 Docker 就会自己去 `git clone` 这个项目、切换到指定分支、并进入到指定目录后开始构建。 - -#### 用给定的 tar 压缩包构建 - -```bash -$ docker build http://server/context.tar.gz -``` - -如果所给出的 URL 不是个 Git repo，而是个 `tar` 压缩包，那么 Docker 引擎会下载这个包，并自动解压缩，以其作为上下文，开始构建。 - -#### 从标准输入中读取 Dockerfile 进行构建 - -```bash -docker build - < Dockerfile -``` - -或 - -```bash -cat Dockerfile | docker build - -``` - -如果标准输入传入的是文本文件，则将其视为 `Dockerfile`，并开始构建。这种形式由于直接从标准输入中读取 Dockerfile 的内容，它没有上下文，因此不可以像其他方法那样可以将本地文件 `COPY` 进镜像之类的事情。 - -#### 从标准输入中读取上下文压缩包进行构建 - -```bash -$ docker build - < context.tar.gz -``` - -如果发现标准输入的文件格式是 `gzip`、`bzip2` 以及 `xz` 的话，将会使其为上下文压缩包，直接将其展开，将里面视为上下文，并开始构建。 diff --git a/image/dockerfile/README.md b/image/dockerfile/README.md deleted file mode 100644 index 662da0b01..000000000 --- a/image/dockerfile/README.md +++ /dev/null @@ -1,3 +0,0 @@ -## Dockerfile 指令详解 - -我们已经介绍了 `FROM`，`RUN`，还提及了 `COPY`, `ADD`，其实 Dockerfile 功能很强大，它提供了十多个指令。这里我们继续讲解剩下的指令。 diff --git a/image/dockerfile/add.md b/image/dockerfile/add.md deleted file mode 100644 index ad6803ad3..000000000 --- a/image/dockerfile/add.md +++ /dev/null @@ -1,23 +0,0 @@ -### ADD 更高级的复制文件 - -`ADD` 指令和 `COPY` 的格式和性质基本一致。但是在 `COPY` 基础上增加了一些功能。 - -比如 `<源路径>` 可以是一个 `URL`，这种情况下，Docker 引擎会试图去下载这个链接的文件放到 `<目标路径>` 去。下载后的文件权限自动设置为 `600`，如果这并不是想要的权限，那么还需要增加额外的一层 `RUN` 进行权限调整，另外，如果下载的是个压缩包，需要解压缩，也一样还需要额外的一层 `RUN` 指令进行解压缩。所以不如直接使用 `RUN` 指令，然后使用 `wget` 或者 `curl` 工具下载，处理权限、解压缩、然后清理无用文件更合理。因此，这个功能其实并不实用，而且不推荐使用。 - -如果 `<源路径>` 为一个 `tar` 压缩文件的话，压缩格式为 `gzip`, `bzip2` 以及 `xz` 的情况下，`ADD` 指令将会自动解压缩这个压缩文件到 `<目标路径>` 去。 - -在某些情况下，这个自动解压缩的功能非常有用，比如官方镜像 `ubuntu` 中： - -```Dockerfile -FROM scratch -ADD ubuntu-xenial-core-cloudimg-amd64-root.tar.gz / -... -``` - -但在某些情况下，如果我们真的是希望复制个压缩文件进去，而不解压缩，这时就不可以使用 `ADD` 命令了。 - -在 Docker 官方的最佳实践文档中要求，尽可能的使用 `COPY`，因为 `COPY` 的语义很明确，就是复制文件而已，而 `ADD` 则包含了更复杂的功能，其行为也不一定很清晰。最适合使用 `ADD` 的场合，就是所提及的需要自动解压缩的场合。 - -另外需要注意的是，`ADD` 指令会令镜像构建缓存失效，从而可能会令镜像构建变得比较缓慢。 - -因此在 `COPY` 和 `ADD` 指令中选择的时候，可以遵循这样的原则，所有的文件复制均使用 `COPY` 指令，仅在需要自动解压缩的场合使用 `ADD`。 diff --git a/image/dockerfile/arg.md b/image/dockerfile/arg.md deleted file mode 100644 index c203bd2ef..000000000 --- a/image/dockerfile/arg.md +++ /dev/null @@ -1,9 +0,0 @@ -### ARG 构建参数 - -格式：`ARG <参数名>[=<默认值>]` - -构建参数和 `ENV` 的效果一样，都是设置环境变量。所不同的是，`ARG` 所设置的构建环境的环境变量，在将来容器运行时是不会存在这些环境变量的。但是不要因此就是用 `ARG` 保存密码之类的信息，因为 `docker history` 还是可以看到所有值的。 - -`Dockerfile` 中的 `ARG` 指令是定义参数名称，以及定义其默认值。该默认值可以在构建命令 `docker build` 中用 `--build-arg <参数名>=<值>` 来覆盖。 - -在 1.13 之前的版本，要求 `--build-arg` 中的参数名，必须在 `Dockerfile` 中用 `ARG` 定义过了，换句话说，就是 `--build-arg` 指定的参数，必须在 `Dockerfile` 中使用了。如果对应参数没有被使用，则会报错退出构建。从 1.13 开始，这种严格的限制被放开，不再报错退出，而是显示警告信息，并继续构建。这对于使用 CI 系统，用同样的构建流程构建不同的 `Dockerfile` 的时候比较有帮助，避免构建命令必须根据每个 Dockerfile 的内容修改。 diff --git a/image/dockerfile/cmd.md b/image/dockerfile/cmd.md deleted file mode 100644 index 56c421ae4..000000000 --- a/image/dockerfile/cmd.md +++ /dev/null @@ -1,49 +0,0 @@ -### CMD 容器启动命令 - -`CMD` 指令的格式和 `RUN` 相似，也是两种格式： - -* `shell` 格式：`CMD <命令>` -* `exec` 格式：`CMD ["可执行文件", "参数1", "参数2"...]` -* 参数列表格式：`CMD ["参数1", "参数2"...]`。在指定了 `ENTRYPOINT` 指令后，用 `CMD` 指定具体的参数。 - -之前介绍容器的时候曾经说过，Docker 不是虚拟机，容器就是进程。既然是进程，那么在启动容器的时候，需要指定所运行的程序及参数。`CMD` 指令就是用于指定默认的容器主进程的启动命令的。 - -在运行时可以指定新的命令来替代镜像设置中的这个默认命令，比如，`ubuntu` 镜像默认的 `CMD` 是 `/bin/bash`，如果我们直接 `docker run -it ubuntu` 的话，会直接进入 `bash`。我们也可以在运行时指定运行别的命令，如 `docker run -it ubuntu cat /etc/os-release`。这就是用 `cat /etc/os-release` 命令替换了默认的 `/bin/bash` 命令了，输出了系统版本信息。 - -在指令格式上，一般推荐使用 `exec` 格式，这类格式在解析时会被解析为 JSON 数组，因此一定要使用双引号 `"`，而不要使用单引号。 - -如果使用 `shell` 格式的话，实际的命令会被包装为 `sh -c` 的参数的形式进行执行。比如： - -```Dockerfile -CMD echo $HOME -``` - -在实际执行中，会将其变更为： - -```Dockerfile -CMD [ "sh", "-c", "echo $HOME" ] -``` - -这就是为什么我们可以使用环境变量的原因，因为这些环境变量会被 shell 进行解析处理。 - -提到 `CMD` 就不得不提容器中应用在前台执行和后台执行的问题。这是初学者常出现的一个混淆。 - -Docker 不是虚拟机，容器中的应用都应该以前台执行，而不是像虚拟机、物理机里面那样，用 upstart/systemd 去启动后台服务，容器内没有后台服务的概念。 - -一些初学者将 `CMD` 写为： - -```Dockerfile -CMD service nginx start -``` - -然后发现容器执行后就立即退出了。甚至在容器内去使用 `systemctl` 命令结果却发现根本执行不了。这就是因为没有搞明白前台、后台的概念，没有区分容器和虚拟机的差异，依旧在以传统虚拟机的角度去理解容器。 - -对于容器而言，其启动程序就是容器应用进程，容器就是为了主进程而存在的，主进程退出，容器就失去了存在的意义，从而退出，其它辅助进程不是它需要关心的东西。 - -而使用 `service nginx start` 命令，则是希望 upstart 来以后台守护进程形式启动 `nginx` 服务。而刚才说了 `CMD service nginx start` 会被理解为 `CMD [ "sh", "-c", "service nginx start"]`，因此主进程实际上是 `sh`。那么当 `service nginx start` 命令结束后，`sh` 也就结束了，`sh` 作为主进程退出了，自然就会令容器退出。 - -正确的做法是直接执行 `nginx` 可执行文件，并且要求以前台形式运行。比如： - -```Dockerfile -CMD ["nginx" "-g" "daemon off;"] -``` diff --git a/image/dockerfile/copy.md b/image/dockerfile/copy.md deleted file mode 100644 index a948a64e4..000000000 --- a/image/dockerfile/copy.md +++ /dev/null @@ -1,25 +0,0 @@ -### COPY 复制文件 - -格式： - -* `COPY <源路径>... <目标路径>` -* `COPY ["<源路径1>",... "<目标路径>"]` - -和 `RUN` 指令一样，也有两种格式，一种类似于命令行，一种类似于函数调用。 - -`COPY` 指令将从构建上下文目录中 `<源路径>` 的文件/目录复制到新的一层的镜像内的 `<目标路径>` 位置。比如： - -```Dockerfile -COPY package.json /usr/src/app/ -``` - -`<源路径>` 可以是多个，甚至可以是通配符，其通配符规则要满足 Go 的 [`filepath.Match`](https://golang.org/pkg/path/filepath/#Match) 规则，如： - -```Dockerfile -COPY hom* /mydir/ -COPY hom?.txt /mydir/ -``` - -`<目标路径>` 可以是容器内的绝对路径，也可以是相对于工作目录的相对路径（工作目录可以用 `WORKDIR` 指令来指定）。目标路径不需要事先创建，如果目录不存在会在复制文件前先行创建缺失目录。 - -此外，还需要注意一点，使用 `COPY` 指令，源文件的各种元数据都会保留。比如读、写、执行权限、文件变更时间等。这个特性对于镜像定制很有用。特别是构建相关文件都在使用 Git 进行管理的时候。 diff --git a/image/dockerfile/entrypoint.md b/image/dockerfile/entrypoint.md deleted file mode 100644 index c652de7db..000000000 --- a/image/dockerfile/entrypoint.md +++ /dev/null @@ -1,124 +0,0 @@ -### ENTRYPOINT 入口点 - -`ENTRYPOINT` 的格式和 `RUN` 指令格式一样，分为 `exec` 格式和 `shell` 格式。 - -`ENTRYPOINT` 的目的和 `CMD` 一样，都是在指定容器启动程序及参数。`ENTRYPOINT` 在运行时也可以替代，不过比 `CMD` 要略显繁琐，需要通过 `docker run` 的参数 `--entrypoint` 来指定。 - -当指定了 `ENTRYPOINT` 后，`CMD` 的含义就发生了改变，不再是直接的运行其命令，而是将 `CMD` 的内容作为参数传给 `ENTRYPOINT` 指令，换句话说实际执行时，将变为： - -```bash -Welcome to nginx!
\nIf you see this page, the nginx web server is successfully installed and\nworking. Further configuration is required.
\n\nFor online documentation and support please refer to\nnginx.org.
\nCommercial support is available at\nnginx.com.
Thank you for using nginx.
\n\n\n", - "Start": "2016-11-25T14:35:37.780192565Z" - } - ], - "Status": "healthy" -} -``` diff --git a/image/dockerfile/onbuild.md b/image/dockerfile/onbuild.md deleted file mode 100644 index 83f88e777..000000000 --- a/image/dockerfile/onbuild.md +++ /dev/null @@ -1,65 +0,0 @@ -### ONBUILD 为他人做嫁衣裳 - -格式：`ONBUILD <其它指令>`。 - -`ONBUILD` 是一个特殊的指令，它后面跟的是其它指令，比如 `RUN`, `COPY` 等，而这些指令，在当前镜像构建时并不会被执行。只有当以当前镜像为基础镜像，去构建下一级镜像的时候才会被执行。 - -`Dockerfile` 中的其它指令都是为了定制当前镜像而准备的，唯有 `ONBUILD` 是为了帮助别人定制自己而准备的。 - -假设我们要制作 Node.js 所写的应用的镜像。我们都知道 Node.js 使用 `npm` 进行包管理，所有依赖、配置、启动信息等会放到 `package.json` 文件里。在拿到程序代码后，需要先进行 `npm install` 才可以获得所有需要的依赖。然后就可以通过 `npm start` 来启动应用。因此，一般来说会这样写 `Dockerfile`： - -```Dockerfile -FROM node:slim -RUN "mkdir /app" -WORKDIR /app -COPY ./package.json /app -RUN [ "npm", "install" ] -COPY . /app/ -CMD [ "npm", "start" ] -``` - -把这个 `Dockerfile` 放到 Node.js 项目的根目录，构建好镜像后，就可以直接拿来启动容器运行。但是如果我们还有第二个 Node.js 项目也差不多呢？好吧，那就再把这个 `Dockerfile` 复制到第二个项目里。那如果有第三个项目呢？再复制么？文件的副本越多，版本控制就越困难，让我们继续看这样的场景维护的问题。 - -如果第一个 Node.js 项目在开发过程中，发现这个 `Dockerfile` 里存在问题，比如敲错字了、或者需要安装额外的包，然后开发人员修复了这个 `Dockerfile`，再次构建，问题解决。第一个项目没问题了，但是第二个项目呢？虽然最初 `Dockerfile` 是复制、粘贴自第一个项目的，但是并不会因为第一个项目修复了他们的 `Dockerfile`，而第二个项目的 `Dockerfile` 就会被自动修复。 - -那么我们可不可以做一个基础镜像，然后各个项目使用这个基础镜像呢？这样基础镜像更新，各个项目不用同步 `Dockerfile` 的变化，重新构建后就继承了基础镜像的更新？好吧，可以，让我们看看这样的结果。那么上面的这个 `Dockerfile` 就会变为： - -```Dockerfile -FROM node:slim -RUN "mkdir /app" -WORKDIR /app -CMD [ "npm", "start" ] -``` - -这里我们把项目相关的构建指令拿出来，放到子项目里去。假设这个基础镜像的名字为 `my-node` 的话，各个项目内的自己的 `Dockerfile` 就变为： - -```Dockerfile -FROM my-node -COPY ./package.json /app -RUN [ "npm", "install" ] -COPY . /app/ -``` - -基础镜像变化后，各个项目都用这个 `Dockerfile` 重新构建镜像，会继承基础镜像的更新。 - -那么，问题解决了么？没有。准确说，只解决了一半。如果这个 `Dockerfile` 里面有些东西需要调整呢？比如 `npm install` 都需要加一些参数，那怎么办？这一行 `RUN` 是不可能放入基础镜像的，因为涉及到了当前项目的 `./package.json`，难道又要一个个修改么？所以说，这样制作基础镜像，只解决了原来的 `Dockerfile` 的前4条指令的变化问题，而后面三条指令的变化则完全没办法处理。 - -`ONBUILD` 可以解决这个问题。让我们用 `ONBUILD` 重新写一下基础镜像的 `Dockerfile`: - -```Dockerfile -FROM node:slim -RUN "mkdir /app" -WORKDIR /app -ONBUILD COPY ./package.json /app -ONBUILD RUN [ "npm", "install" ] -ONBUILD COPY . /app/ -CMD [ "npm", "start" ] -``` - -这次我们回到原始的 `Dockerfile`，但是这次将项目相关的指令加上 `ONBUILD`，这样在构建基础镜像的时候，这三行并不会被执行。然后各个项目的 `Dockerfile` 就变成了简单地： - -```Dockerfile -FROM my-node -``` - -是的，只有这么一行。当在各个项目目录中，用这个只有一行的 `Dockerfile` 构建镜像时，之前基础镜像的那三行 `ONBUILD` 就会开始执行，成功的将当前项目的代码复制进镜像、并且针对本项目执行 `npm install`，生成应用镜像。 diff --git a/image/dockerfile/references.md b/image/dockerfile/references.md deleted file mode 100644 index ba465c8a6..000000000 --- a/image/dockerfile/references.md +++ /dev/null @@ -1,4 +0,0 @@ -### 参考文档 - -* Dockerfie 官方文档：
-
-### 运行
-
-从应用中找到 Docker 图标并点击运行。
-
-
-
-运行之后，会在右上角菜单栏看到多了一个鲸鱼图标，这个图标表明了 Docker 的运行状态。
-
-
-
-第一次点击图标，可能会看到这个安装成功的界面，点击 "Got it!" 可以关闭这个窗口。
-
-
-
-以后每次点击鲸鱼图标会弹出操作菜单。
-
-
-
-*在国内使用 Docker 的话，需要配置加速器，在菜单中点击 `Preferences...`，然后查看 `Advanced` 标签，在其中的 `Registry mirrors` 部分里可以点击加号来添加加速器地址。*
-
-
-
-启动终端后，通过命令可以检查安装后的 Docker 版本。
-
-```bash
-$ docker --version
-Docker version 1.12.3, build 6b644ec
-$ docker-compose --version
-docker-compose version 1.8.1, build 878cff1
-$ docker-machine --version
-docker-machine version 0.8.2, build e18a919
-```
-
-如果 `docker version`、`docker info` 都正常的话，可以运行一个 [Nginx 服务器](https://hub.docker.com/_/nginx/)：
-
-```bash
-$ docker run -d -p 80:80 --name webserver nginx
-```
-
-服务运行后，可以访问
-
-要停止 Nginx 服务器并删除执行下面的命令：
-
-```bash
-$ docker stop webserver
-$ docker rm webserver
-```
diff --git a/install/mirror.md b/install/mirror.md
deleted file mode 100644
index e64885838..000000000
--- a/install/mirror.md
+++ /dev/null
@@ -1,64 +0,0 @@
-## 镜像加速器
-
-国内访问 Docker Hub 有时会遇到困难，此时可以配置镜像加速器。国内很多云服务商都提供了加速器服务，例如：
-
-* [阿里云加速器](https://cr.console.aliyun.com/#/accelerator)
-* [DaoCloud 加速器](https://www.daocloud.io/mirror#accelerator-doc)
-* [灵雀云加速器](http://docs.alauda.cn/feature/accelerator.html)
-
-注册用户并且申请加速器，会获得如 `https://jxus37ad.mirror.aliyuncs.com` 这样的地址。我们需要将其配置给 Docker 引擎。
-
-### Ubuntu 14.04、Debian 7 Wheezy
-
-对于使用 [upstart](http://upstart.ubuntu.com/) 的系统而言，编辑 `/etc/default/docker` 文件，在其中的 `DOCKER_OPTS` 中添加获得的加速器配置 `--registry-mirror=<加速器地址>`，如：
-
-```bash
-DOCKER_OPTS="--registry-mirror=https://jxus37ad.mirror.aliyuncs.com"
-```
-
-重新启动服务。
-
-```bash
-$ sudo service docker restart
-```
-
-### Ubuntu 16.04、Debian 8 Jessie、CentOS 7
-
-对于使用 [systemd](https://www.freedesktop.org/wiki/Software/systemd/) 的系统，用 `systemctl enable docker` 启用服务后，编辑 `/etc/systemd/system/multi-user.target.wants/docker.service` 文件，找到 `ExecStart=` 这一行，在这行最后添加加速器地址 `--registry-mirror=<加速器地址>`，如：
-
-```bash
-ExecStart=/usr/bin/dockerd --registry-mirror=https://jxus37ad.mirror.aliyuncs.com
-```
-
-*注：对于 1.12 以前的版本，`dockerd` 换成 `docker daemon`。*
-
-重新加载配置并且重新启动。
-
-```bash
-$ sudo systemctl daemon-reload
-$ sudo systemctl restart docker
-```
-
-### Windows 10
-对于使用 WINDOWS 10 的系统，在系统右下角托盘图标内右键菜单选择 `Settings`，打开配置窗口后左侧导航菜单选择 `Docker Daemon`。编辑窗口内的JSON串，填写如阿里云、DaoCloud之类的加速器地址，如：
-
-```bash
-{
- "registry-mirrors": [
- "https://sr5arhkn.mirror.aliyuncs.com",
- "http://14d216f4.m.daocloud.io"
- ],
- "insecure-registries": []
-}
-```
-编辑完成，点击Apply保存后Docker服务会重新启动。
-
-### 检查加速器是否生效
-
-Linux系统下配置完加速器需要检查是否生效，在命令行执行 `ps -ef | grep dockerd`，如果从结果中看到了配置的 `--registry-mirror` 参数说明配置成功。
-
-```bash
-$ sudo ps -ef | grep dockerd
-root 5346 1 0 19:03 ? 00:00:00 /usr/bin/dockerd --registry-mirror=https://jxus37ad.mirror.aliyuncs.com
-$
-```
diff --git a/install/ubuntu.md b/install/ubuntu.md
deleted file mode 100644
index ef4baba42..000000000
--- a/install/ubuntu.md
+++ /dev/null
@@ -1,237 +0,0 @@
-## Ubuntu、Debian 系列安装 Docker
-
-### 系统要求
-
-Docker 支持以下版本的 [Ubuntu](https://www.ubuntu.com/server) 和 [Debian](https://www.debian.org/intro/about) 操作系统：
-
-* Ubuntu Xenial 16.04 (LTS)
-* Ubuntu Trusty 14.04 (LTS)
-* Ubuntu Precise 12.04 (LTS)
-* Debian testing stretch (64-bit)
-* Debian 8 Jessie (64-bit)
-* Debian 7 Wheezy (64-bit)（*必须启用 backports*)
-
-Ubuntu 发行版中，LTS（Long-Term-Support）长期支持版本，会获得 5 年的升级维护支持，这样的版本会更稳定，因此在生产环境中推荐使用 LTS 版本。
-
-Docker 目前支持的 Ubuntu 版本最低为 12.04 LTS，但从稳定性上考虑，推荐使用 14.04 LTS 或更高的版本。
-
-Docker 需要安装在 64 位的 x86 平台或 ARM 平台上（如[树莓派](https://www.raspberrypi.org/)），并且要求内核版本不低于 3.10。但实际上内核越新越好，过低的内核版本可能会出现部分功能无法使用，或者不稳定。
-
-用户可以通过如下命令检查自己的内核版本详细信息：
-
-```bash
-$ uname -a
-Linux device 4.4.0-45-generic #66~14.04.1-Ubuntu SMP Wed Oct 19 15:05:38 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
-```
-
-#### 升级内核
-
-如果内核版本过低，可以用下面的命令升级系统内核。
-
-##### Ubuntu 12.04 LTS
-
-```bash
-sudo apt-get install -y --install-recommends linux-generic-lts-trusty
-```
-
-##### Ubuntu 14.04 LTS
-
-```bash
-sudo apt-get install -y --install-recommends linux-generic-lts-xenial
-```
-
-##### Debian 7 Wheezy
-
-Debian 7 的内核默认为 3.2，为了满足 Docker 的需求，应该安装 `backports` 的内核。
-
-执行下面的命令添加 `backports` 源：
-
-```bash
-$ echo "deb http://http.debian.net/debian wheezy-backports main" | sudo tee /etc/apt/sources.list.d/backports.list
-```
-
-升级到 `backports` 内核：
-
-```bash
-$ sudo apt-get update
-$ sudo apt-get -t wheezy-backports install linux-image-amd64
-```
-
-##### Debian 8 Jessie
-
-Debian 8 的内核默认为 3.16，满足基本的 Docker 运行条件。但是如果打算使用 `overlay2` 存储层驱动，或某些功能不够稳定希望升级到较新版本的内核，可以添加 `backports` 源，升级到新版本的内核。
-
-执行下面的命令添加 `backports` 源：
-
-```bash
-$ echo "deb http://http.debian.net/debian jessie-backports main" | sudo tee /etc/apt/sources.list.d/backports.list
-```
-
-升级到 `backports` 内核：
-
-```bash
-$ sudo apt-get update
-$ sudo apt-get -t jessie-backports install linux-image-amd64
-```
-
-需要注意的是，升级到 `backports` 的内核之后，会因为 `AUFS` 内核模块不可用，而使用默认的 `devicemapper` 驱动，并且配置为 `loop-lvm`，这是不推荐的。因此，不要忘记安装 Docker 后，配置 `overlay2` 存储层驱动。
-
-##### 配置 GRUB 引导参数
-
-在 Docker 使用期间，或者在 `docker info` 信息中，可能会看到下面的警告信息：
-
-```bash
-WARNING: Your kernel does not support cgroup swap limit. WARNING: Your
-kernel does not support swap limit capabilities. Limitation discarded.
-```
-
-或者
-
-```bash
-WARNING: No memory limit support
-WARNING: No swap limit support
-WARNING: No oom kill disable support
-```
-
-如果需要这些功能，就需要修改 GRUB 的配置文件 ` /etc/default/grub`，在 `GRUB_CMDLINE_LINUX` 中添加内核引导参数 `cgroup_enable=memory swapaccount=1`。
-
-然后不要忘记了更新 GRUB：
-
-```bash
-$ sudo update-grub
-$ sudo reboot
-```
-
-### 使用脚本自动安装
-
-Docker 官方为了简化安装流程，提供了一套安装脚本，Ubuntu 和 Debian 系统可以使用这套脚本安装：
-
-```bash
-curl -sSL https://get.docker.com/ | sh
-```
-
-执行这个命令后，脚本就会自动的将一切准备工作做好，并且把 Docker 安装在系统中。
-
-不过，由于伟大的墙的原因，在国内使用这个脚本可能会出现某些下载出现错误的情况。国内的一些云服务商提供了这个脚本的修改版本，使其使用国内的 Docker 软件源镜像安装，这样就避免了墙的干扰。
-
-#### 阿里云的安装脚本
-
-```bash
-curl -sSL http://acs-public-mirror.oss-cn-hangzhou.aliyuncs.com/docker-engine/internet | sh -
-```
-
-#### DaoCloud 的安装脚本
-
-```bash
-curl -sSL https://get.daocloud.io/docker | sh
-```
-
-### 手动安装
-
-#### 安装所需的软件包
-
-##### 可选内核模块
-
-从 Ubuntu 14.04 开始，一部分内核模块移到了可选内核模块包(`linux-image-extra-*`)，以减少内核软件包的体积。正常安装的系统应该会包含可选内核模块包，而一些裁剪后的系统可能会将其精简掉。`AUFS` 内核驱动属于可选内核模块的一部分，作为推荐的 Docker 存储层驱动，一般建议安装可选内核模块包以使用 `AUFS`。
-
-如果系统没有安装可选内核模块的话，可以执行下面的命令来安装可选内核模块包：
-
-```bash
-$ sudo apt-get install linux-image-extra-$(uname -r) linux-image-extra-virtual
-```
-
-##### 12.04 LTS 图形界面
-
-在 Ubuntu 12.04 桌面环境下，需要一些额外的软件包，可以用下面的命令安装。
-
-```bash
-$ sudo apt-get install xserver-xorg-lts-trusty libgl1-mesa-glx-lts-trusty
-```
-
-#### 添加 APT 镜像源
-
-虽然 Ubuntu 系统软件源中有 Docker，名为 `docker.io`，但是不应该使用系统源中的这个版本，它的版本太旧。我们需要使用 Docker 官方提供的软件源，因此，我们需要添加 APT 软件源。
-
-由于官方源使用 HTTPS 以确保软件下载过程中不被篡改。因此，我们首先需要添加使用 HTTPS 传输的软件包以及 CA 证书。
-
-*国内的一些软件源镜像（比如[阿里云](http://mirrors.aliyun.com/docker-engine/)）不是太在意系统安全上的细节，可能依旧使用不安全的 HTTP，对于这些源可以不执行这一步。*
-
-```bash
-$ sudo apt-get update
-$ sudo apt-get install apt-transport-https ca-certificates
-```
-
-为了确认所下载软件包的合法性，需要添加 Docker 官方软件源的 GPG 密钥。
-
-```bash
-$ sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
-```
-
-然后，我们需要向 `source.list` 中添加 Docker 软件源，下表列出了不同的 Ubuntu 和 Debian 版本对应的 APT 源。
-
-| 操作系统版本 | REPO |
-|---------------------|--------------------------------------------------------------|
-| Precise 12.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-precise main` |
-| Trusty 14.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-trusty main` |
-| Xenial 16.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-xenial main` |
-| Debian 7 Wheezy | `deb https://apt.dockerproject.org/repo debian-wheezy main` |
-| Debian 8 Jessie | `deb https://apt.dockerproject.org/repo debian-jessie main` |
-| Debian Stretch/Sid | `deb https://apt.dockerproject.org/repo debian-stretch main` |
-
-用下面的命令将 APT 源添加到 `source.list`（将其中的 `
的属性不算正文。',
+ "见 [文档](a.md) https://e.com/x 结束。",
+ "公式 $$L = (预测 - 真实)^2$$ 属于数学。",
+ "记 $a^*$ 与 $O_t$ 为最优解。",
+ ):
+ self.assertEqual([], list(unspaced(sample + "\n")), sample)
+ self.assertEqual([], list(half_width_parens(sample + "\n")), sample)
+
+ def test_prices_are_not_mistaken_for_math(self) -> None:
+ """A pair of '$' around prose must not mask the prose between them."""
+ line = "定价 $25/$125 per M tokens，另有 $1 亿额度给 Glasswing计划。\n"
+ self.assertEqual([(1, "g计", line.strip())], list(unspaced(line)))
+
+ def test_html_text_content_is_still_prose(self) -> None:
+ self.assertEqual(
+ [(1, "文a", "中文abc 属于 HTML。")],
+ list(unspaced("中文abc 属于 HTML。\n")),
+ )
+
+ def test_a_table_row_is_not_an_html_tag(self) -> None:
+ line = "| 33-64 | 其他矿工 | <1% | - | <5 | 各类GPU | >400ms |\n"
+ self.assertEqual([(1, "类G", line.strip())], list(unspaced(line)))
+
+ def test_display_math_blocks_are_skipped_whole(self) -> None:
+ text = "正文一行。\n\n$$\n\\text{原始Adam的权重衰减} = \\eta \\lambda \\theta\n$$\n\n正文二行。\n"
+ self.assertEqual([], list(unspaced(text)))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_example_validation.py b/tests/test_example_validation.py
new file mode 100644
index 000000000..9bcd4c984
--- /dev/null
+++ b/tests/test_example_validation.py
@@ -0,0 +1,200 @@
+import hashlib
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+RUNNER = ROOT / "tools" / "test_examples.py"
+FIXTURES = {
+ "compose": ROOT / "examples" / "validated" / "compose" / "compose.yaml",
+ "dockerfile": ROOT / "examples" / "validated" / "dockerfile" / "Dockerfile",
+ "kubernetes": ROOT / "examples" / "validated" / "kubernetes" / "web.yaml",
+ "github-actions": ROOT / "examples" / "validated" / "github-actions" / "validate.yml",
+}
+CHAPTER_SNIPPETS = {
+ "compose": ROOT / "11_compose" / "11.5_compose_file.md",
+ "dockerfile": ROOT / "07_dockerfile" / "README.md",
+ "kubernetes": ROOT / "13_kubernetes_concepts" / "13.5_practice.md",
+ "github-actions": ROOT / "21_case_devops" / "21.2_github_actions.md",
+}
+SCHEMA_ROOT = (
+ ROOT
+ / "examples"
+ / "validated"
+ / "kubernetes"
+ / "schemas"
+ / "v1.31.0-standalone-strict"
+)
+
+
+class ExampleValidationTests(unittest.TestCase):
+ def run_runner(self, *args, path=None, env=None):
+ run_env = os.environ.copy()
+ run_env.update(env or {})
+ if path is not None:
+ run_env["PATH"] = path
+ return subprocess.run(
+ [sys.executable, str(RUNNER), *args],
+ cwd=ROOT,
+ env=run_env,
+ capture_output=True,
+ text=True,
+ )
+
+ def test_canonical_fixture_files_exist(self):
+ missing = [name for name, path in FIXTURES.items() if not path.is_file()]
+
+ self.assertEqual(missing, [])
+
+ def test_relevant_chapters_link_to_canonical_fixtures(self):
+ references = {
+ ROOT / "11_compose" / "11.5_compose_file.md": "../examples/validated/compose/compose.yaml",
+ ROOT / "07_dockerfile" / "README.md": "../examples/validated/dockerfile/Dockerfile",
+ ROOT / "13_kubernetes_concepts" / "13.5_practice.md": "../examples/validated/kubernetes/web.yaml",
+ ROOT / "21_case_devops" / "21.2_github_actions.md": "../examples/validated/github-actions/validate.yml",
+ }
+
+ missing = []
+ for chapter, fixture in references.items():
+ if fixture not in chapter.read_text(encoding="utf-8"):
+ missing.append(f"{chapter.relative_to(ROOT)} -> {fixture}")
+ self.assertEqual(missing, [])
+
+ def test_chapter_canonical_blocks_exactly_match_fixtures(self):
+ mismatches = []
+ for name, chapter in CHAPTER_SNIPPETS.items():
+ text = chapter.read_text(encoding="utf-8")
+ match = re.search(
+ rf"\s*```[^\n]*\n(.*?)\n```",
+ text,
+ re.DOTALL,
+ )
+ expected = FIXTURES[name].read_text(encoding="utf-8").strip()
+ actual = match.group(1).strip() if match else None
+ if actual != expected:
+ mismatches.append(name)
+ self.assertEqual(mismatches, [])
+ self.assertNotIn(
+ "type: NodePort",
+ CHAPTER_SNIPPETS["kubernetes"].read_text(encoding="utf-8"),
+ )
+
+ def test_kubernetes_fixture_has_vendored_schema_provenance(self):
+ provenance = SCHEMA_ROOT.parent / "README.md"
+ schema_files = (
+ SCHEMA_ROOT / "deployment-apps-v1.json",
+ SCHEMA_ROOT / "service-v1.json",
+ )
+
+ self.assertTrue(provenance.is_file())
+ provenance_text = provenance.read_text(encoding="utf-8")
+ self.assertIn("v1.31.0-standalone-strict", provenance_text)
+ self.assertRegex(provenance_text, r"upstream commit: `[0-9a-f]{40}`")
+ for schema in schema_files:
+ self.assertTrue(schema.is_file(), schema)
+ digest = hashlib.sha256(schema.read_bytes()).hexdigest()
+ self.assertIn(f"`{schema.name}`: `{digest}`", provenance_text)
+
+ def test_dockerfile_fixture_has_no_remote_base_image(self):
+ dockerfile = FIXTURES["dockerfile"].read_text(encoding="utf-8")
+
+ self.assertEqual(dockerfile.splitlines()[0], "FROM scratch")
+
+ def test_github_actions_fixture_installs_integrity_pinned_validators(self):
+ text = FIXTURES["github-actions"].read_text(encoding="utf-8")
+
+ self.assertIn("KUBECONFORM_SHA256", text)
+ self.assertIn("ACTIONLINT_SHA256", text)
+ self.assertGreaterEqual(text.count("sha256sum -c -"), 2)
+ self.assertIn("tools/test_examples.py --require-tools", text)
+
+ def test_local_run_reports_skips_when_tools_are_unavailable(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ result = self.run_runner(path=tmp)
+
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertEqual(result.stdout.count("SKIP"), 4, result.stdout)
+ self.assertIn("docker compose", result.stdout)
+ self.assertIn("docker buildx", result.stdout)
+ self.assertIn("kubeconform", result.stdout)
+ self.assertIn("actionlint", result.stdout)
+
+ def test_required_run_fails_when_tools_are_unavailable(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ result = self.run_runner("--require-tools", path=tmp)
+
+ self.assertNotEqual(result.returncode, 0)
+ self.assertEqual(result.stdout.count("UNAVAILABLE"), 4, result.stdout)
+
+ def test_available_tools_receive_the_canonical_validation_commands(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ log = tmp_path / "commands.log"
+ shim = tmp_path / "validator-shim"
+ shim.write_text(
+ "#!/bin/sh\n"
+ "printf '%s %s\\n' \"$(basename \"$0\")\" \"$*\" >> \"$COMMAND_LOG\"\n"
+ "exit 0\n",
+ encoding="utf-8",
+ )
+ shim.chmod(0o755)
+ for name in ("docker", "kubeconform", "actionlint"):
+ (tmp_path / name).symlink_to(shim)
+
+ result = self.run_runner(
+ "--require-tools",
+ path=f"{tmp_path}:/usr/bin:/bin",
+ env={"COMMAND_LOG": str(log)},
+ )
+
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ commands = log.read_text(encoding="utf-8")
+ self.assertIn("docker compose version", commands)
+ self.assertIn("docker compose -f", commands)
+ self.assertIn("config --quiet", commands)
+ self.assertIn("docker buildx version", commands)
+ self.assertIn("docker buildx build --check", commands)
+ self.assertIn("kubeconform -strict -summary", commands)
+ self.assertIn("-schema-location file://", commands)
+ self.assertIn("actionlint", commands)
+
+ def test_runner_uses_only_vendored_schema_when_network_is_blocked(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ success = tmp_path / "success"
+ success.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+ success.chmod(0o755)
+ for name in ("docker", "actionlint"):
+ (tmp_path / name).symlink_to(success)
+
+ kubeconform = tmp_path / "kubeconform"
+ kubeconform.write_text(
+ "#!/bin/sh\n"
+ "case \"$*\" in\n"
+ " *'-schema-location file://'*) exit 0 ;;\n"
+ " *) exit 23 ;;\n"
+ "esac\n",
+ encoding="utf-8",
+ )
+ kubeconform.chmod(0o755)
+
+ result = self.run_runner(
+ "--require-tools",
+ path=f"{tmp_path}:/usr/bin:/bin",
+ env={
+ "HTTP_PROXY": "http://127.0.0.1:9",
+ "HTTPS_PROXY": "http://127.0.0.1:9",
+ "NO_PROXY": "",
+ },
+ )
+
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_html_list_rendering.py b/tests/test_html_list_rendering.py
new file mode 100644
index 000000000..dbc47e6c2
--- /dev/null
+++ b/tests/test_html_list_rendering.py
@@ -0,0 +1,85 @@
+"""Regression: the HTML reader must not collapse bold-lead-in lists into a paragraph.
+
+The book style writes a bold label immediately followed by a list, with no blank
+line between them:
+
+ **触发分离的条件**：
+ - 输入序列长度 > 某阈值
+
+Strict CommonMark (pandoc's default `-f markdown`) requires a blank line before a
+list, so it folds all three bullets into one . build_html_reader.py therefore +must pass `markdown+lists_without_preceding_blankline`. This test feeds that exact +pattern through the *real* pandoc invocation the reader uses and asserts the list +survives — the check that would have caught the 640 collapsed lists that shipped. +""" + +import re +import shutil +import subprocess +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +READER = ROOT / "tools" / "build_html_reader.py" + +# The pattern the book uses everywhere: bold lead-in, then a list, no blank line. +SAMPLE = "**触发分离的条件**：\n- 输入序列长度 > 某阈值\n- 输入序列未命中前缀缓存\n" + + +def _reader_pandoc_format() -> str: + """Extract the pandoc `-f` value the reader uses, across every fork shape. + + Forks differ: an inline "-f", "markdown..." literal, a `reader = "markdown..."` + variable, a `context="markdown..."` kwarg, or a PANDOC_MARKDOWN_READER constant + living in tools/publication_sources.py (possibly as an implicitly-joined + multiline string). Search both files and stitch adjacent string fragments. + """ + texts = [READER.read_text(encoding="utf-8")] + sources = READER.parent / "publication_sources.py" + if sources.is_file(): + texts.append(sources.read_text(encoding="utf-8")) + for src in texts: + for pat in ( + r'"-f",\s*"(markdown[^"]*)"', + r'reader\s*=\s*"(markdown[^"]*)"', + r'context="(markdown[^"]*)"', + # constant, one or more adjacent "..." fragments (implicit join) + r'PANDOC_MARKDOWN_READER\s*=\s*\(?\s*((?:"[^"]*"\s*)+)\)?', + ): + m = re.search(pat, src) + if m: + raw = m.group(1) + # collapse implicit string concatenation into one value + return "".join(re.findall(r'"([^"]*)"', raw)) or raw + raise AssertionError("could not find the reader's pandoc -f markdown format") + + +class HtmlListRenderingTests(unittest.TestCase): + def test_reader_declares_the_no_blank_line_list_extension(self): + fmt = _reader_pandoc_format() + self.assertIn( + "lists_without_preceding_blankline", + fmt, + "build_html_reader.py must enable lists_without_preceding_blankline; " + f"pandoc format is currently {fmt!r}. Without it, every bold-lead-in " + "list in the book collapses into a paragraph in the shipped HTML.", + ) + + def test_bold_lead_in_list_renders_as_ul_under_real_pandoc(self): + pandoc = shutil.which("pandoc") + if pandoc is None: + self.skipTest("pandoc not installed; CI installs it and runs this check") + fmt = _reader_pandoc_format() + out = subprocess.run( + [pandoc, "-f", fmt, "-t", "html5"], + input=SAMPLE, + capture_output=True, + text=True, + check=True, + ).stdout + self.assertIn("
- ", out, f"list collapsed; pandoc -f {fmt} produced:\n{out}")
+ self.assertEqual(out.count("
- "), 2, f"expected 2
- ; got:\n{out}")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_pages_workflow.py b/tests/test_pages_workflow.py
new file mode 100644
index 000000000..08a170d15
--- /dev/null
+++ b/tests/test_pages_workflow.py
@@ -0,0 +1,74 @@
+import re
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+WORKFLOW = ROOT / ".github" / "workflows" / "pages.yml"
+FULL_ACTION_SHA = re.compile(r"^[^@\s]+@[0-9a-f]{40}$")
+
+
+class PagesWorkflowTests(unittest.TestCase):
+ def workflow_text(self):
+ self.assertTrue(WORKFLOW.is_file(), "custom Pages workflow is missing")
+ return WORKFLOW.read_text(encoding="utf-8")
+
+ def test_custom_pages_workflow_exists(self):
+ self.assertTrue(WORKFLOW.is_file(), "custom Pages workflow is missing")
+
+ def test_builds_mdpress_site_without_jekyll(self):
+ text = self.workflow_text()
+
+ self.assertIn("npm run build", text)
+ self.assertIn("checksums.txt", text)
+ self.assertIn('install -m 0755 "$RUNNER_TEMP/mdpress" "$RUNNER_TEMP/bin/mdpress"', text)
+ self.assertIn('echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"', text)
+ self.assertRegex(text, r"path:\s*_site\b")
+ self.assertNotIn("jekyll", text.lower())
+
+ def test_verifies_built_site_title_before_upload(self):
+ text = self.workflow_text()
+ verify_at = text.find("tools/verify_artifacts.py")
+ upload_at = text.find("actions/upload-pages-artifact@")
+
+ self.assertGreaterEqual(verify_at, 0)
+ self.assertGreater(upload_at, verify_at)
+ self.assertIn('json.load(open("book.json", encoding="utf-8"))["title"]', text)
+ self.assertIn("--site _site", text)
+
+ def test_build_and_deploy_jobs_have_minimum_permissions(self):
+ text = self.workflow_text()
+
+ self.assertRegex(
+ text,
+ r"(?ms)^ build:\n permissions:\n contents: read\n pages: read\b",
+ )
+ self.assertRegex(
+ text,
+ r"(?ms)^ deploy:.*?permissions:\n pages: write\n id-token: write\b",
+ )
+ self.assertRegex(text, r"(?ms)^ deploy:.*?needs: build\b")
+ self.assertIn("environment:", text)
+ self.assertIn("name: github-pages", text)
+
+ def test_actions_are_immutable_and_checkout_drops_credentials(self):
+ text = self.workflow_text()
+ actions = re.findall(r"\buses:\s*([^\s#]+)", text)
+
+ self.assertGreater(len(actions), 0)
+ self.assertTrue(all(FULL_ACTION_SHA.fullmatch(action) for action in actions), actions)
+ self.assertRegex(text, r"actions/checkout@[0-9a-f]{40}\s+# v\d")
+ self.assertRegex(
+ text,
+ r"(?ms)actions/checkout@[0-9a-f]{40}.*?with:\n\s+persist-credentials: false",
+ )
+
+ def test_documents_manual_pages_source_setting(self):
+ text = self.workflow_text()
+
+ self.assertIn("Settings > Pages > Source", text)
+ self.assertIn("GitHub Actions", text)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_verify_artifacts.py b/tests/test_verify_artifacts.py
new file mode 100644
index 000000000..0d3b39e76
--- /dev/null
+++ b/tests/test_verify_artifacts.py
@@ -0,0 +1,90 @@
+import hashlib
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+VERIFIER = ROOT / "tools" / "verify_artifacts.py"
+
+
+class VerifyArtifactsTests(unittest.TestCase):
+ def run_verifier(self, *args):
+ return subprocess.run(
+ [sys.executable, str(VERIFIER), *args],
+ cwd=ROOT,
+ capture_output=True,
+ text=True,
+ )
+
+ def test_verifies_html_title_and_writes_sha256_manifest(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ artifact = Path(tmp) / "reader.html"
+ checksums = Path(tmp) / "SHA256SUMS"
+ artifact.write_text(
+ "
Docker —— 从入门到实践 ", + encoding="utf-8", + ) + + result = self.run_verifier( + "--title", + "Docker —— 从入门到实践", + "--html", + str(artifact), + "--checksums", + str(checksums), + ) + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + expected = hashlib.sha256(artifact.read_bytes()).hexdigest() + self.assertEqual(checksums.read_text(encoding="utf-8"), f"{expected} reader.html\n") + + def test_rejects_missing_artifact(self): + result = self.run_verifier( + "--title", + "Docker —— 从入门到实践", + "--html", + "/does/not/exist.html", + ) + + self.assertNotEqual(result.returncode, 0) + self.assertIn("does not exist", result.stderr) + + def test_rejects_wrong_html_title(self): + with tempfile.TemporaryDirectory() as tmp: + artifact = Path(tmp) / "reader.html" + artifact.write_text("Wrong book ", encoding="utf-8") + + result = self.run_verifier( + "--title", + "Docker —— 从入门到实践", + "--html", + str(artifact), + ) + + self.assertNotEqual(result.returncode, 0) + self.assertIn("title mismatch", result.stderr) + + def test_accepts_mdpress_site_title_with_page_suffix(self): + with tempfile.TemporaryDirectory() as tmp: + site = Path(tmp) / "_site" + site.mkdir() + (site / "index.html").write_text( + "Docker 从入门到实践 - Docker 从入门到实践 ", + encoding="utf-8", + ) + + result = self.run_verifier( + "--title", + "Docker 从入门到实践", + "--site", + str(site), + ) + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_workflow_security.py b/tests/test_workflow_security.py new file mode 100644 index 000000000..a1a03eb46 --- /dev/null +++ b/tests/test_workflow_security.py @@ -0,0 +1,415 @@ +import json +import os +import re +import subprocess +import tempfile +import textwrap +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +WORKFLOW_DIR = ROOT / ".github" / "workflows" +FULL_ACTION_SHA = re.compile(r"^[^@\s]+@[0-9a-f]{40}$") +TEST_REPOSITORY = "owner/repo" +TEST_SHA = "a" * 40 +GET_REF_COMMAND = [ + "api", + "--include", + "--method", + "GET", + f"repos/{TEST_REPOSITORY}/git/ref/tags/preview-pdf", +] +PATCH_REF_COMMAND = [ + "api", + "--silent", + "--method", + "PATCH", + f"repos/{TEST_REPOSITORY}/git/refs/tags/preview-pdf", + "--raw-field", + f"sha={TEST_SHA}", + "--field", + "force=true", +] +POST_REF_COMMAND = [ + "api", + "--silent", + "--method", + "POST", + f"repos/{TEST_REPOSITORY}/git/refs", + "--raw-field", + "ref=refs/tags/preview-pdf", + "--raw-field", + f"sha={TEST_SHA}", +] +EDIT_RELEASE_COMMAND = [ + "release", + "edit", + "preview-pdf", + "--title", + "Latest Preview PDF", + "--notes-file", + "dist/release-notes.md", + "--prerelease", +] +VIEW_RELEASE_COMMAND = ["release", "view", "preview-pdf"] +CREATE_RELEASE_COMMAND = [ + "release", + "create", + "preview-pdf", + "--title", + "Latest Preview PDF", + "--notes-file", + "dist/release-notes.md", + "--prerelease", + "--latest=false", + "--verify-tag", +] + +FAKE_GH = r'''#!/usr/bin/env python3 +import json +import os +import sys + +args = sys.argv[1:] +with open(os.environ["GH_LOG"], "a", encoding="utf-8") as stream: + stream.write(json.dumps(args) + "\n") + +scenario = os.environ["GH_SCENARIO"] +repository = "owner/repo" +sha = "a" * 40 +reasons = { + "401": "Unauthorized", + "403": "Forbidden", + "404": "Not Found", + "429": "Too Many Requests", + "503": "Service Unavailable", +} + +def fail_http(code): + print(f"HTTP/2.0 {code} {reasons[code]}") + print(f"fake gh HTTP {code}", file=sys.stderr) + raise SystemExit(1) + +get_ref = ["api", "--include", "--method", "GET", f"repos/{repository}/git/ref/tags/preview-pdf"] +patch_ref = [ + "api", "--silent", "--method", "PATCH", + f"repos/{repository}/git/refs/tags/preview-pdf", + "--raw-field", f"sha={sha}", "--field", "force=true", +] +post_ref = [ + "api", "--silent", "--method", "POST", f"repos/{repository}/git/refs", + "--raw-field", "ref=refs/tags/preview-pdf", "--raw-field", f"sha={sha}", +] +edit_release = [ + "release", "edit", "preview-pdf", "--title", "Latest Preview PDF", + "--notes-file", "dist/release-notes.md", "--prerelease", +] +create_release = [ + "release", "create", "preview-pdf", "--title", "Latest Preview PDF", + "--notes-file", "dist/release-notes.md", "--prerelease", + "--latest=false", "--verify-tag", +] +view_release = ["release", "view", "preview-pdf"] + +if os.environ.get("GH_REPO") != repository: + print("fake gh requires explicit GH_REPO", file=sys.stderr) + raise SystemExit(2) + +if args == get_ref: + if scenario.startswith("ref_network"): + print("fake gh network failure", file=sys.stderr) + raise SystemExit(1) + for code in reasons: + if scenario.startswith(f"ref_{code}"): + fail_http(code) + print("HTTP/2.0 200 OK") + print('Content-Type: application/json\n\n{"ref":"refs/tags/preview-pdf"}') + raise SystemExit(0) + +if args in (patch_ref, post_ref, edit_release, create_release): + raise SystemExit(0) + +if args == view_release: + if "release_missing" in scenario: + print("release not found", file=sys.stderr) + raise SystemExit(1) + if "release_network" in scenario: + print("fake release network failure", file=sys.stderr) + raise SystemExit(1) + for code in reasons: + if f"release_{code}" in scenario: + print(f"fake release HTTP {code}", file=sys.stderr) + raise SystemExit(1) + raise SystemExit(0) + +print(f"unexpected gh argv: {args!r}", file=sys.stderr) +raise SystemExit(2) +''' + + +def workflow_step_script(workflow_text, step_name): + marker = f" - name: {step_name}\n" + start = workflow_text.index(marker) + len(marker) + run_marker = " run: |\n" + script_start = workflow_text.index(run_marker, start) + len(run_marker) + script_end = workflow_text.find("\n - name:", script_start) + if script_end < 0: + script_end = len(workflow_text) + return textwrap.dedent(workflow_text[script_start:script_end]) + + +def workflow_step_scripts_in_document_order(workflow_text, step_names): + ordered_names = sorted( + step_names, + key=lambda name: workflow_text.index(f" - name: {name}\n"), + ) + return tuple(workflow_step_script(workflow_text, name) for name in ordered_names) + + +class WorkflowSecurityTests(unittest.TestCase): + @staticmethod + def workflows(): + return sorted(WORKFLOW_DIR.glob("*.y*ml")) + + def test_all_actions_are_immutable_with_version_comments(self): + failures = [] + for workflow in self.workflows(): + for number, line in enumerate(workflow.read_text(encoding="utf-8").splitlines(), 1): + match = re.search(r"\buses:\s*([^\s#]+)(?:\s+#\s*(\S+))?", line) + if not match: + continue + action, version = match.groups() + if not FULL_ACTION_SHA.fullmatch(action) or not version or not version.startswith("v"): + failures.append(f"{workflow.name}:{number}: {line.strip()}") + self.assertEqual(failures, []) + + def test_checkout_never_persists_credentials(self): + failures = [] + for workflow in self.workflows(): + lines = workflow.read_text(encoding="utf-8").splitlines() + for index, line in enumerate(lines): + if "uses: actions/checkout@" not in line: + continue + step = "\n".join(lines[index : index + 8]) + if "persist-credentials: false" not in step: + failures.append(f"{workflow.name}:{index + 1}") + self.assertEqual(failures, []) + + def test_every_workflow_declares_permissions(self): + failures = [] + for workflow in self.workflows(): + text = workflow.read_text(encoding="utf-8") + before_jobs = text.split("\njobs:", 1)[0] + if not re.search(r"(?m)^permissions:", before_jobs): + failures.append(workflow.name) + self.assertEqual(failures, []) + + def test_release_and_preview_separate_read_only_builds_from_writes(self): + expectations = { + "auto-release.yml": ("release",), + "preview-pdf.yml": ("publish",), + } + for name, write_jobs in expectations.items(): + text = (WORKFLOW_DIR / name).read_text(encoding="utf-8") + self.assertRegex(text, r"(?ms)^ build:\n permissions:\n contents: read\b", name) + for job in write_jobs: + self.assertRegex( + text, + rf"(?ms)^ {job}:.*?permissions:\n contents: write\b.*?needs: build\b", + name, + ) + + def test_preview_publish_steps_follow_tag_release_asset_order(self): + preview = (WORKFLOW_DIR / "preview-pdf.yml").read_text(encoding="utf-8") + synchronize = preview.index(" - name: Synchronize mutable preview tag\n") + release = preview.index(" - name: Create or update preview release\n") + upload = preview.index(" - name: Replace preview assets\n") + + self.assertLess(synchronize, release) + self.assertLess(release, upload) + + def run_preview_scripts( + self, + scenario, + *, + repository=TEST_REPOSITORY, + sha=TEST_SHA, + ): + preview = (WORKFLOW_DIR / "preview-pdf.yml").read_text(encoding="utf-8") + scripts = workflow_step_scripts_in_document_order( + preview, + ( + "Synchronize mutable preview tag", + "Create or update preview release", + ), + ) + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + fake_gh = root / "gh" + fake_gh.write_text(FAKE_GH, encoding="utf-8") + fake_gh.chmod(0o755) + log = root / "commands.jsonl" + env = os.environ.copy() + env.update( + { + "PATH": f"{root}:{env.get('PATH', '')}", + "GH_LOG": str(log), + "GH_SCENARIO": scenario, + "GH_TOKEN": "test-token", + "GH_REPO": repository, + "GITHUB_REPOSITORY": repository, + "GITHUB_SHA": sha, + } + ) + result = None + for script in scripts: + result = subprocess.run( + ["/bin/bash", "-c", script], + cwd=ROOT, + env=env, + capture_output=True, + text=True, + ) + if result.returncode != 0: + break + commands = [] + if log.exists(): + commands = [ + json.loads(line) + for line in log.read_text(encoding="utf-8").splitlines() + ] + return result, commands + + def test_mutable_preview_updates_existing_tag_and_release(self): + result, commands = self.run_preview_scripts("ref_200_release_exists") + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual( + commands, + [GET_REF_COMMAND, PATCH_REF_COMMAND, VIEW_RELEASE_COMMAND, EDIT_RELEASE_COMMAND], + ) + + def test_mutable_preview_creates_only_on_explicit_not_found(self): + result, commands = self.run_preview_scripts("ref_404_release_missing") + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual( + commands, + [GET_REF_COMMAND, POST_REF_COMMAND, VIEW_RELEASE_COMMAND, CREATE_RELEASE_COMMAND], + ) + flattened = [argument for command in commands for argument in command] + self.assertNotIn("--target", flattened) + + def test_preview_rejects_invalid_repository_and_sha_before_calling_gh(self): + cases = ( + {"repository": "owner/repo/extra", "sha": TEST_SHA, "message": "Invalid GITHUB_REPOSITORY"}, + {"repository": TEST_REPOSITORY, "sha": "a" * 39, "message": "Invalid GITHUB_SHA"}, + ) + for case in cases: + with self.subTest(case=case): + result, commands = self.run_preview_scripts( + "ref_200_release_exists", + repository=case["repository"], + sha=case["sha"], + ) + self.assertNotEqual(result.returncode, 0) + self.assertEqual(commands, []) + self.assertIn(case["message"], result.stderr) + + def test_preview_tag_lookup_fails_closed_on_non_404_errors(self): + for scenario in ("ref_401", "ref_403", "ref_429", "ref_503", "ref_network"): + with self.subTest(scenario=scenario): + result, commands = self.run_preview_scripts(scenario) + self.assertNotEqual(result.returncode, 0) + self.assertEqual(commands, [GET_REF_COMMAND]) + expected = "network failure" if scenario.endswith("network") else scenario.removeprefix("ref_") + self.assertIn(expected, result.stderr) + + def test_preview_release_lookup_fails_closed_except_exact_not_found(self): + scenarios = ( + "ref_200_release_401", + "ref_200_release_403", + "ref_200_release_404", + "ref_200_release_429", + "ref_200_release_503", + "ref_200_release_network", + ) + for scenario in scenarios: + with self.subTest(scenario=scenario): + result, commands = self.run_preview_scripts(scenario) + self.assertNotEqual(result.returncode, 0) + self.assertEqual( + commands, + [GET_REF_COMMAND, PATCH_REF_COMMAND, VIEW_RELEASE_COMMAND], + ) + expected = "network failure" if scenario.endswith("network") else scenario.rsplit("release_", 1)[1] + self.assertIn(expected, result.stderr) + + def test_preview_publish_has_explicit_repo_context_only_in_write_job(self): + preview = (WORKFLOW_DIR / "preview-pdf.yml").read_text(encoding="utf-8") + build, publish = preview.split("\n publish:\n", 1) + + self.assertNotIn("GH_REPO", build) + self.assertIn("GH_REPO: ${{ github.repository }}", publish) + + def test_downloads_dependencies_and_link_checker_are_integrity_pinned(self): + combined = "\n".join(path.read_text(encoding="utf-8") for path in self.workflows()) + link_text = (WORKFLOW_DIR / "check-link.yml").read_text(encoding="utf-8") + + self.assertNotRegex(combined, r"npm install\s+-g\s+@mermaid-js/mermaid-cli") + self.assertIn("PANDOC_SHA256", combined) + self.assertIn("KUBECONFORM_SHA256", combined) + self.assertIn("ACTIONLINT_SHA256", combined) + self.assertRegex(link_text, r"dkhamsing/awesome_bot@sha256:[0-9a-f]{64}") + + def test_mermaid_is_exact_and_lockfile_backed(self): + package = json.loads((ROOT / "package.json").read_text(encoding="utf-8")) + version = package["devDependencies"]["@mermaid-js/mermaid-cli"] + + self.assertRegex(version, r"^\d+\.\d+\.\d+$") + self.assertTrue((ROOT / "package-lock.json").is_file()) + ignored = { + line.strip() + for line in (ROOT / ".gitignore").read_text(encoding="utf-8").splitlines() + if line.strip() and not line.lstrip().startswith("#") + } + self.assertNotIn("package-lock.json", ignored) + self.assertTrue(all("npm ci" in path.read_text(encoding="utf-8") for path in self.workflows() if path.name not in {"check-link.yml", "dependabot-automerge.yml", "identity-guard.yaml"})) + + def test_artifacts_are_smoke_tested_and_html_failures_are_not_silent(self): + verifier = ROOT / "tools" / "verify_artifacts.py" + self.assertTrue(verifier.is_file()) + for name in ("auto-release.yml", "ci.yaml", "preview-pdf.yml"): + text = (WORKFLOW_DIR / name).read_text(encoding="utf-8") + self.assertIn("tools/verify_artifacts.py", text, name) + self.assertIn("SHA256SUMS", text, name) + auto_release = (WORKFLOW_DIR / "auto-release.yml").read_text(encoding="utf-8") + self.assertNotIn("continue-on-error: true", auto_release) + + def test_tagged_release_attests_every_formal_artifact_with_minimum_permissions(self): + release = (WORKFLOW_DIR / "auto-release.yml").read_text(encoding="utf-8") + preview = (WORKFLOW_DIR / "preview-pdf.yml").read_text(encoding="utf-8") + build_part, release_job = release.split("\n release:\n", 1) + + self.assertIn("contents: write", release_job) + self.assertIn("id-token: write", release_job) + self.assertIn("attestations: write", release_job) + self.assertRegex( + release_job, + r"actions/attest-build-provenance@[0-9a-f]{40} # v\d", + ) + self.assertIn("subject-path: |", release_job) + self.assertIn("dist/docker_practice-*.pdf", release_job) + self.assertIn("dist/docker_practice-*.html", release_job) + self.assertIn("dist/SHA256SUMS", release_job) + self.assertNotIn("attest-build-provenance", build_part) + self.assertNotIn("attestations: write", build_part) + self.assertNotIn("id-token: write", build_part) + self.assertNotIn("attest-build-provenance", preview) + self.assertIn("mutable preview", preview.lower()) + self.assertIn("tagged release", preview.lower()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/build_html_reader.py b/tools/build_html_reader.py new file mode 100644 index 000000000..d80a58d90 --- /dev/null +++ b/tools/build_html_reader.py @@ -0,0 +1,265 @@ +#!/usr/bin/env python3 +"""Build a single self-contained, GitBook-style PAGED mobile reader — offline-robust. + +Works even where JavaScript is disabled (iOS Files/Quick Look): pages are a readable +scroll by default; JS (Safari, Documents app, etc.) upgrades to one-page-at-a-time. +- Math: pandoc --mathml (native WebKit, no JS) +- Mermaid: PRE-RENDERED to static SVG (no JS, no mermaid.js) — pass --svg-dir +- TOC drawer: CSS checkbox hack (opens without JS); prev/next are static anchors +- Images/CSS embedded (--embed-resources) -> one offline file +""" +import argparse, os, re, subprocess, sys, posixpath + +def esc(s): return s.replace("&","&").replace("<","<").replace(">",">") +def escattr(s): return s.replace("&","&").replace('"',""").replace("<","<") + +def parse_summary(book_dir): + items, seen = [], set() + with open(os.path.join(book_dir, "SUMMARY.md"), encoding="utf-8") as f: + for line in f: + m = re.match(r'^##\s+(.+?)\s*$', line) + if m: items.append(("part", m.group(1))); continue + m = re.match(r'^(\s*)[-*]\s+\[(.*?)\]\(([^)]+?)\)', line) + if m: + indent, title, path = m.group(1), m.group(2).strip(), m.group(3).strip() + if path.endswith(".md") and path not in seen and os.path.isfile(os.path.join(book_dir, path)): + seen.add(path) + items.append(("file", path, title, min(len(indent.replace("\t"," "))//2, 2))) + return items + +def fix_inline_dollar(text): + def repl(m): + s, e = m.start(), m.end(); inner = m.group(1) + if "\n" in inner: return m.group(0) + ls = text.rfind("\n", 0, s) + 1 + le = text.find("\n", e); le = len(text) if le < 0 else le + if text[ls:s].strip() == "" and text[e:le].strip() == "": return m.group(0) + return "$" + inner.strip() + "$" + return re.sub(r'\$\$(.+?)\$\$', repl, text, flags=re.DOTALL) + +def process_file(text, reldir, mermaid_store, path_to_id): + def grab(m): + idx = len(mermaid_store); mermaid_store.append(m.group(1)) + return f"\n\nMERMAIDZZ{idx}ZZ\n\n" + text = re.sub(r'```mermaid[ \t]*\n(.*?)\n[ \t]*```', grab, text, flags=re.DOTALL) + text = fix_inline_dollar(text) + text = re.sub(r'\[!\[[^\]]*\]\(https?://[^)]*\)\]\([^)]*\)', '', text) + text = re.sub(r'!\[[^\]]*\]\(https?://[^)]*\)', '', text) + text = re.sub(r'^\s*\[\]\([^)]*\)\s*$', '', text, flags=re.M) + def md_img(m): + alt, url = m.group(1), m.group(2).strip() + if url.startswith(("http://","https://","/","data:")): return m.group(0) + return f")})" + text = re.sub(r'!\[([^\]]*)\]\(([^)]+)\)', md_img, text) + def html_img(m): + src = m.group(1) + if src.startswith(("http://","https://","/","data:")): return m.group(0) + return m.group(0).replace(f'src="{src}"', f'src="{posixpath.normpath(posixpath.join(reldir, src))}"') + text = re.sub(r'$title$ + + + + +$title$ + + ++$body$ + + + + +''' + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--book-dir", required=True) + ap.add_argument("--title", required=True) + ap.add_argument("--out", required=True) + ap.add_argument("--svg-dir", required=True, help="dir with pre-rendered d-1.svg .. d-N.svg") + a = ap.parse_args() + book_dir = os.path.abspath(a.book_dir) + + items = parse_summary(book_dir) + page_meta, path_to_id, pidc = [], {}, 0 + for it in items: + if it[0] == "file": + _, path, title, lvl = it + page_meta.append((f"p{pidc}", path, title, lvl)) + path_to_id[posixpath.normpath(path)] = f"p{pidc}"; pidc += 1 + id_to_title = {pi: ti for (pi, _, ti, _) in page_meta} + + mermaid_store, chunks, pi = [], [], 0 + for it in items: + if it[0] != "file": continue + _, path, title, lvl = it + with open(os.path.join(book_dir, path), encoding="utf-8") as f: txt = f.read() + txt = process_file(txt, posixpath.dirname(path), mermaid_store, path_to_id) + chunks.append(f'\n\nPGBKZZp{pi}ZZ\n\n{txt}\n\n'); pi += 1 + combined = "\n".join(chunks) + print(f" pages: {len(page_meta)}, mermaid blocks: {len(mermaid_store)}") + + # load pre-rendered SVGs, namespace ids to avoid collisions; fall back to source on miss + svgs, missing = [], 0 + for i in range(len(mermaid_store)): + p = os.path.join(a.svg_dir, f"d-{i+1}.svg") + if os.path.isfile(p) and os.path.getsize(p) > 0: + s = open(p, encoding="utf-8").read() + j = s.find("' + esc(mermaid_store[i]) + '
') + if missing: print(f" WARNING: {missing}/{len(mermaid_store)} diagrams failed to render -> showing source as fallback") + + # sidebar TOC + sb = ['目录- ']; fi = 0
+ for it in items:
+ if it[0] == "part": sb.append(f'