matrixdotorg/pantalaimon

Pantalaimon Docker镜像文档

镜像概述和主要用途

Pantalaimon是一个端到端加密感知的Matrix反向代理守护进程，充当中间人角色，为客户端透明处理消息的加密与解密。它允许不原生支持端到端加密的Matrix客户端通过代理方式安全通信，简化加密流程，主要用于需要处理Matrix加密消息的应用场景，如机器人、客户端代理等。

核心功能和特性

• 端到端加密支持：自动处理Matrix消息的加密与解密，无需客户端直接处理加密逻辑
• 透明代理：对客户端透明工作，客户端只需连接Pantalaimon代理，无需修改自身加密功能
• 多用户支持：支持同一 homeserver 上的多个用户，每个用户通过登录启动同步循环
• 灵活配置：通过配置文件自定义 homeserver 连接、监听地址端口、日志级别等参数
• 设备管理：提供panctl工具用于验证、黑名单或忽略设备，导入/导出会话密钥等
• 可选DBus UI：提供基于DBus的用户界面，用于控制守护进程（需额外安装）

使用场景和适用范围

• Matrix客户端代理：为不支持端到端加密的Matrix客户端提供加密能力
• 机器人集成：使Matrix机器人能够处理加密房间消息，无需自行实现加密逻辑
• 简化加密流程：降低客户端实现端到端加密的复杂度，统一加密处理逻辑
• 多用户环境：在需要为多个用户提供加密代理服务的场景中使用

使用方法和配置说明

前提条件

使用Pantalaimon Docker镜像前，需准备配置文件（pantalaimon.conf），指定homeserver连接信息、监听参数等。

配置文件说明

配置文件采用INI格式，包含默认配置段（[Default]）和每个homeserver的配置段（如[local-matrix]）。主要参数说明：

Docker部署示例

构建镜像

可直接从GitHub仓库构建镜像：

bash
docker build -t pantalaimon github.com/matrix-org/pantalaimon#master

或本地构建（需先克隆仓库）：

bash
git clone https://github.com/matrix-org/pantalaimon
cd pantalaimon
docker build -t pantalaimon .

运行容器

创建配置文件（示例pantalaimon.conf）：

conf
[Default]
LogLevel = Debug
SSL = True

[local-matrix]
Homeserver = https://matrix.org
ListenAddress = 0.0.0.0
ListenPort = 8008
SSL = False
UseKeyring = False
IgnoreVerification = True

运行容器，挂载配置文件目录和数据目录：

bash
docker run -it --rm \
  -v /path/to/your/config:/data \  # 包含pantalaimon.conf的目录
  -p 8008:8008 \                   # 映射监听端口
  pantalaimon

docker-compose配置示例

yaml
version: '3'
services:
  pantalaimon:
    build: github.com/matrix-org/pantalaimon#master
    volumes:
      - ./pantalaimon-config:/data  # 本地配置目录，包含pantalaimon.conf
    ports:
      - "8008:8008"
    restart: unless-stopped

客户端配置

运行容器后，将Matrix客户端的服务器地址配置为Pantalaimon代理地址（如http://localhost:8008），而非直接连接Matrix homeserver。登录后，Pantalaimon将自动处理加密消息的加密与解密。

设备管理

使用panctl工具管理设备（需进入容器执行）：

bash
docker exec -it <container_id> panctl

panctl支持的操作包括：验证设备、黑名单设备、忽略设备、导入/导出会话密钥等。详细使用方法可参考https://github.com/matrix-org/pantalaimon/blob/master/docs/man/panctl.1.md%E3%80%82