Errbot 6.2.1 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 Errbot 聊天机器人，完成配置挂载、启动验证、数据持久化与日常运维。本文全部命令与回显已在 Docker 29.9.2 + Compose v5.6.1 环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Docker 版本：29.9.2
• Docker Compose 版本：v5.6.1
• 镜像：errbotio/errbot:6.2.1（镜像内 errbot 实为 6.2.0，见二、镜像选型说明）
• Compose 项目目录：/opt/errbot/compose
• 端口映射：宿主 8142 → 容器 3141（Webserver webhook）

二、镜像选型说明

Docker Hub 官方镜像仓库 errbotio/errbot（查询日期 2026-10-25：累计拉取 84669 次）可用标签：latest、6.2.1、6.2.0、6.1.9、6.1.8、6.1.7。

镜像关键事实（docker image inspect errbotio/errbot:6.2.1 实测）：

⚠️ 注意：errbotio/errbot:6.2.1 镜像内安装的 errbot 实际是 6.2.0（容器内执行 errbot --version 实测回显 Errbot version 6.2.0），镜像标签与包版本不一致是官方构建滞后的已知情况。生产如对补丁版本敏感，可基于该镜像 pip install -U errbot==6.2.1 自建镜像；功能层面 6.2.0 与 6.2.1 差异极小，本文按镜像现状实测。

💡 技术拓展：Errbot 容器化部署的镜像选择不止官方镜像一种——

镜像方案	特点	适用场景
errbotio/errbot 官方镜像	开箱即用、自带 Text 最小配置与 Slack 后端	快速上手、演示（本文方案）
python:3.x + pip install errbot 自建	版本完全可控、可装任意 extras	生产定制、固定补丁版本
distroless/精简基底自建	体积最小、攻击面小	安全敏感环境

本文采用官方 errbotio/errbot:6.2.1，理由是零构建、自带运行用户与入口，最适合快速验证。

三、前置条件

• Docker 与 Docker Compose 插件已安装并可用：

执行命令：

docker --version
docker compose version

执行结果：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

• 宿主可访问 Docker Hub 拉取镜像（离线环境请先 docker save/docker load 导入镜像）。
• 规划端口：本文将宿主 8142 映射到容器 3141（Webserver webhook 端口），如 8142 被占用可换任意空闲端口。

四、部署步骤

4.1 准备项目目录与配置文件

执行命令：

mkdir -p /opt/errbot/compose/home

创建 /opt/errbot/compose/home/config.py（机器人配置，将被挂载进容器作为 errbot 主配置）：

import logging

BACKEND = "Text"

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

BOT_LOG_FILE = r"/home/errbot/errbot.log"
BOT_LOG_LEVEL = logging.INFO

BOT_ADMINS = ("@admin",)

逐项说明：

• BACKEND = "Text"：控制台文本后端，容器启动后可通过 docker attach 直接对话，零外部依赖完成验证；接入真实聊天平台时改为 Slack/IRC 等并补 BOT_IDENTITY。
• BOT_DATA_DIR 等三个路径均指向 /home/errbot 下——该目录整体挂载到宿主，数据、插件、后端插件全部持久化。
• BOT_ADMINS = ("@admin",)：管理员列表，演示环境统一使用 admin；注意元组尾随逗号不能省。
• BOT_LOG_FILE：日志写到挂载目录内，宿主可直接查看。

4.2 处理挂载目录属主

镜像以 uid 1000 的 errbot 用户运行，宿主挂载目录必须归属 1000:1000，否则容器内写数据/日志会权限拒绝：

执行命令：

chown -R 1000:1000 /opt/errbot/compose/home

执行结果： 无输出即成功。

⚠️ 注意：这是本部署最容易踩的坑。漏掉这一步，容器启动后会因无法在 /home/errbot 写 data/、errbot.log 而报错退出。

4.3 编写 docker-compose.yml

