SimpleX Chat 7.0.4 Docker Compose 部署指南

用官方 smp-server 与 xftp-server 镜像（v7.0.1）单机部署 SimpleX Chat 自托管中继，含证书与指纹、服务器信息页、数据持久化、运维命令，并以 CLI 双端完成连接、消息与文件传输实测。

SimpleX ChatSimpleX Chat即时通讯端到端加密隐私安全2026/10/27

SimpleX Chat 7.0.4 Docker Compose 部署指南

目标：用官方 simplexchat/smp-server 与 simplexchat/xftp-server 镜像（服务端稳定版 v7.0.1）在一台服务器上完成 SimpleX Chat 中继 0→1 部署，覆盖证书与指纹、服务器信息页、数据持久化与常用运维命令，并以 CLI 双端实测连接、消息收发与文件传输。客户端侧的定位与选型见 《SimpleX Chat 7.0.4 介绍与选型指南》。

一、环境信息

项目内容
宿主操作系统Ubuntu 24.04.5 LTS（内核 7.0.0-38-generic）
Docker / ComposeDocker 29.9.2 / Docker Compose v5.6.1
部署根目录/opt/simplex-chat/
内网网段10.89.62.0/24（自定义 bridge，服务器固定 IP）
服务器地址（ADDR）smp 中继 10.89.62.10 / 文件中继 10.89.62.11
实测端口5223（SMP）、8141（信息页，容器内 8000）、8140（XFTP，容器内 443）
客户端SimpleX Chat CLI v7.0.4，两台内网终端（用户 alice / bob）

⚠️ 镜像版本口径：客户端 v7.0.4 与服务端镜像 v7.0.1 是两个发布线（服务端来自 simplex-chat/simplexmq 仓库），v7.0.1 为 Docker Hub 上 simplexchat/smp-server 与 simplexchat/xftp-server 的最新稳定标签（另有 v7.1.0-beta.x 预发布标签，本文不采用）。实测 v7.0.4 客户端与 v7.0.1 服务端互通正常。

二、镜像选型说明

SimpleX 官方在 Docker Hub 提供两个服务端镜像，均由仓库 simplex-chat/simplexmq 构建并随镜像自动完成初始化：

镜像用途实测标签镜像摘要（v7.0.1）
simplexchat/smp-server消息中继（队列暂存、转发）v7.0.1sha256:7d825822839a…af54
simplexchat/xftp-server大文件中继（分块暂存）v7.0.1sha256:69a7f95746bb…d26b

选型要点：

  • TLS 证书不需要申请：镜像首启自动生成自签 CA 与服务器证书，客户端按服务器地址中的证书指纹锁定校验，公网部署也无需 Let's Encrypt 与域名。
  • 两个镜像均为只读运行时 + bind mount 持久化，升级镜像不影响证书与队列数据。
  • 环境里对 Docker Hub 官方源拉取会长时间悬挂（daemon 配置的 daocloud mirror 返回"不在白名单"拒绝）。实测降级路径：docker pull hub.rat.dev/simplexchat/smp-server:v7.0.1 可拉取且与官方标签同摘要，拉取后 docker tag 重打官方标签即可，不影响后续步骤。

三、前置条件

  • 一台可被客户端访问的服务器（云主机或内网机器），已安装 Docker 与 Compose 插件。
  • 端口规划：5223/TCP 为 SMP 主端口；443/TCP 为 XFTP 主端口（本文宿主机 443 已被占用，实测映射到 8140）；8000/TCP 为可选的服务器信息页端口（本文映射到 8141）。
  • 放行防火墙：ufw allow 5223/tcp && ufw allow 8140/tcp && ufw allow 8141/tcp（公网部署按实际映射端口放行）。
  • 客户端侧准备：按《SimpleX Chat 7.0.4 介绍与选型指南》安装 CLI 客户端；本文用两台内网终端（alice、bob）做双端实测。

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/simplex-chat && cd /opt/simplex-chat
mkdir -p smp_configs smp_state xftp_configs xftp_state xftp_files

目录用途见"八、配置文件挂载与目录结构"。

4.2 编写 docker-compose.yml

/opt/simplex-chat/docker-compose.yml 完整内容（与实测一致）：

name: simplex-7.0.4-stack

