matrixdotorg/go-neb

Go-NEB

镜像概述和主要用途

Go-NEB是一个用Go语言开发的Matrix机器人，作为Matrix-NEB（初代Python编写的Matrix机器人）的继任者，旨在通过Matrix协议实现与各类第三方服务的集成，提供自动化通知、内容生成及交互式功能。

核心功能和特性

Github

• 支持OAuth2登录认证
• 可创建任意项目的Github Issue
• 跟踪项目更新（通过Webhook），包括新Issue、拉取请求及代码提交
• 提及foo/bar#1234格式时自动展开Issue详情
• 为Matrix房间设置"默认仓库"，支持#1234简化格式展开及快捷Issue创建

JIRA

• 支持OAuth1登录认证
• 可在指定项目创建JIRA Issue
• 提及FOO-1234格式时自动展开JIRA Issue详情

媒体服务集成

• Giphy：查询Giphy的"文本转GIF"引擎
• Guggy：查询Guggy的GIF引擎

内容与通知服务

• RSS Bot：读取Atom/RSS订阅源并推送更新
• Travis CI：接收构建通知并支持自定义消息格式
• Alertmanager：接收告警并使用Go模板渲染展示

使用场景和适用范围

适用于需要在Matrix聊天平台中集成第三方服务（如Github、JIRA）、实现自动化通知（CI构建结果、RSS更新）、提供交互式内容生成（GIF查询）的个人用户或团队协作场景。

详细使用方法和配置说明

环境要求

• Go 1.16+（源码构建时）
• libolm3及开发依赖（用于端到端加密）：Ubuntu需安装libolm3和libolm-dev，CentOS需安装libolm-devel

安装方法

源码构建

bash
# 克隆仓库
git clone https://github.com/matrix-org/go-neb
cd go-neb

# 构建可执行文件
go build github.com/matrix-org/go-neb

Docker部署

使用官方镜像：

bash
docker run -v /path/to/data:/data -e "BASE_URL=http://your.public.url:4050" -p 4050:4050 matrixdotorg/go-neb

本地构建镜像：

bash
git clone https://github.com/matrix-org/go-neb
cd go-neb
docker build -t go-neb .

Docker镜像默认配置：

• 环境变量：BIND_ADDRESS=:4050、DATABASE_TYPE=sqlite3、DATABASE_URL=/data/go-neb.db?_busy_timeout=5000
• 暴露端口：4050
• 数据卷：/data（用于存储数据库文件）

运行配置

环境变量说明

基本运行命令

bash
BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=https://public.facing.endpoint ./go-neb

快速入门指南

1. 启动服务：

   bash
   go build github.com/matrix-org/go-neb
   BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=http://localhost:4050 ./go-neb
   

2. 获取Matrix用户凭证（使用Synapse登录API）：

   bash
   curl -X POST --header 'Content-Type: application/json' -d '{
       "identifier": { "type": "m.id.user", "user": "nebUsername" },
       "password": "nebPassword",
       "type": "m.login.password"
   }' 'http://localhost:8008/_matrix/client/r0/login'
   

   响应包含access_token和device_id。

3. 配置Matrix客户端：

   bash
   curl -X POST localhost:4050/admin/configureClient --data-binary '{
       "UserID": "@goneb:localhost",
       "HomeserverURL": "http://localhost:8008",
       "AccessToken": "<access_token>",
       "DeviceID": "<DEVICEID>",
       "Sync": true,
       "AutoJoinRooms": true,
       "DisplayName": "My Bot"
   }'
   

4. 配置服务（以echo服务为例）：

   bash
   curl -X POST localhost:4050/admin/configureService --data-binary '{
       "Type": "echo",
       "Id": "myserviceid",
       "UserID": "@goneb:localhost",
       "Config": {}
   }'
   

5. 测试交互：邀请@goneb:localhost进入Matrix房间，发送!echo hello world，机器人将回复hello world。

API参考

配置客户端

用于配置Matrix用户账号，支持多用户同时在线。

• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureClient.OnIncomingRequest
• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ClientConfig

配置服务

服务是实现具体功能的组件，需关联Matrix客户端。

• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureService.OnIncomingRequest
• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
• 支持的服务类型：Echo、Giphy、Github、Github Webhook、Guggy、JIRA、RSS Bot、Travis CI

配置认证领域

用于第三方服务（如Github、JIRA）的身份认证。

• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureAuthRealm.OnIncomingRequest
• https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureAuthRealmRequest
• 支持的领域：Github、JIRA

SAS验证

用于设备信任验证，需将3个SAS整数发送至/verifySAS端点：

bash
curl -X POST --header 'Content-Type: application/json' -d '{
    "UserID": "@neb:localhost",
    "OtherUserID": "@user:localhost",
    "OtherDeviceID": "ABCD",
    "SAS": [1111,2222,3333]
}' 'http://localhost:4050/verifySAS'

开发指南

架构概述

   HOMESERVER
       |
+=============================================================+
|      |                 Go-NEB                               |
| +---------+                                                 |
| | Clients | (与Homeserver通信，监听事件)                     |
| +---------+                                                 |
|      |                                                      |
| +---------+       +------------+      +--------------+      |
| | Service |-------| Auth Realm |------| Auth Session |-+    |
| +---------+       +------------+      +--------------+ |    |
|     ^                   ^              +---------------+    |
|     |                   |                                   |
+=============================================================+
      |                   |                   
    WEBHOOK            REDIRECT
    REQUEST            REQUEST

本地API文档

bash
# 启动文档服务器（监听:6060）
GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &

# 在浏览器中访问
http://localhost:6060/pkg/github.com/matrix-org/go-neb

开发依赖

bash
# 安装代码检查工具
go install honnef.co/go/tools/cmd/staticcheck@latest
go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

# 安装预提交钩子
./hooks/install.sh