edfialliance/ods-compose-generator

Ed-Fi-ODS-Docker 镜像文档

镜像概述和主要用途

该镜像为Ed-Fi ODS/API提供Docker部署源代码，用于生成年度特定和地区特定安装的Docker Compose文件。使用前需参考https://techdocs.ed-fi.org/display/EDFITOOLS/Docker+Deployment+2.xt%E8%AE%BE%E7%BD%AEDocker%E7%8E%AF%E5%A2%83%E3%80%82

核心功能和特性

• 支持Ed-Fi ODS/API和Admin App的容器化部署
• 提供PostgreSQL连接池管理（通过PgBouncer）
• 可配置客户端/服务器端连接池选项
• 支持环境变量自定义配置
• 包含敏感信息保护机制（如日志抑制）

发布标签

当前发布的活跃Docker标签：

• TAG=2.3.1：对应ODS/API 6.2（运行于.NET 8）
• ADMINAPP_TAG=v3.2.1：对应Admin App 3.2.1（运行于.NET Core 3.1）

暴露端口

Compose文件通过PgBouncer将数据库暴露到Docker网络外部。如需禁用此功能，需修改Compose文件，移除数据库PgBouncers的ports键。例如：

原配置：

yaml
pb-ods:
  build:
      context: ../../PgBouncer/Alpine
      dockerfile: Dockerfile
  environment:
      PGBOUNCER_DATABASE: "*"
      PGBOUNCER_PORT: "${PGBOUNCER_LISTEN_PORT:-6432}"
      PGBOUNCER_EXTRA_FLAGS: ${PGBOUNCER_EXTRA_FLAGS}
      POSTGRESQL_USER: "${POSTGRES_USER}"
      POSTGRESQL_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRESQL_HOST: db-ods
      PGBOUNCER_SET_DATABASE_USER: "yes"
      PGBOUNCER_SET_DATABASE_PASSWORD: "yes"
  ports:
    - "5402:${PGBOUNCER_LISTEN_PORT:-6432}"
  restart: always
  container_name: ed-fi-pb-ods
  depends_on:
    - db-ods

修改后：

yaml
pb-ods:
  build:
      context: ../../PgBouncer/Alpine
      dockerfile: Dockerfile
  environment:
      PGBOUNCER_DATABASE: "*"
      PGBOUNCER_PORT: "${PGBOUNCER_LISTEN_PORT:-6432}"
      PGBOUNCER_EXTRA_FLAGS: ${PGBOUNCER_EXTRA_FLAGS}
      POSTGRESQL_USER: "${POSTGRES_USER}"
      POSTGRESQL_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRESQL_HOST: db-ods
      PGBOUNCER_SET_DATABASE_USER: "yes"
      PGBOUNCER_SET_DATABASE_PASSWORD: "yes"
  restart: always
  container_name: ed-fi-pb-ods
  depends_on:
    - db-ods

支持的环境变量

仓库中包含的.env.example文件列出了所有支持的环境变量。

连接池

PgBouncer安全

环境变量POSTGRESQL_USER: "${POSTGRES_USER}"和POSTGRESQL_PASSWORD: "${POSTGRES_PASSWORD}"用于设置auth_file安全机制。通过暴露的pgbouncer端口进行的连接需要有效的用户名和密码。变量PGBOUNCER_SET_DATABASE_USER: "yes"和PGBOUNCER_SET_DATABASE_PASSWORD: "yes"会在连接字符串中包含数据库和密码，允许访问PG服务器中的数据库。

PgBouncer日志

默认情况下，PgBouncer会记录包含敏感信息（如主机数据库用户名和密码）的配置文件。可通过应用QUIET标志禁用此功能。最新版本的.env.example包含配置变量PGBOUNCER_EXTRA_FLAGS="--quiet"，可抑制此类消息。但未提供PGBOUNCER_QUIET配置变量的旧.env文件仍有在日志中暴露敏感信息的风险。

连接池选项

这些Compose文件使用PGBouncer为PostgreSQL提供服务器端连接池解决方案。若无此类连接管理，数据库服务器可能会耗尽连接并需要重启。除PGBouncer外，另一种方法是使用npgsql ADO.NET数据提供程序提供的客户端连接池，但使用前需考虑以下重要事项。

npgsql的客户端池基于连接字符串（参见Npgsql连接池说明）。可在连接字符串中配置池的最小（默认=0）和最大（默认=100）大小。首次从客户端池请求连接时，池将使用配置的最小连接数（默认=0）初始化。之后，池会根据需要增长到配置的最大值（默认=100）。此外，池会在一段不活动时间后释放空闲连接（默认=300秒）。

客户端池的挑战之一是PostgreSQL默认连接限制为100，因此配置客户端池时，部署环境的性质将极大影响适当的配置（以避免因超出可用连接总数而导致连接失败）。需考虑：

• Admin App和API进程/容器各有至少3个连接池（用于EdFi_Admin、EdFi_Security和EdFi_Ods数据库）
• 在年度特定部署中，不同ODS连接字符串（和池）的数量随每个学年增长
• 在地区特定或实例部署中，池的数量可能变得相当大
• 考虑高可用性和/或横向扩展的额外容器，客户端连接池总数会进一步增加

因此，客户端池可能仅适用于最简单的部署。

以下环境变量可用于控制API、Admin App和Sandbox Admin容器的客户端池：

如需移除PGBouncer，需进行以下更改：

1. 从Compose文件中移除和/或注释掉pb-admin和pb-ods*服务
2. 更新admin和api服务，将数据库环境变量（ODS_POSTGRES_HOST和ADMIN_POSTGRES_HOST）从pb-ods和pb-admin更改为指向db-ods和db-admin
3. 更新POSTGRES_PORT环境变量指向5432
4. 如需要，在db-admin和db-ods服务上暴露端口（注意这些端口应独立）

贡献指南

Ed-Fi联盟欢迎社区贡献代码。更多信息请参见：

• https://techdocs.ed-fi.org/display/ETKB/Code+Contribution+Guidelines
• https://techdocs.ed-fi.org/display/ETKB/How+To%3A+Submit+an+Issue
• https://techdocs.ed-fi.org/display/ETKB/How+To%3A+Submit+a+Feature+Request

***信息

版权所有 (c) 2024 Ed-Fi Alliance, LLC及贡献者。

根据Apache License, Version 2.0（"许可证"）授权。

除非适用***要求或书面同意，否则根据许可证分发的软件按"原样"分发，不提供任何明示或暗示的保证或条件。详见许可证以了解具体的权限和限制。

有关其他版权和许可证通知，请参见NOTICES。