services:
  smp-server:
    image: simplexchat/smp-server:v7.0.1
    environment:
      WEB_MANUAL: 1
      ADDR: 10.89.62.10
      PASS: q1w2e3r4
    volumes:
      - ./smp_configs:/etc/opt/simplex
      - ./smp_state:/var/opt/simplex
    ports:
      - 5223:5223
      - 8141:8000
    networks:
      simplex-7.0.4-net:
        ipv4_address: 10.89.62.10
    restart: unless-stopped

  xftp-server:
    image: simplexchat/xftp-server:v7.0.1
    environment:
      ADDR: 10.89.62.11
      QUOTA: 10gb
      PASS: q1w2e3r4
    volumes:
      - ./xftp_configs:/etc/opt/simplex-xftp
      - ./xftp_state:/var/opt/simplex-xftp
      - ./xftp_files:/srv/xftp
    ports:
      - 8140:443
    networks:
      simplex-7.0.4-net:
        ipv4_address: 10.89.62.11
    restart: unless-stopped

networks:
  simplex-7.0.4-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.62.0/24
          gateway: 10.89.62.1

参数说明：

  • ADDR：必填，客户端实际可达的地址（公网填公网 IP 或域名，本文内网实测填固定 IP）。smp 与 xftp 分别填各自对外地址。
  • PASS：可填，队列创建口令。填入后客户端只有在服务器地址中携带该口令才能创建新队列，防止服务器被陌生人占用（实测日志回显 creating new queues requires password）。
  • WEB_MANUAL: 1：smp 镜像手动模式，首启按单端口 5223 生成 INI（不写 https 证书行），并生成静态信息页文件。
  • QUOTA: 10gb：xftp 必填，文件存储配额，实测回显 Total / available storage: 10737418240 / 10737418240。
  • 端口映射：5223:5223 主端口直映射；宿主 443 已被占用，故 xftp 用 8140:443、信息页用 8141:8000（生产环境 443 空闲时建议直接 443:443）。

4.3 启动并观察首启日志

cd /opt/simplex-chat
docker compose up -d

实测回显：

 Container simplex-704-stack-smp-server-1 Created
 Container simplex-704-stack-xftp-server-1 Starting
 Container simplex-704-stack-smp-server-1 Starting
 Container simplex-704-stack-xftp-server-1 Started
 Container simplex-704-stack-smp-server-1 Started

首启时 entrypoint 会根据 ADDR/PASS 自动执行初始化并生成证书与 INI，随后拉起服务。docker compose logs smp-server 实测回显（节选）：

SMP server v7.0.1.0 /
Fingerprint: H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=
Server address: smp://H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=:q1w2e3r4@10.89.62.10
Server source code: https://github.com/simplex-chat/simplexmq
Store log: /var/opt/simplex/smp-server-store.log
Serving SMP protocol on port 5223 (TLS)...

WARNING: the clients will use port 443 by default soon.
Set `port` in smp-server.ini section [TRANSPORT] to `5223,443`

expiring messages after 21 days
expiring clients inactive for 21600 seconds every 3600 seconds
creating new queues requires password

docker compose logs xftp-server 实测回显（节选）：

XFTP server v7.0.1.0 /
Fingerprint: kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=
Server address: xftp://kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=@10.89.62.11
Store log: /var/opt/simplex-xftp/file-server-store.log
Serving XFTP protocol on port 443 (TLS)...
WARNING: server source code is not specified!
Use `source_code` in file-server.ini section [SERVER] to specify the server source code URL.
expiring files after 2 days
Total / available storage: 10737418240 / 10737418240

两段日志中的 Fingerprint 即客户端校验用的证书指纹，Server address 即服务器地址（smp 形式含创建队列口令）。

⚠️ xftp 首启会提示未设置 source_code（smp 镜像初始化参数已带 --source-code，xftp 未带）。消除方法：在 xftp_configs/file-server.ini 的 [SERVER] 段补一行 source_code: https://github.com/simplex-chat/simplexmq，重启后警告消失。

4.4 获取服务器地址与指纹

地址与指纹可直接在宿主机读取挂载目录中的指纹文件：

cat /opt/simplex-chat/smp_configs/fingerprint
cat /opt/simplex-chat/xftp_configs/fingerprint

实测回显：

H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=
kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=

据此得到两台中继的完整服务器地址（客户端配置用）：

smp://H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=:q1w2e3r4@10.89.62.10:5223
xftp://kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=:q1w2e3r4@10.89.62.11:443

