Ubuntu 22.04 安装 Errbot 6.2.1 指南

在 Ubuntu 22.04 上安装 Errbot 6.2.1 的完整指南，覆盖 pip 在线、离线包、源码包三种安装方案、config.py 初始化、Text 后端交互验证、第三方插件安装、Webserver webhook 实测、systemd 托管、升级降级与卸载清理

ErrbotErrbotChatOps自动化运维2026/10/25

Ubuntu 22.04 安装 Errbot 6.2.1 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Errbot 6.2.1 聊天机器人框架，完成初始化、交互验证、插件安装与 webhook 联调，并掌握升级降级与卸载方法。本文三种安装方案（pip 在线、pip 离线包、源码包）均已在 Ubuntu 22.04（Python 3.10.12）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（Jammy）
  • 系统架构：x86_64
  • Python 版本：3.10.12（系统自带）
  • pip 版本：22.0.2（系统）/ 26.2.2（虚拟环境内升级后）
  • Git 版本：2.34.1
  • Errbot 版本：6.2.1（PyPI 当前最新稳定版）
  • 安装路径：虚拟环境 /opt/errbot/venv，机器人工作目录 /opt/errbot/bot
  • Webhook 验证端口：3141

二、前置条件

  • 拥有 root 权限或 sudo 权限（本文以 root 演示）。
  • 方案 A/C 需要服务器可访问 PyPI；方案 C 与插件安装需要访问 GitHub。实测环境通过代理访问外网，如遇直连失败请先配置代理（见十三、常见问题 Q4）。
  • Errbot 6.2.x 要求 Python 3.9–3.13，Ubuntu 22.04 自带的 Python 3.10 满足要求，无需额外编译 Python。

安装系统依赖（Python 虚拟环境支持、pip、Git，其中 Git 用于插件仓库安装）：

执行命令：

apt update && apt install -y python3 python3-venv python3-pip git

执行结果：

python3 is already the newest version (3.10.6-1~22.04.1).
python3-pip is already the newest version (22.0.2+dfsg-1ubuntu0.7).
python3-venv is already the newest version (3.10.6-1~22.04.1).
git is already the newest version (1:2.34.1-1ubuntu1.18).
0 upgraded, 0 newly installed, 0 to remove and 3 not upgraded.

💡 说明：本文实测机器已预装这四个包，回显显示 "already the newest version"；全新系统执行同一命令会自动完成安装。

验证依赖版本：

执行命令：

python3 --version
pip3 --version
git --version

执行结果：

Python 3.10.12
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)
git version 2.34.1

三、版本选型说明

通过 pip 查询 PyPI 上 errbot 的全部可用版本：

执行命令：

/opt/errbot/venv/bin/pip index versions errbot

执行结果：

errbot (6.2.1)
Available versions: 6.2.1, 6.2.0, 6.1.9, 6.1.8, 6.1.7, 6.1.6, 6.1.5, 6.1.4, 6.1.3, 6.1.2, 6.1.1, 6.1.0, 6.0.0, 5.2.0, 5.1.3, 5.1.2, 5.1.1, 5.1.0, 5.0.1, 5.0.0, 4.3.7, 4.3.6, 4.3.5, 4.3.4, 4.3.3, 4.3.2, 4.3.1, 4.3.0, 4.2.2, 4.2.1, 4.2.0, 4.1.3, 4.1.2, 4.1.1, 4.1.0, 4.0.3, 4.0.2, 4.0.1, 4.0.0, 3.2.4, 3.2.3, 3.2.2, 3.2.1
  INSTALLED: 6.2.1
  LATEST:    6.2.1
版本线说明选型建议
6.2.x（6.2.0 / 6.2.1）当前最新稳定线，移除 Python 3.8 支持，支持 Python 3.9–3.13新部署一律选 6.2.1
6.1.x（6.1.0–6.1.9）上一代稳定线，支持 Python 3.8仅存量老系统（Python 3.8）考虑
5.x 及更早已停止维护不建议使用

