【docker 】Compose 使用介绍

Docker Compose

Docker Compose文档

Docker Compose GitHub地址

Docker Compose 是用于定义和运行多容器 Docker 应用程序的工具。通过 Compose，您可以使用 YML 文件来配置应用程序需要的所有服务。然后，使用一个命令，就可以从 YML 文件配置中创建并启动所有服务。

在`Compose` 中有两个重要的概念：

服务 (service)：一个应用的容器，实际上可以包括若干运行相同镜像的容器实例。
项目 (project)：由一组关联的应用容器组成的一个完整业务单元，在 docker-compose.yml 文件中定义。

Compose的默认管理对象是项目，也就是通过docker-compose.yml定义的一组服务集合，通过一些命令来对项目中的一组容器进行便捷地生命周期管理。

Compose 使用的三个步骤：

使用 Dockerfile 定义应用程序的环境。
使用 docker-compose.yml 定义构成应用程序的服务，这样它们可以在隔离环境中一起运行。
最后，执行 docker-compose up 命令来启动并运行整个应用程序。

Compose 文件

Compose 文件的默认路径是compose.yaml（首选）或compose.yml放置在工作目录中。Compose 还支持docker-compose.yaml并向docker-compose.yml后兼容早期版本。如果两个文件都存在，Compose 会优先选择规范的compose.yaml。

可以将多个 Compose 文件合并在一起来定义应用程序模型。YAML 文件的组合是通过根据设置的 Compose 文件顺序附加或覆盖 YAML 元素来实现的。简单的属性和映射会被最高阶的 Compose 文件覆盖，列表会通过附加进行合并。只要要合并的补充文件托管在其他文件夹中，就会根据第一个 Compose 文件的父文件夹解析相对路径。由于某些 Compose 文件元素既可以表示为单个字符串也可以表示为复杂对象，因此合并适用于扩展形式。

如果想重用其他 Compose 文件，或者将应用程序模型的一部分分解为单独的 Compose 文件，还可以使用 include. 如果 Compose 应用程序依赖于由不同团队管理的另一个应用程序，或者需要与其他人共享，这非常有用。

docker-compose.yml文件配置

Compose file | Docker Docs（官方）

示例（mysql）：

version: '3'
services:
  mysql:
    restart: always
    image: mysql:5.7.18
    container_name: mysql-lable
    volumes:
      - /apps/mysql/mydir:/mydir
      - /apps/mysql/datadir:/var/lib/mysql
      - /apps/mysql/conf/my.cnf:/etc/my.cnf
      # 数据库还原目录 可将需要还原的sql文件放在这里
      - /apps/mysql/source:/docker-entrypoint-initdb.d
    environment:
      - "MYSQL_ROOT_PASSWORD=yourpassword"
      - "MYSQL_DATABASE=yourdbname"
      - "TZ=Asia/Shanghai"
    ports:
      # 使用宿主机的3306端口映射到容器的3306端口
      # 宿主机：容器
      - 3306:3306

version（版本：可选）

version版本信息，version属性由 Compose 规范定义，以实现向后兼容性。它只是提供信息。

Compose 不会version选择精确的架构来验证 Compose 文件，而是在实现时更喜欢使用最新的架构。
Compose 验证它是否可以完全解析 Compose 文件。

services（服务）

服务是应用程序中计算资源的抽象定义，可以独立于其他组件进行扩展或替换。服务由一组容器支持，由平台根据复制要求和放置约束运行。由于服务由容器支持，因此它们由 Docker 映像和一组运行时参数定义。服务中的所有容器都是使用这些参数创建的。

Compose 文件必须将services顶级元素声明为映射，其键是服务名称的字符串表示形式，其值是服务定义。服务定义包含应用于每个服务容器的配置。

每个服务还可能包含一个build部分，该部分定义如何为该服务创建 Docker 映像。Compose 支持使用此服务定义构建 docker 镜像。如果未使用，该build部分将被忽略，并且 Compose 文件仍被视为有效。

每个服务都定义运行其容器的运行时约束和要求。该deploy部分对这些约束进行分组，并允许平台调整部署策略，以最好地匹配容器的需求与可用资源。

build

Compose file build | Docker Docs（官方）

指定为构建镜像上下文路径。build可以指定为定义上下文路径的单个字符串，也可以指定为详细的构建定义。

Compose 文件服务的子集build ，其他服务可以使用该image属性。当build服务存在时，Compose 会忽略image相应服务的属性，因为 Compose 可以从源构建图像。

