Hocus项目开发环境Docker Compose配置解析

概述

本文将深入解析Hocus项目开发环境中的Docker Compose配置文件，该文件定义了三个核心服务：生成器服务(gen)、数据库服务(db)和Keycloak身份认证服务(keycloak)。通过这份配置，开发者可以快速搭建一个完整的本地开发环境。

网络配置

首先定义了一个名为hocus_dev_net的Docker网络，所有服务都将连接到此网络，确保服务间可以相互通信。

networks:
  hocus_dev_net:
    name: hocus_dev_net

服务详解

1. 生成器服务(gen)

这是一个临时性的服务，主要职责是准备Keycloak的初始化脚本：

gen:
  image: alpine:latest
  volumes:
    - ./:/data
  command: >
    sh -c '
      cd /data && \
      cp resources/keycloak-setup.sh db-init/keycloak-setup.sh && \
      sed -i -e "/-- SQL_DB_DUMP_GOES_HERE/r resources/keycloak-db-dump.sql" db-init/keycloak-setup.sh && \
      sed -i \
        "s/github_client_secret_goes_here/${GITHUB_APP_HOCUS_DEV_CLIENT_SECRET}/g" \
        db-init/keycloak-setup.sh && \
      sed -i \
        "s@hocus_callback_url_goes_here@http://localhost:3000/app/callback@g" \
        db-init/keycloak-setup.sh && \
      sed -i \
        "s@hocus_logout_redirect_url_goes_here@http://localhost:3000/@g" \
        db-init/keycloak-setup.sh
    '

该服务使用轻量级的Alpine Linux镜像，主要完成以下工作：

1. 将资源目录中的Keycloak设置脚本复制到数据库初始化目录
2. 将SQL数据库转储文件插入到设置脚本中特定位置
3. 替换脚本中的多个占位符，包括：
   • GitHub应用客户端密钥
   • 回调URL
   • 登出重定向URL

2. 数据库服务(db)

PostgreSQL数据库服务配置相当详细，针对开发环境进行了性能优化：

db:
  image: "postgres:alpine"
  networks:
    - hocus_dev_net
  command: postgres -c 'max_connections=10000' -c 'shared_buffers=2GB' -c 'effective_cache_size=6GB' -c 'maintenance_work_mem=512MB' -c 'random_page_cost=1.1' -c 'effective_io_concurrency=200' -c 'work_mem=4MB' -c 'min_wal_size=2GB' -c 'max_wal_size=8GB' -c 'max_worker_processes=8' -c 'max_parallel_workers_per_gather=4' -c 'max_parallel_workers=8' -c 'max_parallel_maintenance_workers=4' -c 'fsync=off' -c 'full_page_writes=off' -c 'synchronous_commit=off' -c 'wal_level=minimal' -c 'max_wal_senders=0' -c 'log_error_verbosity=terse'
  restart: unless-stopped
  ports:
    - "${NO_EXPOSE_PORTS-5432:}5432"
  depends_on:
    gen:
      condition: service_completed_successfully
  environment:
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_DB: rooms
    PGDATA: /pgtmpfs
  volumes:
    - ./db-init:/docker-entrypoint-initdb.d/
  tmpfs:
    - /pgtmpfs
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 1s
    timeout: 10s
    retries: 30

关键配置点：

• 使用轻量级的PostgreSQL Alpine镜像
• 通过命令参数进行了大量性能调优，适合开发环境：
  • 提高了连接数和各种内存参数
  • 关闭了fsync等持久性保证以提升性能
  • 减少了WAL日志相关开销
• 数据库数据存储在tmpfs中，确保高性能但非持久化
• 健康检查确保服务可用性
• 依赖生成器服务完成后再启动
• 挂载初始化脚本目录，自动执行Keycloak设置

3. Keycloak身份认证服务

keycloak:
  depends_on:
    db:
      condition: service_healthy
  networks:
    - hocus_dev_net
  command: "start"
  build:
    dockerfile: keycloak-dev.Dockerfile
  ports:
    - "${NO_EXPOSE_PORTS-4200:}8080"
  restart: unless-stopped

主要特点：

• 依赖数据库服务健康状态
• 使用自定义Dockerfile构建
• 将容器内8080端口映射到主机4200端口
• 自动重启策略确保服务可用性

环境变量说明

配置中使用了几个关键环境变量：

• GITHUB_APP_HOCUS_DEV_CLIENT_SECRET: GitHub应用的客户端密钥
• POSTGRES_PASSWORD: PostgreSQL数据库密码
• POSTGRES_USER: PostgreSQL数据库用户
• NO_EXPOSE_PORTS: 控制是否暴露端口到主机

最佳实践建议

1. 性能与持久化权衡：开发环境配置牺牲了数据持久性换取性能，生产环境应调整相关参数
2. 安全注意事项：GitHub客户端密钥等敏感信息应通过安全方式管理
3. 初始化顺序：服务间依赖关系确保了正确的启动顺序
4. 资源监控：开发环境中可监控tmpfs使用情况，避免内存不足

通过这份Docker Compose配置，Hocus项目实现了开发环境的快速搭建和一致性保证，大大简化了开发者的环境准备过程。