创建 /opt/errbot/compose/docker-compose.yml：

name: errbot-6.2.1-stack
services:
  errbot:
    image: errbotio/errbot:6.2.1
    container_name: errbot-6.2.1-compose
    hostname: errbot.example.com
    stdin_open: true
    tty: true
    ports:
      - "8142:3141"
    volumes:
      - /opt/errbot/compose/home:/home/errbot
    restart: unless-stopped

逐项说明：

• stdin_open: true + tty: true：Text 后端必需——它从 stdin 读命令，没有 tty 时 stdin 立即 EOF，进程启动即退出（真实聊天后端可去掉）。
• ports：宿主 8142 → 容器 3141，供 Webserver 插件的 webhook 使用。
• volumes：整个 /home/errbot（errbot 工作目录）挂载到宿主，配置、数据、插件、日志一处持久化。
• restart: unless-stopped：异常退出自动拉起。

4.4 启动并验证

执行命令：

cd /opt/errbot/compose
docker compose up -d

执行结果：

 Network errbot-621-stack_default Created 
 Container errbot-6.2.1-compose Created 
 Container errbot-6.2.1-compose Starting 
 Container errbot-6.2.1-compose Started 

查看启动日志：

执行命令：

docker compose logs errbot | head -20

执行结果：

05:36:17 INFO     errbot.bootstrap          Found Storage plugin: Shelf.
05:36:17 INFO     errbot.bootstrap          Found Backend plugin: Text
05:36:17 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).

✅ 验证通过：Shelf 存储、Text 后端、webhook 路由均加载成功。

确认容器状态与端口：

执行命令：

docker compose ps

执行结果：

NAME                   IMAGE                   COMMAND                  SERVICE   CREATED          STATUS          PORTS
errbot-6.2.1-compose   errbotio/errbot:6.2.1   "/usr/local/bin/errb…"   errbot    9 seconds ago   Up 9 seconds   3142/tcp, 0.0.0.0:8142->3141/tcp, [::]:8142->3141/tcp

确认容器内版本与运行用户：

执行命令：

docker compose exec errbot errbot --version
docker compose exec errbot id

执行结果：

Errbot version 6.2.0
uid=1000(errbot) gid=1000(errbot) groups=1000(errbot)

💡 说明：容器内 errbot 为 6.2.0（镜像构建滞后，见二、镜像选型说明）；进程以 uid 1000 运行，再次印证挂载目录属主必须为 1000。

与机器人交互：执行 docker attach errbot-6.2.1-compose 即可进入 Text 会话，输入 !about、!echo hello 等命令（退出用 Ctrl+P Ctrl+Q，不要用 Ctrl+C，否则会把容器停掉）。

五、数据持久化说明

整个 /home/errbot 挂载到宿主 /opt/errbot/compose/home，持久化内容一览（实测）：

执行命令：

ls /opt/errbot/compose/home
ls /opt/errbot/compose/home/data

执行结果：

__pycache__
backend-plugins
config.py
data
errbot.log
plugins

ACLs.db
Backup.db
ChatRoom.db
CommandNotFoundFilter.db
Flows.db
Health.db
Help.db
Plugins.db
TextCmds.db
Utils.db
core.db
plugins
repomgr.db
text_backend.db

✅ 持久化验证：执行 docker compose down && docker compose up -d 后上述 .db 文件与日志原样保留，配置不丢。

六、环境变量表

errbot 本身以 config.py（Python 文件）为配置入口，官方镜像未定义专用环境变量；常用做法是通过 Compose 注入通用运行参数：

注入方式（在 services.errbot 下追加）：

    environment:
      - TZ=Asia/Shanghai

💡 说明：聊天平台凭据（Slack token 等）不属于环境变量注入范畴，应写入挂载的 config.py 的 BOT_IDENTITY 中。

七、配置参数说明

除 4.1 已列的基础项外，生产常用增补项（写入同一个 home/config.py）：

