API Platform 项目 Docker Compose 配置深度解析

概述

API Platform 是一个强大的 PHP 框架，用于快速构建 API 驱动的应用程序。其 Docker Compose 配置文件 (compose.yaml) 定义了整个应用的基础架构组件及其相互关系。本文将深入解析这一配置文件的技术细节，帮助开发者理解 API Platform 的容器化部署架构。

核心服务解析

PHP 应用服务

php:
  image: ${IMAGES_PREFIX:-}app-php
  depends_on:
    - database
  restart: unless-stopped

PHP 服务是整个应用的核心，它基于自定义的 app-php 镜像构建，并依赖于数据库服务。restart: unless-stopped 确保服务在意外退出时自动重启。

关键环境变量配置

1. 数据库连接:

   DATABASE_URL: postgresql://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD:-!ChangeMe!}@database:5432/${POSTGRES_DB:-app}?serverVersion=${POSTGRES_VERSION:-16}&charset=${POSTGRES_CHARSET:-utf8}
   

   使用 PostgreSQL 数据库，连接字符串包含用户名、密码、数据库名等参数，并指定了服务器版本和字符集。

2. Mercure 实时通信:

   MERCURE_URL: ${CADDY_MERCURE_URL:-http://php/.well-known/mercure}
   MERCURE_PUBLIC_URL: ${CADDY_MERCURE_PUBLIC_URL:-https://${SERVER_NAME:-localhost}:${HTTPS_PORT:-443}/.well-known/mercure}
   MERCURE_JWT_SECRET: ${CADDY_MERCURE_JWT_SECRET:-!ChangeThisMercureHubJWTSecretKey!}
   

   Mercure 是用于实时通信的协议，这里配置了内部和公开的 Mercure URL 以及 JWT 密钥。

3. 安全配置:

   TRUSTED_PROXIES: ${TRUSTED_PROXIES:-127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}
   TRUSTED_HOSTS: ${TRUSTED_HOSTS:-^${SERVER_NAME:-example\.com|localhost}|php$$}
   

   定义了可信代理和主机，增强应用安全性。

网络与存储

volumes:
  - caddy_data:/data
  - caddy_config:/config
ports:
  - target: 80
    published: ${HTTP_PORT:-80}
    protocol: tcp
  - target: 443
    published: ${HTTPS_PORT:-443}
    protocol: tcp
  - target: 443
    published: ${HTTP3_PORT:-443}
    protocol: udp

PHP 服务挂载了 Caddy 的数据和配置卷，并暴露了 HTTP(80)、HTTPS(443) 和 HTTP/3(443 UDP) 端口。

PWA (渐进式 Web 应用) 服务

pwa:
  image: ${IMAGES_PREFIX:-}app-pwa
  environment:
    NEXT_PUBLIC_ENTRYPOINT: http://php

PWA 服务基于 Next.js 构建，通过 NEXT_PUBLIC_ENTRYPOINT 环境变量指定后端 API 的入口点。

数据库服务

database:
  image: postgres:${POSTGRES_VERSION:-16}-alpine
  environment:
    - POSTGRES_DB=${POSTGRES_DB:-app}
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-!ChangeMe!}
    - POSTGRES_USER=${POSTGRES_USER:-app}
  healthcheck:
    test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB:-app}", "-U", "${POSTGRES_USER:-app}"]
    timeout: 5s
    retries: 5
    start_period: 60s
  volumes:
    - database_data:/var/lib/postgresql/data:rw

使用 PostgreSQL 的 Alpine 版本镜像，配置了数据库名、用户和密码。健康检查确保数据库服务正常运行后才启动依赖服务。

数据持久化

volumes:
  - database_data:/var/lib/postgresql/data:rw

使用命名卷 database_data 持久化存储数据库数据，避免容器重启后数据丢失。

存储卷配置

volumes:
  caddy_data:
  caddy_config:
  database_data:

定义了三个持久化存储卷：

1. caddy_data: 存储 Caddy 服务器的数据
2. caddy_config: 存储 Caddy 服务器的配置
3. database_data: 存储 PostgreSQL 数据库数据

安全最佳实践

1. 敏感信息管理:

   • 所有密码和密钥都使用环境变量配置
   • 提供了默认值但明确提示需要修改 (!ChangeMe!, !ChangeThisMercureHubJWTSecretKey!)

2. 网络隔离:

   • 服务间通过 Docker 内部网络通信
   • 仅暴露必要的端口到主机

3. 健康检查:

   • 数据库服务配置了健康检查，确保依赖服务可用

部署建议

1. 生产环境调整:

   • 必须修改所有默认密码和密钥
   • 考虑使用外部数据库服务而非容器化数据库
   • 配置适当的资源限制 (CPU/内存)

2. 性能优化:

   • 根据负载调整 PHP 服务的副本数量
   • 考虑添加 Redis 缓存服务

3. 监控:

   • 添加 Prometheus 和 Grafana 进行监控
   • 配置日志收集和分析

总结

API Platform 的 Docker Compose 配置展示了一个完整的现代 Web 应用架构，包含后端 API 服务、前端 PWA 和数据库服务。通过合理的容器化设计，它实现了:

• 服务隔离与依赖管理
• 配置与数据分离
• 安全默认值
• 可扩展的架构

理解这一配置文件对于定制化部署 API Platform 项目至关重要，开发者可以根据实际需求调整服务配置、扩展组件或优化性能参数。