💡 说明：INSTALLED/LATEST 两行表明本机安装的就是 PyPI 当前最新版 6.2.1。6.2.1 是相对 6.2.0 的补丁版本，修复优先级最高，直接使用即可。

四、在线安装方案（A：pip + venv，官方推荐）

4.1 方案说明

Errbot 是纯 Python 软件，官方推荐的安装方式是通过 pip 安装到 Python 虚拟环境（venv）中：依赖与系统 Python 完全隔离，升级/卸载干净，不污染系统包管理。本方案适用于可访问 PyPI 的服务器。

4.2 创建虚拟环境

执行命令：

mkdir -p /opt/errbot
python3 -m venv /opt/errbot/venv

执行结果： 无输出即成功。虚拟环境创建在 /opt/errbot/venv，后续所有 pip/errbot 命令均使用该目录下的二进制，避免污染系统 Python。

4.3 升级 venv 内 pip 并安装 Errbot

系统自带 pip 22.0.2 较旧，先在虚拟环境内升级 pip，再安装 errbot：

执行命令：

/opt/errbot/venv/bin/pip install --upgrade pip

执行结果：

      Successfully uninstalled pip-22.0.2
Successfully installed pip-26.2.2

执行命令：

/opt/errbot/venv/bin/pip install errbot

执行结果（输出节选，实测首尾）：

Collecting errbot
  Using cached errbot-6.2.1-py3-none-any.whl.metadata (23 kB)
Collecting webtest==3.0.7 (from errbot)
  Using cached webtest-3.0.7-py3-none-any.whl.metadata (2.0 kB)
......
Successfully installed Pygments-2.20.0 WebOb-1.8.11 ansi-0.3.7 beautifulsoup4-4.15.0 blinker-1.9.0 certifi-2026.10.23 cffi-2.1.1 charset_normalizer-3.5.2 click-8.5.0 colorlog-6.10.1 cryptography-47.0.0 daemonize-2.5.0 deepmerge-2.0 dulwich-1.2.1 errbot-6.2.1 flask-3.1.3 idna-3.20 itsdangerous-2.2.0 jinja2-3.1.6 markdown-3.10.2 markupsafe-3.0.4 pyOpenSSL-26.1.0 pycparser-3.11 pygments-markdown-lexer-0.1.0.dev39 requests-2.32.5 setuptools-84.2.1 soupsieve-2.10 typing_extensions-4.16.0 urllib3-2.8.0 waitress-3.0.2 webtest-3.0.7 werkzeug-3.1.9

💡 说明：pip 共安装 32 个包——errbot 6.2.1 本体加上 Flask（内置 Web 服务器）、dulwich（纯 Python Git 客户端，用于插件仓库管理）、Jinja2、Markdown、colorlog 等依赖。完整输出 102 行，此处保留首尾。

4.4 验证安装

执行命令：

/opt/errbot/venv/bin/errbot --version

执行结果：

Errbot version 6.2.1

✅ 验证通过：errbot CLI 可用，版本为 6.2.1。初始化与功能验证统一在「九、首次启动与功能验证」进行，三种方案共用。

五、离线 pip 包安装方案（B：断网/内网环境）

5.1 方案说明

目标服务器无法访问 PyPI 时，在一台同 OS、同 Python 版本的联网机器上用 pip download 把 errbot 及全部依赖的 wheel 包打包，拷贝到目标机后用 --no-index --find-links 离线安装。实测离线包目录共 32 个包、约 11MB。

⚠️ 注意：pip download 默认按当前平台与 Python 版本下载 wheel，务必保证下载机与目标机均为 Linux x86_64 + Python 3.10，否则需加 --platform/--python-version/--only-binary=:all: 参数指定目标平台。

5.2 联网机下载离线包

执行命令（在可访问 PyPI 的机器上）：

mkdir -p /opt/errbot/offline-pkgs
pip3 download errbot==6.2.1 -d /opt/errbot/offline-pkgs

执行结果（输出节选，实测首尾）：

