GitHub 平台适配器完整指南 — Token 认证、Webhook / Polling 双模式、内网穿透方案。

---

Quick Reference

属性	值
适配器名称	github
平台标识	github
协议	GitHub Webhook (HTTP) / REST API Polling
类	GitHubAdapter
导入	from ncatbot.adapter.github import GitHubAdapter

# 最小配置
adapters:
  - type: github
    platform: github
    enabled: true
    config:
      token: "ghp_xxxxxxxxxxxx"
      repos:
        - "owner/repo"
      mode: webhook

---

Token 认证

GitHub 适配器使用 Personal Access Token (PAT) 认证，无交互式登录流程。

创建 Token

1. 访问 GitHub Settings → Developer settings → Personal access tokens
2. 点击 Generate new token (classic) 或使用 Fine-grained tokens
3. 勾选所需权限（推荐最小权限）：
   • repo — 仓库读写（Issue / PR / Comment）
   • read:org — 组织仓库（如需要）
4. 生成后复制 Token，填入 config.yaml

验证

适配器启动时自动调用 GET /user 验证 Token 有效性。验证失败会报错并终止启动。

提示

不配置 Token 也可运行（适用于公开仓库 Webhook 接收），但 API 调用会受到严格速率限制（60 次/小时 vs 5000 次/小时）。

---

两种模式

Webhook 模式（默认）

启动 HTTP Server 监听 GitHub Webhook 推送，实时性最好。

config:
  token: "ghp_xxxx"
  repos: ["owner/repo"]
  mode: webhook
  webhook_host: "0.0.0.0"
  webhook_port: 8080
  webhook_path: "/webhook"
  webhook_secret: "your-secret"    # 推荐配置，用于签名验证

流程：

GitHub → POST /webhook → NcatBot HTTP Server → 解析事件 → Dispatcher

配置 GitHub 仓库的 Webhook：

1. 仓库 → Settings → Webhooks → Add webhook
2. Payload URL: http://your-server:8080/webhook
3. Content type: application/json
4. Secret: 与 webhook_secret 一致
5. 选择需要接收的事件（或 "Send me everything"）

内网环境使用 Webhook

如果 Bot 运行在内网（无公网 IP），可以使用 smee.io + gosmee 方案将 Webhook 转发到本地。

方案一：smee.io（推荐入门）

smee.io 是 GitHub 官方推荐的 Webhook 代理服务，免费使用。

1. 访问 https://smee.io ，点击 Start a new channel，获得一个唯一 URL（如 https://smee.io/AbCdEfGh）
2. 将该 URL 填入 GitHub 仓库的 Webhook Payload URL
3. 本地安装 smee-client 并启动转发：

npm install -g smee-client
smee -u https://smee.io/AbCdEfGh -t http://localhost:8080/webhook

4. smee-client 会将 GitHub 发到 smee.io 的 Webhook 请求实时转发到本地的 NcatBot HTTP Server

方案二：gosmee（推荐生产）

gosmee 是用 Go 编写的高性能 smee 兼容客户端，支持自建服务端，适合生产环境。

1. 安装 gosmee：

# Go install
go install github.com/chmouel/gosmee@latest

# 或下载二进制
# https://github.com/chmouel/gosmee/releases

2. 使用 smee.io 作为中转（与 smee-client 兼容）：

gosmee client https://smee.io/AbCdEfGh http://localhost:8080/webhook

3. 或者自建 gosmee server（完全自托管，无需依赖第三方服务）：

# 在有公网 IP 的服务器上启动 gosmee server
gosmee server --port 3333

# GitHub Webhook Payload URL 填: http://your-server:3333/webhook-channel-id
# 本地运行 gosmee client 连接到自建 server
gosmee client http://your-server:3333/webhook-channel-id http://localhost:8080/webhook

整体拓扑：

GitHub ──POST──→ smee.io / gosmee server (公网)
                        │
                    SSE 推送
                        │
              smee-client / gosmee client (内网)
                        │
                   POST 转发
                        │
              NcatBot HTTP Server (localhost:8080)

注意

smee.io 的 channel 是公开的，不要依赖它做安全控制。始终配置 webhook_secret 进行签名验证。

Polling 模式

定时调用 GitHub Events API 获取事件。适合无法接收 Webhook 的环境（如防火墙限制且不想配内网穿透）。

config:
  token: "ghp_xxxx"
  repos: ["owner/repo"]
  mode: polling
  poll_interval: 60.0    # 每 60 秒轮询一次

流程：

NcatBot → GET /repos/{owner}/{repo}/events → 解析新事件 → Dispatcher

对比	Webhook	Polling
实时性	秒级	poll_interval 延迟
网络要求	需要公网可达或内网穿透	仅需出站 HTTPS
API 配额	不消耗	消耗 REST API 配额
适用场景	生产环境	开发/测试、防火墙内

---

配置项详解

adapters:
  - type: github
    platform: github
    enabled: true
    config:
      # 认证
      token: "ghp_xxxx"          # GitHub Personal Access Token

      # 监听仓库
      repos:                     # 仅 Polling 模式需要配置
        - "owner/repo1"          # Webhook 模式下 GitHub 自行推送
        - "owner/repo2"

      # 连接模式
      mode: webhook              # "webhook" 或 "polling"

      # Webhook 配置
      webhook_host: "0.0.0.0"   # HTTP Server 监听地址
      webhook_port: 8080         # HTTP Server 监听端口
      webhook_path: "/webhook"   # Webhook 路径
      webhook_secret: ""         # Webhook Secret（用于签名验证）

      # Polling 配置
      poll_interval: 60.0        # 轮询间隔（秒）

配置项说明

配置项	类型	默认值	说明
token	string	""	GitHub PAT，为空时 API 受限
repos	list[string]	[]	监听的仓库列表（格式 owner/repo）
mode	string	"webhook"	"webhook" 或 "polling"
webhook_host	string	"0.0.0.0"	Webhook HTTP Server 监听地址
webhook_port	int	8080	Webhook HTTP Server 端口
webhook_path	string	"/webhook"	Webhook 接收路径
webhook_secret	string	""	用于验证 Webhook 签名（推荐配置）
poll_interval	float	60.0	Polling 模式轮询间隔（秒）

---

Webhook 签名验证

配置 webhook_secret 后，适配器会对每个 Webhook 请求验证 X-Hub-Signature-256 头，使用 HMAC-SHA256 算法比对签名。签名不匹配的请求返回 403。

webhook_secret: "my-super-secret"  # 与 GitHub Webhook 设置中的 Secret 一致

---

常见问题

问题	原因	解决方案
Token 验证失败	Token 过期或权限不足	重新生成 Token 并确认权限
Webhook 不触发	GitHub 无法访问 Bot 服务器	确认公网可达或使用 smee/gosmee 内网穿透
Webhook 端口冲突	端口已被占用	修改 webhook_port
Polling 无事件	repos 列表为空或 Token 无权限	确认仓库配置和 Token 权限
签名验证失败	Secret 不匹配	确认两端 webhook_secret 一致

---

示例

• examples/github/01_hello_world/ — 最简 GitHub Bot
• examples/github/02_issue_bot/ — Issue 自动处理

---

延伸阅读

• GitHub 消息发送 → send_message/github/
• GitHub Bot API → api_usage/github/
• 多平台开发 → multi_platform/
• 适配器接口参考 → reference/adapter/

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)