rocketchat/hubot-rocketchat

hubot-rocketchat

Rocket.Chat的Hubot适配器，用于在Rocket.Chat平台上部署和运行聊天机器人。可通过环境变量灵活配置，支持多种监听模式、认证方式及自定义脚本，适用于团队协作自动化、第三方服务集成等场景。

重要变更

重大变更： v2.x.x版本包含重大突破性变更。从此版本开始：

• 不再支持CoffeeScript编写的机器人脚本，所有新脚本需使用NodeJS 8兼容的JavaScript
• 仅支持https://github.com/hubotio/hubot/tree/v3
• 需配合https://github.com/RocketChat/Rocket.Chat/releases/tag/0.63.0%E5%8F%8A%E6%9B%B4%E9%AB%98%E7%89%88%E6%9C%AC%E4%BD%BF%E7%94%A8
• 停止支持Yeoman生成器，应使用https://github.com/RocketChat/hubot-rocketchat-boilerplate%E5%88%9B%E5%BB%BA%E6%96%B0%E9%A1%B9%E7%9B%AE
• 要求NodeJS 8或更高版本
• 完全支持NodeJS 8中的最新ES6语法，包括async-await

v1.x.x版本适配器仅兼容Rocket.Chat Server 0.37.1及更高版本。若需继续使用v1.x.x适配器和CoffeeScript机器人，可配合最新版服务器运行。

若使用Rocket.Chat 0.35.0或更早版本，请使用适配器v0.1.4（不推荐在0.35.0至0.37.1版本间使用hubot）。

注意

如需将Rocket.Chat与GitHub或GitLab集成，建议先参考https://github.com/RocketChat/Rocket.-Chat.Ops%E9%A1%B9%E7%9B%AE%EF%BC%8C%E8%AF%A5%E9%A1%B9%E7%9B%AE%E5%B7%B2%E5%8C%85%E5%90%AB%E5%A4%9A%E7%A7%8Dwebhook%E4%BA%8B%E4%BB%B6%E5%A4%84%E7%90%86%E5%8F%8AAPI%E8%AE%BF%E9%97%AE%E8%84%9A%E6%9C%AC%EF%BC%8C%E5%8F%AF%E7%9B%B4%E6%8E%A5%E6%89%A9%E5%B1%95%E7%94%A8%E4%BA%8E%E8%87%AA%E5%AE%9A%E4%B9%89%E9%9C%80%E6%B1%82%E3%80%82

v2.x.x适配器使用指南（支持Hubot v3和ES6）

如需要编写CoffeeScript机器人、使用Hubot 2.x及v1.x.x/v0.x.x适配器，请参见v1.x.x和v0.x.x适配器说明。

以下说明仅适用于v2.x.x适配器。

机器人连接Rocket.Chat

Docker快速部署

可通过以下命令快速启动Docker镜像：

bash
docker run -it -e ROCKETCHAT_URL=<你的RocketChat实例地址>:<端口> \
    -e ROCKETCHAT_ROOM='' \
    -e LISTEN_ON_ALL_PUBLIC=true \
    -e ROCKETCHAT_USER=bot \
    -e ROCKETCHAT_PASSWORD=bot \
    -e ROCKETCHAT_AUTH=password \
    -e BOT_NAME=bot \
    -e EXTERNAL_SCRIPTS=hubot-pugme,hubot-help \
    rocketchat/hubot-rocketchat

加载自定义脚本

如需包含自定义脚本，可挂载本地脚本目录：

bash
docker run -it -e ROCKETCHAT_URL=<你的RocketChat实例地址>:<端口> \
    -e ROCKETCHAT_ROOM='' \
    -e LISTEN_ON_ALL_PUBLIC=true \
    -e ROCKETCHAT_USER=bot \
    -e ROCKETCHAT_PASSWORD=bot \
    -e ROCKETCHAT_AUTH=password \
    -e BOT_NAME=bot \
    -e EXTERNAL_SCRIPTS=hubot-pugme,hubot-help \
    -v $PWD/scripts:/home/hubot/scripts \
    rocketchat/hubot-rocketchat

在服务器上创建机器人用户

需管理员账户创建机器人登录账户：

1. 从管理 > 用户菜单进入
2. 点击+创建新用户
3. 输入姓名、用户名、*****（勾选已验证）及密码
4. 取消勾选要求密码更改
5. 从角色选择中选择bot并点击添加角色
6. 建议取消勾选加入默认频道，避免意外监听
7. 取消勾选发送欢迎邮件
8. 点击保存