Saved ./opt/errbot/offline-pkgs/soupsieve-2.10-py3-none-any.whl
Saved ./opt/errbot/offline-pkgs/pycparser-3.11-py3-none-any.whl
Successfully downloaded errbot ansi colorlog daemonize deepmerge dulwich flask jinja2 markdown Pygments pygments-markdown-lexer pyOpenSSL requests webtest charset_normalizer cryptography idna urllib3 blinker certifi cffi click itsdangerous markupsafe setuptools typing_extensions waitress WebOb werkzeug beautifulsoup4 soupsieve pycparser

确认产物：

执行命令：

ls /opt/errbot/offline-pkgs | wc -l
du -sh /opt/errbot/offline-pkgs
ls /opt/errbot/offline-pkgs | head -5

执行结果：

32
11M	/opt/errbot/offline-pkgs
ansi-0.3.7-py3-none-any.whl
beautifulsoup4-4.15.0-py3-none-any.whl
blinker-1.9.0-py3-none-any.whl
certifi-2026.10.23-py3-none-any.whl
cffi-2.1.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

💡 说明：32 个依赖包中绝大多数是纯 Python 的 py3-none-any 通用 wheel；cffi、markupsafe、cryptography 等为 cp310 平台相关 wheel，这就是下载机必须与目标机平台一致的原因。将 /opt/errbot/offline-pkgs 整个目录用 scp/U盘等方式拷贝到目标机相同路径。

5.3 目标机离线安装

执行命令（在目标机上）：

mkdir -p /opt/errbot
python3 -m venv /opt/errbot/venv
/opt/errbot/venv/bin/pip install --no-index --find-links /opt/errbot/offline-pkgs errbot

执行结果：

  Running setup.py install for pygments-markdown-lexer: finished with status 'done'
Successfully installed Pygments-2.20.0 WebOb-1.8.11 ansi-0.3.7 beautifulsoup4-4.15.0 blinker-1.9.0 certifi-2026.10.23 cffi-2.1.1 charset_normalizer-3.5.2 click-8.5.0 colorlog-6.10.1 cryptography-47.0.0 daemonize-2.5.0 deepmerge-2.0 dulwich-1.2.1 errbot-6.2.1 flask-3.1.3 idna-3.20 itsdangerous-2.2.0 jinja2-3.1.6 markdown-3.10.2 markupsafe-3.0.4 pyOpenSSL-26.1.0 pycparser-3.11 pygments-markdown-lexer-0.1.0.dev39 requests-2.32.5 setuptools-84.2.1 soupsieve-2.10 typing_extensions-4.16.0 urllib3-2.8.0 waitress-3.0.2 webtest-3.0.7 werkzeug-3.1.9

💡 命令解释：--no-index 禁止访问 PyPI，--find-links 指定本地包目录。pygments-markdown-lexer 只有 sdist 源码包（.zip），因此离线安装时会现场执行 setup.py install，属正常现象。

5.4 验证安装

执行命令：

/opt/errbot/venv/bin/errbot --version

执行结果：

Errbot version 6.2.1

✅ 验证通过：离线安装结果与在线安装完全一致。

六、源码包安装方案（C：PyPI sdist）

6.1 方案说明

需要审计源码、打私有补丁或定制安装时使用源码安装。Errbot 在 PyPI 提供 sdist 源码包 errbot-6.2.1.tar.gz（约 176KB），pip 可直接从源码包构建安装。与方案 B 的区别：方案 B 离线安装的是预构建 wheel，本方案是现场编译（纯 Python 项目，"编译"仅为打包过程，无需 gcc）。

6.2 下载源码包

执行命令：

mkdir -p /opt/errbot/src
pip3 download --no-deps --no-binary :all: errbot==6.2.1 -d /opt/errbot/src
ls -lh /opt/errbot/src

执行结果：

Saved ./opt/errbot/src/errbot-6.2.1.tar.gz
Successfully downloaded errbot
-rw-r--r-- 1 root root 176K Oct 25 06:10 /opt/errbot/src/errbot-6.2.1.tar.gz

