softonic/homing-pigeon

Homing Pigeon

概述

!overview

Homing Pigeon是一款用于轻松连接读写适配器的应用程序。无论输入接口接收什么消息，都会将其发送到特定的输出接口，无需编写常规样板代码。该工具设计为可轻松插入任何类型的输入和输出适配器，可用于消息存储或消息代理等场景，例如AMQP到Elasticsearch、HTTP到MySQL、HTTP到HTTP或任何其他组合。

重要细节：消息将“原样”从读取接口转发到写入接口，因此预期格式取决于所连接的写入适配器。

核心功能和特性

已实现的接口

读取接口

RabbitMQ

• 从单个队列读取消息，根据写入接口的指示确认（ack）或（可选）拒绝（nack）消息
• 所有被拒绝的消息将自动进入死信队列，不会重试

写入接口

Elasticsearch（使用Bulk API）

• 失败的消息将被拒绝（nack），成功的消息将被确认（ack）
• 支持特定JSON格式，遵循Elasticsearch Bulk API规范：

  json
  {
    "meta": { "index" : { "_index" : "test", "_id" : "1" } },
    "data": { "field1" : "value1" }
  }
  

  更多信息请参见https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html

使用场景和适用范围

适用于需要在不同系统间转发消息的场景，例如：

• 从消息队列（如RabbitMQ）接收消息并存储到搜索引擎（如Elasticsearch）
• 实现HTTP到HTTP的消息代理
• 收集用户行为事件并持久化以便后续分析

示例场景：
假设拥有example.com，需跟踪多种用户事件（点击按钮、填写表单等）并快速可视化。可部署Homing Pigeon连接现有RabbitMQ和Elasticsearch集群，网站发送事件消息到指定交换机（按特定格式），消息将自动持久化到Elasticsearch，最后部署Kibana即可实现数据可视化。

使用方法和配置说明

部署方式

Docker镜像

所有版本均通过Docker镜像发布：softonic/homing-pigeon

Kubernetes部署

提供Helm Chart便于K8s部署：https://github.com/softonic/homing-pigeon-chart

Docker运行示例

bash
docker run -d \
  -e READ_ADAPTER=AMQP \
  -e WRITE_ADAPTER=ELASTIC \
  -e RABBITMQ_URL=amqp://user:password@rabbitmq:5672/ \
  -e ELASTICSEARCH_URL=http://elasticsearch:9200 \
  docker.xuanyuan.run/softonic/homing-pigeon

环境变量配置

核心配置

读取适配器配置：RabbitMQ

写入适配器配置：Elasticsearch

输入格式

仅支持批量操作，格式如下：

json
{
  "meta": { "<operation>": { ... } },  // 操作元数据，如索引信息
  "data": { "<field>": "<value>" }     // 文档数据
}

详细格式参见https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html

配置参数

开发指南

构建Docker镜像

bash
make docker-build

启动应用

bash
docker compose up -d

运行测试

bash
make test

未来规划

• 实现消息转换接口，支持读取后、写入前的消息转换
• 为适配器添加URL外的用户名和密码配置方式

致谢

特别感谢https://dribbble.com/muniatu%E8%AE%BE%E8%AE%A1%E7%9A%84Homing Pigeon logo。