创建的用户名和密码需分别配置到环境变量ROCKETCHAT_USER和ROCKETCHAT_PASSWORD中。

注意：为避免创建多个***账户，可使用Gmail的+地址功能，例如youremail+botname@gmail.com。

构建自定义机器人

请参考[模板机器人的快速入门文档][getting-started]！

模板项目本质是一个简单的Node.js包，包含Hubot、Rocket.Chat适配器及Coffeescript依赖：

json
"dependencies": {
    "coffeescript": "^2.2.2",
    "hubot": "3",
    "hubot-rocketchat": "^2.0.0"
}

生产环境中可通过bin文件执行机器人，https://github.com/RocketChat/hubot-rocketchat-boilerplate/tree/master/bin%EF%BC%9B%E6%9C%AC%E5%9C%B0%E5%BC%80%E5%8F%91%E5%8F%AF%E4%BD%BF%E7%94%A8%60npm run local或yarn local`命令。

使用模板示例时，生产环境启动命令：bin/hubot -a rocketchat（将安装依赖并使用当前适配器运行机器人）。

https://hubot.github.com/docs/%E6%8F%90%E4%BE%9B%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%E3%80%82

机器人配置

本地开发时，配置可保存在.env文件中；生产环境需在服务器启动时设置。

* 必需设置
** 需设为rocketchat启用适配器（或作为启动参数传递）

若需机器人监听所有公共频道及已加入的私有频道，需将ROCKETCHAT_ROOM设为空（ROCKETCHAT_ROOM=''）并设置LISTEN_ON_ALL_PUBLIC=true。

Rocket.Chat适配器通过Rocket.Chat Node.js SDK调用服务器方法并选择性缓存结果。高级用户可通过SDK环境变量修改默认设置，详见https://github.com/rocketchat/rocket.chat.js.sdk#settings%E3%80%82

常用配置

常见配置需求：监听私聊、所有新公共频道及私有群组，可使用以下选项：

• LISTEN_ON_ALL_PUBLIC=true
• ROCKETCHAT_ROOM=''
• 不设置RESPOND_TO_DM

注意：机器人需先被添加为私有群组成员才能响应消息。

连接Rocket.Chat

以下为适配器的其他连接方式。

Docker部署

基础启动命令：

bash
docker run -it -e ROCKETCHAT_URL=<你的RocketChat实例地址>:<port> \
    -e ROCKETCHAT_ROOM='' \
    -e LISTEN_ON_ALL_PUBLIC=true \
    -e ROCKETCHAT_USER=bot \
    -e ROCKETCHAT_PASSWORD=bot \
    -e HUBOT_NAME=bot \
    -e EXTERNAL_SCRIPTS=hubot-help,hubot-diagnostics \
    rocketchat/hubot-rocketchat

自定义脚本

挂载本地脚本目录：

bash
docker run -it -e ROCKETCHAT_URL=<你的RocketChat实例地址>:<port> \
    -e ROCKETCHAT_ROOM='' \
    -e LISTEN_ON_ALL_PUBLIC=true \
    -e ROCKETCHAT_USER=botname \
    -e ROCKETCHAT_PASSWORD=botpass \
    -e HUBOT_NAME=botname \
    -e EXTERNAL_SCRIPTS=hubot-help,hubot-diagnostics \
    -v $PWD/scripts:/home/hubot/scripts \
    rocketchat/hubot-rocketchat

配置选项

所有可配置选项如下：

Docker环境使用：-e VAR=Value
常规Hubot环境使用：export VAR=Value或配置到pm2等进程管理工具

** - 仅Docker镜像支持

监听私聊、所有新公共频道及私有群组的配置

常用配置： LISTEN_ON_ALL_PUBLIC=true 且 ROCKETCHAT_ROOM=''，不设置RESPOND_TO_DM

注意：机器人需先被添加为私有群组成员才能响应消息。

验证机器人工作状态

测试命令：

rocketbot ping

查看帮助：

rocketbot help

示例脚本响应：

rocketbot report status

v2.x.x开发指南

Docker开发

克隆源码并进入目录：

bash
git clone git@github.com:RocketChat/hubot-rocketchat.git
cd hubot-rocketchat

启动开发容器：

bash
docker run -it -e ROCKETCHAT_URL=<你的RocketChat实例地址>:<port> \
    -e ROCKETCHAT_ROOM='' \
    -e LISTEN_ON_ALL_PUBLIC=true \
    -e ROCKETCHAT_USER=bot \
    -e ROCKETCHAT_PASSWORD=bot \
    -e HUBOT_NAME=bot \
    -e EXTERNAL_SCRIPTS=hubot-help,hubot-diagnostic \
    -v $PWD:/home/hubot/node_modules/hubot-rocketchat rocketchat/hubot-rocketchat

