SAMA 0.37 介绍与选型指南

SAMA（Simple but Advanced Messaging Alternative）0.37.2 自托管聊天服务器的第一站认知文档：产品定位、uWebSockets.js+MongoDB+Redis+MinIO 架构解析、功能特性、适用场景与限制、与 Rocket.Chat/SimpleX Chat 等同类方案的量化选型对比，全链路 12 项功能于 2026-10-30 Docker 实测通过。

SAMA即时通讯SAMAWebSocketNode.js自托管2026/10/30

SAMA 0.37 介绍与选型指南

目标：本文是 SAMA 的第一站认知文档，面向正在评估「自托管即时通讯服务端」的后端工程师与架构选型人员，讲清 SAMA 是什么、协议与架构如何、能做什么、值不值得选。本文全部实测结论来自 2026-10-30 在 Docker Compose 上对 SAMA 0.37.2 的真实部署与 12 项功能链路验证（注册、登录、频道创建、消息收发、S3 文件上传下载等），部署过程见 《SAMA 0.37 Docker Compose 部署指南》。

1. SAMA 是什么

SAMA（Simple but Advanced Messaging Alternative） 是一个开源（GPL-3.0）的下一代自托管聊天服务器与客户端套件，由 Igor Khomenko 发起、SAMA-Communications 组织维护，官方仓库：

  • 服务端：github.com/SAMA-Communications/sama-server（本文实测版本 0.37.2，Release #219）
  • Web 客户端：github.com/SAMA-Communications/sama-client（Vue 3 + Vite monorepo，含 @sama-communications/sdk、ui-kit、client 三个 workspace）
  • 移动端：github.com/SAMA-Communications/sama-client-flutter

它的动机写在 README 第一段：提供一个不同于且可替代 XMPP 的现代消息协议与聊天服务器——XMPP 是当下唯一广泛流行的自托管消息"标准"，但协议包袱沉重。SAMA 用基于 WebSocket 的 JSON 包协议替代 XMPP 的 XML stanza，用 uWebSockets.js（C++ 编写的极高性能 Node.js WebSocket 库）承载长连接。

一句话定位：SAMA 不是开箱即用的"团队协作工作台"，而是一套协议清晰、组件解耦的 IM 引擎 + 参考客户端，适合作为自建聊天产品的底层进行集成与二次开发。

2. 架构解析（实测 7 容器拓扑）

SAMA 官方主推的部署形态就是 Docker Compose 多容器 stack，本文实测 stack 由 7 个容器组成：

容器角色实测镜像/基础职责
sama-server基于 node:22 本地构建（0.37.2）消息服务核心，uWebSockets.js 监听 WS/HTTP/TCP，内部以 PM2 跑 2 个节点（9001/9002）组成集群
sama-client基于 node:22 构建期克隆 sama-client一次性构建容器：npm run build 产出静态文件写入共享卷 sama-client-dist 后退出
nginxnginx:1.31.8双端口入口：静态 SPA（实测映射 8161）+ WS/HTTP 反向代理与两节点负载均衡（实测映射 8162）
s3MinIO对象存储，存放聊天附件（实测桶名 samabucket）
s3-serviceMinIO 镜像 + mc一次性初始化容器：建桶、设策略、创建 S3 服务账号后退出
mongomongo:6.0.11业务主库（用户/会话/消息/组织等），数据库名 samadb
redisredis（官方镜像）集群节点协调、Bull 任务队列、操作日志过期等

核心工作原理：

  • 连接层：单个 server 容器内可用环境变量定义多个 Node 节点（RUN_NODE_1_CMD/RUN_NODE_2_CMD，实测各监听 9001/9002），nginx upstream 做轮询负载均衡，跨节点消息投递依赖 Redis 中登记的集群节点信息（NODE_CLUSTER_DATA_EXPIRES_IN）。
  • 协议层：app/networking 下同时实现 JSON over WebSocket、HTTP（登录/管理端点）与 TCP 三种传输；JSON 处理器位于 APIs/JSON，按路由名分发到对应 Controller。
  • 多租户：所有业务数据（用户、会话、文件）都挂在 organization_id 下，首次部署需执行数据库迁移生成 default 组织（见 B2 部署指南实测坑一）。
  • 端到端加密：内置 Signal 风格的设备密钥体系（request_keys、device_register、加密消息 TTL 等配置），加密消息解密失败可上报（message_decryption_failed）。
  • AI 扩展：依赖内置 @ai-sdk/google 与 quickjs 沙箱，支持给会话挂载服务端 Bot（conversation handlers），可接 Gemini 做机器人回复。

