SimpleX Chat 7.0.4 常用 CLI 命令详解

目标：按"连接 → 消息 → 文件 → 群组 → 服务端运维"主线整理 SimpleX Chat CLI v7.0.4 终端命令矩阵，全部命令给出 alice/bob 双端实测回显，并覆盖 smp-server / xftp-server 的服务端运维命令与控制端口会话。部署与参数配置见《SimpleX Chat 7.0.4 Docker Compose 部署指南》《SimpleX Chat 7.0.4 配置参数详解》。

一、环境信息

项目	内容
服务端系统	Ubuntu 22.04（systemd 管理 smp-server.service / xftp-server.service）
服务端程序	smp-server v7.0.1.0（构建 27a3738）、xftp-server v7.0.1.0
实测中继	消息/群组/文件命令经 10.89.62.10:5223（见部署指南）；连通性与服务端运维在 10.89.61.10:5223（systemd 实例，地址 smp://ml_GdNzOiCaM7rsJfxrAy6H_4-PFLOja4TqewPF3r8o=:0eqByp3FaLF8Kq7Wp69-74-l2cUJ0p8H1nca_8gqNZ8=@10.89.61.10:5223）
客户端	SimpleX Chat CLI v7.0.4，两台内网终端（用户 alice / bob，独立数据库）
实测范围	客户端命令在双端终端完成；服务端命令在服务器本机完成

客户端二进制以发布 tag v7.0.4 发布（内部版本串自报 SimpleX Chat v7.0.0.12，同一发布件，/version 回显见 3.3 节）。

二、命令总览

终端内输入 /help 可随时调出命令卡（实测回显节选）：

Other commands:
        /help <topic>     - help on: groups, contacts, messages, files, address, incognito, remote, settings, db
        /profile          - show / update user profile
        /delete <contact> - delete contact and all messages with them
        /chats            - most recent chats
        /markdown         - supported markdown syntax
        /version          - SimpleX Chat version
        /quit             - quit chat

The commands may be abbreviated: /c, /f, /g, /p, /ad, etc.

分类	命令（缩写）	用途	实测
连接	/smp、/xftp（无缩写）	配置/测试中继服务器	双端 ✓
连接	/connect（/c）	发起/接受单聊连接	双端 ✓
信息	/profile（/p）、/contacts、/chats、/version、/help	档案与列表	✓
消息	@<contact> <msg>、#<group> <msg>	单聊/群聊消息	双端 ✓
文件	/file（/f）、/freceive（/fr）、/fcancel（/fc）、/fstatus（/fs）、/image（/img）、/fforward（/ff）	文件收发与转发	/file、/fr 全闭环 ✓
群组	/group（/g）、/add（/a）、/join（/j）、/members、/remove、/leave	群组生命周期	全闭环 ✓
服务端	smp-server/xftp-server 子命令、systemctl、journalctl、控制端口	部署与运维	全部 ✓

三、连接管理命令

3.1 /smp 与 /xftp：配置并测试中继

/smp smp://ml_GdNzOiCaM7rsJfxrAy6H_4-PFLOja4TqewPF3r8o=:0eqByp3FaLF8Kq7Wp69-74-l2cUJ0p8H1nca_8gqNZ8=@10.89.61.10:5223

实测回显：

ok

连通性与建队能力测试：

/smp test smp://ml_GdNzOiCaM7rsJfxrAy6H_4-PFLOja4TqewPF3r8o=:0eqByp3FaLF8Kq7Wp69-74-l2cUJ0p8H1nca_8gqNZ8=@10.89.61.10:5223

实测回显（正常）：

SMP server test passed

/xftp 与 /xftp test 同构，实测回显 ok 与 XFTP server test passed。地址格式为 smp://指纹:建队口令@主机:端口，口令仅用于在该服务器创建新队列。

⚠️ 修改 /smp 列表会即时重连既有连接，实测回显：

disconnected 1 connections on server 10.89.62.10
subscribed 1 connections on server 10.89.62.10

3.2 /connect：发起与接受连接

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>

链接中的 p=5223 与 c=指纹 即队列所在服务器的端口与证书指纹。bob 接受：

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

实测回显：

confirmation sent!
alice: contact is connected

alice 端同步回显 bob: contact is connected，单聊连接建立。

3.3 档案与列表命令

命令	实测回显
/profile	`user profile: alice` + `use /p <name> [<bio>] to change it`
/contacts	`bob`
/version	`SimpleX Chat v7.0.0.12`
/chats	最近会话列表（单聊、群聊预览与最后一条消息）
/help groups、/help files	分主题子命令卡（见五、六节）

