update .env.example and README.md to reflect port change from 3000 to 3001

.env.example

@@ -1,5 +1,5 @@
 # Server
-PORT=3000
+PORT=3001
 
 # Gitea Webhook Secret (optional)
 GITEA_WEBHOOK_SECRET=your_gitea_webhook_secret_here

README.md

@@ -71,16 +71,26 @@ npm start
 ### 重要：选择正确的 Webhook 类型
 确保在 Gitea 中创建 Webhook 时选择 **“Gitea”** 类型，而不是“飞书”或其他类型。Gitea 类型会发送结构化的 JSON 数据，便于解析。
 
+### 详细字段填写（根据用户界面）
+在 Gitea 的 Webhook 创建页面中，请按以下说明填写：
+
+| 字段 | 填写示例 | 说明 |
+|------|----------|------|
+| **目标 URL** | `http://192.168.0.15:3001` 或 `http://192.168.0.15:3001/webhook/gitea` | 根据你的服务地址和端口（默认为3000，若修改了环境变量 `PORT` 则对应调整）。如果服务部署在本地，请使用内网 IP。 |
+| **HTTP 方法** | `POST` | 保持默认。 |
+| **内容类型** | `application/json` | 保持默认。 |
+| **授权标头** | （留空） | 除非你的服务需要 Bearer 或 Basic 认证，否则不需要填写。 |
+| **密钥** | （可选）填写与 `GITEA_WEBHOOK_SECRET` 环境变量相同的字符串 | 用于验证 Webhook 请求的签名，增强安全性。如果留空，服务将跳过签名验证。 |
+| **触发事件** | 勾选 **“工单事件”**（Issue） | 可根据需要勾选其他事件，但本服务目前只处理工单事件。 |
+
 ### 步骤
-1. 进入 Gitea 仓库的设置 → Webhooks → 添加 Webhook
+1. 进入 Gitea 仓库的设置 → Webhooks → 添加 Webhook。
-2. 选择 **“Gitea”** 类型
+2. 选择 **“Gitea”** 类型（不要选“飞书”或“自定义”）。
-3. 目标 URL：`http://your-server-ip:3000/webhook/gitea`（也可以使用根路径 `http://your-server-ip:3000/`）
+3. 按照上表填写各字段。
-4. 密钥：填写与 `GITEA_WEBHOOK_SECRET` 相同的值（可选，但建议设置）
+4. 点击“添加 Webhook”保存。
-5. 触发事件：勾选“工单事件”（可根据需要选择其他事件）
-6. 保存
 
 ### 验证
-保存后，Gitea 会发送一个测试事件（ping）。检查服务日志以确认接收成功。
+保存后，Gitea 会立即发送一个测试事件（ping）。检查服务日志以确认接收成功。如果看到日志输出 `Received Gitea webhook` 且没有错误，说明配置正确。
 
 ## 飞书机器人配置
 
@@ -149,6 +159,65 @@ src/
 npm test
 ```
 
+## 测试建议
+
+### 1. 启动服务
+确保服务已运行并监听正确端口：
+```bash
+npm start
+```
+检查控制台输出是否有 `Server listening on port 3001`（或你设置的端口）。
+
+### 2. 健康检查
+使用 curl 或浏览器访问健康检查端点：
+```bash
+curl http://localhost:3001/health
+```
+应返回 `{"status":"ok","timestamp":"..."}`。
+
+### 3. 模拟 Gitea Webhook 请求
+你可以使用 `curl` 发送一个模拟的 Gitea 工单事件来测试转换和转发功能：
+
+```bash
+curl -X POST http://localhost:3001/webhook/gitea \
+  -H "Content-Type: application/json" \
+  -H "X-Gitea-Signature: sha256=..." \
+  -d '{
+    "action": "opened",
+    "issue": {
+      "id": 123,
+      "number": 45,
+      "title": "测试工单",
+      "body": "这是一个测试工单",
+      "state": "open",
+      "created_at": "2025-12-02T05:00:00Z",
+      "user": {
+        "id": 1,
+        "login": "testuser",
+        "full_name": "测试用户"
+      },
+      "assignee": null,
+      "labels": [],
+      "milestone": null
+    },
+    "repository": {
+      "id": 1,
+      "name": "test-repo",
+      "full_name": "org/test-repo",
+      "html_url": "https://gitea.example.com/org/test-repo"
+    },
+    "sender": {
+      "id": 1,
+      "login": "testuser"
+    }
+  }'
+```
+
+如果配置了 `FEISHU_WEBHOOK_URL`，服务会将转换后的卡片发送到飞书群聊。检查服务日志和飞书群聊以确认消息送达。
+
+### 4. 查看日志
+日志文件位于 `logs/` 目录，或直接在控制台查看。关注 `info` 和 `error` 级别的消息。
+
 ## 故障排除
 
 1. **收不到飞书消息**
@@ -164,6 +233,10 @@ npm test
    - 确认端口未被占用
    - 检查 Node.js 版本
 
+4. **Webhook 请求被忽略**
+   - 确认 Gitea 发送的 JSON 格式符合预期（包含 `action`、`issue`、`repository`）
+   - 检查日志中是否有 `Event ignored` 消息，可能是动作被过滤（如 `labeled`）
+
 ## 许可证
 
 MIT