gcloud-pubsub-emulator Docker镜像文档

镜像概述和主要用途

gcloud-pubsub-emulator 是一个基于 marcelcorso/gcloud-pubsub-emulator 构建的Docker镜像，提供Google Cloud Pub/Sub服务的本地模拟器。该镜像支持自动构建以追踪 gcloud 工具的最新版本，并集成了更新后的 pubsubc 工具，可在启动时自动初始化主题（topics）和订阅（subscriptions）。主要用于本地开发、集成测试及CI/CD流程中，模拟Pub/Sub服务环境，避免依赖真实云资源。

核心功能和特性

• 自动构建与版本追踪：基于 gcloud 新版本自动构建，支持按版本号（\d+.\d+.\d+）、提交哈希（commit hash）及 latest 标签区分镜像版本。
• 主题与订阅自动创建：通过配置文件或环境变量，在启动时自动创建多项目的主题及订阅，支持拉取（pull）和推送（push）订阅类型。
• 健康检查支持：暴露额外端口（8682）用于健康探针，便于监控容器启动状态。
• 灵活配置：支持通过配置文件（JSON格式）或环境变量定义项目、主题及订阅，满足复杂场景需求。
• 超时控制：可自定义模拟器就绪超时时间，适配不同环境下的启动速度。

使用场景和适用范围

• 本地开发：开发阶段模拟Pub/Sub服务，无需连接Google Cloud，加速开发迭代。
• 集成测试：在单元测试或集成测试中使用，确保应用对Pub/Sub的交互逻辑正确。
• CI/CD流程：在持续集成/部署管道中作为依赖服务，验证应用在Pub/Sub集成场景下的稳定性。
• 多项目隔离：支持同时配置多个项目的主题和订阅，模拟复杂的多服务交互场景。

详细使用方法和配置说明

基本运行

直接运行（Docker Hub）

$ docker run --rm -it -p 8681:8681 thekevjames/gcloud-pubsub-emulator:latest

直接运行（quay.io）

$ docker run --rm -it -p 8681:8681 quay.io/thekevjames/gcloud-pubsub-emulator:latest

应用连接配置

启动后，通过环境变量 PUBSUB_EMULATOR_HOST 指向模拟器地址：

$ export PUBSUB_EMULATOR_HOST=localhost:8681
$ ./your_application  # 应用程序将使用模拟器而非真实Pub/Sub服务

自动主题和订阅创建

支持通过配置文件或环境变量两种方式，在启动时自动创建主题和订阅。

方式一：配置文件（推荐）

1. 配置文件路径
   默认路径为 /etc/pubsubc/config.json，可通过环境变量 PUBSUBC_CONFIG 自定义路径。

2. 配置文件格式
   JSON数组格式，每个元素为项目-主题配置，支持嵌套订阅定义。示例：

   [
     {
       "topic": "topic1",  // 主题名称（必填）
       "project": "project1"  // 项目ID（必填）
     },
     {
       "topic": "topic2",
       "project": "project1",
       "subscriptions": [  // 可选，订阅列表
         {
           "name": "subscription1",  // 订阅名称（必填）
           "push_config": {  // 可选，推送订阅配置（无此键则为拉取订阅）
             "push_endpoint": "http://localhost:3001/messages"  // 推送目标地址
           }
         },
         {
           "name": "subscription2"  // 拉取订阅
         }
       ]
     }
   ]
   

3. 启动命令示例
   挂载自定义配置文件并指定路径：

   $ docker run --rm -it \
       -p 8681:8681 \
       -e PUBSUBC_CONFIG=/custom/config.json \  # 自定义配置文件路径
       -v ./local-config.json:/custom/config.json \  # 挂载本地配置文件
       thekevjames/gcloud-pubsub-emulator:latest
   

方式二：环境变量（不支持推送订阅）

仅在未指定配置文件时生效，通过 PUBSUB_PROJECT<N>（N 从1开始）定义项目及主题/订阅。

1. 环境变量格式
   格式：PROJECTID,TOPIC1,TOPIC2:SUBSCRIPTION1:SUBSCRIPTION2,TOPIC3:SUBSCRIPTION3

   • 第一个元素为项目ID；
   • 后续元素为主题，格式为 TOPIC_ID[:SUBSCRIPTION1[:SUBSCRIPTION2]...]（: 后为订阅名称，可多个）。

2. 示例
   项目 company-dev 包含：

   • 主题 invoices，订阅 invoice-calculator；
   • 主题 chats，订阅 slack-out、irc-out；
   • 主题 notifications，无订阅。

   环境变量配置：

   $ export PUBSUB_PROJECT1=company-dev,invoices:invoice-calculator,chats:slack-out:irc-out,notifications
   

3. 启动命令示例

   $ docker run --rm -it \
       -p 8681:8681 \
       -e PUBSUB_PROJECT1=company-dev,invoices:invoice-calculator,chats:slack-out:irc-out,notifications \
       thekevjames/gcloud-pubsub-emulator:latest
   

4. 多项目配置
   通过 PUBSUB_PROJECT2、PUBSUB_PROJECT3 等添加更多项目，格式同上。

健康检查（Liveness Probes）

当启用自动创建主题/订阅时，需暴露端口 8682 用于健康检查（模拟器就绪后监听此端口）。检查方法示例：

• 使用 nc：nc -z 127.0.0.1 8682
• 使用 bash：true &>/dev/null </dev/tcp/127.0.0.1/8682
• 使用 wget：wget 127.0.0.1:8682

超时配置

若模拟器启动缓慢导致主题/订阅创建超时（默认15秒），可通过 PUBSUB_EMULATOR_WAIT_TIMEOUT 环境变量调整超时时间（单位：秒）。示例：

$ docker run --rm -it \
    -p 8681:8681 \
    -e PUBSUB_EMULATOR_WAIT_TIMEOUT=60 \  # 超时设为60秒
    -e PUBSUB_PROJECT1=company-dev,invoices:invoice-calculator \
    thekevjames/gcloud-pubsub-emulator:latest

Docker部署方案示例

示例1：基本运行（仅模拟器服务）

$ docker run --rm -it \
    -p 8681:8681 \  # 模拟器服务端口
    thekevjames/gcloud-pubsub-emulator:latest

示例2：带配置文件的自动初始化

$ docker run --rm -it \
    -p 8681:8681 \
    -p 8682:8682 \  # 健康检查端口
    -e PUBSUBC_CONFIG=/config/pubsub.json \
    -v ./my-pubsub-config.json:/config/pubsub.json \  # 挂载本地配置文件
    thekevjames/gcloud-pubsub-emulator:latest

示例3：docker-compose配置

version: '3'
services:
  pubsub-emulator:
    image: thekevjames/gcloud-pubsub-emulator:latest
    ports:
      - "8681:8681"  # 模拟器服务端口
      - "8682:8682"  # 健康检查端口
    environment:
      - PUBSUB_EMULATOR_WAIT_TIMEOUT=60  # 超时配置
      - PUBSUBC_CONFIG=/config/config.json  # 配置文件路径
    volumes:
      - ./local-config.json:/config/config.json  # 挂载配置文件
    restart: unless-stopped

配置参数与环境变量

镜像标签说明

• latest：主分支最新构建版本。
• \d+.\d+.\d+：对应 gcloud 工具版本的构建（如 460.0.0）。
• 提交哈希标签：每个Git提交对应唯一标签（如 a1b2c3d4），用于版本精确追溯。