四、消息命令

单聊双向（alice → bob）：

@bob 你好，这是通过自建 smp-server 中继的消息

alice 终端回显：

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

bob 终端回显：

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

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

⚠️ 命令拼写错误时的报错形式（实测把发文件误输成 /send，v7.0.4 无此命令）：

bad chat command: Failed reading: empty

正确命令是 /file（见第五节）。

五、文件命令

发送（alice → bob，实测 20 KiB 文件）：

/file @bob /tmp/b2-sample.bin

alice 端回显：

01:10 /f @bob /tmp/b2-sample.bin
use /fc 1 to cancel sending

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，内容一致。

/help files 其余子命令（--help 口径，缩写 /img、/ff、/fc、/fs）：

命令	用途
/file #<group> <file_path>	发文件到群组
/image <name> [<file_path>]	以图片形式发送
/freceive <file_id> [<file_path>]	接收文件
/fforward <name> [<file_id>]	转发已收文件
/fcancel <file_id>	取消收发
/fstatus <file_id>	查询传输状态
/imgf @<contact>\|#<group> <file_id>	转发已收图片

六、群组命令

6.1 建群与邀请（alice 端）

/group dev-team 自建中继实测小组

实测回显：

group #dev-team (自建中继实测小组) is created

邀请 bob：

/add dev-team @bob

实测回显：

invitation to join the group #dev-team sent to bob

6.2 入群（bob 端）

bob 收到（实测回显）：

#dev-team (自建中继实测小组): alice invites you to join the group as member
use /j dev-team to accept

接受：

/join dev-team

实测回显：

#dev-team: you joined the group

6.3 群消息与成员管理

alice 发群消息 #dev-team 大家好，群组链路测试，bob 回显：

01:39 #dev-team alice> 大家好，群组链路测试

bob 回复 #dev-team 群消息双向正常，alice 回显：

01:39 #dev-team bob> 群消息双向正常

成员与角色：

/members dev-team

实测回显：

alice: owner, you, created group
bob: member, invited, connected

/help groups 其余子命令（帮助口径，缩写 /a、/j、/rm、/l、/d、/ms、/gs）：

命令	用途
/add <group> <contact> [<role>]	加人，角色 owner/admin/member
/remove <group> <member>、/leave <group>	移除成员/退群
/gp <group> [<name> [<description>]]	查看/更新群档案
/create link #<group> [role]	创建公开入群链接
/show link #<group>、/delete link #<group>	查看/删除入群链接
/set voice\|files\|history\|delete\|direct #<group> on/off	群聊天偏好开关
/set disappear #<group> on <time>	阅后即焚（30s～month）
/mute #<group>、/unmute #<group>	免打扰
/code、/verify #<group> <member>	成员安全码核对
/switch #<group> <member>	把成员收消息切换到另一 SMP 中继

七、服务端运维命令

7.1 systemd 与日志

systemctl status smp-server --no-pager
journalctl -u smp-server --since "1 min ago" --no-pager -o cat
systemctl restart smp-server

实测 systemctl status 回显（节选）：