⚠️ 指纹与证书绑定生成，删除 smp_configs/xftp_configs 重新初始化会更换指纹，已分发的服务器地址随之失效。

4.5 开启服务器信息页

WEB_MANUAL=1 首启只生成信息页静态文件，不启用内嵌 Web 服务。实测宿主机 curl http://127.0.0.1:8141/ 无响应。在 smp_configs/smp-server.ini 的 [WEB] 段把注释项放开为 http = 8000，然后重启：

docker compose restart smp-server
curl -s -o /dev/null -w "HTTP %{http_code}, %{size_download} bytes\n" http://127.0.0.1:8141/

实测回显：

HTTP 200, 46742 bytes

页面标题实测为 SimpleX Chat - Server Information，包含服务器指纹、地址与二维码，可直接发给用户。

4.6 客户端连接实测（双端）

在两台客户端终端分别执行（示例为 alice 端，bob 端同样先配置服务器）：

/smp smp://H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=:q1w2e3r4@10.89.62.10:5223
/xftp xftp://kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=:q1w2e3r4@10.89.62.11:443
/smp test smp://H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE=:q1w2e3r4@10.89.62.10:5223
/xftp test xftp://kL1aZsuHWIhaIW-lcBHG5lZM0On7nK_9vJQyMnqXEeU=:q1w2e3r4@10.89.62.11:443

实测回显依次为：

ok
ok
SMP server test passed
XFTP server test passed

alice 发起连接：

/connect

实测回显（节选）：

pass this invitation link to your contact (via another channel):
https://10.89.62.10/i#G-S3BF6ETOi6EzH8ClFnDsv2XcMaS8pg/2SlptdgZPKlfoNgsLxTCcM7F9vyH98NK9JW2nEk3-xs?p=5223&c=H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE
and ask them to connect: /c <invitation_link_above>

链接参数即自建服务器信息：10.89.62.10、端口 p=5223、证书指纹 c=H2Z_…。bob 接受邀请：

/connect https://10.89.62.10/i#G-S3BF6ETOi6EzH8ClFnDsv2XcMaS8pg/2SlptdgZPKlfoNgsLxTCcM7F9vyH98NK9JW2nEk3-xs?p=5223&c=H2Z_jKo6JIjojuUI3bD3p9XHgRlhS3e_fxV-2FcPWoE

bob 实测回显：

confirmation sent!
alice: contact is connected

alice 端同步收到 bob: contact is connected。随后双向发消息：alice 输入 @bob 你好，这是通过自建 smp-server 中继的消息，alice 终端回显 01:07 @bob 你好，这是通过自建 smp-server 中继的消息，bob 终端回显：

01:07 alice> 你好，这是通过自建 smp-server 中继的消息

bob 回复 @alice 收到，双向链路正常，alice 终端回显 01:08 bob> 收到，双向链路正常。

文件传输（走 xftp/直连文件通道）实测：alice 执行 /file @bob /tmp/b2-sample.bin（20 KiB 随机文件），bob 端回显：

01:10 alice> sends file b2-sample.bin (20.0 KiB / 20480 bytes)
use /fr 1 [<dir>/ | <path>] to receive it

bob 执行 /fr 1 /tmp/b2-recv.bin 接收后，双方回显：

completed uploading file 1 (b2-sample.bin) for bob        # alice 端
completed receiving file 1 (b2-sample.bin) from alice     # bob 端

两端文件 md5 均为 3a8f32b2cad892ccdb6971ff1011aa00，传输一致。说明：同网段场景下文件走客户端直连通道（xftp-server 容器日志无中继访问记录），xftp-server 在不可直连的公网场景承担文件中继，本文以 XFTP server test passed 与端口探测验证其可达性。

五、数据持久化说明

持久化全部通过 bind mount 落在部署目录（见第八节），其中 smp 队列与消息依赖 store log 机制：运行时写 smp-server-store.log，停机时自动滚动备份到 var/opt/simplex/backups/。实测 docker compose down && docker compose up -d 重建容器后，日志完整回显恢复过程：

Storelog backup successful: /var/opt/simplex/backups/queues/smp-server-store.log.2026-10-27T01:14:24
Messages backup successful: /var/opt/simplex/backups/messages/smp-server-messages.log.2026-10-27T01:14:24
...
restoring messages from file /var/opt/simplex/smp-server-messages.log
...
messages stored: 0, expired: 0, queues: 4

