calendar gateway 镜像文档

镜像概述

calendar gateway镜像是一个轻量级日历网关服务，旨在整合各类第三方日历数据源（如Google Calendar、Microsoft Outlook Calendar、Apple Calendar等），提供统一的API接口，简化应用程序对接多个日历服务的开发复杂度，实现日历数据的集中获取、转发与同步管理。

核心功能和特性

• 多日历源支持：兼容主流日历服务，包括Google Calendar、Microsoft Outlook Calendar、iCloud Calendar等，可灵活扩展支持其他日历数据源。
• 统一API接口：对外提供标准化的RESTful API，屏蔽不同日历服务的接口差异，降低应用对接多个日历服务的开发成本。
• 数据转换与标准化：自动将不同日历服务返回的事件数据（如日期格式、字段名称）转换为统一标准格式（支持iCalendar或自定义JSON格式）。
• 请求转发与路由：根据请求参数自动路由至对应的日历数据源，并支持请求负载均衡与限流，保障服务稳定性。
• 认证代理：支持代理第三方日历服务的认证流程（如OAuth 2.0），减少应用直接处理多个服务认证逻辑的复杂度。

使用场景

• 企业应用集成：企业级应用需同时对接多个员工使用的不同日历服务（如部分团队使用Google Calendar，部分使用Outlook）时，通过网关实现统一接入与数据聚合。
• 跨平台日历工具开发：开发跨平台日历同步工具或日程管理应用时，利用网关统一处理不同日历服务的接口差异，专注于业务逻辑实现。
• 日历数据聚合服务：需集中获取、汇总多个日历数据源事件信息的场景，如团队日程汇总看板、跨部门会议协调工具等。
• API请求管理：需要对日历API请求进行统一监控、日志记录或访问控制的场景，通过网关实现请求审计与权限管理。

使用方法

快速启动

通过以下命令快速启动日历网关服务（默认配置下仅启动基础服务，需进一步配置日历源）：

docker run -d -p 8080:8080 --name calendar-gateway calendar-gateway:latest

环境变量配置

通过环境变量配置网关基础参数，常用环境变量说明如下：

日历源配置

需为启用的日历源配置认证信息，支持环境变量或配置文件两种方式：

方式1：环境变量配置（以Google Calendar为例）

docker run -d -p 8080:8080 \
  -e PORT=8080 \
  -e SUPPORTED_CALENDARS=google,outlook \
  -e GOOGLE_CLIENT_ID="your_google_client_id" \
  -e GOOGLE_CLIENT_SECRET="your_google_client_secret" \
  -e OUTLOOK_CLIENT_ID="your_outlook_client_id" \
  -e OUTLOOK_CLIENT_SECRET="your_outlook_client_secret" \
  --name calendar-gateway calendar-gateway:latest

方式2：配置文件配置

创建config.yaml配置文件，定义日历源及服务参数：

calendars:
  google:
    client_id: "your_google_client_id"       # Google Calendar API客户端ID
    client_secret: "your_google_client_secret" # Google Calendar API客户端密钥
    scope: "[***]" # 权限范围
  outlook:
    client_id: "your_outlook_client_id"      # Outlook Calendar API客户端ID
    client_secret: "your_outlook_client_secret" # Outlook Calendar API客户端密钥
    tenant: "common"                         # 租户ID（Outlook专用，默认common）
server:
  port: 8080                                 # 服务监听端口
  timeout: 30                                # 请求超时时间（秒）
log:
  level: "info"                              # 日志级别

通过挂载配置文件启动服务：

docker run -d -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config/config.yaml \
  --name calendar-gateway calendar-gateway:latest

接口使用示例

通过统一API接口与网关交互，以下为获取日历事件的示例请求：

获取指定日历源的事件列表

curl "http://localhost:8080/api/v1/calendars/google/events?start_date=2024-01-01&end_date=2024-01-31"

• google：目标日历源名称（需与配置中的日历源名称一致）
• start_date/end_date：事件查询的日期范围（格式：YYYY-MM-DD）

响应示例（统一JSON格式）：

{
  "events": [
    {
      "id": "event_123",
      "title": "团队周会",
      "start_time": "2024-01-05T09:00:00Z",
      "end_time": "2024-01-05T10:00:00Z",
      "location": "会议室A",
      "description": "本周项目进度同步"
    }
  ],
  "source": "google",
  "total": 1
}