标准开发

在Hubot项目中，替换已安装的适配器为开发版本：

• 从机器人项目根目录进入node_modules
• 删除已发布版本：rm -rf hubot-rocketchat
• 克隆开发版本：git clone git@github.com:RocketChat/hubot-rocketchat.git
• 进入开发目录：cd hubot-rocketchat
• 安装依赖：npm install

链接开发

设置本地链接包便于持续开发或在多个机器人中使用同一开发版本：

• 进入适配器开发目录
• 执行npm link或yarn link设置链接源
• 进入机器人项目根目录
• 执行npm link hubot-rocketchat或yarn link hubot-rocketchat创建链接

重要注意事项

• 首次运行Docker容器时需从公共仓库拉取镜像，耗时较长，后续运行速度较快
• 非Linux系统（如Mac或PC）无法使用$PWD挂载卷，需参考Docker卷文档（页面第二个注意事项：If you are using Boot2Docker...）确定绝对路径

v1.x.x 和 v0.x.x 适配器说明

Docker-compose部署

v0.1.4适配器的docker-compose配置示例（添加到docker-compose.yml）：

yaml
# hubot，流行的聊天机器人（需先创建机器人用户并修改密码）
hubot:
  image: rocketchat/hubot-rocketchat:v0.1.4
  environment:
    - ROCKETCHAT_URL=你的RocketChat实例IP:3000（例如192.168.2.240:3000）
    - ROCKETCHAT_ROOM=
    - LISTEN_ON_ALL_PUBLIC=true
    - ROCKETCHAT_USER=机器人用户名
    - ROCKETCHAT_PASSWORD=机器人密码
    - BOT_NAME=bot
    - GOOGLE_API_KEY=你的Google API密钥
# 可在此添加更多脚本，需通过npm安装
    - EXTERNAL_SCRIPTS=hubot-help,hubot-seen,hubot-links,hubot-diagnostics,hubot-google,hubot-reddit,hubot-bofh,hubot-bookmark,hubot-shipit,hubot-maps
  links:
    - rocketchat:rocketchat
# 暴露hubot端口（3001）用于主机通知，如hubot-jenkins-notifier
  ports:
    - 3001:8080

若需机器人监听所有公共频道及已加入的私有频道，需将ROCKETCHAT_ROOM设为空并设置LISTEN_ON_ALL_PUBLIC=true。

注意：示例中的部分外部脚本（如hubot-google）需要在docker-compose中配置Google API密钥。

使用Node Version Manager（nvm）在Debian/Ubuntu本地环境安装

bash
# 添加hubot用户
# su - hubot
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash
$ exit
# su - hubot
$ nvm install v4.8.5
$ npm update -g
$ npm install -g yo generator-hubot
$ mkdir hubot
$ cd hubot
$ yo hubot（回答问题并使用"rocketchat"作为适配器）
$ npm install coffee-script -save

确保~/hubot/bin/hubot可执行：chmod 755 ./bin/hubot

如需Redis数据库：apt install redis-server

设置Node版本：export NODE_VERSION=default

使用systemd启动hubot时，需使用nvm-exec：

ExecStart=/home/hubot/.nvm/nvm-exec /home/hubot/hubot/bin/hubot --adapter rocketchat

参考systemd单元的EnvironmentFile指令设置环境变量。

为Hubot添加适配器

全新安装

可在设置过程中指定适配器。

首先安装hubot：

bash
npm install -g yo generator-hubot

然后创建机器人：

bash
mkdir myhubot
cd myhubot
yo hubot --adapter="rocketchat@1"

根据提示回答问题，或通过一条命令指定所有参数：

bash
yo hubot --owner="OWNER <owner@example.com>" --name="bot" --description="Bot" --adapter="rocketchat@0.1"

记录设置的机器人名称，这是机器人在Rocket.Chat中的响应名称。

配置适配器：

bash
export ROCKETCHAT_ROOM=''
export LISTEN_ON_ALL_PUBLIC=true
export ROCKETCHAT_USER=bot
export ROCKETCHAT_PASSWORD=bot
export ROCKETCHAT_AUTH=password

启动机器人：bin/hubot -a rocketchat

https://hubot.github.com/docs/

现有安装

已安装Hubot的情况下，通过以下命令添加