nim65s/matrix-webhook

Matrix Webhook

镜像概述和主要用途

Matrix Webhook是一个轻量级工具，通过HTTP POST请求将消息发送至Matrix房间。它允许外部服务（如GitHub、Grafana、GitLab等）轻松集成Matrix聊天系统，实现事件通知自动化，支持多种消息格式化方式，适用于各类监控告警、代码仓库事件等场景的消息推送。

核心功能和特性

• 简易HTTP接口：通过标准HTTP POST请求即可发送消息至指定Matrix房间
• 多服务适配：内置GitHub、Grafana、GitLab等服务的消息格式化器
• 安全访问控制：通过API密钥验证请求合法性，防止未授权访问
• 灵活认证方式：支持Matrix用户密码或访问令牌两种认证模式
• 健康检查机制：提供/health端点，便于负载均衡器监控服务状态
• 容器化部署：提供Docker镜像及docker-compose配置，简化生产环境部署

使用场景和适用范围

• GitHub仓库事件通知（提交、PR、Issue等活动）
• Grafana监控告警消息推送
• GitLab项目事件通知（通过Google Chat/Microsoft Teams集成方式）
• CI/CD流水线状态报告
• 各类自动化工具的事件结果通知

详细的使用方法和配置说明

安装方式

通过Python pip安装

bash
python3 -m pip install matrix-webhook

通过Docker拉取镜像

bash
docker pull nim65s/matrix-webhook

启动与配置参数

查看帮助信息

bash
# 直接运行
matrix-webhook -h

# Python模块方式
python -m matrix_webhook -h

# Docker方式
docker run --rm -it nim65s/matrix-webhook -h

配置参数说明

开发环境搭建

bash
# 使用poetry安装依赖
poetry install

# 或使用pip直接安装依赖
python3 -m pip install --user markdown matrix-nio

# 启动服务
python3 -m matrix_webhook

生产环境部署

docker-compose部署

项目提供完整的docker-compose配置，适用于生产环境：

1. 前置要求：

   • Docker网络需包含web网络（推荐配合Traefik反向代理）
   • 配置参数需写入.env文件
   • DNS需解析至${CHATONS_SERVICE:-matrixwebhook}.${CHATONS_DOMAIN:-localhost}

2. 启动服务：

bash
docker-compose up -d

健康检查配置

对于需要健康检查的负载均衡器，可使用/health端点（返回HTTP 200状态码及JSON响应）。在Traefik中配置示例：

yaml
services:
  bot:
    labels:
      traefik.http.services.matrix-webhook.loadbalancer.healthcheck.path: /health

使用示例

基础消息发送

bash
curl -d '{"body":"新贡献来自toto: [44](http://radio.localhost/map/#44)", "key": "your_api_key"}' \
  'http://matrixwebhook.localhost/!房间ID:matrix.org'

注：若未使用Docker，服务地址为localhost:4785

GitHub集成

1. 在GitHub仓库设置中添加Webhook
2. Payload URL格式：http://matrixwebhook地址/!房间ID:matrix.org?formatter=github
3. 选择Content type为application/json
4. Secret填写API_KEY值

Grafana集成

在Grafana告警配置中添加Webhook，URL格式：

http://matrixwebhook地址/!房间ID:matrix.org?formatter=grafana&key=your_api_key

GitLab集成

GitLab组级别不支持直接配置Webhook，可通过以下方式集成：

Google Chat方式

添加Google Chat集成，Webhook URL格式：

http://matrixwebhook地址/!房间ID:matrix.org?formatter=gitlab_gchat&key=your_api_key

Microsoft Teams方式

添加Microsoft Teams集成，Webhook URL格式：

http://matrixwebhook地址/!房间ID:matrix.org?formatter=gitlab_teams&key=your_api_key

测试资源

公共测试房间

可在Matrix房间#matrix-webhook:tetaneutral.net进行功能测试。

单元测试

bash
docker-compose -f test.yml up --exit-code-from tests --force-recreate --build