当服务定义同时包含image属性和build部分时，Compose 无法保证拉取的映像严格等同于从源构建相同的映像。如果没有任何明确的用户指令，带有build支持的 Compose 首先尝试拉取映像，然后如果在注册表中找不到映像，则从源构建。Compose 可能会提供选项来根据用户请求自定义此行为。

Compose 文件的父文件夹的相对路径。该路径必须是一个目录并且必须包含Dockerfile。

services:
  webapp:
    build: ./dir

git 存储库 URL。Git URL 在其片段部分接受上下文配置，以冒号 ( :) 分隔。第一部分表示 Git 签出的引用，可以是分支、标签或远程引用。第二部分表示存储库内用作构建上下文的子目录。

services:
  webapp:
    build: https://gitee.com/chengxuyuan/example.git#branch_or_tag:subdirectory

context定义包含 Dockerfile 的目录的路径，或 git 存储库的 URL。如果未明确设置，context则默认为项目目录 ( .)。

context

上下文路径。

args参数

定义构建参数，即 DockerfileARG值。args可以在Compose文件下设置build键来定义GIT_COMMIT。args可以设置为映射或列表.

指定构建参数时可以省略值，在这种情况下，构建时的值必须通过用户交互获取，否则在构建 Docker 映像时将不会设置构建参数。

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19

SSH

ssh定义镜像构建器在镜像构建期间应使用的 SSH 身份验证（例如，克隆私有存储库）。

ssh属性语法可以是：

default：让构建器连接到 ssh-agent。
ID=path：ID 和关联路径的键/值定义。它可以是 PEM文件或 ssh-agent 套接字的路径。

build:
  context: .
  ssh:
    - default   # mount the default ssh agent

或者

build:
  context: .
  ssh: ["default"]   # mount the default ssh agent

myproject使用带有本地 SSH 密钥路径的自定义 ID ：

build:
  context: .
  ssh:
    - myproject=~/.ssh/shitang.pem

cache_from

cache_from定义图像生成器应用于缓存解析的源列表。
缓存位置语法遵循全局格式[NAME|type=TYPE[,KEY=VALUE]]。SimpleNAME实际上是的快捷表示法type=registry,ref=NAME。

不支持的缓存将被忽略，并且不会阻止您构建图像。
Compose Build 实现可能支持自定义类型，Compose 规范定义了必须支持的规范类型：

registry从按键设置的 OCI 映像中检索构建缓存ref

build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

cache_to

定义用于与未来构建共享构建缓存的导出位置列表。

缓存目标是使用type=TYPE[,KEY=VALUE]与 cache_from.
不支持的缓存将被忽略，并且不会阻止您构建图像。

build:
  context: .
  cache_to:
   - user/app:cache
   - type=local,dest=path/to/cache

labels标签

labels将元数据添加到结果图像中。labels可以设置为数组或映射。
建议您使用反向 DNS 表示法，以防止您的标签与其他软件发生冲突。

build:
  context: .
  labels:
    com.example.description: "chengxuyuan webapp"
    com.example.department: "dashu"
    com.example.label-with-empty-value: ""

或者

build:
  context: .
  labels:
    - "com.example.description=chengxuyuan webapp"
    - "com.example.department=dashu"
    - "com.example.label-with-empty-value"

network网络

设置网络容器连接以获取RUN构建期间的说明。

build:
  context: .
  network: host

用于none在构建期间禁用网络：

build:
  context: .
  network: none

target目标

定义要构建的阶段，如多阶段中定义的那样Dockerfile。多层构建，可以指定构建哪一层。

build:
  context: .
  target: prod

secrets

secrets授予对每个服务构建基础上秘密定义的敏感数据的访问权限。支持两种不同的语法变体：短语法和长语法。
如果此 Compose 文件的部分中未定义密钥，Compose 会报告错误 secrets。

简短语法

短语法变体仅指定秘密名称。这将授予容器对机密的访问权限，并将其以只读方式安装到/run/secrets/<secret_name> 容器内。源名称和目标安装点均设置为秘密名称。
以下示例使用短语法来授予服务构建frontend对server-certificate密钥的访问权限。的值server-certificate设置为文件的内容./server.cert。

services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

长语法

长语法提供了如何在服务容器内创建机密的更细粒度。

source：平台上存在的机密名称。
target/run/secrets/：要挂载到服务任务容器中的文件的名称。如果未指定则默认为source。
uid和gid：拥有 /run/secrets/服务任务容器中的文件的数字 UID 或 GID。默认值是运行容器的用户。
mode：权限用于将文件安装到/run/secrets/ 服务的任务容器中，以八进制表示法。默认值是世界可读的权限（mode 0444）。如果设置了可写位，则必须忽略该位。可以设置可执行位。