实测重建后 4 个既有队列（双端连接与文件通道）全部恢复，客户端无需重连配置。宿主机侧整机备份：

cd /opt/simplex-chat
tar czf /root/simplex-chat-backup-$(date +%Y%m%d).tar.gz smp_configs smp_state xftp_configs xftp_state xftp_files

恢复时解包回部署目录后 docker compose up -d 即可（证书指纹随 *_configs 恢复，服务器地址不变）。

六、环境变量表

变量适用镜像实测值说明
ADDR两者10.89.62.10 / 10.89.62.11必填。客户端可达地址；纯数字按 IP 处理（--ip），含点号按域名处理（--fqdn）。仅首启初始化时生效
PASS两者q1w2e3r4可选。队列/文件创建口令；留空则任何人可建队列（--no-password）
QUOTAxftp-server10gb必填。文件存储配额，实测写入 INI storage_quota: 10737418240
WEB_MANUALsmp-server1可选。手动模式：单端口 5223 生成 INI、不写 https 证书行、生成信息页静态文件
SIMPLEX_IMAGE两者—可选。覆盖 INI 中记录的镜像标签

⚠️ 环境变量只在 *_configs 中没有对应 INI 时（首启）参与初始化；之后的配置变更一律改 INI 文件再重启（详见《SimpleX Chat 7.0.4 配置参数详解》）。要重新生成全部证书与 INI，可停服后清空 smp_configs、xftp_configs 再 up -d（注意指纹会变更）。

七、配置参数说明

首启自动生成两份 INI，核心段位实测值：

文件段参数实测值/默认说明
smp-server.iniTRANSPORThost10.89.62.10对外地址，来自 ADDR
smp-server.iniTRANSPORTport5223SMP 监听端口；官方日志提示未来客户端默认尝试 443，可设 5223,443
smp-server.iniTRANSPORTcontrol_port注释（默认 5224）管理控制端口，启用后可远程查看状态、清理异常队列
smp-server.iniAUTHnew_queueson是否允许新建队列
smp-server.iniAUTHcreate_passwordq1w2e3r4建队口令，来自 PASS
smp-server.iniEXPIRATIONexpire_messages_days21队列内未取消息过期天数
smp-server.iniINACTIVE_CLIENTSdisconnect21600空闲断开秒数，实测日志 expiring clients inactive for 21600 seconds
smp-server.iniSTORE_LOGenableon队列 store log，持久化与恢复依赖此项
smp-server.iniWEBstatic_path/var/opt/simplex/www信息页静态文件目录
smp-server.iniWEBhttp8000（默认注释）信息页内嵌服务端口，见 4.5 节
file-server.iniTRANSPORTport443XFTP 监听端口
file-server.iniAUTHcreate_passwordq1w2e3r4建文件口令
file-server.iniEXPIRATIONexpire_files_hours48文件分块过期时间，实测日志 expiring files after 2 days
file-server.iniSTORAGEquota10737418240配额字节数，来自 QUOTA=10gb
file-server.iniSTORAGEpath/srv/xftp文件分块存储目录

逐项修改-验证方法与全量参数逐条解释见《SimpleX Chat 7.0.4 配置参数详解》。

八、配置文件挂载与目录结构

实测部署目录结构（tree -L 2 形态整理）：

/opt/simplex-chat/
├── docker-compose.yml
├── smp_configs/            → 容器内 /etc/opt/simplex（证书 + INI）
│   ├── ca.crt  ca.key  ca.srl
│   ├── server.crt  server.csr  server.key
│   ├── openssl_ca.conf  openssl_server.conf
│   ├── fingerprint
│   └── smp-server.ini
├── smp_state/              → 容器内 /var/opt/simplex（运行数据）
│   ├── smp-server-store.log  smp-server-messages.log
│   ├── smp-server-stats.daily.log
│   ├── backups/{queues,messages,stats}/
│   └── www/
├── xftp_configs/           → 容器内 /etc/opt/simplex-xftp
│   ├── ca.crt  ca.key  server.crt  server.key
│   ├── fingerprint
│   └── file-server.ini
├── xftp_state/             → 容器内 /var/opt/simplex-xftp
│   ├── file-server-store.log
│   └── backups/
└── xftp_files/             → 容器内 /srv/xftp（文件分块）

四个目录都建议纳入备份；smp_configs/xftp_configs 丢失等于丢失服务器身份（指纹变更）。

九、等价 docker run 命令

