Construindo um Ambiente RuoYi Completo com Docker Compose

Este guia detalha o processo de empacotar e implantar o projeto RuoYi, incluindo suas camadas de backend (Spring Boot) e front end (Vue.js), junto com serviços essenciais como MySQL e Redis, utilizando Docker Compose para uma gestão de contêineres simplificada. A abordagem visa criar um ambiente isolado e de fácil replicação.

Estrutura de Diretórios Essencial

Para manter o projeto organizado e modular, começamos criando uma estrtuura de diretórios para os componentes Dockerizados diretamente na raiz do projeto RuoYi:

  • docker/mysql: Contém arquivos de inicialização para o banco de dados.
  • docker/backend: Armazena o Dockerfile para a aplicação Spring Boot.
  • docker/frontend: Inclui o Dockerfile para a interface Vue.js e a configuração do Nginx.

Configuração do Banco de Dados MySQL

Os scripts de inicialização do MySQL são cruciais para configurar o esquema e os dados iniciais do RuoYi. Esses arquivos devem ser colocados em docker/mysql/init. Recomenda-se exportar as tabelas e dados existentes do seu ambiente de desenvolvimento.

Exportação de Dados e Tratamento de Codificação

Ao exportar o banco de dados (por exemplo, usando ferramentas como DBeaver), é fundamental garantir que o arquivo SQL gerado seja compatível com a codificação UTF-8 dentro do contêiner MySQL. Para isso, adicione a seguinte linha no início do seu arquivo .sql principal:

/*!40101 SET NAMES utf8 */;

Esta etapa previne problemas de caracteres acentuados ou especiais (caracteres chineses, por exemplo) após a inicialização do banco de dados no contêiner.

Script de Criação e Permissão de Usuário

Além da estrutura do banco de dados, é boa prática criar um usuário dedicado com as permissões mínimas necessárias. Crie um arquivo como 01-init-user.sql dentro de docker/mysql/init:

/*!40101 SET NAMES utf8 */;
-- Este script concede permissões ao usuário 'ruoyi_user' no banco de dados 'ry_vue'.
-- O usuário 'ruoyi_user' pode ser criado automaticamente pelo Docker Compose,
-- se definido nas variáveis de ambiente do serviço MySQL.
GRANT ALL PRIVILEGES ON ry_vue.* TO 'ruoyi_user'@'%';
FLUSH PRIVILEGES; -- Recarrega as permissões para que entrem em vigor imediatamente.

Dockerfile para o Backend (Spring Boot)

O Dockerfile localizado em docker/backend/Dockerfile define como a aplicação Spring Boot será construída e executada. Utilizamos uma abordagem de múltiplas fases (multi-stage build) para otimizar o tamanho final da imagem.

# docker/backend/Dockerfile

# --- Fase de Construção (Build Stage) ---
# Usa uma imagem base com Maven e JDK para compilar o projeto.
FROM maven:3.9.5-openjdk-17 AS build_env

# Define o diretório de trabalho dentro do contêiner.
WORKDIR /app/ruoyi-backend

# Copia os arquivos de configuração do Maven e as estruturas dos módulos.
# O "contexto de construção" (build context) será a raiz do projeto RuoYi.
COPY pom.xml ./
COPY ruoyi-common ./ruoyi-common/
COPY ruoyi-framework ./ruoyi-framework/
COPY ruoyi-system ./ruoyi-system/
COPY ruoyi-quartz ./ruoyi-quartz/
COPY ruoyi-generator ./ruoyi-generator/
COPY ruoyi-admin ./ruoyi-admin/

# Navega para o módulo comum e instala no repositório local Maven.
WORKDIR /app/ruoyi-backend/ruoyi-common
RUN mvn clean install -DskipTests

# Retorna ao diretório raiz do backend e compila o módulo 'ruoyi-admin'.
# '-pl ruoyi-admin' seleciona o módulo principal, '-am' inclui as dependências.
WORKDIR /app/ruoyi-backend
RUN mvn clean package -pl ruoyi-admin -am -DskipTests

# --- Fase de Execução (Runtime Stage) ---
# Usa uma imagem JRE leve para executar a aplicação compilada.
FROM openjdk:17-jre-slim

# Define o diretório de trabalho para a aplicação final.
WORKDIR /app

# Copia o JAR compilado da fase de construção.
COPY --from=build_env /app/ruoyi-backend/ruoyi-admin/target/ruoyi-admin.jar ./app.jar

# Expõe a porta padrão do Spring Boot.
EXPOSE 8080