💡 命令解释：--no-deps 只下载 errbot 本体（依赖仍由 pip 正常解析安装），--no-binary :all: 强制选择 sdist 源码包而非 wheel。

6.3 从源码包安装

执行命令：

mkdir -p /opt/errbot
python3 -m venv /opt/errbot/venv
/opt/errbot/venv/bin/pip install /opt/errbot/src/errbot-6.2.1.tar.gz

执行结果：

  Running setup.py install for errbot: finished with status 'done'
Successfully installed Pygments-2.20.0 WebOb-1.8.11 ansi-0.3.7 beautifulsoup4-4.15.0 blinker-1.9.0 certifi-2026.10.23 cffi-2.1.1 charset_normalizer-3.5.2 click-8.5.0 colorlog-6.10.1 cryptography-47.0.0 daemonize-2.5.0 deepmerge-2.0 dulwich-1.2.1 errbot-6.2.1 flask-3.1.3 idna-3.20 itsdangerous-2.2.0 jinja2-3.1.6 markdown-3.10.2 markupsafe-3.0.4 pyOpenSSL-26.1.0 pycparser-3.11 pygments-markdown-lexer-0.1.0.dev39 requests-2.32.5 setuptools-84.2.1 soupsieve-2.10 typing_extensions-4.16.0 urllib3-2.8.0 waitress-3.0.2 webtest-3.0.7 werkzeug-3.1.9

💡 说明：源码安装需要联网解析依赖（依赖仍走 PyPI）；如需完全离线，可将本方案与方案 B 组合——先用 --no-index --find-links 装依赖，再装源码包。回显中 Running setup.py install for errbot 即源码构建过程。

6.4 验证安装

执行命令：

/opt/errbot/venv/bin/errbot --version

执行结果：

Errbot version 6.2.1

✅ 验证通过：源码安装与 wheel 安装产物一致。

七、方案对比与选择建议

对比项方案 A：pip 在线方案 B：离线包方案 C：源码包
网络要求目标机可访问 PyPI仅需一台联网下载机装本体可离线，依赖仍需联网（或与 B 组合）
安装速度快（全部 wheel）快（本地 wheel 为主）略慢（本体现场构建）
依赖隔离venv 隔离venv 隔离venv 隔离
适用场景绝大多数服务器内网/断网/安全隔离区源码审计、打补丁、定制
关键限制无下载机与目标机平台/Python 版本必须一致需联网装依赖

💡 选型建议：能联网就用方案 A；内网环境用方案 B（注意平台一致性）；仅当需要修改源码时用方案 C。三种方案最终得到的 errbot 命令与运行行为完全一致，后续章节通用。

八、基础配置（config.py）

8.1 初始化机器人工作目录

Errbot 的所有运行时状态（配置、数据、插件、日志）都集中在一个工作目录中，用 --init 初始化：

执行命令：

mkdir -p /opt/errbot/bot
/opt/errbot/venv/bin/errbot --init /opt/errbot/bot
ls /opt/errbot/bot

执行结果：

Your Errbot directory has been correctly initialized!
Just do "cd /opt/errbot/bot" then "errbot" and it should start in text/development mode.
backend-plugins
config.py
data
plugins

⚠️ 注意：目标目录必须提前创建。若直接对不存在的目录执行 errbot --init /opt/errbot/bot，会报错 Target directory /opt/errbot/bot must exist. Please create it.（见十三、常见问题 Q1）。

生成的目录结构说明：

路径作用
config.py主配置文件（Python 语法）
data/机器人数据目录（各插件的 Shelf 持久化文件、插件仓库克隆）
plugins/本地插件开发目录（BOT_EXTRA_PLUGIN_DIR）
backend-plugins/第三方后端插件目录（BOT_EXTRA_BACKEND_DIR）

8.2 初始配置文件解读

--init 生成的 /opt/errbot/bot/config.py 全文如下（实测）：

import logging

# This is a minimal configuration to get you started with the Text mode.
# If you want to connect Errbot to chat services, checkout
# the options in the more complete config-template.py from here:
# https://raw.githubusercontent.com/errbotio/errbot/master/errbot/config-template.py

