mirror of
https://github.com/sky22333/qqbot.git
synced 2026-09-05 23:47:38 +08:00
优化文档和CI
This commit is contained in:
sky22333
@@ -0,0 +1,72 @@
|
|||||||
|
name: 发布二进制
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_dispatch:
|
||||||
|
inputs:
|
||||||
|
version:
|
||||||
|
description: "版本号（例如：v1.0.0）"
|
||||||
|
required: true
|
||||||
|
default: "v1.0.0"
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
release:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: write
|
||||||
|
steps:
|
||||||
|
- name: 检出代码
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: 设置 Go 环境
|
||||||
|
uses: actions/setup-go@v5
|
||||||
|
with:
|
||||||
|
go-version-file: go.mod
|
||||||
|
|
||||||
|
- name: 计算版本号
|
||||||
|
id: meta
|
||||||
|
run: |
|
||||||
|
VERSION="${{ github.event.inputs.version }}"
|
||||||
|
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
|
||||||
|
|
||||||
|
- name: 运行测试与静态检查
|
||||||
|
run: |
|
||||||
|
go test ./...
|
||||||
|
go vet ./...
|
||||||
|
|
||||||
|
- name: 构建 Linux 二进制
|
||||||
|
run: |
|
||||||
|
mkdir -p dist
|
||||||
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o dist/qqbotd-linux-amd64 ./cmd/qqbotd
|
||||||
|
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o dist/qqbotd-linux-arm64 ./cmd/qqbotd
|
||||||
|
|
||||||
|
- name: 生成发布说明
|
||||||
|
id: notes
|
||||||
|
run: |
|
||||||
|
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || true)
|
||||||
|
{
|
||||||
|
echo "body<<EOF"
|
||||||
|
if [ -n "$PREV_TAG" ]; then
|
||||||
|
echo "## 更新内容"
|
||||||
|
git log --pretty=format:"- %s" "$PREV_TAG"..HEAD
|
||||||
|
echo ""
|
||||||
|
else
|
||||||
|
echo "## 首次发布"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
echo "## 二进制文件"
|
||||||
|
echo "- qqbotd-linux-amd64"
|
||||||
|
echo "- qqbotd-linux-arm64"
|
||||||
|
echo "EOF"
|
||||||
|
} >> "$GITHUB_OUTPUT"
|
||||||
|
|
||||||
|
- name: 发布 Release
|
||||||
|
uses: softprops/action-gh-release@v2
|
||||||
|
with:
|
||||||
|
tag_name: ${{ steps.meta.outputs.version }}
|
||||||
|
name: qqbot ${{ steps.meta.outputs.version }}
|
||||||
|
body: ${{ steps.notes.outputs.body }}
|
||||||
|
files: |
|
||||||
|
dist/qqbotd-linux-amd64
|
||||||
|
dist/qqbotd-linux-arm64
|
||||||
@@ -1,14 +1,28 @@
|
|||||||
# qqbot
|
# qqbot
|
||||||
|
|
||||||
轻量级 QQ 通知机器人，支持 HTTP 服务与 Go SDK 两种使用方式。
|
轻量级 QQ 通知机器人，支持 HTTP 与 Go SDK 接入，提供同步发送、异步队列、状态查询与目标自动采集能力，内置失败重试，部署简单、使用方便。
|
||||||
|
|
||||||
## 1. 快速开始
|
## 1. 快速开始
|
||||||
|
|
||||||
- Go 1.26+
|
|
||||||
- 已开通 QQ 机器人并拿到 `app_id`、`client_secret`
|
- 已开通 QQ 机器人并拿到 `app_id`、`client_secret`
|
||||||
- 开通地址：https://q.qq.com/qqbot/openclaw/login.html
|
- 开通地址：https://q.qq.com/qqbot/openclaw/login.html
|
||||||
|
|
||||||
最小配置示例：
|
使用docker-compose部署：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
qqbot:
|
||||||
|
image: ghcr.io/sky22333/qqbot
|
||||||
|
container_name: qqbot
|
||||||
|
restart: always
|
||||||
|
ports:
|
||||||
|
- "8080:8080"
|
||||||
|
volumes:
|
||||||
|
- ./configs/config.toml:/root/config.toml
|
||||||
|
- ./data:/root/data
|
||||||
|
```
|
||||||
|
|
||||||
|
`config.toml`最小配置示例：
|
||||||
```toml
|
```toml
|
||||||
[qqbot]
|
[qqbot]
|
||||||
app_id = "你的AppID"
|
app_id = "你的AppID"
|
||||||
@@ -20,55 +34,25 @@ listen_addr = ":8080"
|
|||||||
api_token = "强密码token"
|
api_token = "强密码token"
|
||||||
```
|
```
|
||||||
|
|
||||||
## 2. HTTP 调用方式
|
启动服务后，需要用自己的 QQ 给机器人发一次消息，让系统自动采集目标ID后才能正常推送信息。
|
||||||
|
|
||||||
除健康检查外，业务接口都需要鉴权：
|
## 2. 推送测试
|
||||||
|
```
|
||||||
|
# 异步推送
|
||||||
|
curl -X POST "http://127.0.0.1:8080/api/v1/messages" \
|
||||||
|
-H "Authorization: Bearer 接口鉴权token" \
|
||||||
|
-H "Content-Type: application/json; charset=utf-8" \
|
||||||
|
-d '{"content":"这是一条异步推送测试"}'
|
||||||
|
|
||||||
```http
|
# 同步推送
|
||||||
Authorization: Bearer 你的api_token
|
curl -X POST "http://127.0.0.1:8080/api/v1/messages/send" \
|
||||||
Content-Type: application/json
|
-H "Authorization: Bearer 接口鉴权token" \
|
||||||
|
-H "Content-Type: application/json; charset=utf-8" \
|
||||||
|
-d '{"content":"这是一条同步推送测试"}'
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 2.1 同步发送 `POST /api/v1/messages/send`
|
|
||||||
|
|
||||||
```json
|
## 3. 常用命令
|
||||||
{
|
|
||||||
"target_type": "c2c",
|
|
||||||
"content": "这是一条通知"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`target_id` 可选；不传时自动使用最近采集目标。
|
|
||||||
`target_type` 也可选；不传时自动使用最近采集目标的类型与 ID。
|
|
||||||
|
|
||||||
#### 2.2 异步入队 `POST /api/v1/messages`
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"target_type": "group",
|
|
||||||
"content": "这是一条群通知"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`target_id` 可选；不传时自动使用最近采集目标。
|
|
||||||
|
|
||||||
#### 2.3 查询状态 `GET /api/v1/messages/{request_id}`
|
|
||||||
|
|
||||||
#### 2.4 查询目标 `GET /api/v1/targets`
|
|
||||||
|
|
||||||
可选参数：`target_type=c2c|group|channel`
|
|
||||||
|
|
||||||
#### 2.5 健康检查（无需鉴权）
|
|
||||||
|
|
||||||
- `GET /healthz`
|
|
||||||
- `GET /readyz`
|
|
||||||
|
|
||||||
## 3. 目标采集
|
|
||||||
|
|
||||||
启动服务后，用自己的 QQ 给机器人发消息，系统会自动采集目标并写入 `targets.file_path` 对应的文件（默认 `data/targets.json`）。
|
|
||||||
可通过 `GET /api/v1/targets` 查看。
|
|
||||||
|
|
||||||
## 4. 常用命令
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 运行测试
|
# 运行测试
|
||||||
@@ -87,17 +71,58 @@ go build ./cmd/qqbotd
|
|||||||
go build -trimpath -ldflags "-s -w -buildid=" -o qqbotd ./cmd/qqbotd
|
go build -trimpath -ldflags "-s -w -buildid=" -o qqbotd ./cmd/qqbotd
|
||||||
```
|
```
|
||||||
|
|
||||||
## 5. 推送测试
|
## 4. HTTP 调用方式
|
||||||
```
|
|
||||||
# 异步推送
|
|
||||||
curl -X POST "http://127.0.0.1:8080/api/v1/messages" \
|
|
||||||
-H "Authorization: Bearer 接口鉴权token" \
|
|
||||||
-H "Content-Type: application/json; charset=utf-8" \
|
|
||||||
-d '{"content":"这是一条异步推送测试"}'
|
|
||||||
|
|
||||||
# 同步推送
|
除健康检查外，业务接口都需要鉴权：
|
||||||
curl -X POST "http://127.0.0.1:8080/api/v1/messages/send" \
|
|
||||||
-H "Authorization: Bearer 接口鉴权token" \
|
```http
|
||||||
-H "Content-Type: application/json; charset=utf-8" \
|
Authorization: Bearer 你的api_token
|
||||||
-d '{"content":"这是一条同步推送测试"}'
|
Content-Type: application/json
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### 4.1 同步发送 `POST /api/v1/messages/send`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"target_type": "c2c",
|
||||||
|
"content": "这是一条通知"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`target_id` 可选；不传时自动使用最近采集目标。
|
||||||
|
`target_type` 也可选；不传时自动使用最近采集目标的类型与 ID。
|
||||||
|
|
||||||
|
#### 4.2 异步入队 `POST /api/v1/messages`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"target_type": "group",
|
||||||
|
"content": "这是一条群通知"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`target_id` 可选；不传时自动使用最近采集目标。
|
||||||
|
|
||||||
|
#### 4.3 查询状态 `GET /api/v1/messages/{request_id}`
|
||||||
|
|
||||||
|
#### 4.4 查询目标 `GET /api/v1/targets`
|
||||||
|
|
||||||
|
可选参数：`target_type=c2c|group|channel`
|
||||||
|
|
||||||
|
#### 4.5 健康检查（无需鉴权）
|
||||||
|
|
||||||
|
- `GET /healthz`
|
||||||
|
- `GET /readyz`
|
||||||
|
|
||||||
|
## 5. 目标采集
|
||||||
|
|
||||||
|
启动服务后，用自己的 QQ 给机器人发消息，系统会自动采集目标并写入 `targets.file_path` 对应的文件（默认 `data/targets.json`）。
|
||||||
|
可通过 `GET /api/v1/targets` 查看。
|
||||||
|
|
||||||
|
## 6. 时效与可达性说明
|
||||||
|
|
||||||
|
- `target_id`（如 `user_openid`）作为发送目标标识可长期保存，不按 TTL 失效
|
||||||
|
- 服务端调用凭证 `access_token` 会过期，项目已自动刷新
|
||||||
|
- 当前项目仅发送文本或 markdown，不包含富媒体 `file_info` 链路
|
||||||
|
- 是否可送达受平台规则影响：用户关闭主动消息、频控超限都会导致发送失败
|
||||||
|
- 建议用异步接口发送，并通过 `GET /api/v1/messages/{request_id}` 跟踪状态
|
||||||
|
|||||||
Reference in New Issue
Block a user