GitHub到飞书Webhook转发服务

这是一个Python Web服务，用于接收GitHub仓库的Webhook推送，并将Issue、Pull Request和Push事件格式化后转发到飞书群聊中。

功能特性

• ✅ 支持GitHub Issue事件（创建、关闭、重新打开）
• ✅ 支持GitHub Pull Request事件（创建、关闭、重新打开、合并）
• ✅ 支持GitHub Push事件（代码推送）
• ✅ 美观的飞书卡片消息格式
• ✅ GitHub Webhook签名验证
• ✅ 环境变量配置管理
• ✅ 完整的日志记录
• ✅ 健康检查接口

系统要求

• Python 3.10.x 及以上版本
• 网络连接（用于接收GitHub Webhook和发送飞书消息）

快速开始

1. 克隆项目

git clone <your-repo-url>
cd github-feishu-webhook

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，填入必要的配置：

# 飞书机器人Webhook地址（必填）
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-token

# GitHub Webhook验证密钥（可选，建议配置）
GITHUB_WEBHOOK_SECRET=your-github-webhook-secret

# 服务器配置
HOST=0.0.0.0
PORT=5000
DEBUG=False

4. 启动服务

python app.py

服务将在 http://localhost:5000 启动。

5. 配置GitHub Webhook

1. 进入你的GitHub仓库设置页面
2. 点击 "Webhooks" → "Add webhook"
3. 填入以下信息：
   • Payload URL: http://your-server:5000/webhook
   • Content type: application/json
   • Secret: 与环境变量中的 GITHUB_WEBHOOK_SECRET 保持一致
   • Events: 选择 Issues, Pull requests, Pushes

6. 配置飞书机器人

1. 在飞书群聊中添加机器人
2. 获取机器人的Webhook地址
3. 将地址配置到环境变量 FEISHU_WEBHOOK_URL 中

API接口

Webhook接收接口

• URL: /webhook
• 方法: POST
• 描述: 接收GitHub Webhook推送

健康检查接口

• URL: /health
• 方法: GET
• 描述: 检查服务运行状态

根接口

• URL: /
• 方法: GET
• 描述: 显示服务信息

支持的GitHub事件

Issue事件

• opened: Issue创建
• closed: Issue关闭
• reopened: Issue重新打开

Pull Request事件

• opened: PR创建
• closed: PR关闭
• reopened: PR重新打开
• merged: PR合并（自动检测）

Push事件

• 代码推送到任意分支
• 显示提交信息、统计数据等

消息格式

服务会将GitHub事件转换为美观的飞书卡片消息，包含：

• 📋 Issue消息: 标题、描述、标签、指派人、状态等
• 🔀 Pull Request消息: 标题、描述、分支信息、统计数据、审核者等
• 📤 Push消息: 分支、提交列表、变更统计等

部署建议

使用Gunicorn部署

gunicorn -w 4 -b 0.0.0.0:5000 app:app

使用Docker部署

创建 Dockerfile：

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 5000

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]

构建和运行：

docker build -t github-feishu-webhook .
docker run -d -p 5000:5000 --env-file .env github-feishu-webhook

使用Nginx反向代理

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

安全建议

1. 配置Webhook密钥: 在GitHub和环境变量中设置相同的密钥，确保请求来源的合法性
2. 使用HTTPS: 在生产环境中使用HTTPS协议
3. 防火墙配置: 只允许GitHub的IP地址访问Webhook接口
4. 日志监控: 定期检查日志文件，监控异常活动

故障排除

常见问题

1. 消息发送失败

   • 检查飞书Webhook地址是否正确
   • 确认网络连接正常
   • 查看日志文件获取详细错误信息

2. GitHub签名验证失败

   • 确认环境变量中的密钥与GitHub配置一致
   • 检查请求头中是否包含正确的签名

3. 服务无法启动

   • 检查Python版本是否符合要求
   • 确认所有依赖已正确安装
   • 验证环境变量配置

日志查看

服务会输出详细的日志信息，包括：

• 接收到的GitHub事件类型
• 消息处理过程
• 发送结果
• 错误信息

开发指南

项目结构

github-feishu-webhook/
├── app.py              # 主应用程序
├── config.py           # 配置管理
├── github_parser.py    # GitHub事件解析器
├── feishu_sender.py    # 飞书消息发送器
├── requirements.txt    # Python依赖
├── .env.example       # 环境变量示例
├── .gitignore         # Git忽略文件
└── README.md          # 项目文档

添加新的事件类型

1. 在 github_parser.py 中添加新的解析方法
2. 在 feishu_sender.py 中添加对应的消息格式化方法
3. 更新 supported_events 字典

自定义消息格式

修改 feishu_sender.py 中的格式化方法，可以自定义消息的样式和内容。

许可证

MIT License

贡献

欢迎提交Issue和Pull Request来改进这个项目！