go-clean-arch部署指南：Docker Compose一键启动与环境配置最佳实践-优快云博客

go-clean-arch部署指南：Docker Compose一键启动与环境配置最佳实践

【免费下载链接】go-clean-arch bxcodec/go-clean-arch: 这是一个用于创建符合Clean Architecture原则的Go项目的模板。适合用于创建遵循Clean Architecture原则的Go项目。特点：遵循Clean Architecture原则，包含示例代码，简化了项目结构。项目地址: https://gitcode.com/gh_mirrors/go/go-clean-arch

你是否还在为Go项目的环境配置而烦恼？是否遇到过本地开发环境与生产环境不一致导致的各种问题？本文将带你通过Docker Compose实现go-clean-arch项目的一键部署，解决环境配置难题，让你专注于业务开发而非环境调试。读完本文，你将掌握：Docker镜像构建流程、环境变量配置技巧、Docker Compose服务编排、一键启动与停止项目的方法，以及部署过程中的常见问题解决方案。

项目架构概览

go-clean-arch是一个遵循Clean Architecture原则的Go项目模板，其架构设计确保了业务逻辑与外部依赖的解耦。项目主要分为领域层、应用层、接口适配层和基础设施层。在部署方面，项目提供了完整的Docker支持，包括Dockerfile和Docker Compose配置文件，简化了部署流程。

项目的部署相关文件主要包括：

Dockerfile：用于构建Go应用镜像
compose.yaml：Docker Compose服务编排配置
example.env：环境变量示例文件
Makefile：包含部署相关的命令

环境准备

在开始部署前，请确保你的系统已安装以下工具：

Docker Engine (20.10+)
Docker Compose (v2+)
Git

如果你还未安装这些工具，可以参考Docker官方文档进行安装。安装完成后，可以通过以下命令验证安装是否成功：

docker --version
docker compose version
git --version

项目获取

首先，克隆项目代码库到本地：

git clone https://gitcode.com/gh_mirrors/go/go-clean-arch
cd go-clean-arch

Docker镜像构建解析

项目提供了Dockerfile用于构建应用镜像，采用多阶段构建方式，减小最终镜像体积。

构建流程解析

构建阶段：使用golang:1.20.7-alpine3.17作为基础镜像，安装依赖并编译应用

FROM golang:1.20.7-alpine3.17 as builder
RUN apk update && apk upgrade && \
    apk --update add git make bash build-base
WORKDIR /app
COPY . .
RUN make build

运行阶段：使用alpine:latest作为基础镜像，仅复制编译产物

FROM alpine:latest
RUN apk update && apk upgrade && \
    apk --update --no-cache add tzdata && \
    mkdir /app 
WORKDIR /app 
EXPOSE 9090
COPY --from=builder /app/engine /app/
CMD /app/engine

手动构建镜像

如果需要手动构建镜像，可以执行以下命令：

make image-build

该命令会调用Makefile中的image-build目标，执行Docker构建过程：

image-build:
	@ echo "Docker Build"
	@ DOCKER_BUILDKIT=0 docker build \
		--file Dockerfile \
		--tag go-clean-arch \
			.

环境变量配置

项目使用环境变量进行配置，提供了example.env作为配置示例。在部署前，需要根据实际情况创建.env文件。

配置项说明

example.env包含以下主要配置项：

DEBUG = True
SERVER_ADDRESS = ":9090"
CONTEXT_TIMEOUT = 2
DATABASE_HOST = "localhost"
DATABASE_PORT = "3306"
DATABASE_USER = "user"
DATABASE_PASS = "password"
DATABASE_NAME = "article"

创建.env文件

复制示例文件创建实际配置文件：

cp example.env .env

然后根据你的环境修改.env文件中的配置值，特别是数据库相关配置。

Docker Compose服务编排

compose.yaml定义了项目的服务组合，包括应用服务和数据库服务。

服务配置解析

version: "3.7"
services:
  web:
    image: go-clean-arch
    container_name: article_management_api
    ports:
      - 9090:9090
    depends_on:
      mysql:
        condition: service_healthy
    volumes:
      - ./config.json:/app/config.json

  mysql:
    image: mysql:8.3
    container_name: go_clean_arch_mysql
    command: mysqld --user=root
    volumes:
      - ./article.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - 3306:3306
    environment:
      - MYSQL_DATABASE=article
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
      - MYSQL_ROOT_PASSWORD=root
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 5s
      retries: 10

配置说明：

