You've already forked GiteaToFeishuMsg
161 lines
3.5 KiB
Markdown
161 lines
3.5 KiB
Markdown
# Gitea 到飞书 Webhook 中转服务
|
||
|
||
将 Gitea 的工单事件（创建、更新、关闭等）通过 Webhook 接收，转换为美观的飞书卡片消息，并转发到飞书群聊。
|
||
|
||
## 功能特性
|
||
|
||
- 接收 Gitea Webhook 事件（支持工单相关动作）
|
||
- 验证 Webhook 签名（可选）
|
||
- 将事件转换为飞书交互式卡片
|
||
- 支持自定义卡片标题、颜色、字段
|
||
- 完整的错误处理和日志记录
|
||
- 健康检查端点
|
||
- 易于部署和配置
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
Gitea → Webhook → 中转服务 (Express) → 飞书机器人 → 飞书群聊
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前提条件
|
||
|
||
- Node.js 18+
|
||
- 一个飞书机器人，并获取其 Webhook URL
|
||
- Gitea 实例（版本 1.20+）
|
||
|
||
### 安装
|
||
|
||
1. 克隆仓库
|
||
```bash
|
||
git clone <repository-url>
|
||
cd gitea-feishu-webhook-relay
|
||
```
|
||
|
||
2. 安装依赖
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. 配置环境变量
|
||
复制 `.env.example` 为 `.env` 并填写实际值：
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
编辑 `.env`：
|
||
```env
|
||
PORT=3000
|
||
GITEA_WEBHOOK_SECRET=your_gitea_webhook_secret
|
||
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
|
||
LOG_LEVEL=info
|
||
```
|
||
|
||
### 运行
|
||
|
||
开发模式（使用 nodemon）：
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
生产模式：
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
服务将在 `http://localhost:3000` 启动。
|
||
|
||
## 配置 Gitea Webhook
|
||
|
||
1. 进入 Gitea 仓库的设置 → Webhooks → 添加 Webhook
|
||
2. 选择 “Gitea” 类型
|
||
3. 目标 URL：`http://your-server-ip:3000/webhook/gitea`
|
||
4. 密钥：填写与 `GITEA_WEBHOOK_SECRET` 相同的值
|
||
5. 触发事件：选择 “工单事件”
|
||
6. 保存
|
||
|
||
## 飞书机器人配置
|
||
|
||
1. 在飞书开放平台创建一个自定义机器人，获取 Webhook URL。
|
||
2. 将机器人添加到目标群聊。
|
||
3. 将 Webhook URL 填入 `FEISHU_WEBHOOK_URL`。
|
||
|
||
## API 端点
|
||
|
||
- `GET /health` – 健康检查
|
||
- `POST /webhook/gitea` – 接收 Gitea Webhook
|
||
|
||
## 日志
|
||
|
||
日志使用 Winston 输出到控制台和文件：
|
||
- `logs/error.log` – 错误日志
|
||
- `logs/combined.log` – 所有日志
|
||
|
||
## Docker 部署
|
||
|
||
提供 Dockerfile 便于容器化部署。
|
||
|
||
构建镜像：
|
||
```bash
|
||
docker build -t gitea-feishu-relay .
|
||
```
|
||
|
||
运行容器：
|
||
```bash
|
||
docker run -p 3000:3000 --env-file .env gitea-feishu-relay
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量名 | 描述 | 默认值 |
|
||
|--------|------|--------|
|
||
| PORT | 服务监听端口 | 3000 |
|
||
| GITEA_WEBHOOK_SECRET | Gitea Webhook 签名密钥 | （空） |
|
||
| FEISHU_WEBHOOK_URL | 飞书机器人 Webhook URL | （必需） |
|
||
| LOG_LEVEL | 日志级别 (error, warn, info, debug) | info |
|
||
| NODE_ENV | 运行环境 (development, production) | development |
|
||
|
||
## 开发
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
src/
|
||
├── server.js # Express 服务器入口
|
||
├── config.js # 配置管理
|
||
├── webhooks/
|
||
│ └── gitea.js # Webhook 处理器
|
||
├── transformers/
|
||
│ └── giteaToFeishu.js # 消息转换器
|
||
├── clients/
|
||
│ └── feishu.js # 飞书 API 客户端
|
||
└── utils/
|
||
└── logger.js # 日志工具
|
||
```
|
||
|
||
### 测试
|
||
|
||
运行单元测试：
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
1. **收不到飞书消息**
|
||
- 检查 `FEISHU_WEBHOOK_URL` 是否正确
|
||
- 查看日志中是否有错误信息
|
||
- 确认飞书机器人已加入群聊
|
||
|
||
2. **Gitea Webhook 验证失败**
|
||
- 确保 `GITEA_WEBHOOK_SECRET` 与 Gitea 中设置的密钥一致
|
||
- 检查请求头中是否包含 `X-Gitea-Signature`
|
||
|
||
3. **服务无法启动**
|
||
- 确认端口未被占用
|
||
- 检查 Node.js 版本
|
||
|
||
## 许可证
|
||
|
||
MIT |