修改 config.py 后执行 docker compose restart errbot 生效。

八、配置文件挂载

本文采用「整个工作目录挂载」（/home/errbot），配置、数据、日志一处管理，是最省事的方式。若只想挂载配置文件而不挂载数据目录，可细粒度挂载：

    volumes:
      - /opt/errbot/compose/home/config.py:/home/errbot/config.py
      - errbot-data:/home/errbot/data

volumes:
  errbot-data:

⚠️ 注意：单文件挂载要求宿主机上的 config.py 已存在且属主为 1000:1000；named volume 首次初始化时 Docker 会把镜像内 /home/errbot/data 内容拷入，权限自动正确。两种挂载方式二选一，不要混用。

九、等价 docker run

不使用 Compose 时，与本文 Compose 配置等价的命令：

docker run -d \
  --name errbot-6.2.1-compose \
  --hostname errbot.example.com \
  -it \
  -p 8142:3141 \
  -v /opt/errbot/compose/home:/home/errbot \
  --restart unless-stopped \
  errbotio/errbot:6.2.1

💡 说明：-it 对应 Compose 的 stdin_open: true + tty: true（Text 后端必需）；-d 后台运行。生产管理仍推荐 Compose——配置即代码，重建/升级一条命令完成。

十、常用运维命令

查看实时日志：

docker compose logs -f errbot

优雅停止（SIGINT）/ 启动：

docker compose stop errbot
docker compose start errbot

修改配置后重启：

docker compose restart errbot

进入容器排障（另起 shell，不影响运行中的机器人）：

docker compose exec errbot bash

升级镜像（以 6.2.x 新标签为例）：

docker compose pull
docker compose up -d

查看资源占用：

docker stats errbot-6.2.1-compose --no-stream

备份数据（停机一致性备份）：

docker compose stop errbot
tar -czf /opt/errbot/errbot-backup-$(date +%F).tar.gz -C /opt/errbot/compose home
docker compose start errbot

十一、常见问题

Q1：容器启动后立即退出（docker compose ps 看不到进程）？

排查：docker compose logs errbot 若显示权限拒绝（无法在 /home/errbot 写文件），是漏了 chown -R 1000:1000；若日志正常显示 Text 横幅但进程退出，是 compose 文件缺 stdin_open: true/tty: true，Text 后端 stdin EOF 自杀（见 4.3）。两者修正后 docker compose up -d 即可。

Q2：docker attach 进去后怎么退出？

用 Ctrl+P 再 Ctrl+Q 脱离；直接 Ctrl+C 会把 SIGINT 传给 errbot 进程导致容器停止（镜像 StopSignal 就是 SIGINT，属优雅停机，但机器人会下线）。

Q3：docker compose exec errbot errbot --storage-get core 报 "Storage does not appear to have been opened yet"？

实测回显：

Storage does not appear to have been opened yet

原因：机器人运行期间存储被独占打开，exec 另起的 CLI 进程无法再打开同一存储。需要读写存储时先 docker compose stop errbot，再执行 docker compose run --rm errbot --storage-get core 之类的一次性命令（注意 run 会基于同配置另起临时容器）。

Q4：插件 !repos install 克隆失败（Connection refused）？

容器内访问 GitHub 需要出网代理：在 compose 文件 environment: 中加入 HTTPS_PROXY/HTTP_PROXY（见六、环境变量表），重启后重试。

Q5：8142 端口被占用？

改用其他空闲端口，如 "8143:3141"，执行 docker compose up -d 重建即可，容器内服务端口不变。

十二、参考链接

• errbotio/errbot Docker Hub：https://hub.docker.com/r/errbotio/errbot
• Errbot 官方文档：https://errbot.io/en/latest/
• Errbot GitHub 仓库：https://github.com/errbotio/errbot
• 宿主机安装（pip 三方案）见《Ubuntu 22.04 安装 Errbot 6.2.1 指南》