web服务：应用服务，使用本地构建的go-clean-arch镜像，依赖mysql服务健康状态
mysql服务：数据库服务，使用mysql:8.3镜像，通过article.sql初始化数据库结构和数据
健康检查：配置了数据库健康检查，确保应用在数据库就绪后才启动

网络配置

Docker Compose会自动创建网络并连接服务，服务之间可以通过服务名相互访问。例如，应用服务可以通过mysql:3306访问数据库服务。

一键部署与启动

项目提供了Makefile简化部署流程，定义了多个便捷命令。

启动服务

使用以下命令一键启动所有服务：

make up

该命令会执行Makefile中的up目标：

up: dev-env dev-air             ## Startup / Spinup Docker Compose and air
dev-env: ## Bootstrap Environment (with a Docker-Compose help).
	@ docker-compose up -d --build mysql
dev-air: $(AIR) ## Starts AIR ( Continuous Development app).
	air

服务启动流程

启动并构建mysql服务
启动air工具实现热重载开发环境

查看服务状态

服务启动后，可以使用以下命令查看运行状态：

docker compose ps

正常情况下，你会看到类似以下输出：

NAME                        IMAGE               COMMAND                  SERVICE             CREATED             STATUS                    PORTS
article_management_api      go-clean-arch       "/app/engine"            web                 5 minutes ago       Up 5 minutes              0.0.0.0:9090->9090/tcp
go_clean_arch_mysql         mysql:8.3           "docker-entrypoint.s…"   mysql               5 minutes ago       Up 5 minutes (healthy)    0.0.0.0:3306->3306/tcp, 33060/tcp

服务停止与清理

停止服务

使用以下命令停止所有服务：

make down

该命令会执行Makefile中的down目标：

down: docker-stop               ## Stop Docker
docker-stop:
	@ docker-compose down

清理环境

如果需要完全清理环境（包括删除数据卷），可以使用：

make destroy

该命令会执行Makefile中的destroy目标：

destroy: docker-teardown clean  ## Teardown (removes volumes, tmp files, etc...)
docker-teardown:
	@ docker-compose down --remove-orphans -v
clean: clean-artifacts clean-docker
clean-artifacts: ## Removes Artifacts (*.out)
	@printf "Cleanning artifacts... "
	@rm -f *.out
	@echo "done."
clean-docker: ## Removes dangling docker images
	@ docker image prune -f

验证部署

服务启动后，可以通过以下方式验证部署是否成功。

访问应用

打开浏览器访问http://localhost:9090，如果看到应用响应，说明部署成功。

查看日志

使用以下命令查看应用服务日志：

docker compose logs -f web

使用以下命令查看数据库服务日志：

docker compose logs -f mysql

常见问题解决

端口冲突

如果启动时提示端口已被占用，可以修改compose.yaml中的端口映射。例如，修改应用服务端口：

services:
  web:
    ports:
      - 9091:9090  # 将主机端口改为9091

环境变量不生效

确保已正确创建.env文件，并且compose.yaml中已配置使用环境变量。如果需要在compose.yaml中使用环境变量，可以添加env_file配置：

services:
  web:
    env_file:
      - .env

数据库连接问题

如果应用无法连接数据库，可以检查以下几点：

数据库服务是否正常运行：docker compose ps mysql
数据库连接参数是否正确配置在.env文件中
应用服务是否依赖数据库服务健康状态：检查compose.yaml中的depends_on配置

部署最佳实践

生产环境配置

在生产环境部署时，建议进行以下优化：

禁用DEBUG模式：在.env文件中设置DEBUG = False
使用环境变量注入敏感信息：避免在配置文件中硬编码密码等敏感信息
配置日志轮转：避免日志文件过大
设置资源限制：在compose.yaml中为服务设置资源限制

services:
  web:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
  mysql:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G

持续集成/持续部署

可以结合CI/CD工具实现自动构建和部署。例如，使用GitLab CI/CD，创建.gitlab-ci.yml文件：

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - make image-build
    - docker save -o go-clean-arch.tar go-clean-arch
  artifacts:
    paths:
      - go-clean-arch.tar

deploy:
  stage: deploy
  script:
    - docker load -i go-clean-arch.tar
    - make up

总结

通过本文的指南，你已经掌握了使用Docker Compose部署go-clean-arch项目的方法。项目提供的Dockerfile、compose.yaml和Makefile极大简化了部署流程，实现了一键启动。

建议在实际部署时，根据具体需求调整配置，遵循最佳实践，确保系统稳定可靠运行。如需进一步了解项目结构和代码实现，可以参考项目的README.md和源代码文件。

部署完成后，你可以专注于业务功能开发，而无需担心环境配置问题。祝你的项目开发顺利！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考