# Comando de inicialização da aplicação, com injeção de variáveis de ambiente para configuração.
ENTRYPOINT ["java", \
            "-Djava.security.egd=file:/dev/./urandom", \
            "-jar", \
            "app.jar", \
            "--spring.datasource.url=jdbc:mysql://${DB_HOST:mysql}:${DB_PORT:3306}/${DB_NAME:ry_vue}?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8&allowPublicKeyRetrieval=true", \
            "--spring.datasource.username=${DB_USER:ruoyi_user}", \
            "--spring.datasource.password=${DB_PASS:ruoyi_user_pass}", \
            "--spring.redis.host=${REDIS_HOST:redis}", \
            "--spring.redis.port=${REDIS_PORT:6379}", \
            "--spring.redis.password=${REDIS_PASS:}" \
           ]

Dockerfile para o Frontend (Vue.js)

O Dockerfile em docker/frontend/Dockerfile é responsável por construir a aplicação Vue.js e configurá-la para ser servida por um servidor web Nginx.

# docker/frontend/Dockerfile

# --- Fase de Construção (Build Stage) ---
# Usa uma imagem Node.js para compilar a aplicação Vue.js.
FROM node:18.17.0-alpine AS frontend_builder

# Define o diretório de trabalho.
WORKDIR /app/ruoyi-ui

# Define o registro npm para acelerar a instalação de dependências (opcional).
# RUN npm config set registry https://registry.npmmirror.com

# Copia os arquivos de definição de dependências para aproveitar o cache do Docker.
COPY ruoyi-ui/package.json ruoyi-ui/package-lock.json ./

# Instala as dependências do projeto.
RUN npm install

# Copia o restante dos arquivos do frontend.
COPY ruoyi-ui .

# Executa o comando de build do Vue.js. Verifique o package.json para o script correto (geralmente 'build:prod').
RUN npm run build:prod

# --- Fase de Execução (Runtime Stage) ---
# Usa uma imagem Nginx leve para servir os arquivos estáticos.
FROM nginx:1.25-alpine

# Remove a configuração padrão do Nginx.
RUN rm /etc/nginx/conf.d/default.conf

# Copia a configuração personalizada do Nginx.
COPY docker/frontend/nginx.conf /etc/nginx/conf.d/app.conf

# Copia os arquivos estáticos gerados pela fase de construção para o diretório de serviço do Nginx.
COPY --from=frontend_builder /app/ruoyi-ui/dist /usr/share/nginx/html

# Expõe a porta HTTP padrão do Nginx.
EXPOSE 80

# O Nginx é configurado para rodar em primeiro plano por padrão, não sendo necessário um ENTRYPOINT ou CMD explícito.

Configuração do Nginx para o Frontend

O arquivo nginx.conf, localizado em docker/frontend/nginx.conf, define como o Nginx irá servir os arquivos estáticos do Vue.js e como irá rotear as requisições de API para o backend.

# docker/frontend/nginx.conf

server {
    listen       80;
    server_name  localhost; # Pode ser substituído pelo seu domínio
    charset      utf-8;    # Garante que os arquivos estáticos sejam servidos com UTF-8

    access_log  /var/log/nginx/access.log;
    error_log   /var/log/nginx/error.log warn;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        # Configuração essencial para aplicações SPA (Single Page Application) com Vue Router
        # Garante que as rotas internas do Vue.js funcionem corretamente ao recarregar a página.
        try_files $uri $uri/ /index.html;
    }

    # Proxy reverso para as requisições de API.
    # O prefixo '/prod-api/' deve corresponder ao VUE_APP_BASE_API configurado no frontend.
    location /prod-api/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # O 'ruoyi-backend' é o nome do serviço definido no docker-compose.yml.
        proxy_pass http://ruoyi-backend:8080/;

        # Se o backend não espera o prefixo /prod-api/, use esta linha:
        # rewrite ^/prod-api/(.*)$ /$1 break;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

Arquivo docker-compose.yml

O arquivo docker-compose.yml, posicionado na raiz do projeto, orquestra todos os serviços necessários: MySQL, Redis, o backend RuoYi e o frontend com Nginx.

# docker-compose.yml
version: '3.8'

