Release v1.5.0: Restructure chapters and update for Docker v30.x

04_image/dockerfile/expose.md

@@ -0,0 +1,219 @@
+# EXPOSE 声明端口
+
+## 基本语法
+
+```docker
+EXPOSE <端口> [<端口>/<协议>...]
+```
+
+`EXPOSE` 声明容器运行时提供服务的端口。这是一个**文档性质的声明**，告诉使用者容器会监听哪些端口。
+
+---
+
+## 基本用法
+
+```docker
+# 声明单个端口
+EXPOSE 80
+
+# 声明多个端口
+EXPOSE 80 443
+
+# 声明 TCP 和 UDP 端口
+EXPOSE 80/tcp
+EXPOSE 53/udp
+```
+
+---
+
+## 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
+```
+
+---
+
+## EXPOSE vs -p
+
+| 特性 | EXPOSE | -p |
+|------|--------|-----|
+| **位置** | Dockerfile | docker run 命令 |
+| **作用** | 声明/文档 | 实际端口映射 |
+| **是否必需** | 否 | 是（外部访问时） |
+| **映射发生时** | 不发生 | 运行时发生 |
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                        EXPOSE 80                           │
+│                          ↓                                 │
+│                    仅声明意图                               │
+│        └───────────────────────────────────────┘           │
+│                                                            │
+│                     docker run -p                          │
+│                          ↓                                 │
+│              ┌─────────────────────┐                       │
+│              │   实际端口映射       │                       │
+│              │   宿主机 ←→ 容器    │                       │
+│              └─────────────────────┘                       │
+└────────────────────────────────────────────────────────────┘
+```
+
+### 没有 EXPOSE 也能 -p
+
+```docker
+# 即使没有 EXPOSE，也可以使用 -p
+FROM nginx
+# 没有 EXPOSE
+```
+
+```bash
+# 仍然可以映射端口
+$ docker run -p 8080:80 mynginx
+```
+
+---
+
+## 常见误解
+
+### 误解：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
+```
+
+---
+
+## 最佳实践
+
+### 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
+```
+
+---
+
+## 使用环境变量
+
+```docker
+ARG PORT=80
+EXPOSE $PORT
+```
+
+---
+
+## 在 Compose 中
+
+```yaml
+services:
+  web:
+    build: .
+    ports:
+      - "8080:80"    # 映射端口（类似 -p）
+    expose:
+      - "80"         # 仅声明（类似 EXPOSE）
+```
+
+`expose` 在 Compose 中仅用于容器间通信的文档说明，不进行端口映射。
+
+---
+
+## 本章小结
+
+| 要点 | 说明 |
+|------|------|
+| **作用** | 声明容器提供服务的端口（文档） |
+| **不会** | 自动映射端口或开放外部访问 |
+| **配合** | `docker run -P` 自动映射 |
+| **外部访问** | 需要 `-p 宿主机端口:容器端口` |
+| **语法** | `EXPOSE 80` 或 `EXPOSE 80/tcp` |
+
+## 延伸阅读
+
+- [网络配置](../../network/README.md)：Docker 网络详解
+- [端口映射](../../network/port_bindingbindingbinding.md)：-p 参数详解
+- [Compose 端口](../../compose/compose_file.md)：Compose 中的端口配置