pdok/gokoala

云原生OGC API服务器镜像文档

1. 镜像概述

本镜像为基于Go语言开发的云原生OGC API服务器，旨在提供符合开放地理空间信息联盟（OGC）标准的API服务。通过容器化部署，支持在各类云环境及容器平台中快速搭建高性能、可扩展的地理空间数据服务，实现标准化的空间数据访问与共享。

2. 核心功能与特性

2.1 标准化API支持

• 兼容OGC API系列标准，包括但不限于：
  • OGC API - Features（地理要素访问）
  • OGC API - Tiles（地图瓦片服务）
  • OGC API - Maps（动态地图渲染）
• 遵循OpenAPI规范，提供自动生成的API文档（如Swagger UI）

2.2 云原生架构

• 轻量级容器设计，适合Kubernetes等容器编排平台部署
• 支持水平扩展，通过负载均衡实现高并发请求处理
• 内置健康检查接口，支持容器自愈能力

2.3 高性能与可靠性

• 基于Go语言开发，利用其原生并发模型实现高效请求处理
• 低内存占用，支持单机万级并发连接
• 内置数据缓存机制，优化重复查询性能

2.4 灵活配置能力

• 多维度配置方式：环境变量、配置文件、API动态配置
• 支持多数据源接入（PostGIS、GeoPackage、Shapefile等）
• 可自定义CORS策略、认证授权规则及请求限流

3. 使用场景

3.1 地理信息服务提供商

作为核心服务组件，为***、企业或开发者提供标准化的地理空间数据API，支持地图显示、空间查询等基础功能。

3.2 空间数据共享平台

构建跨组织、跨系统的空间数据交换枢纽，通过统一OGC API接口实现多源数据的规范化共享。

3.3 GIS应用后端服务

为WebGIS、移动GIS等应用提供数据支撑，处理空间查询、要素编辑、地图渲染等核心业务逻辑。

3.4 科研与教育环境

搭建标准化地理信息教学实验平台，用于OGC标准实践教学或空间数据处理研究。

4. 使用方法

4.1 快速启动

通过以下命令可快速启动基础服务实例：

bash
docker run -d -p 8080:8080 --name ogc-api-server [镜像名称]:latest

说明：请将[镜像名称]替换为实际镜像标签（如ogc-api-server:v1.0.0）

服务启动后，可通过http://localhost:8080访问API根目录，通过http://localhost:8080/swagger查看API文档。

4.2 环境变量配置

通过环境变量可自定义服务核心参数，常用配置项如下：

配置示例：

bash
docker run -d \
  -p 9000:9000 \
  -e PORT=9000 \
  -e LOG_LEVEL=debug \
  -e DATABASE_URL="postgresql://admin:secret@pg-db:5432/gisdata?sslmode=disable" \
  -e CORS_ALLOWED_ORIGINS="https://example.com,https://map.example.com" \
  --name ogc-api-server \
  [镜像名称]:latest

4.3 持久化配置

如需使用复杂配置或自定义数据源，可通过挂载配置文件实现：

1. 本地创建配置文件（示例config.yaml）：

yaml
server:
  port: 8080
  read_timeout: 30s
  write_timeout: 60s

ogc:
  profiles:
    - features
    - tiles
  features:
    max_limit: 1000
    default_limit: 100

datasources:
  primary:
    type: postgis
    url: "postgresql://user:pass@db:5432/geodb"
    pool_size: 20
  secondary:
    type: geopackage
    path: "/data/cities.gpkg"

cache:
  type: redis
  address: "redis:6379"
  password: "redis-pass"

2. 通过挂载文件启动容器：

bash
docker run -d \
  -p 8080:8080 \
  -v ./config.yaml:/app/config.yaml \
  -v ./data:/data \  # 挂载数据文件目录
  --name ogc-api-server \
  [镜像名称]:latest \
  --config /app/config.yaml

4.4 Docker Compose部署

推荐使用Docker Compose实现多组件协同部署（如配合数据库），示例配置：

yaml
version: '3.8'

services:
  ogc-api:
    image: docker.xuanyuan.run/[镜像名称]:latest
    container_name: ogc-api-server
    restart: always
    ports:
      - "8080:8080"
    environment:
      - LOG_LEVEL=info
      - DATABASE_URL=postgresql://ogcuser:ogcpass@postgis:5432/ogcdata?sslmode=disable
    volumes:
      - ./config.yaml:/app/config.yaml
    depends_on:
      - postgis
      - redis

  postgis:
    image: docker.xuanyuan.run/postgis/postgis:15-3.4
    container_name: ogc-postgis
    restart: always
    environment:
      - POSTGRES_USER=ogcuser
      - POSTGRES_PASSWORD=ogcpass
      - POSTGRES_DB=ogcdata
    volumes:
      - postgis_data:/var/lib/postgresql/data

  redis:
    image: docker.xuanyuan.run/redis:7-alpine
    container_name: ogc-redis
    restart: always
    volumes:
      - redis_data:/data
    command: redis-server --requirepass "redis-pass"

volumes:
  postgis_data:
  redis_data:

启动服务栈：

bash
docker-compose up -d

5. 注意事项

• 生产环境建议配置持久化存储，避免容器重启导致配置丢失
• 高并发场景下建议配合Redis等分布式缓存使用
• 涉及敏感数据时，应通过环境变量或密钥管理服务注入认证信息，避免硬编码
• 定期更新镜像以获取最新安全补丁和功能优化