Skip to content

Commit 69fdc53

Browse files
AptS-1547AptS-1547
committed
feat: 更新文档，添加 API 参考、部署建议、常见问题和开发路线图，移除功能特点部分
1 parent feb41bc commit 69fdc53

9 files changed

Lines changed: 265 additions & 30 deletions

File tree

‎docs/src/SUMMARY.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Summary
22

33
- [介绍](./introduction.md)
4-
- [功能特点](./features.md)
54
- [安装与配置](./installation.md)
6-
- [使用指南](./usage.md)
5+
- [开发路线图](./roadmap.md)
6+
- [API 文档](./api.md)
77
- [项目结构](./structure.md)
8+
- [部署建议](./deployment.md)
9+
- [常见问题](./faq.md)

‎docs/src/api.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## API 参考
2+
3+
### Webhook 接口
4+
5+
- **路径**: `/github-webhook`
6+
- **方法**: POST
7+
- **请求头**:
8+
- `Content-Type`: application/json
9+
- `X-GitHub-Event`: 事件类型
10+
- `X-Hub-Signature-256`: SHA-256 HMAC 签名
11+
12+
- **响应**:
13+
14+
```json
15+
{
16+
"status": "success|ignored",
17+
"message": "处理信息"
18+
}
19+
```

‎docs/src/deployment.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## 部署建议
2+
3+
### Docker 部署（计划支持）
4+
5+
```bash
6+
docker run -d \
7+
--name onebot-github-webhook \
8+
-p 8000:8000 \
9+
-v $(pwd)/config.yaml:/app/config.yaml \
10+
e1saps/onebot-github-webhook:latest
11+
```
12+
13+
### Systemd 服务
14+
15+
创建 `/etc/systemd/system/onebot-github-webhook.service`:
16+
17+
```ini
18+
[Unit]
19+
Description=OneBot GitHub Webhook Service
20+
After=network.target
21+
22+
[Service]
23+
User=www-data
24+
WorkingDirectory=/opt/onebot-github-webhook
25+
ExecStart=/opt/onebot-github-webhook/.venv/bin/python -m uvicorn app:app --host 0.0.0.0 --port 8000
26+
Restart=on-failure
27+
RestartSec=5s
28+
29+
[Install]
30+
WantedBy=multi-user.target
31+
```
32+
33+
启用服务:
34+
35+
```bash
36+
sudo systemctl enable onebot-github-webhook
37+
sudo systemctl start onebot-github-webhook
38+
```

‎docs/src/faq.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## 常见问题
2+
3+
**Q: Webhook 触发但 QQ 未收到消息怎么办？**
4+
5+
A: 请检查以下几点：
6+
7+
1. OneBot 地址和 token 是否正确
8+
2. OneBot 实现是否支持 WebSocket/HTTP 连接
9+
3. QQ 机器人是否在目标群/好友中
10+
4. 查看日志获取详细错误信息
11+
12+
**Q: 如何支持多个 QQ 机器人？**
13+
14+
A: 本程序暂时不支持推送到多个 QQ 机器人
15+
16+
## 贡献指南
17+
18+
欢迎提交 Pull Request 或 Issue 来帮助改进本项目！
19+
20+
1. Fork 本仓库
21+
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
22+
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
23+
4. 推送到分支 (`git push origin feature/amazing-feature`)
24+
5. 创建 Pull Request
25+
26+
## 许可证
27+
28+
本项目采用 GPL-3.0 许可证。

‎docs/src/features.md‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/src/installation.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
## 安装
32