● smp-server.service - SMP server
     Loaded: loaded (/etc/systemd/system/smp-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 01:34:07 UTC; 6min ago
   Main PID: 4252 (smp-server)
      Tasks: 6 (limit: 3172)
     Memory: 9.6M

7.2 smp-server 子命令

$ smp-server --help
SMP server v7.0.1.0 / 27a3738

Usage: smp-server [-v|--version] COMMAND

Available commands:
  init                     Initialize server - creates /etc/opt/simplex and
                           /var/opt/simplex directories and configuration files
  cert                     Generate new online TLS server credentials
                           (configuration: /etc/opt/simplex/smp-server.ini)
  start                    Start server (configuration:
                           /etc/opt/simplex/smp-server.ini)
  delete                   Delete configuration and log files
  journal                  Import/export messages to/from journal storage
  database                 Import/export queues to/from PostgreSQL database
                           storage

xftp-server --help 同构（配置路径 /etc/opt/simplex-xftp/file-server.ini，database 为文件存储导入导出）。

cert：在线证书轮换（实测闭环）。 执行后生成新的在线 TLS 凭据：

Certificate request self-signature ok
subject=CN = 10.89.61.10
Generated new server credentials
----------
You should store CA private key securely and delete it from the server.
...
CA private key location:
/etc/opt/simplex/ca.key
----------

轮换只更新 server.crt/server.key，离线 CA 不动，因此服务器指纹不变——实测 /etc/opt/simplex/fingerprint 在轮换前后均为 ml_GdNzOiCaM7rsJfxrAy6H_4-PFLOja4TqewPF3r8o=，重启服务后日志 Fingerprint: 一行也保持一致，既有连接不受影响。

journal / database： 数据迁移工具，不带子命令时打印用法（实测节选）：

Usage: smp-server database COMMAND [--table TABLE] [-d|--database DB_CONN] ...
  --table TABLE            Database tables: queues/messages
Usage: smp-server journal COMMAND
  Import/export messages to/from journal storage

存储文件巡检（实测清单）：

/var/opt/simplex/
├── smp-server-store.log                    # 队列记录（append-only）
├── smp-server-store.log.2026-10-27T01:24:53…  # 每次停机滚动备份
├── smp-server-messages.log.bak             # 未送达消息快照
└── backups/{queues,messages,stats}/

7.3 控制端口会话（实测）

INI 启用控制端口（默认只绑本机回环，日志 binding to 127.0.0.1:5224）后，从服务器本机建立 TCP 会话：

>> auth Admin-5224-Pass
SMP server control port
'help' for supported commands
Current role is CPRAdmin
>> server-info
Threads: 16
Clients: 0
Client queues (rcvQ, sndQ, msgQ): (0,0,0)
SMP subscriptions (via clients): 0
...
>> stats
fromTime: 2026-10-27 01:33:13.797043899 UTC
qCreated: 0
...
qCount: 0
qCount 2: 4
notifiers: 0
...
>> clients
clientId,sessionId,connected,createdAt,rcvActiveAt,sndActiveAt,age,subscriptions
>> help
commands: stats, stats-rts, clients, sockets, socket-threads, threads, server-info, delete, save, help, quit
>> quit

要点：登录命令为 auth <口令>（管理员口令登录回显 Current role is CPRAdmin）；stats 中 qCount 2: 4 的 4 即当前队列数；delete <队列> 可经控制端口清理异常队列，受 daily_block_queue_quota（默认每日 20 个）限制；save 手工落盘，quit 退出。

7.4 openssl 端口与指纹自检

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

实测回显：

subject=CN = 10.89.61.10

结合 /etc/opt/simplex/fingerprint 与客户端 /smp test 三方核对，即可确认"端口通、指纹对、建队可用"。

八、常见问题（FAQ）

Q1：bad chat command: Failed reading: empty 是什么问题？ 输入了不存在的命令（如把发文件误写成 /send，v7.0.4 的发文件命令是 /file）。/help 与 /help files 可核对命令名。

Q2：/smp test 通过但 /connect 失败？ 测试通过只代表 TLS 与指纹正确；若服务器开启了建队口令而地址未带 :口令，或服务器 new_queues = off，建队都会被拒（详细错误与闭环见《SimpleX Chat 7.0.4 配置参数详解》4.4 节）。

Q3：smp-server cert 报 hGetContents: invalid argument (cannot decode byte sequence starting from 228)？ INI 中存在中文等非 ASCII 内容（哪怕是注释行），而执行时 locale 非 UTF-8。用 LC_ALL=C.UTF-8 smp-server cert 执行即可（实测修复）。

Q4：轮换证书后客户端要重连吗？ 不用。smp-server cert 只换在线证书，离线 CA 与指纹不变（实测前后指纹一致），客户端按指纹锁定服务器身份，无感知。

Q5：命令可以缩写吗？ 可以，官方命令卡注明 /c、/f、/g、/p、/ad、/j、/fr 等缩写；群邀请回显也直接给出缩写用法（use /j dev-team to accept）。

Q6：/smp 改服务器列表会断线吗？ 会即时切换：实测回显 disconnected 1 connections on server … 紧跟 subscribed 1 connections on server …，既有连接按新列表重新订阅，消息不丢。

九、参考链接

《SimpleX Chat 7.0.4 介绍与选型指南》：https://www.quzuo.net/document/LsjsWxVptIAh
《SimpleX Chat 7.0.4 Docker Compose 部署指南》：https://www.quzuo.net/document/wthVPGVL9bt9
《SimpleX Chat 7.0.4 配置参数详解》：https://www.quzuo.net/document/PX5k4w104ePI
客户端源码仓库：https://github.com/simplex-chat/simplex-chat
服务端源码仓库：https://github.com/simplex-chat/simplexmq