不使用 Compose 时，以下两条与本文实测等价（先建同名 bridge 网络与目录）：

docker network create --subnet 10.89.62.0/24 --gateway 10.89.62.1 simplex-7.0.4-net

docker run -d --name smp-server \
  --network simplex-7.0.4-net --ip 10.89.62.10 \
  -e WEB_MANUAL=1 -e ADDR=10.89.62.10 -e PASS=q1w2e3r4 \
  -v /opt/simplex-chat/smp_configs:/etc/opt/simplex \
  -v /opt/simplex-chat/smp_state:/var/opt/simplex \
  -p 5223:5223 -p 8141:8000 \
  --restart unless-stopped \
  simplexchat/smp-server:v7.0.1

docker run -d --name xftp-server \
  --network simplex-7.0.4-net --ip 10.89.62.11 \
  -e ADDR=10.89.62.11 -e QUOTA=10gb -e PASS=q1w2e3r4 \
  -v /opt/simplex-chat/xftp_configs:/etc/opt/simplex-xftp \
  -v /opt/simplex-chat/xftp_state:/var/opt/simplex-xftp \
  -v /opt/simplex-chat/xftp_files:/srv/xftp \
  -p 8140:443 \
  --restart unless-stopped \
  simplexchat/xftp-server:v7.0.1

十、常用运维命令

在部署目录内执行：

docker compose ps                          # 实例状态与端口映射
docker compose logs -f smp-server          # 跟踪 SMP 日志
docker compose restart smp-server          # 修改 INI 后生效
docker compose down && docker compose up -d   # 完整重建（数据持久化验证见第五节）

实测 docker compose ps 回显（表格形态）：

NAME                            IMAGE                           STATUS         PORTS
simplex-704-stack-smp-server-1  simplexchat/smp-server:v7.0.1   Up 7 minutes   443/tcp, 0.0.0.0:5223->5223/tcp, 0.0.0.0:8141->8000/tcp
simplex-704-stack-xftp-server-1 simplexchat/xftp-server:v7.0.1  Up 9 minutes   0.0.0.0:8140->443/tcp

端口与证书自检（在任意客户端机器执行，验证服务与指纹一致）：

echo | openssl s_client -connect 10.89.62.10:5223 2>/dev/null | grep subject=
echo | openssl s_client -connect 10.89.62.11:8140 2>/dev/null | grep subject=

实测回显：

subject=CN = 10.89.62.10
subject=CN = 10.89.62.11

存储水位观察：xftp 启动与过期巡检日志会输出 Total / available storage 与 Used 0mb -> 0mb, 0mb reclaimed.，配额写满将拒绝新文件上传。

十一、常见问题（FAQ）

Q1：客户端 /smp test 报连接失败？ 按序检查：客户端地址是否带了正确端口与指纹（smp://指纹:口令@地址:5223）；服务器防火墙是否放行 5223；docker compose logs smp-server 是否有 Serving SMP protocol on port 5223 (TLS)...。

Q2：为什么日志里有 WARNING: the clients will use port 443 by default soon.？ 官方预告未来客户端将默认尝试 443 端口。生产环境建议把 smp-server.ini 的 [TRANSPORT] port 设为 5223,443 并放行两个端口；本文实测环境宿主 443 被占用，保留单端口 5223（客户端地址已显式带端口，不影响连接）。

Q3：建不了队列，报"creating new queues requires password"？ 服务器设置了 PASS，客户端服务器地址必须携带口令段（smp://指纹:口令@地址:端口），口令错误或缺失时无法在该服务器创建新队列。

Q4：文件传输走了 xftp-server 吗？ 客户端之间能直连时优先走直连（本文同网段实测即直连，xftp 容器无访问记录）；不可直连时自动经 xftp-server 中继，文件分块默认 48 小时过期。服务端可用 /xftp test <地址> 预验证可达性。

Q5：重建容器后客户端要重新添加服务器吗？ 不需要。证书与指纹在 smp_configs/xftp_configs 中持久化，队列由 store log 恢复（实测 queues: 4）。只有清空 configs 重新初始化才会换指纹，需要重新分发服务器地址。

Q6：Docker Hub 拉镜像很慢或悬挂？ 见第二节镜像选型说明：官方源悬挂时可用 hub.rat.dev/simplexchat/smp-server:v7.0.1 等镜像源拉取后重打官方标签，注意核对镜像摘要一致。

十二、参考链接