3. 功能特性清单（实测验证项已标注 ✅）

  • 用户体系：注册（WS user_create ✅）、登录（HTTP /login 返回 JWT access_token + refresh cookie ✅）、登出、OTP 找回密码、多设备管理（device_register/device_list/device_delete ✅ 结构确认）、用户搜索、资料编辑
  • 会话类型：单聊 u、群聊 g、频道 c（实测创建频道 ✅，订阅/退订 ✅），频道支持管理员角色；会话上限人数可配（实测 50）
  • 消息能力：发送（✅ 实测回显 ask.mid/server_mid）、编辑、删除、表情回应、回复引用、已读回执、message_list 拉取（✅）、typing 输入中状态、消息 summary、tone 语气改写（AI）
  • 文件传输：create_files 申请预签名上传 URL（✅ 实测 S3 PUT 200）、get_file_urls 获取预签名下载 URL（✅ 实测 7 天有效期），支持 MinIO/S3/DigitalOcean Spaces 三种驱动
  • 联系人与隐私：通讯录增删改查、双向拉黑、在线状态与最后活动时间订阅
  • 推送：Web Push（VAPID）+ 原生推送守护进程 sama-push-daemon（FCM/APNs，官方 compose 可选组件）
  • 管理面：HTTP 管理端点（/admin/organization、/admin/message 系列、/admin/server-stats、/admin/activity/online），用 HTTP_ADMIN_API_KEY 鉴权 ✅ 结构确认
  • 运维观测：/health 健康检查 ✅ 实测、/health-stats、操作日志 op_log_list

4. 与同类自托管聊天方案对比

维度SAMA 0.37Rocket.Chat 8.9SimpleX Chat 7.0Matrix/Synapse
定位IM 引擎 + 参考客户端，面向二次开发开箱即用团队协作工作台隐私优先匿名聊天去中心化联邦 IM
协议自研 WS JSON 包（文档完整）REST + WebSocket + 集成扩展自研二进制（无账号设计）Matrix 联邦开放协议
技术栈Node 22 + uWS + MongoDB + Redis + MinIOMeteor/Node + MongoDB 8.0 + NATSHaskell 中继（smp-server）Synapse(Python)/Dendrite(Go) + PostgreSQL
多租户组织（organization）原生支持工作区/企业版分级不支持不支持（按 homeserver 划分）
E2E 加密内置 Signal 风格设备密钥体系端到端加密房间（企业特性为主）全链路匿名、元数据最小化房间级加密
资源占用轻（uWS，单机 2C4G 可跑全栈）重（Meteor 全家桶，官方建议 2C4G 起）轻中
二次开发友好度高：路由即包名，Controller/Operation 分层清晰，含测试套件中：API 面广但代码体量大低：协议专有中：协议复杂但生态成熟
移动端Flutter 官方客户端官方 React Native官方多端多实现（Element 等）

选型结论：

  • 想要最小依赖、协议透明、以 API 集成为主的自托管聊天（如给现有产品内嵌 IM、做行业专属通讯端），SAMA 是同类中最轻的起点之一；同类工作台型方案见站内 Rocket.Chat 8.9 介绍与选型指南。
  • 若核心诉求是元数据隐私与匿名，SimpleX 的设计更彻底，见 SimpleX Chat 7.0.4 介绍与选型指南。
  • 若需要开箱即用的频道/工单/集成市场，Rocket.Chat/Mattermost 更合适。

5. 适用场景与限制

适合：自建 IM 底层引擎；需要多组织隔离的 B2B 消息平台；对消息协议想要完全掌控的团队；低资源 VPS 上的私人聊天服务。

限制（实测/源码确认）：

  1. 版本尚在 0.x（0.37.2），官方文档站 docs.samacloud.io 为主要资料源，API 细节以仓库 APIs/JSON 代码为准。
  2. 无内置管理后台 UI，管理动作走 HTTP 管理端点 + API Key。
  3. Web 客户端与 server 版本解耦发布（client 构建期从 GitHub 拉 main 分支），生产建议锁定分支或自行维护前端构建。
  4. 推送守护进程（FCM/APNs）需单独配置 sama-push-daemon 与厂商凭据，Web Push 需要 HTTPS。
  5. GPL-3.0 对闭源商用分发有传染性约束。

6. 下一步