jore4-hasura Docker 镜像文档

镜像概述

jore4-hasura 是基于 Hasura GraphQL 引擎的定制化 Docker 镜像，专为 Jore4 项目设计。该镜像提供了一个强大的 GraphQL API 层，用于查询和操作 Jore4 项目的后端数据，简化了前端应用与数据库之间的交互。

核心功能和特性

• 基于最新稳定版 Hasura GraphQL 引擎构建
• 预配置 Jore4 项目所需的数据库连接和权限
• 内置数据验证和业务规则逻辑
• 支持实时数据订阅功能
• 包含自定义 GraphQL 解析器和业务逻辑
• 提供内置的监控和日志功能

使用场景和适用范围

• Jore4 项目前端应用的后端 API 服务
• 数据集成和转换服务
• 第三方系统与 Jore4 数据库的接口
• 开发和测试环境的快速部署
• 生产环境的可扩展 GraphQL 服务

环境变量配置

使用方法

基本使用 (docker run)

bash
docker run -d \
  --name jore4-hasura \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@postgres:5432/jore4 \
  -e HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret \
  hsldevcom/jore4-hasura:latest

使用 Docker Compose

创建 docker-compose.yml 文件:

yaml
version: '3.8'

services:
  hasura:
    image: hsldevcom/jore4-hasura:latest
    container_name: jore4-hasura
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://user:password@postgres:5432/jore4
      - HASURA_GRAPHQL_ADMIN_SECRET=${HASURA_ADMIN_SECRET}
      - HASURA_GRAPHQL_UNAUTHORIZED_ROLE=anonymous
      - LOG_LEVEL=INFO
    depends_on:
      - postgres
    restart: unless-stopped
    volumes:
      - ./metadata:/hasura-metadata

  postgres:
    image: postgres:13
    container_name: jore4-postgres
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=jore4
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

启动服务:

bash
docker-compose up -d

加载自定义元数据

bash
docker run -d \
  --name jore4-hasura \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@postgres:5432/jore4 \
  -e HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret \
  -v ./custom-metadata:/hasura-metadata \
  hsldevcom/jore4-hasura:latest

初始化和迁移

容器启动时会自动应用 /hasura-metadata 目录中的元数据配置。如需手动应用迁移或元数据:

bash
# 应用元数据
docker exec -it jore4-hasura hasura metadata apply

# 查看状态
docker exec -it jore4-hasura hasura status

访问 Hasura 控制台

启动容器后，可以通过以下 URL 访问 Hasura 管理控制台:

• 控制台地址: http://localhost:8080/console
• 使用环境变量 HASURA_GRAPHQL_ADMIN_SECRET 中配置的密钥进行认证

健康检查

容器内置健康检查机制，可通过以下命令手动检查:

bash
docker exec -it jore4-hasura curl -f http://localhost:8080/healthz || echo "Not healthy"

持久化数据

为确保元数据和配置的持久性，建议挂载以下目录:

bash
-v ./metadata:/hasura-metadata
-v ./migrations:/hasura-migrations

扩展配置

启用 JWT 认证

bash
docker run -d \
  --name jore4-hasura \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@postgres:5432/jore4 \
  -e HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret \
  -e HASURA_GRAPHQL_JWT_SECRET='{"type":"HS256", "key":"your-jwt-secret-key"}' \
  hsldevcom/jore4-hasura:latest

配置日志级别

bash
docker run -d \
  --name jore4-hasura \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@postgres:5432/jore4 \
  -e HASURA_GRAPHQL_ADMIN_SECRET=your-admin-secret \
  -e LOG_LEVEL=DEBUG \
  hsldevcom/jore4-hasura:latest

故障排除

常见问题

1. 数据库连接失败:

   • 检查 DATABASE_URL 环境变量配置
   • 确保数据库服务可访问
   • 验证数据库用户权限

2. 元数据应用失败:

   • 检查挂载的元数据目录权限
   • 验证元数据文件格式是否正确
   • 查看容器日志获取详细错误信息

3. 控制台访问问题:

   • 确认 HASURA_GRAPHQL_ADMIN_SECRET 配置正确
   • 检查端口映射是否正确
   • 验证容器是否正常运行

查看日志

bash
docker logs jore4-hasura
# 实时查看日志
docker logs -f jore4-hasura

版本信息

• 基础镜像: hasura/graphql-engine:v2.x.x
• 操作系统: Debian GNU/Linux
• 默认端口: 8080

维护和更新

建议定期更新镜像以获取最新功能和安全修复:

bash
docker pull hsldevcom/jore4-hasura:latest

对于生产环境，建议使用特定版本标签而非 latest，以确保环境稳定性。