Coolify项目中Docker Compose构建参数的正确配置方式

在使用Coolify进行容器化部署时，正确配置Docker Compose文件中的构建参数(ARG)是一个常见的技术要点。本文将详细介绍如何在Docker Compose中正确传递构建参数，以及常见的配置误区。

构建参数的基本概念

Docker构建参数(ARG)允许在构建镜像时动态传递值，这些值可以在Dockerfile中使用。与运行时环境变量(ENV)不同，ARG只在构建阶段有效，不会保留在最终镜像中。

常见错误配置

很多开发者初次尝试时，容易将构建参数直接放在服务层级下，例如：

services:
  xyz:
    build: .
    args:  # 这是错误的放置位置
      - "VARIABLE_ONE=${VARIABLE_ONE}"

这种配置会导致Coolify报错："services.xyz Additional property args is not allowed"，因为args属性不能直接放在服务层级下。

正确配置方法

构建参数必须嵌套在build指令下，正确的格式应该是：

services:
  xyz:
    build: 
      context: .  # 构建上下文路径
      args:      # 正确的参数位置
        - "VARIABLE_ONE=${VARIABLE_ONE}"
        - "VARIABLE_TWO=${VARIABLE_TWO}"

完整示例

一个完整的Docker Compose与Dockerfile配合示例如下：

docker-compose.yml

services:
  app:
    build:
      context: .
      args:
        - "BUILD_VERSION=1.0.0"
    environment:
      - "RUNTIME_ENV=production"

Dockerfile

ARG BUILD_VERSION

FROM node:16
ENV RUNTIME_ENV=production

# 使用构建参数
LABEL version=${BUILD_VERSION}

注意事项

1. 构建参数只在构建阶段有效，如果需要在容器运行时使用，应该使用environment指令配置环境变量

2. 在Coolify环境中，可以使用${VARIABLE}语法引用已定义的环境变量

3. 构建参数的值不会保留在最终镜像中，如果需要持久化，应该在Dockerfile中使用ENV指令

4. 对于敏感信息，建议使用Coolify的密钥管理功能，而不是直接写在compose文件中

通过正确理解Docker Compose中构建参数的配置位置，可以避免常见的部署错误，使Coolify的容器化部署流程更加顺畅。