以下示例将机密文件的名称设置server-certificate为server.crt 在容器内，将模式设置为0440（组可读）并将用户和组设置为103。Secret的值server-certificate由平台通过查找提供，并且 Secret 生命周期不由 Compose 直接管理。

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: server.cert
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true

tags标签

tags定义必须与构建映像关联的标签映射列表。此列表是对image

tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"

platforms平台

platforms定义目标平台。

当platforms省略该属性时，Compose 会将服务的平台包含在默认构建目标平台的列表中。
定义该platforms属性后，Compose 会包含该服务的平台，否则用户将无法运行他们构建的映像。

平台列表。

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"

Compose安装

【docker 】Compose安装

networks

配置容器连接的网络，顶级networks元素允许您配置可跨多个服务重用的命名网络。要跨多个服务使用网络，您必须使用顶级元素中的网络属性显式授予每个服务访问权限。顶级元素具有提供更精细控制的附加语法services。

基本示例

在以下示例中，在运行时创建网络front-tier和，并将服务连接到和网络。back-tierfrontendfront-tierback-tier

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

networks:
  front-tier:
  back-tier:

高级示例

高级示例显示了一个定义两个自定义网络的 Compose 文件。服务与服务proxy之间是隔离的db，因为它们不共享公共网络。只能app与两者对话。

services:
  proxy:
    build: ./proxy
    networks:
      - frontend
  app:
    build: ./app
    networks:
      - frontend
      - backend
  db:
    image: postgres
    networks:
      - backend

networks:
  frontend:
    # Use a custom driver
    driver: custom-driver-1
  backend:
    # Use a custom driver which takes special options
    driver: custom-driver-2
    driver_opts:
      foo: "1"
      bar: "2"

driver

指定该网络应使用哪个驱动程序。如果驱动程序在平台上不可用，Compose 将返回错误。

默认值和可用值是特定于平台的。Compose 支持以下驱动程序： none和host

host：使用主机的网络堆栈。
none：关闭网络。

使用内置网络（例如host和）的语法none是不同的，因为此类网络隐式存在于 Compose 范围之外。要使用它们，您必须使用名称host或none以及 Compose 可以使用的别名（hostnet在nonet以下示例中）定义外部网络，然后使用其别名授予服务访问该网络的权限。

services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host

services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

volumes

volumes是由容器引擎实现的持久数据存储。Compose 为服务提供了一种中立的方式来挂载卷，并提供配置参数来将卷分配给基础设施。

volumes声明允许您配置可在多个服务之间重用的命名卷。要在多个服务中使用卷，您必须使用顶级元素中的volumes属性显式授予每个服务访问权限。services该volumes属性具有提供更精细控制的附加语法。

以下示例显示了一个双服务设置，其中数据库的数据目录作为名为的卷与另一个服务共享， db-data以便可以定期备份。

services:
  backend:
    image: example/database
    volumes:
      - db-data:/etc/data

  backup:
    image: backup-service
    volumes:
      - db-data:/var/lib/backup/data

volumes:
  db-data:

cap_add，cap_drop

添加或删除容器拥有的宿主机的内核功能。

cap_add:
  - ALL # 开启全部权限

cap_drop:
  - SYS_PTRACE # 关闭 ptrace权限

cgroup_parent

为容器指定父 cgroup 组，意味着将继承该组的资源限制。

cgroup_parent: m-executor-abcd

command

覆盖容器启动的默认命令。

command: ["bundle", "exec", "thin", "-p", "3000"]

常用命令

docker-compose up

部署一个 Compose 应用，默认情况下该命令会读取名为 docker-compose.yml 或 docker-compose.yaml 的文件，当然用户也可以使用 -f 指定其他文件名。通常情况下，会使用 -d 参数令应用在后台启动

docker-compose stop

停止 Compose 应用相关的所有容器，但不会删除它们，被停止的应用可以很容易地通过 docker-compose restart 命令重新启动。

docker-compose rm

用于删除已停止的 Compose 应用，它会删除容器和网络，但是不会删除卷和镜像。

docker-compose restart

重启已停止的 Compose 应用，如果用户在停止该应用后对其进行了变更，那么变更的内容不会反映在重启后的应用中，这时需要重新部署应用使变更生效。

docker-compose ps

用于列出 Compose 应用中的各个容器，输出内容包括当前状态、容器运行的命令以及网络端口。

docker-compose down

停止并删除运行中的 Compose 应用，它会删除容器和网络，但是不会删除卷和镜像。