ACI项目后端服务Docker Compose配置详解

概述

ACI项目采用Docker Compose作为本地开发环境的核心编排工具，通过精心设计的服务配置实现了数据库、API服务、测试环境等关键组件的容器化部署。本文将深入解析该项目的docker-compose配置，帮助开发者理解其架构设计和技术选型。

核心服务架构

ACI项目的后端服务主要包含以下几个关键组件：

1. 数据库服务（PostgreSQL with pgvector扩展）
2. 本地AWS模拟服务（LocalStack）
3. 认证模拟服务
4. 主API服务
5. 运行器服务（用于脚本执行）
6. 测试环境相关服务

数据库服务配置

项目使用了pgvector/pgvector:pg17镜像而非官方PostgreSQL镜像，这是为了支持pgvector扩展，该扩展为PostgreSQL提供了向量搜索能力：

db:
  image: pgvector/pgvector:pg17
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U user -d local_db"]
    interval: 1s
    retries: 5
    start_period: 1s
    timeout: 10s
  environment:
    POSTGRES_USER: user
    POSTGRES_PASSWORD: password
    POSTGRES_DB: local_db
  ports:
    - "5432:5432"

关键点说明：

• 健康检查配置确保服务启动顺序正确
• 端口映射5432便于本地连接
• 使用了简化的认证信息（user/password）适合开发环境

本地AWS服务模拟

项目使用LocalStack来模拟AWS服务，特别是KMS（密钥管理服务）：

aws:
  image: localstack/localstack
  ports:
    - "4566:4566"
  environment:
    - DEBUG=1
    - SERVICES=kms
  volumes:
    - ./scripts/create-kms-encryption-key.sh:/etc/localstack/init/ready.d/create-kms-encryption-key.sh

技术亮点：

• 仅加载必要的AWS服务（KMS）减少资源占用
• 通过初始化脚本自动创建加密密钥
• 调试模式便于问题排查

主API服务配置

主服务采用Python构建，基于Uvicorn运行：

server:
  build:
    context: .
    dockerfile: Dockerfile.server
  env_file:
    - .env.local
  volumes:
    - ./aci/server:/workdir/aci/server
    - ./aci/common:/workdir/aci/common
    - ./mock/propelauth_fastapi_mock.py:/workdir/.venv/lib/python3.12/site-packages/propelauth_fastapi/__init__.py
  command: uvicorn aci.server.main:app --proxy-headers --forwarded-allow-ips=* --host 0.0.0.0 --port 8000 --reload --no-access-log

开发友好特性：

• 代码热重载（--reload参数）
• 本地代码挂载实现即时修改生效
• 认证模块mock简化开发流程
• 健康检查端点确保服务可用性

运行器服务设计

runner服务作为多功能执行环境：

runner:
  build:
    context: .
    dockerfile: Dockerfile.runner
  volumes:
    - ./aci:/workdir/aci
    - ./apps:/workdir/apps
    - ./scripts:/workdir/scripts
  command: >
    /bin/sh -c "alembic upgrade head && tail -f /dev/null"

功能特点：

• 集成数据库迁移工具（Alembic）
• 挂载多个代码目录支持不同场景
• 保持容器运行状态便于执行临时命令

测试环境隔离

项目实现了完整的测试环境隔离：

test-db:
  # 独立测试数据库配置
test-runner:
  # 覆盖数据库连接配置指向test-db
  environment:
    - SERVER_DB_HOST=test-db
    - ALEMBIC_DB_HOST=test-db
    - CLI_DB_HOST=test-db

测试策略：

• 独立数据库实例避免污染开发数据
• 环境变量覆盖确保连接正确
• 与开发环境相同的初始化流程

开发实践建议

1. 认证模拟：项目通过mock方式简化了认证流程，实际开发中应注意：

   volumes:
     - ./mock/propelauth_fastapi_mock.py:/workdir/.venv/lib/python3.12/site-packages/propelauth_fastapi/__init__.py
   

2. 依赖管理：服务间依赖通过healthcheck和depends_on确保启动顺序：

   depends_on:
     db:
       condition: service_healthy
   

3. 开发效率优化：

   • 代码热加载
   • 本地修改即时生效
   • 精简的日志输出配置

总结

ACI项目的Docker Compose配置展现了现代化开发环境的优秀实践，通过容器化技术实现了：

• 开发与测试环境隔离
• 第三方服务模拟
• 高效的开发工作流
• 可扩展的服务架构

这种配置方式特别适合需要处理向量数据、云服务集成和复杂认证场景的应用开发，为开发者提供了开箱即用且高度可定制的工作环境。