OpenFGA 项目 Docker Compose 部署指南

OpenFGA 是一个高性能的授权系统，基于 Google Zanzibar 论文设计，提供细粒度的访问控制能力。本文将深入解析其 Docker Compose 部署方案，帮助开发者快速搭建完整的 OpenFGA 开发环境。

部署架构概述

该 Docker Compose 文件定义了一个完整的 OpenFGA 服务栈，包含三个核心服务：

1. PostgreSQL 数据库服务 - 作为 OpenFGA 的数据存储后端
2. 数据库迁移服务 - 负责初始化数据库表结构
3. OpenFGA 主服务 - 提供授权决策的核心服务

服务详解

PostgreSQL 数据库服务

postgres:
  image: postgres:17
  container_name: postgres
  command: postgres -c 'max_connections=100'
  ports:
    - "5432:5432"
  environment:
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=password
  healthcheck:
    test: [ "CMD-SHELL", "pg_isready -U postgres" ]
    interval: 5s
    timeout: 5s
    retries: 5

该服务使用 PostgreSQL 17 官方镜像，配置了以下关键参数：

• 最大连接数设置为 100，与后续 OpenFGA 服务的连接池配置对应
• 默认用户名为 postgres，密码为 password（生产环境应修改）
• 健康检查确保数据库完全启动后才进行后续操作
• 暴露 5432 端口供其他容器访问

数据库迁移服务

migrate:
  depends_on:
    postgres:
      condition: service_healthy
  image: openfga/openfga:latest
  container_name: migrate
  environment:
    - OPENFGA_DATASTORE_ENGINE=postgres
    - OPENFGA_DATASTORE_URI=postgres://postgres:password@postgres:5432/postgres?sslmode=disable
  command: migrate

迁移服务负责初始化 OpenFGA 所需的数据库表结构：

• 依赖 PostgreSQL 服务健康状态
• 使用 OpenFGA 官方镜像的 migrate 命令
• 配置 PostgreSQL 连接信息，包括用户名、密码和主机地址
• 迁移完成后自动退出

OpenFGA 主服务

openfga:
  depends_on:
    migrate:
      condition: service_completed_successfully
  image: openfga/openfga:latest
  container_name: openfga
  command: run
  environment:
    - OPENFGA_DATASTORE_ENGINE=postgres
    - OPENFGA_DATASTORE_URI=postgres://postgres:password@postgres:5432/postgres?sslmode=disable
    - OPENFGA_DATASTORE_MAX_OPEN_CONNS=100
    - OPENFGA_PLAYGROUND_ENABLED=true
  ports:
    - "8080:8080" #http
    - "8081:8081" #grpc
    - "3000:3000" #playground
    - "2112:2112" #prometheus metrics
  healthcheck:
    test:
      [
        "CMD",
        "/usr/local/bin/grpc_health_probe",
        "-addr=openfga:8081"
      ]
    interval: 5s
    timeout: 30s
    retries: 3

OpenFGA 主服务提供核心功能：

• 确保迁移服务成功完成后才启动
• 运行 run 命令启动服务
• 配置 PostgreSQL 连接池大小为 100
• 启用 Playground 开发界面
• 暴露多个端口：
  • 8080: HTTP API 端口
  • 8081: gRPC API 端口
  • 3000: Playground Web 界面
  • 2112: Prometheus 监控指标
• gRPC 健康检查确保服务可用性

部署实践建议

1. 安全配置：生产环境务必修改默认的数据库密码，并考虑启用 SSL 连接

2. 性能调优：根据实际负载调整数据库连接池大小(max_connections 和 OPENFGA_DATASTORE_MAX_OPEN_CONNS)

3. 监控集成：利用暴露的 2112 端口集成 Prometheus 监控

4. 开发体验：Playground 界面(3000 端口)提供直观的授权模型设计和测试能力

5. 高可用部署：生产环境应考虑数据库集群和 OpenFGA 多实例部署

启动与验证

1. 使用 docker-compose up -d 启动服务
2. 访问 http://localhost:3000 验证 Playground 是否正常
3. 通过 http://localhost:8080 测试 HTTP API
4. 检查日志确认服务健康状态

该部署方案为开发者提供了完整的 OpenFGA 开发环境，便于快速开始授权系统的设计与实现。