initProject

README.md

@@ -0,0 +1,161 @@
+# 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