43
1. 克隆本仓库：
@@ -22,18 +21,18 @@ source .venv/bin/activate # Linux/Mac
2221
pip install -r requirements.txt
2322
```
2423

25-
4. 修改配置文件
24+
4. 配置文件设置：
2625

27-
在程序第一次运行时会自动生成 `config.yaml` 文件，您可以根据需要修改其中的配置项。
28-
或者复制 `config.yaml.example` 文件并重命名为 `config.yaml`，然后根据需要修改配置项。
26+
在程序第一次运行时会自动生成 config.yaml 文件，您可以根据需要修改其中的配置项。
27+
或者复制示例配置文件：
2928

3029
```bash
3130
cp config.yaml.example config.yaml
3231
```
3332

3433
## 配置说明
3534

36-
配置文件 `config.yaml` 的结构如下：
35+
配置文件 config.yaml 的结构如下：
3736

3837
```yaml
3938
ENV: "production" # 环境变量，可选值为 "production" 或 "development"
@@ -60,3 +59,24 @@ GITHUB_WEBHOOK:
6059
- type: "group" # 目标类型，可选值为 "group" 或 "private"
6160
id: 123456789 # 目标 ID，群号或用户 ID
6261
```
62+
63+
## 运行
64+
65+
```bash
66+
uvicorn app:app --host 0.0.0.0 --port 8000
67+
```
68+
69+
或者直接执行：
70+
71+
```bash
72+
python app.py
73+
```
74+
75+
## GitHub Webhook 设置
76+
77+
1. 在 GitHub 仓库中前往 Settings -> Webhooks -> Add webhook
78+
2. Payload URL 设置为 `http://你的服务器地址:8000/github-webhook`
79+
3. Content type 选择 `application/json`
80+
4. Secret 填写与配置文件中 `SECRET` 相同的值
81+
5. 选择需要监听的事件（或选择 "Send me everything" 接收所有事件）
82+
6. 启用 webhook（勾选 "Active"）

‎docs/src/introduction.md‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
</h1>
44

55
<p align="center">
6-
一个用于接收 GitHub Webhook 并通过 OneBot 协议将推送通知转发到 QQ 群的服务。
6+
OneBot GitHub Webhook 是一个用于接收 GitHub Webhook 推送事件并通过 OneBot 协议将通知转发到 QQ 群/好友的轻量级服务。它允许开发者和团队实时跟踪 GitHub 仓库活动，提高协作效率和项目透明度。
77
</p>
88

99
<p align="center">
@@ -19,3 +19,40 @@
1919
<img src="https://img.shields.io/github/license/AptS-1547/onebot-github-webhook" alt="GPL-3.0\"/>
2020
</a>
2121
</p>
22+
23+
## 功能特点
24+
25+
### 现有功能
26+
27+
- **Webhook 事件接收**：接收并处理 GitHub 的 Webhook 推送事件
28+
- **安全验证**：支持 Webhook 签名验证，确保请求安全性
29+
- **OneBot 协议支持**：通过 OneBot 协议将推送信息转发到指定的 QQ 群或私聊
30+
- **灵活配置**：可配置监听的仓库、分支和事件类型
31+
- **高级仓库匹配**：
32+
- 支持大小写不敏感的仓库名匹配
33+
- 支持 `用户名/*` 通配符匹配用户的所有仓库
34+
- **格式化消息**：结构化的推送通知，包含仓库、分支、推送者和最新提交信息
35+
36+
### 计划实现功能
37+
38+
- **GitHub API 轮询**：
39+
- 为无法设置 Webhook 的场景提供定时轮询机制
40+
- 支持自定义轮询间隔
41+
- 检测提交、PR、Issue 等变化
42+
43+
- **自定义模板系统**：
44+
- 支持用户自定义消息格式
45+
- Jinja2 模板语法
46+
- 支持不同事件类型的独立模板
47+
- 多种消息格式（纯文本、Markdown、JSON 等）
48+
49+
- **更多事件支持**：
50+
- Issues 事件（创建、关闭、重新打开）
51+
- Pull Request 事件（创建、合并、评论）
52+
- Release 事件（发布、预发布）
53+
- Discussion 事件
54+
55+
- **统计与监控**：
56+
- 处理事件统计
57+
- 服务健康检查
58+
- Prometheus 指标导出

