matrix-commander Docker镜像文档

镜像概述

matrix-commander Docker镜像是matrix-commander的官方容器化版本。matrix-commander是一个基于Python 3的命令行Matrix客户端，使用matrix-nio SDK开发，专注于提供简洁高效的命令行界面（CLI），无图形界面（GUI）。该镜像可快速部署，支持Matrix协议下的消息收发、文件传输、房间管理、设备验证等多种操作，适用于自动化脚本、机器人开发、系统监控等场景。

核心功能与特性

• 消息与媒体处理

  • 发送文本消息、图片、音频、视频及任意文件
  • 接收并下载各类媒体文件（自动解密）
  • 发送格式化消息（Markdown、代码块）及事件（表情反应、线程回复、消息编辑）

• 房间管理

  • 创建房间、邀请用户、列出房间及成员
  • 加入/离开/遗忘房间、禁言/解除禁言/踢出用户

• 设备与账户操作

  • 执行Matrix表情验证
  • 重命名设备、获取/设置显示名称及在线状态
  • 支持SSO登录、访问令牌认证

• 接收与通知

  • 持续监听或单次接收消息
  • 通过系统通知弹窗提醒新消息

• 灵活性与兼容性

  • 支持跳过SSL验证或使用本地SSL证书
  • 提供日志功能（多级别）、PID文件，可作为服务运行
  • 支持crontab定时执行，bash自动补全

• 轻量与集成

  • 基于Python 3，镜像体积小
  • 可通过shell（如bash）或Python程序调用
  • 直接从Docker Hub拉取，安装简单

使用场景

• 机器人开发：作为Matrix机器人核心组件，处理自动化消息响应
• 系统监控与警报：结合监控工具发送系统状态警报或错误通知
• 定时任务：通过crontab定时发送周期性数据（如日报、提醒）
• 终端消息收发：在命令行环境中直接收发消息，适合服务器管理场景
• 自动化脚本集成：嵌入shell/Python脚本，实现文件自动上传、房间批量管理
• 教育示例：展示matrix-nio SDK使用，作为Matrix客户端开发学***案例

使用方法

镜像获取

从Docker Hub拉取官方镜像：

docker pull matrixcommander/matrix-commander

基本使用示例

首次运行（初始化配置）

首次使用需初始化凭证（存储于挂载的数据目录）：

docker run -it --rm -v ./matrix-data:/data matrixcommander/matrix-commander \
  --login *** \
  --password your_password \
  --homeserver [***]

说明：-v ./matrix-data:/data 挂载本地目录存储凭证，后续运行无需重复登录

发送文本消息

向指定房间发送文本消息：

docker run --rm -v ./matrix-data:/data matrixcommander/matrix-commander \
  --message "Hello from Docker!" \
  --room "#myroom:example.com"

发送文件

发送本地图片文件（需挂载文件目录）：

docker run --rm -v ./matrix-data:/data -v ./local-files:/files matrixcommander/matrix-commander \
  --file /files/report.jpg \
  --room "#myroom:example.com"

监听消息

后台持续监听消息：

docker run -d --name matrix-listener -v ./matrix-data:/data matrixcommander/matrix-commander --listen

查看监听日志：

docker logs -f matrix-listener

关键参数说明

注意事项

• 首次运行需通过--login等参数完成初始化，凭证存储在挂载的/data目录，后续运行无需重复登录
• 发送文件时需将本地文件目录挂载到容器内（如-v ./local-files:/files），确保容器可访问文件
• 后台运行建议使用-d参数（守护进程模式）并指定容器名称（--name）以便管理
• 可通过--help查看所有参数：docker run --rm matrixcommander/matrix-commander --help