matrix-sms-bridge 镜像文档

镜像概述

matrix-sms-bridge 是一个 Matrix 协议桥接器，专门用于实现 Matrix 房间与 SMS 消息系统之间的双向通信。该镜像的核心功能是通过单个电话号码，将 Matrix 房间内的消息转发至 SMS 网络，同时将接收到的 SMS 消息同步至指定的 Matrix 房间，实现跨平台消息互通。

核心功能与特性

• 单号码桥接：仅支持配置单个电话号码进行 SMS 通信
• 双向消息同步：Matrix 房间消息可转发至 SMS 接收方，同时接收的 SMS 消息可同步至 Matrix 房间
• Matrix 协议兼容：遵循 Matrix 客户端协议，可与标准 Matrix 家庭服务器（如 Synapse）配合使用
• 轻量化部署：基于 Docker 容器化设计，便于快速部署和管理

使用场景

• 个人用户通过 Matrix 客户端集中管理 SMS 消息，实现多设备消息同步
• 小型团队将 SMS 通知（如验证码、告警信息）聚合至 Matrix 房间进行协作处理
• 需要将 Matrix 生态系统与传统 SMS 网络打通的集成场景

使用方法

前置条件

• 已部署 Matrix 家庭服务器（如 Synapse）并拥有可登录的 Matrix 账号
• 拥有可用于发送/接收 SMS 的电话号码及相应的调制解调器或 SMS 服务提供商配置

Docker Run 示例

docker run -d \
  --name matrix-sms-bridge \
  -e MATRIX_HOMESERVER=[***] \
  -e MATRIX_USER_ID=@sms-bridge:example.com \
  -e MATRIX_ACCESS_TOKEN=your-matrix-access-token \
  -e SMS_PHONE_NUMBER=+1234567890 \
  -e SMS_MODEM_PATH=/dev/ttyUSB0 \
  -v /path/to/local/modem:/dev/ttyUSB0 \
  benkuly/matrix-sms-bridge

Docker Compose 配置示例

version: '3'
services:
  matrix-sms-bridge:
    image: benkuly/matrix-sms-bridge
    container_name: matrix-sms-bridge
    restart: unless-stopped
    environment:
      - MATRIX_HOMESERVER=[***]
      - MATRIX_USER_ID=@sms-bridge:example.com
      - MATRIX_ACCESS_TOKEN=your-matrix-access-token
      - SMS_PHONE_NUMBER=+1234567890
      - SMS_MODEM_PATH=/dev/ttyUSB0
      - LOG_LEVEL=info
    volumes:
      - /path/to/local/modem:/dev/ttyUSB0
    network_mode: bridge

配置参数说明

环境变量

设备挂载

若使用物理调制解调器，需将宿主机的调制解调器设备路径（如 /dev/ttyUSB0）挂载至容器内，确保桥接器可访问调制解调器硬件。

房间配置

1. 启动容器后，通过 Matrix 客户端邀请桥接器用户（MATRIX_USER_ID）加入目标房间
2. 在房间内发送命令（如 !sms bridge）激活桥接功能
3. 桥接器将自动将房间内消息转发至 SMS_PHONE_NUMBER 对应的 SMS 接收方，并将接收到的 SMS 消息同步至该房间

注意事项

• 仅支持单个电话号码，无法同时桥接多个 SMS 号码
• SMS 功能依赖调制解调器或 SMS API 服务，需确保相关硬件/服务已正确配置
• 请妥善保管 Matrix 访问令牌及电话号码信息，避免信息泄露
• 桥接器需持续运行以确保消息实时同步，建议配置容器自动重启策略