BACKEND = "Text"  # Errbot will start in text mode (console only mode) and will answer commands from there.

BOT_DATA_DIR = r"/opt/errbot/bot/data"
BOT_EXTRA_PLUGIN_DIR = r"/opt/errbot/bot/plugins"
BOT_EXTRA_BACKEND_DIR = r"/opt/errbot/bot/backend-plugins"

BOT_LOG_FILE = r"/opt/errbot/bot/errbot.log"
BOT_LOG_LEVEL = logging.INFO

BOT_ADMINS = (
    "@CHANGE_ME",
)  # Don't leave this as "@CHANGE_ME" if you connect your errbot to a chat system!!

逐项说明：

  • BACKEND = "Text"：使用文本控制台后端，启动后直接在终端与机器人对话，用于本地开发与调试。
  • BOT_DATA_DIR：数据目录，存放各插件的持久化数据（data/*.db）与 !repos install 克隆的插件仓库（data/plugins/）。
  • BOT_EXTRA_PLUGIN_DIR / BOT_EXTRA_BACKEND_DIR：本地插件/后端开发目录。
  • BOT_LOG_FILE / BOT_LOG_LEVEL：日志文件路径与级别。
  • BOT_ADMINS：机器人管理员列表，接入真实聊天系统前必须改掉 @CHANGE_ME。Text 后端下默认身份即 @CHANGE_ME（属管理员）。

💡 技术拓展：Errbot 的「后端（Backend）」是聊天协议适配层，同一套机器人逻辑可跑在不同聊天平台上。常见后端对比——

后端类型安装方式适用场景
Text内置自带本地调试、插件开发
Test内置自带单元测试（pytest 插件测试）
Null内置自带仅跑 webhook/定时任务，不聊天
Slack（SlackV3）官方扩展pip install "errbot[slack]"Slack 团队
IRC内置自带（依赖 irc 包）传统 IRC 频道
Telegram官方扩展pip install "errbot[telegram]"Telegram 群组
XMPP内置自带（依赖 slixmpp）XMPP/Jabber
Discord / Mattermost官方扩展errbot[discord] / errbot[mattermost]对应平台

本文以 Text 后端完成安装验证（无需任何外部账号），接入真实聊天平台时按上表安装对应 extras 并修改 BACKEND 与 BOT_IDENTITY（见十、安装聊天后端扩展）。

九、首次启动与功能验证（Text 后端）

9.1 启动机器人

在机器人工作目录中直接运行 errbot（默认读取当前目录的 config.py）：

执行命令：

cd /opt/errbot/bot
/opt/errbot/venv/bin/errbot

执行结果（输出节选，实测首尾）：

2026-10-25 05:50:47,178 INFO     errbot.bootstrap          Found Storage plugin: Shelf.
2026-10-25 05:50:47,190 INFO     errbot.bootstrap          Found Backend plugin: Text
2026-10-25 05:50:48,825 INFO     errbot                    webhooks: Flag to bind /echo to echo
────────────────────────────────────────────────────────────────────────────────
 You start as a bot admin in a one-on-one conversation with the bot.

    Context of the chat

• Use !inroom to switch to a room conversation.
• Use !inperson to switch back to a one-on-one conversation.
• Use !asuser to talk as a normal user.
• Use !asadmin to switch back as a bot admin.

    Preferences

• Use !ml to flip on/off the multiline mode (Enter twice at the end to send).
────────────────────────────────────────────────────────────────────────────────

[@CHANGE_ME ➡ @errbot] >>>

💡 说明：启动日志依次显示加载了 Shelf 存储插件与 Text 后端、Webserver 插件注册了 /echo webhook 路由；随后的横幅提示 Text 模式的会话切换命令。[@CHANGE_ME ➡ @errbot] >>> 为交互提示符，直接输入以 ! 开头的命令即可与机器人对话。

9.2 内置命令交互验证

在提示符下依次输入以下命令（实测逐条回显）：

输入：

!about

回显（节选）：

This is Errbot version 6.2.1
• Visit http://errbot.io/ for more information about errbot in general.
• Visit http://errbot.io/en/latest/#user-guide for help with configuration,
  administration and plugin development.

输入：

!whoami

回显：

┏━━━━━━━━━━┳━━━━━━━━━━━┓
┃ key      ┃ value     ┃
┡━━━━━━━━━━╇━━━━━━━━━━━┩
│ person   │ CHANGE_ME │
├──────────┼───────────┤
│ nick     │ None      │
├──────────┼───────────┤
│ fullname │ None      │
├──────────┼───────────┤
│ client   │ None      │
├──────────┼───────────┤
│ email    │ ``        │
└──────────┴───────────┘
• string representation is '@CHANGE_ME'
• class is 'TextPerson'

输入：

!echo hello errbot

回显：

hello errbot

输入：

!status plugins

回显：

Plugins

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Name                  ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ A │ ACLs                  │
├────────┼───────────────────────┤
│ A │ Backup                │
├────────┼───────────────────────┤
│ A │ ChatRoom              │
├────────┼───────────────────────┤
│ A │ CommandNotFoundFilter │
├────────┼───────────────────────┤
│ A │ Example               │
├────────┼───────────────────────┤
│ A │ Flows                 │
├────────┼───────────────────────┤
│ A │ Health                │
├────────┼───────────────────────┤
│ A │ Help                  │
├────────┼───────────────────────┤
│ A │ Plugins               │
├────────┼───────────────────────┤
│ A │ TextCmds              │
├────────┼───────────────────────┤
│ A │ Utils                 │
├────────┼───────────────────────┤
│ D │ VersionChecker        │
├────────┼───────────────────────┤
│ C │ Webserver             │
└────────┴───────────────────────┘
 A = Activated, D = Deactivated, B = Blacklisted, C = Needs to be configured

✅ 验证通过：!about 显示版本 6.2.1；!whoami 显示 Text 后端下当前身份为管理员 @CHANGE_ME；!echo 正常应答；!status plugins 列出 13 个内置核心插件，其中 11 个已激活（A），VersionChecker 默认停用（D），Webserver 待配置（C）。按 Ctrl+C 退出交互。

9.3 安装第三方插件（err-helloworld）

Errbot 通过 git 仓库分发插件，机器人内置 !repos install 命令在线安装。以官方示例插件 err-helloworld 为例（需可访问 GitHub）：

输入：

!repos install https://github.com/errbotio/err-helloworld.git

回显（输出节选，实测首尾）：

Installing https://github.com/errbotio/err-helloworld.git...
Enumerating objects: 39, done.
Receiving objects: 100% (39/39), 0.01 MiB | 0.00 MiB/s, done.
......
A new plugin repository has been installed correctly from https://github.com/errbotio/err-helloworld.git. Refreshing the plugins commands...
Plugins reloaded.

输入：

!hello

回显：

Hello World !

输入：

!repos

回显：

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Name                    ┃ Description                             ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ I │ errbotio/err-helloworld │ HelloWorld: let's say hello ! │
└────────┴─────────────────────────┴─────────────────────────────────────────┘

✅ 验证通过：插件经 git 克隆到 data/plugins/errbotio/err-helloworld/，加载后 !hello 命令立即可用（无需重启），!repos 列表中状态为 I（Installed）。

9.4 配置并验证 Webserver（webhook）

Errbot 内置基于 Flask 的 Web 服务器插件，插件可通过 @webhook 装饰器暴露 HTTP 端点。核心插件自带一个 /echo 调试 webhook，配置后可直接验证：

输入：

!plugin config Webserver {'HOST': '0.0.0.0', 'PORT': 3141, 'SSL': None}

回显：

Plugin configuration done.

配置后 Webserver 状态由 C（待配置）变为 A（已激活），可用 !status plugins 复核。随后在另一个终端用 curl 验证 webhook：

执行命令：

curl -s -o /dev/null -w "%{http_code}\n" -X POST -d "hello webhook" http://127.0.0.1:3141/echo
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3141/

执行结果：

200
404

✅ 验证通过：POST /echo 返回 200（内置 echo webhook 只回 200 空体，用于联调探测）；根路径未注册路由返回 404，说明 Web 服务器仅暴露插件注册的端点。SSL: None 表示不启用 TLS；生产环境如需 HTTPS 可在该配置中填入证书/私钥路径。

十、安装聊天后端扩展（接入 Slack/IRC 等）

Text 后端仅用于本地调试。接入真实聊天平台时，用 pip extras 安装对应后端依赖：

执行命令：

/opt/errbot/venv/bin/pip install "errbot[slack,irc]"

安装后在机器人目录执行 errbot -l 查看可用后端：

执行命令：

cd /opt/errbot/bot
/opt/errbot/venv/bin/errbot -l

执行结果：

Available backends:
		Test
		Text
		XMPP
		IRC
		Telegram
		Null
		SlackV3

💡 说明：安装 slack extras 后列表中多出 SlackV3。可用的 extras 与后端对应关系：slack→SlackV3、discord、mattermost、irc、telegram、xmpp。接入时把 config.py 的 BACKEND 改为对应名称并在 BOT_IDENTITY 中填入该平台凭据（如 Slack 的 token），同时把 BOT_ADMINS 改为平台上的管理员账号（如 "@admin"）。

十一、systemd 托管与守护进程

11.1 systemd 单元配置

接入真实聊天后端后，机器人需要常驻运行，用 systemd 托管。Errbot 自带 -d（守护进程）与 -p（pidfile）参数，按 forking 类型配置：

创建 /etc/systemd/system/errbot.service：

[Unit]
Description=Errbot ChatOps Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
WorkingDirectory=/opt/errbot/bot
ExecStart=/opt/errbot/venv/bin/errbot -d -p /opt/errbot/bot/errbot.pid
PIDFile=/opt/errbot/bot/errbot.pid
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

加载并启动：

systemctl daemon-reload
systemctl enable errbot
systemctl start errbot
systemctl is-active errbot

预期回显：

active

⚠️ 注意：

  1. systemd 托管要求操作系统以 systemd 为 init 的 Linux 真机（Ubuntu 22.04 默认满足）。
  2. -d 守护进程模式只适用于真实聊天后端（Slack/IRC 等）。Text 后端从 stdin 读取命令，后台运行时 stdin 立即 EOF，进程随即退出——实测 errbot -d -p /tmp/errbot.pid 返回码为 0，但 pidfile 随后被清理，日志出现 Disconnect callback, deactivating all the plugins. → Bye.。调试期请前台运行 errbot 或 errbot -T。
  3. 生产建议创建专用运行用户（如 useradd -r -s /usr/sbin/nologin errbot，并在单元中加 User=errbot），本文演示环境以 root 运行。

十二、升级、降级与多版本共存

12.1 升级到最新版

/opt/errbot/venv/bin/pip install -U errbot

12.2 降级到指定版本

执行命令：

/opt/errbot/venv/bin/pip install errbot==6.2.0
/opt/errbot/venv/bin/errbot --version

执行结果：

Successfully installed Pygments-2.16.1 ansi-0.3.6 colorlog-6.7.0 cryptography-41.0.7 deepmerge-1.1.0 dulwich-0.21.5 errbot-6.2.0 flask-2.3.3 jinja2-3.1.2 markdown-3.4.4 pyOpenSSL-23.2.0 requests-2.31.0 setuptools-68.1.2 webtest-3.0.0
Errbot version 6.2.0

💡 说明：pip 会自动把 errbot 及依赖切换到目标版本声明的配套版本（如 6.2.0 配套 dulwich 0.21.5、flask 2.3.3）。升降级只影响 venv 内的代码，/opt/errbot/bot 下的配置与数据不动；跨版本升降级后建议先在前台启动观察日志再恢复常驻。

再升回最新版：

执行命令：

/opt/errbot/venv/bin/pip install -U errbot
/opt/errbot/venv/bin/errbot --version

执行结果：

Successfully installed Pygments-2.20.0 ansi-0.3.7 colorlog-6.10.1 cryptography-47.0.0 deepmerge-2.0 dulwich-1.2.1 errbot-6.2.1 flask-3.1.3 jinja2-3.1.6 markdown-3.10.2 pyOpenSSL-26.1.0 requests-2.32.5 setuptools-84.2.1 webtest-3.0.7
Errbot version 6.2.1

12.3 多版本共存

需要同时保留多个版本时，为每个版本建独立虚拟环境（如 /opt/errbot/venv-6.1.9、/opt/errbot/venv-6.2.1`），机器人工作目录可共用也可分开（建议分开，避免数据文件跨版本读写）。通过不同 systemd 单元或不同端口区分实例。

十三、常见问题

Q1：errbot --init 报 "Target directory ... must exist"？

实测回显：

Target directory /opt/errbot/bot2 must exist. Please create it.
The initialization of your errbot directory failed: [Errno 2] No such file or directory: '/opt/errbot/bot2/data'.
Command failed with exit code 1

原因：--init 不会自动创建目标目录。解决：先 mkdir -p /opt/errbot/bot 再执行 --init。

Q2：执行 errbot -l 或启动时报找不到 config.py？

实测回显（在没有 config.py 的目录执行）：

I cannot find the config file //config.py.
You can change this path with the -c parameter see --help

原因：errbot 默认读取当前工作目录下的 config.py。解决：cd /opt/errbot/bot 后再执行，或用 -c /opt/errbot/bot/config.py 显式指定。

Q3：errbot -d 守护进程模式启动后立刻退出、pidfile 消失？

原因：当前配置是 Text 后端，它从 stdin 读命令，后台运行 stdin 立即 EOF，机器人判定断开连接而退出（日志含 Disconnect callback, deactivating all the plugins. → Bye.）。解决：daemon 模式仅在接入真实聊天后端（Slack/IRC 等）后使用；Text 调试期前台运行。

Q4：!repos install 报 Connection refused / Failed to establish a new connection？

实测回显（节选）：

Error installing the repo: Could not load this plugin: 
 https://github.com/errbotio/err-helloworld.git
HTTPSConnectionPool(host='github.com', port=443): Max retries exceeded with url: /errbotio/err-helloworld.git/info/refs?service=git-upload-pack (Caused by NewConnectionError("HTTPSConnection(host='github.com', port=443): Failed to establish a new connection: [Errno 111] Connection refused"))

原因：服务器无法直连 GitHub。解决：为运行 errbot 的用户配置 git 代理（errbot 底层经 git 协议克隆插件仓库），例如 git config --global http.proxy http://192.168.1.62:7897（替换为实际代理地址）；或在允许出网的机器上 git clone 后将仓库目录拷入 data/plugins/。

Q5：PyPI 下载慢？

为 pip 配置国内镜像：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple（对运行 errbot 的用户执行），或临时加 -i https://pypi.tuna.tsinghua.edu.cn/simple。

Q6：忘记加虚拟环境路径，直接运行 errbot 提示 command not found？

errbot 只安装在 /opt/errbot/venv/bin/ 下。每次写全路径较繁琐，可建软链：ln -s /opt/errbot/venv/bin/errbot /usr/local/bin/errbot，之后直接 errbot --version 即可。

十四、卸载清理

Errbot 全部内容集中在 venv 与机器人工作目录，卸载即删除目录：

执行命令：

# 停止服务（如已配置 systemd）
systemctl stop errbot 2>/dev/null; systemctl disable errbot 2>/dev/null
rm -f /etc/systemd/system/errbot.service && systemctl daemon-reload

# 删除软链、虚拟环境与机器人数据
rm -f /usr/local/bin/errbot
rm -rf /opt/errbot

⚠️ 注意：rm -rf /opt/errbot 会一并删除 bot/data/ 下的插件数据与 errbot.log 日志，卸载前如有需要请备份该目录。

十五、参考链接