‎docs/src/roadmap.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
## 开发路线图
2+
3+
### 1. GitHub API 轮询（计划中）
4+
5+
对于无法使用 webhook 的场景（如私有仓库或受限环境），我们计划实现基于 GitHub API 的轮询机制。
6+
7+
#### 设计概要
8+
9+
- **配置方式**：
10+
11+
```yaml
12+
GITHUB_API_POLLING:
13+
- NAME: "polling-example"
14+
REPO:
15+
- "username/repo"
16+
BRANCH:
17+
- "main"
18+
INTERVAL: 300 # 轮询间隔（秒）
19+
EVENTS:
20+
- "push"
21+
- "pull_request"
22+
TOKEN: "github_personal_access_token" # GitHub 个人访问令牌
23+
ONEBOT:
24+
- type: "group"
25+
id: 123456789
26+
```
27+
28+
- **功能**：
29+
- 定时检查仓库变更
30+
- 对比上次轮询结果，只通知新变更
31+
- 支持提交、PR、Issue 等多种数据类型轮询
32+
- 优化请求频率，避免触发 GitHub API 限流
33+
34+
- **实现计划**：
35+
- 使用 `APScheduler` 实现定时任务
36+
- 使用 `aiohttp` 实现异步 HTTP 请求
37+
- 使用本地文件存储上次轮询状态 ~~（轻量化的玩意不可能给你上数据库 or Redis）~~
38+
- 封装 GitHub API 客户端，处理认证和错误
39+
40+
### 2. 自定义模板系统（计划中）
41+
42+
允许用户自定义各类事件的通知消息格式，提供更灵活的展示方式。
43+
44+
#### 设计概要
45+
46+
- **模板存储**：
47+
- 模板文件存储在 `templates/` 目录下
48+
- 按照事件类型命名，如 `templates/push.txt`、`templates/issues.txt` 等
49+
- 也可以创建自定义命名的模板文件用于不同场景
50+
51+
- **配置方式**：
52+
53+
```yaml
54+
GITHUB_WEBHOOK:
55+
- NAME: "github"
56+
REPO:
57+
- "username/repo"
58+
BRANCH:
59+
- "main"
60+
SECRET: "your_secret"
61+
EVENTS:
62+
- "push"
63+
- "issues"
64+
TEMPLATES: # 为不同事件类型指定自定义模板
65+
push: "custom_push.txt" # 使用自定义推送模板
66+
issues: "default" # 使用默认 issues 模板
67+
ONEBOT:
68+
- type: "group"
69+
id: 123456789
70+
```
71+
72+
- **模板示例** (`templates/push.txt`):
73+
74+
```
75+
📢 GitHub 推送通知
76+
仓库：{{ repo_name }}
77+
分支：{{ branch }}
78+
推送者：{{ pusher }}
79+
提交数量：{{ commit_count }}
80+
{% for commit in commits %}
81+
[{{ loop.index }}] {{ commit.id[:7] }} by {{ commit.author.name }}
82+
{{ commit.message.split('\n')[0] }}
83+
{% endfor %}
84+
```
85+
86+
- **模板示例** (`templates/issues.txt`):
87+
88+
```
89+
📋 Issue {{ action }}
90+
仓库：{{ repo_name }}
91+
标题：{{ issue.title }}
92+
作者：{{ issue.user.login }}
93+
链接：{{ issue.html_url }}
94+
```
95+
96+
- **功能**：
97+
- 基于 Jinja2 模板引擎
98+
- 支持条件语句和循环
99+
- 每个 Webhook 可以指定不同的模板集合
100+
- 提供默认模板，无需配置即可使用
101+
- 模板变量自动文档化（将提供变量参考）
102+
103+
- **实现计划**：
104+
- 引入 Jinja2 依赖
105+
- 实现模板目录扫描和加载机制
106+
- 开发模板缓存以提高性能
107+
- 提供模板变量参考文档
108+
- 添加模板验证功能，避免语法错误

‎docs/src/structure.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,7 @@
11
## 项目结构
22

3-
- [app.py](app.py): 主应用入口和 Web 服务器
4-
- [hooks/github_webhook.py](hooks/github_webhook.py): GitHub Webhook 处理逻辑
5-
- [send_message.py](send_message.py): OneBot 消息发送客户端
6-
- [settings.py](settings.py): 配置加载和验证
7-
- [requirements.txt](requirements.txt): 项目依赖
8-
9-
## 依赖
10-
11-
- FastAPI: Web 框架
12-
- Uvicorn: ASGI 服务器
13-
- aiohttp: 异步 HTTP 客户端
14-
- pydantic: 数据验证
15-
- PyYAML: YAML 配置文件解析
3+
- app.py: 主应用入口和 Web 服务器
4+
- github_webhook.py: GitHub Webhook 处理逻辑
5+
- send_message.py: OneBot 消息发送客户端
6+
- settings.py: 配置加载和验证
7+
- requirements.txt: 项目依赖

0 commit comments

Comments
 (0)