From 7eaa5786d1bd4b33c04f8a621052c76717bdc2bd Mon Sep 17 00:00:00 2001 From: jaywcjlove <398188662@qq.com> Date: Sat, 11 May 2024 17:46:32 +0800 Subject: [PATCH] doc: update docs/docker-compose.md (#645) --- docs/docker-compose.md | 270 ++++++++++++++++++++++++++++------------- 1 file changed, 186 insertions(+), 84 deletions(-) diff --git a/docs/docker-compose.md b/docs/docker-compose.md index 949ed77..1edcaf3 100644 --- a/docs/docker-compose.md +++ b/docs/docker-compose.md @@ -1,82 +1,132 @@ -docker-compose 备忘清单 +Docker Compose 备忘清单 === -这是 [docker-compose](https://docs.docker.com/compose/) 的官方文档。 你可以在这里找到最常见的 docker-compose 使用方式。 ---- +这是 [docker-compose](https://docs.docker.com/compose/) 的快速参考备忘单。你可以在这里找到最常见的 Docker Compose 使用方式。 入门 --- - -#### 安装 docker-compose 需要安装（docker desktop） +### Docker Compose 是什么？ -- windows 安装 +- `Docker-compsoe` 是一个开源项目，用于定义和运行多容器 `Docker` 应用程序的工具。由 `Docker` 社区维护。 +- 通过一个 `YAML` 文件来配置应用程序的服务，以便可以使用一个命令启动、停止和重启整个应用程序。 +- [Docker Compose 开源地址](https://github.com/docker/compose) +- [Docker Compose 发行地址](https://github.com/docker/compose/releases) _github.com_ - - 官网地址:[https://docs.docker.com/desktop/install/windows-install/](https://docs.docker.com/desktop/install/windows-install/) +### 基本概念 -- linux 版本安装 +- **服务 (services):** 一个服务指的是一个容器，即一个应用程序的一个实例。 +- **容器 (container):** `Docker` 容器，其中运行着应用程序的一个实例。 +- **镜像 (image):** `Docker` 镜像，用于创建容器的模板。 +- **Docker-Compose 文件：** 一个 `YAML` 文件，描述了应用程序的各个服务以及它们之间的关系、配置等信息。 - - 官网地址:[https://docs.docker.com/desktop/install/linux-install/](https://docs.docker.com/desktop/install/linux-install/) +### Docker-Compose 文件结构 -- mac 版本安装 +- `version`: _Docker-Compose_ 文件的版本。 +- `services`: 定义了各个服务，每个服务都有自己的配置项，如镜像、端口映射、依赖等。 +- `networks`: 定义了应用程序使用的网络，可以自定义网络以控制服务之间的通信。 +- `volumes`: 定义了应用程序使用的卷，用于持久化数据或与主机共享文件。 - - 官网地址:[https://docs.docker.com/desktop/install/mac-install/](https://docs.docker.com/desktop/install/mac-install/) +### 安装 + -- 可以通过 releases 下载安装 releases 地址：[https://github.com/docker/compose/releases](https://github.com/docker/compose/releases) +对于 Ubuntu 和 Debian，运行： -- 安装成功 - - ```sh - docker compose version - Docker Compose version v2.17.3 +```bash +sudo apt-get update +sudo apt-get install docker-compose-plugin +``` - docker --version - Docker version 23.0.5, build bc4487a +对于基于 RPM 的发行版，运行： - docker version - Client: Docker Engine - Community - Cloud integration: v1.0.31 - Version: 23.0.5 - API version: 1.42 - <...> - ``` +```bash +sudo yum update +sudo yum install docker-compose-plugin +``` -介绍 ---- +通过检查版本来验证 Docker Compose 是否正确安装 -**Docker-Compose 是什么？** +```sh +docker compose version +# Docker Compose version v2.17.3 - - `Docker-compsoe` 是一个开源项目，用于定义和运行多容器 `Docker` 应用程序的工具。由 `Docker` 社区维护。 +docker --version +# Docker version 23.0.5, build bc4487a - - 通过一个 `YAML` 文件来配置应用程序的服务，以便可以使用一个命令启动、停止和重启整个应用程序。 +docker version +# Client: Docker Engine - Community +# Cloud integration: v1.0.31 +# Version: 23.0.5 +# API version: 1.42 +# <...> +``` - - 开源地址：[https://github.com/docker/compose](https://github.com/docker/compose) - - - releases 地址：[https://github.com/docker/compose/releases](https://github.com/docker/compose/releases) +### 独立安装 Compose -**基本概念：** - - - **服务 (services):** 一个服务指的是一个容器，即一个应用程序的一个实例。 - - - **容器 (container):** `Docker` 容器，其中运行着应用程序的一个实例。 - - - **镜像 (image):** `Docker` 镜像，用于创建容器的模板。 - - - **Docker-Compose 文件：** 一个 `YAML` 文件，描述了应用程序的各个服务以及它们之间的关系、配置等信息。 +```sh +curl -SL https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose +``` + -**Docker-Compose 文件结构：** - - - `version`: `Docker-Compose` 文件的版本。 - - - `services`: 定义了各个服务，每个服务都有自己的配置项，如镜像、端口映射、依赖等。 - - - `networks`: 定义了应用程序使用的网络，可以自定义网络以控制服务之间的通信。 - - - `volumes`: 定义了应用程序使用的卷，用于持久化数据或与主机共享文件。 +如果命令 `docker-compose` 安装失败，请检查你的路径。你也可以创建一个符号链接，指向 `/usr/bin` 或路径中的任何其他目录。例如 -命令 ---- -**常用命令：** +```sh +$ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose +``` + + +### 更新 Compose + +对于 Ubuntu 和 Debian，运行： + +```sh +sudo apt-get update +sudo apt-get install docker-compose-plugin +``` + +对于基于 RPM 的发行版，运行： + +```sh +sudo yum update +sudo yum install docker-compose-plugin +``` + +### 卸载 Docker Compose + + +Ubuntu, Debian: + +```sh +sudo apt-get remove docker-compose-plugin +``` + +基于 RPM 的发行版 + +```sh +sudo yum remove docker-compose-plugin +``` + +如果您使用curl安装Compose CLI插件，要卸载它，请运行： + +```sh +rm $DOCKER_CONFIG/cli-plugins/docker-compose +``` + +为所有用户删除，或者，如果您已为所有用户安装 Compose，请运行： + +```sh +rm /usr/local/lib/docker/cli-plugins/docker-compose +``` + +### 检查 Compose 的安装位置 + + +```sh +docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}' +``` + +### 常用命令 + | docker compose命令 | 说明 | 常见参数说明 | | ------------------------ | ---------------- | -------------------- | @@ -96,65 +146,117 @@ docker-compose 备忘清单 | `docker compose images` | 列出镜像 | | | `docker compose push` | 推送镜像 | | | `docker compose version` | 查看版本信息 | | + -配置模板 +Docker Compose 配置 --- -**示例 Docker-Compose 文件：** +### 示例配置文件 + -`docker-compsoe` 的配置文件是一个 `YAML` 文件，用于定义和运行多容器 Docker 应用程序。它使用 一个单一的 YAML 文件（通常命名为 `docker-compose.yml`）来定义多个容器的集合，以及它们之间的依赖关系和服务。 +`docker-compose` 的配置文件是一个 `YAML` 文件，用于定义和运行多容器 Docker 应用程序。通常命名为 `docker-compose.yml`，它使用单一的 YAML 文件来定义多个容器的集合，以及它们之间的依赖关系和服务。以下是一份 `docker-compose.yml` 文件的配置模板，包含了常用配置项和解释： -以下是一份 `docker-compose.yml` 文件的配置模板，包含了常用配置项和解释： - -```yaml -version: '3' # 指定使用的Docker Compose文件格式版本，目前推荐使用3.x或更高 +```yml +version: '3' # 指定使用的 Docker Compose 文件格式版本，目前推荐使用 3.x 或更高 services: # 定义一个或多个服务 service1: # 服务名称 - image: nginx:latest # 使用的Docker镜像，这里是Nginx的最新版本 - # 或者使用构建指令来从Dockerfile构建镜像 + image: nginx:latest # 使用的 Docker 镜像，这里是 Nginx 的最新版本 + + # 或者使用构建指令来从 Dockerfile 构建镜像 build: - context: ./path/to/Dockerfile # Dockerfile所在的目录 - dockerfile: Dockerfile-alternative # 可选的Dockerfile名称，默认是Dockerfile + context: ./path/to/Dockerfile # Dockerfile 所在的目录 + dockerfile: Dockerfile-alternative # 可选的 Dockerfile 名称，默认是 Dockerfile # 容器启动时执行的命令，覆盖默认的命令 - command: ["nginx", "-g", "daemon off;"] # 以数组形式指定，防止shell解析 + command: + - "nginx" + - "-g" + - "daemon off;" # 以数组形式指定，防止 shell 解析 ports: # 容器端口与主机端口映射 - - "80:80" # 主机80端口映射到容器的80端口 + - "80:80" # 主机 80 端口映射到容器的 80 端口 volumes: # 数据卷挂载 - - ./nginx.conf:/etc/nginx/nginx.conf:ro # 将主机上的nginx.conf挂载到容器的/etc/nginx/nginx.conf，只读 - - ./logs:/var/log/nginx # 将logs目录挂载到容器的/var/log/nginx + - ./nginx.conf:/etc/nginx/nginx.conf:ro # 将主机上的 nginx.conf 挂载到容器的 /etc/nginx/nginx.conf，只读 + - ./logs:/var/log/nginx # 将 logs 目录挂载到容器的 /var/log/nginx environment: # 设置环境变量 - - MYSQL_HOST=database # 可以引用其他服务，这里假设有一个名为database的服务 + - MYSQL_HOST=database # 可以引用其他服务，这里假设有一个名为 database 的服务 - MYSQL_PORT=3306 - depends_on: # 服务启动顺序，这里表明service1依赖于database服务 + depends_on: # 服务启动顺序，这里表明 service1 依赖于 database 服务 - database networks: # 定义网络 - - my_network # 参与名为my_network的网络 + - my_network # 参与名为 my_network 的网络 service2: # 另一个服务示例 # ... 类似地定义其他服务 -networks: # 定义网络 +networks: # 定义网络 my_network: # 网络名称 - driver: bridge # 网络驱动，通常是bridge模式 + driver: bridge # 网络驱动，通常是 bridge 模式 volumes: # 定义数据卷 nginx_logs: # 卷名称 + ``` - -**备忘录事项** +备忘录事项 - - 配置文件中的缩进必须使用空格，不能使用制表符。 - - 可以使用环境变量来动态设置配置项，如数据库密码。 - - 使用 `Docker-Compose` 可以简化多容器应用程序的部署和管理，但需要注意容器之间的依赖关系和通信。 - - 当你修改了 `docker-compose.yml` 文件后，需要重新运行 `docker-compose up` 来使改动生效。 - - 使用 `docker-compose build` 仅重建镜像，而不启动容器。 - - 使用 `docker-compose restart` 重启容器。 - - 记得清理不再需要的容器和镜像，以避免磁盘空间不足。 +- 使用 Docker-Compose 可以简化多容器应用程序的部署和管理，但需要注意容器之间的依赖关系和通信。 +- 配置文件中的缩进必须使用空格，不能使用制表符。 +- 可以使用环境变量来动态设置配置项，如数据库密码。 +- 当你修改了 `docker-compose.yml` 文件后，需要重新运行 `docker-compose up` 来使改动生效。 +- 使用 `docker-compose build` 仅重建镜像，而不启动容器。 +- 使用 `docker-compose restart` 重启容器。 +- 记得清理不再需要的容器和镜像，以避免磁盘空间不足。 + +### 使用环境变量 + +与 `docker run -e VARIABLE=VALUE ...` 相同 + +```yml +web: + environment: + - DEBUG=1 +``` + +您可以选择不设置值并将环境变量从 shell 直接传递到容器。它的工作方式与 `docker run -e VARIABLE ...` 相同： + +```yml +web: + environment: + - DEBUG +web: + environment: + - DEBUG=${DEBUG} +``` + +`env_file` 属性允许您在 Compose 应用程序中使用多个 `.env` 文件。 +它的工作方式与 `docker run --env-file=FILE ...` 相同。 + +```yml +web: + env_file: + - web-variables.env +``` + +#### 额外的信息 + +```yml +env_file: + - path: ./default.env + required: true # default + - path: ./override.env + required: false +``` + +- 如果指定了多个文件，则它们将按顺序进行评估，可以覆盖先前文件中设置的值。 +- 在 `.env` 文件中声明的环境变量不能在 Compose 文件中单独再次引用。 +- 如果同时使用 `env_file` 和 `environment` 属性，则由 `environment` 设置的环境变量优先级更高。 +- 在 `env_file` 属性中指定的 `.env` 文件的路径是相对于 compose.yml 文件的位置的。 +- `.env` 文件中的值可以通过使用 `docker compose run -e` 命令行来从命令行覆盖。 +- 如果使用 `--env-file` 替换了另一个 `.env`，则您的 `.env` 文件可以被另一个 `.env` 文件覆盖。 +- 从 Docker Compose 版本 2.24.0 开始，您可以通过使用 `required` 字段将 `.env` 文件设置为可选项。当 `required` 设置为 `false` 且 `.env` 文件丢失时，Compose 将静默忽略该条目