services:
  # Serviço de Banco de Dados MySQL
  mysql-db:
    image: mysql:8.0 # Garanta compatibilidade com o RuoYi
    container_name: ruoyi-mysql-container
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-my_root_password}
      MYSQL_DATABASE: ${MYSQL_DB_NAME:-ry_vue}
      MYSQL_USER: ${MYSQL_USER:-ruoyi_user}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-ruoyi_user_pass}
    ports:
      - "${MYSQL_EXPOSED_PORT:-3306}:3306"
    volumes:
      - ruoyi_mysql_data:/var/lib/mysql
      - ./docker/mysql/init:/docker-entrypoint-initdb.d # Carrega scripts SQL de inicialização
    networks:
      - ruoyi_network
    restart: unless-stopped
    command: # Configurações adicionais para o MySQL
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci

  # Serviço Redis para Cache e Sessões
  redis-cache:
    image: redis:6.2-alpine # Imagem leve do Redis
    container_name: ruoyi-redis-container
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD:-}"] # Define senha se a variável for fornecida
    ports:
      - "${REDIS_EXPOSED_PORT:-6379}:6379"
    volumes:
      - ruoyi_redis_data:/data
    networks:
      - ruoyi_network
    restart: unless-stopped

  # Serviço Backend da Aplicação RuoYi (Spring Boot)
  ruoyi-backend:
    container_name: ruoyi-backend-app
    build:
      context: . # Contexto de construção é a raiz do projeto
      dockerfile: docker/backend/Dockerfile
    environment:
      # Variáveis de ambiente passadas para o ENTRYPOINT do Dockerfile do backend
      DB_HOST: mysql-db # Usa o nome do serviço MySQL como hostname
      DB_PORT: 3306
      DB_NAME: ${MYSQL_DB_NAME:-ry_vue}
      DB_USER: ${MYSQL_USER:-ruoyi_user}
      DB_PASS: ${MYSQL_PASSWORD:-ruoyi_user_pass}
      REDIS_HOST: redis-cache # Usa o nome do serviço Redis como hostname
      REDIS_PORT: 6379
      REDIS_PASS: ${REDIS_PASSWORD:-}
      SERVER_PORT: 8080
    ports:
      - "${BACKEND_EXPOSED_PORT:-8080}:8080"
    depends_on:
      - mysql-db
      - redis-cache
    networks:
      - ruoyi_network
    restart: unless-stopped

  # Serviço Frontend da Aplicação RuoYi (Vue.js com Nginx)
  ruoyi-frontend:
    container_name: ruoyi-frontend-web
    build:
      context: . # Contexto de construção é a raiz do projeto
      dockerfile: docker/frontend/Dockerfile
    ports:
      - "${FRONTEND_EXPOSED_PORT:-80}:80"
    depends_on:
      - ruoyi-backend # Garante que o backend esteja iniciando antes do frontend
    networks:
      - ruoyi_network
    restart: unless-stopped

networks:
  ruoyi_network: # Define uma rede interna para comunicação entre os serviços
    driver: bridge

volumes: # Define volumes persistentes para dados
  ruoyi_mysql_data:
  ruoyi_redis_data:

Observações Importantes

  1. **Gerenciamento de Usuários MySQL:** É fortemente recomendado evitar o uso do usuário root para a aplicação. O docker-compose.yml e o script de inicialiazção MySQL configuram um usuário específico (ruoyi\_user) com permissões para o banco de dados da aplicação (ry\_vue).
  2. **Consistência de Caminhos e Variáveis:** Verifique cuidadosamente todos os caminhos de arquivos e nomes de variáveis de ambiente. Erros de digitação em portas, hosts ou nomes de serviços podem causar falhas na comunicação entre os contêineres.
  3. **Conflitos de Portas:** Em ambientes como WSL2 (Windows Subsystem for Linux 2) ou máquinas Windows/macOS, pode haver conflitos se as portas expostas pelos contêineres já estiverem sendo utilizadas por outros serviços no host. Ajuste as variáveis de porta no docker-compose.yml (ex: MYSQL\_EXPOSED\_PORT, FRONTEND\_EXPOSED\_PORT).

Comandos Úteis do Docker Compose

Após carregar os arquivos do projeto para o servidor, navegue até o diretório raiz do código-fonte onde reside o docker-compose.yml.

# Primeira construção e inicialização de todos os serviços em modo detached (segundo plano).
# O --build garante que as imagens serão construídas a partir dos Dockerfiles.
docker compose up -d --build

# Se houver atualizações no código-fonte ou nos Dockerfiles, você precisará reconstruir as imagens:
docker compose build
# E então, para aplicar as mudanças e reiniciar os serviços:
docker compose up -d

# Para parar e remover todos os contêineres, redes e volumes associados ao projeto Docker Compose:
# ATENÇÃO: '--volumes' removerá os dados persistidos (ex: dados do MySQL).
# Certifique-se de ter feito backup de dados importantes antes de executar.
docker compose down --volumes

Tags: Docker DockerCompose MySQL Redis Spring Boot

Publicado em 6-23 19:19

Tags em Destaque

©2026 Doido Dev