StackGres REST API 容器文档

1. 镜像概述和主要用途

StackGres REST API 容器是 StackGres 管理平台的核心组件之一，提供标准化的 RESTful API 接口，用于与 StackGres 控制器交互，实现对 PostgreSQL 集群的程序化管理。该容器封装了 StackGres API 服务，支持通过 HTTP/HTTPS 协议执行集群创建、配置更新、状态查询、备份管理等操作，是自动化运维、第三方系统集成的关键入口。

2. 核心功能和特性

2.1 核心功能

• 集群生命周期管理：提供 API 接口支持 StackGres PostgreSQL 集群的创建、删除、重启、扩容/缩容等操作。
• 配置管理：支持数据库参数组、连接池配置、备份策略等资源的创建、查询、更新和删除。
• 状态监控：实时返回集群状态、节点健康度、资源使用率等关键指标。
• 备份与恢复：触发手动备份、查询备份历史、恢复集群数据等操作。
• 事件通知：提供集群事件（如故障、配置变更）的查询接口，支持集成外部告警系统。

2.2 特性

• RESTful 规范：遵循标准 REST 设计原则，支持 JSON 数据格式，接口路径清晰（如 /stackgres/clusters、/stackgres/backups）。
• 多模式认证：支持 API Token、Basic Auth 等认证方式，确保接口访问安全性。
• 高兼容性：与 StackGres 控制器版本严格匹配，支持 v1.3+ 及以上 StackGres 集群。
• 可观测性：内置 Prometheus 指标暴露接口，支持监控 API 服务自身性能（如请求量、响应延迟）。
• 轻量级部署：容器体积小，依赖少，支持单机部署或 Kubernetes 集群内部署。

3. 使用场景和适用范围

3.1 典型使用场景

• 自动化运维集成：通过 API 与 CI/CD 流水线集成，实现集群环境的自动部署与配置更新。
• 第三方系统对接：供监控平台（如 Grafana）、工单系统（如 Jira）调用，触发集群操作或获取状态数据。
• 批量操作执行：通过脚本调用 API 批量管理多集群（如统一调整备份策略、升级数据库版本）。
• 自定义管理平台开发：作为后端服务支撑，供前端管理界面（如内部运维平台）调用。

3.2 适用范围

• 已部署 StackGres 控制器的 Kubernetes 集群环境。
• 需要通过程序化方式管理 PostgreSQL 集群的场景（非手动操作）。
• 对集群操作有自动化、可追溯需求的企业级 PostgreSQL 部署环境。

4. 使用方法和配置说明

4.1 前提条件

• 已部署 StackGres 控制器（版本需与 API 容器版本匹配，推荐使用相同版本标签）。
• API 容器与 StackGres 控制器之间网络可达（通常通过 Kubernetes Service 或集群内 Pod 通信）。
• 已获取有效的认证凭证（如 API Token 或 Basic Auth 用户名/密码）。

4.2 镜像获取

从 StackGres 官方镜像仓库拉取镜像（需替换 <version> 为实际版本，如 1.6.0）：

docker pull stackgres/stackgres-rest-api:<version>

4.3 部署方案示例

4.3.1 Docker Run 部署

通过 docker run 直接启动容器，需指定连接控制器的地址、认证信息等核心参数：

docker run -d \
  --name stackgres-rest-api \
  -p 8080:8080 \
  -e STACKGRES_CONTROLLER_URL="[***]" \
  -e AUTH_MODE="token" \
  -e API_TOKEN="your-stackgres-api-token" \
  -e PORT=8080 \
  -e LOG_LEVEL="info" \
  stackgres/stackgres-rest-api:<version>

4.3.2 Docker Compose 部署

创建 docker-compose.yml 文件，定义服务及依赖（若需与其他组件联动）：

version: '3.8'
services:
  stackgres-rest-api:
    image: stackgres/stackgres-rest-api:<version>
    container_name: stackgres-rest-api
    ports:
      - "8080:8080"
    environment:
      - STACKGRES_CONTROLLER_URL=[***]  # StackGres 控制器地址
      - AUTH_MODE=token                                           # 认证模式：token/basic
      - API_TOKEN=your-stackgres-api-token                        # 认证令牌（token 模式必填）
      - PORT=8080                                                 # API 服务端口
      - LOG_LEVEL=info                                            # 日志级别：debug/info/warn/error
      - TLS_ENABLED=false                                         # 是否启用 HTTPS（true/false）
    restart: unless-stopped

启动服务：

docker-compose up -d

4.4 配置说明

4.4.1 环境变量配置

4.4.2 配置文件挂载（可选）

若需使用自定义配置文件（如调整 API 路由规则、跨域设置），可通过挂载配置文件到容器内 /etc/stackgres-api/config.yaml 路径。配置文件示例：

cors:
  allowed-origins: ["[***]"]  # 允许跨域请求的源
  allowed-methods: ["GET", "POST", "PUT", "DELETE"]      # 允许的 HTTP 方法
rate-limit:
  enabled: true                                          # 是否启用请求限流
  requests-per-minute: 600                               # 每分钟最大请求数

挂载命令示例（docker run）：

docker run -d \
  ...（其他参数）...
  -v /path/to/custom/config.yaml:/etc/stackgres-api/config.yaml \
  stackgres/stackgres-rest-api:<version>

5. 验证服务可用性

服务启动后，可通过以下命令验证 API 是否正常运行：

curl -H "Authorization: Bearer your-api-token" http://localhost:8080/stackgres/api/v1/clusters

若返回集群列表 JSON 数据，表明服务部署成功。

6. 注意事项

• 版本兼容性：API 容器版本需与 StackGres 控制器版本严格一致，避免因接口变更导致调用失败。
• 认证安全：生产环境中必须启用认证（推荐 token 模式），并通过 TLS 加密传输（TLS_ENABLED=true）。
• 资源限制：根据实际请求量调整容器 CPU/内存资源（如 Kubernetes 部署时设置 resources 限制），避免 API 服务因资源不足影响响应性能。