Stoat 0.15.5 介绍与选型指南

说清 Stoat 是什么、从哪里来、由哪些服务组成、能做什么、与 Revolt/Mattermost/Rocket.Chat 等同类自托管聊天平台相比如何选型。本篇为认知篇，全部信息来自官方站点与官方仓库的联网溯源（查询日期 2026-10-30），未做本地实测；部署实测结论见本专栏部署与配置各篇。

StoatStoatChat即时通讯2026/10/30

Stoat 0.15.5 介绍与选型指南

目标：说清 Stoat 是什么、从哪里来、由哪些服务组成、能做什么、与 Revolt/Mattermost/Rocket.Chat 等同类自托管聊天平台相比如何选型。本篇为认知篇，全部信息来自官方站点与官方仓库的联网溯源（查询日期 2026-10-30），未做本地实测；部署实测结论见本专栏部署与配置各篇。

一、环境信息

本篇为联网溯源认知篇，不依赖本地实验环境。溯源所用信息源与查询日期汇总如下，供读者复核：

信息源地址取证内容查询日期
Stoat 官网https://stoat.chat产品定位、官方 GitHub 组织入口、客户端与状态页入口2026-10-30
Stoat 开发者站https://developers.stoat.chat许可与品牌使用 FAQ 入口2026-10-30
GitHub 组织仓库页https://github.com/orgs/stoatchat/repositories仓库矩阵（后端/自托管/客户端等）2026-10-30
后端 monorepohttps://github.com/stoatchat/stoatchatLICENSE、README（crate 清单、MSRV）、crates/core/config/Revolt.toml2026-10-30
自托管编排仓库https://github.com/stoatchat/self-hostedcompose.yml、Caddyfile、generate_config.sh、README/Guides（main 分支 tarball）2026-10-30
实时网关仓库https://github.com/stoatchat/gatewaygateway-main tarball（Elixir 工程结构）2026-10-30
releases.atom（后端）https://github.com/stoatchat/stoatchat/releases.atom版本发布时间线2026-10-30
releases.atom（for-web）https://github.com/stoatchat/for-web/releases.atomWeb 前端版本时间线2026-10-30
shields.io 徽章https://img.shields.io/github/stars/….json各仓库星数2026-10-30
Revolt 上游仓库https://github.com/revoltchat/revolt、https://github.com/revoltchat/backend上游星数与 LICENSE 对比2026-10-30

💡 说明：Stoat 官方把自托管编排与后端源码分仓维护，self-hosted 仓库的 compose 编排固定搭配一组经过联调的后端服务版本（本次溯源时 main 分支钉在 v0.15.5），后端 monorepo 的最新 release（v0.16.2）并不等于自托管编排当前引用的版本。选版本时应以 self-hosted 仓库 compose.yml 中的镜像标签为准，这一点在选型时容易踩坑。

二、软件概述

Stoat 是一个开源、可自托管、面向朋友与社区的聊天平台，官方自我定位为"the chat app for friends and communities that finally works the way you always wished it would"（官网首页 meta 描述，查询日期 2026-10-30）。它是即时通讯软件 Revolt 的社区延续：2025 年 10 月 5 日，官方自托管编排中的项目名由 revolt 整体更名为 stoat，配置文件仍沿用 Revolt.toml 名称（self-hosted 仓库 README Notices 一节，查询日期 2026-10-30），官方站点的关键词标签也同时写着 "Stoat, Revolt, chat, messaging, open-source, community, customisation"（官网 HTML 源码，查询日期 2026-10-30）。可以把它理解为：产品形态对标 Discord（服务器-频道-角色、语音房间、社区玩法），代码基因来自 Revolt，由 Stoat 社区接续维护并按自己的节奏发布。

项目整体采用"组织多仓库"形态，官方 GitHub 组织为 stoatchat（官网页脚链接，查询日期 2026-10-30）。截至 2026-10-30 的主要仓库与社区热度如下：

仓库角色星数（shields.io，2026-10-30）
stoatchat/stoatchat后端 monorepo（REST API、事件、文件、代理、守护进程）3.4k
stoatchat/self-hosted自托管编排（compose、配置生成脚本、Caddy 配置）2.7k
stoatchat/for-webWeb 前端769
stoatchat/gateway新一代实时网关（Elixir，2026 年新立仓库，V0.1.0）0（新建）
for-desktop / for-android / for-ios桌面与移动客户端—
awesome-stoat社区客户端与生态清单—
service-admin-panel、service-geoblocking、service-easypwned 等官方运营侧配套服务—

版本时间线（后端 monorepo releases.atom，查询日期 2026-10-30）：v0.15.5 发布于 2026-09-12，v0.15.6 发布于 2026-09-25，v0.16.0 发布于 2026-10-15，v0.16.1 发布于 2026-10-14 前后，v0.16.2 发布于 2026-10-19；Web 前端 for-web 最新为 v0.16.3。也就是说，2026 年 9 月到 10 月两个月内后端从 v0.15.5 迭代到 v0.16.2，处于活跃的月度级迭代节奏；而自托管编排仓库最近一次提交为 2026-10-07（commits/main.atom，查询日期 2026-10-30），其 compose.yml 仍引用 v0.15.5 服务端与 for-web v0.15.3（代码内注释标注），属于"编排版本落后于后端最新版"的常见滞后状态。

许可证方面，后端 monorepo 与自托管编排仓库的 LICENSE 文件均为 GNU Affero General Public License v3（AGPL-3.0-or-later，源码 LICENSE 文件直接读取，2026-10-30）。这意味着：把 Stoat 改造后仅提供网络服务（不分发二进制）也需按 AGPL 义务向使用者开放源码，商业闭源集成前必须先过许可证关。官方开发者站的 FAQ《What can I do with Stoat and how do I self-host?》专门说明了许可与品牌使用边界（self-hosted README 引注，查询日期 2026-10-30）。

💡 技术拓展：自托管 IM 的开源许可证常见三种取向，选型前值得分清——

许可证代表产品对自托管部署者的影响
AGPL-3.0Stoat、Revolt、Mattermost 源码路径二次修改后对外提供服务须开放修改后源码
MITRocket.Chat 主仓库（ee 目录除外）可自由修改、闭源集成，义务最轻
MIT（编译版）/AGPL+商业（源码）Mattermost直接用官方编译包=MIT 义务；自行编译源码=AGPL 义务

Stoat 实际采用 AGPL-3.0-or-later，与上游 Revolt 后端一脉相承，适合"用得彻底、改得透明"的社区型部署；若你的场景要求改造后闭源，应优先看 Rocket.Chat 或购买 Mattermost 商业授权。

三、核心架构

Stoat 采用微服务全家桶架构。官方自托管编排（self-hosted 仓库 compose.yml 与 Caddyfile，main 分支 tarball，查询日期 2026-10-30）把整套系统拆为「存储层 + 服务层 + 接入层」三部分，一次编排同时拉起 16 个服务。各组件分工如下：

组件角色内部端口依赖
api（delta）REST API 服务，账号/服务器/频道/消息等全部业务入口14702MongoDB、Redis、RabbitMQ
events（bonfire）WebSocket 实时事件服务，消息推送、在线状态14703MongoDB、Redis、RabbitMQ
autumn文件服务器，头像/附件/表情等上传下载14704MongoDB、对象存储
january元数据与图片代理，链接预览抓取14705—
gifboxTenor GIF 代理14706—
crond定时任务守护进程（数据清理等）—MongoDB、对象存储
pushd推送通知守护进程（Web Push/FCM/APN）—MongoDB、Redis、RabbitMQ
voice-ingress语音房间的信令入口8500MongoDB、RabbitMQ
livekitLiveKit SFU，实际承载音视频流7880/7881 + 50000-50100/UDPRedis
caddyWeb 服务器/反向代理，按路径把流量分发给上面各服务80/443—
webWeb 前端（for-web）5000—
databaseMongoDB 8，唯一持久化业务库27017—
redis（Valkey 9）事件消息总线与 KV 缓存6379—
rabbitRabbitMQ 4，内部任务/通知队列5672—
minio（silo）S3 兼容对象存储，存放全部上传文件9000—
createbuckets一次性初始化任务，创建默认 bucket—对象存储

对外接入由 Caddy 统一收口：/api/* 转 api、/ws 转 events、/autumn/* 转 autumn、/january/* 转 january、/gifbox/* 转 gifbox、/livekit* 转 livekit、/ingress* 转 voice-ingress，其余路径落到 Web 前端（Caddyfile 逐行核读，2026-10-30）。浏览器只面对一个域名，语音视频所需的 RTC 端口（7881/TCP 与 50000-50100/UDP）则必须直接对公网开放，官方 README 专门解释了这两个端口不走 Caddy 的原因。

代码侧，后端是 Rust 单仓多 crate 工程（MSRV 1.86.0，monorepo README，查询日期 2026-10-30）：delta 为 REST API 服务、bonfire 为 WebSocket 事件服务、autumn/january/gifbox 为三个独立服务、crond/pushd 为守护进程，底层共享 core/config（配置模型，对应 Revolt.toml）、core/database、core/files、core/models、core/permissions 等 crate。此外 2026 年新立了 gateway 仓库（Elixir/Phoenix 工程，目录结构与 mix.exs 核读确认），作为新一代实时网关，当前仅 V0.1.0，尚未进入自托管编排的默认服务清单。存储侧默认搭配 MongoDB 8 + Valkey 9（Redis 协议兼容，官方编排提供换回 redis/valkey 8 的兼容说明）+ RabbitMQ 4 + S3 兼容对象存储，其中对象存储自 2026-09-17 起由 MinIO 镜像迁移到官方推荐的 silo 镜像（README Notices，2026-10-30）。

💡 技术拓展：「事件推送」在自托管 IM 里常见三条路线——

路线原理代表取舍
WebSocket 长连接客户端与服务端保持全双工连接，服务端主动推事件Stoat（events 服务）实时性最好，需维护连接状态与断线重连
消息轮询/长轮询客户端定时拉取增量早期 Web IM实现简单，延迟与空轮询开销大
SSE 单向推送服务端单向流式下发轻量通知类场景只能服务端到客户端，双向交互受限

Stoat 实际采用 WebSocket 长连接（bonfire/events 服务），并辅以 Redis pub/sub 与 RabbitMQ 队列在多服务间分发事件，这是 Discord 类产品的典型选择。

四、功能特性

以下特性清单逐项对应官方配置文件 Revolt.toml 的功能开关、自托管 README/Guides 的说明（tarball 直接核读，查询日期 2026-10-30），可视为"能通过配置落地的能力"而非宣传口径：

  • 社区服务器体系：服务器（guild）-频道-角色-权限体系，支持自定义 emoji、服务器横幅/图标，单服务器默认上限 200 频道、200 角色、100 表情。
  • 消息与互动：消息长度默认 2000 字符、单条消息 5 个嵌入、5 条回复引用、20 个表情回应；支持 @提及与全员/角色提及（可配置是否推送通知）。
  • 文件上传：默认单附件 20MB、头像 4MB、横幅/背景 6MB、图标 2.5MB、emoji 500KB；图片最大 40 MP/10000 px；存储侧支持服务端加密（files.encryption_key）、WebP 压缩预览、按 MIME 类型封锁上传、可选 ClamAV 病毒扫描（files.clamd_host）。
  • 语音与视频：基于 LiveKit SFU 的语音房间与屏幕共享，配置脚本可一键开启 1080p 并支持调到 4K；注意官方提示当前实现下"上传超过配置分辨率的视频流会被踢出房间"的已知问题。
  • 推送通知：Web Push（VAPID）、Google FCM、Apple APN 三通道，由独立的 pushd 服务与 RabbitMQ 队列承载，自托管默认启用 VAPID。
  • 账号安全：邮箱验证/密码找回/账号删除（需自配 SMTP）、MFA、邀请制注册（api.registration.invite_only，配合 MongoDB 写入邀请码）、可选 hCaptcha 验证码与 Cloudflare 信任模式、可选 easypwned 泄露密码库校验。
  • 机器人与 Webhook：账号体系内置 bot 用户（新用户默认 2 个、普通用户 5 个上限）；消息 webhook 默认关闭（features.webhooks_enabled = false）需显式打开。
  • 运营与治理：审计日志默认保留 30 天、用户名最短 2 字符、新账号 72 小时内适用更严格的速率限制（好友请求 5 个/服务器 50 个）、服务器创建可按用户 ID 白名单收敛（restrict_server_creation）、法律文档链接可自定义。
  • GIF 与外部内容：gifbox 提供 Tenor GIF 选择器代理（需自配 Tenor API Key）；january 负责链接预览抓取并支持域名黑名单。

客户端体验是自托管场景的显性短板，官方 README 用显著位置声明：目前大多数官方客户端不支持自托管实例，Web 客户端工作良好，配合 PWA 安装后体验接近原生应用；桌面客户端支持自托管但需以 --force-server=https://你的域名 启动参数指定实例（self-hosted README 与 Guides，查询日期 2026-10-30）。移动端 App 在本次溯源的官方文档中未见自托管接入说明，社区客户端可参考 awesome-stoat 清单。

安全公告方面，self-hosted README 底部列出两个历史安全通告的修复版本：后端 0.15.0 与 for-web 0.14.1（Security Advisories 一节，查询日期 2026-10-30），自托管时应至少部署不低于该版本的服务端与前端。

五、快速开始（最小可用示例）

官方推荐的自托管上手路径只有三条命令（引自官方 self-hosted 仓库 README 的 Configuration 一节，查询日期 2026-10-30；命令中的 your.domain 需替换为你的实际域名）：

git clone https://github.com/stoatchat/self-hosted stoat   # 拉取官方自托管编排
cd stoat                                                   # 进入编排目录
chmod +x ./generate_config.sh                              # 赋予配置脚本执行权限
./generate_config.sh your.domain                           # 生成密钥与配置（交互式问答）
docker compose up -d                                       # 按官方 compose 全量拉起

generate_config.sh 会交互式询问两件事（是否使用外部反向代理、是否启用摄像头/屏幕共享），随后自动生成 5 组密钥写入 secrets.env（VAPID 推送密钥对、文件加密密钥、LiveKit key/secret）、服务配置 Revolt.toml、语音配置 livekit.yml、前端环境 .env.web 与客户端发现配置 stoat.json（脚本逐行核读，2026-10-30）。脚本内建的防护值得注意：检测到已有配置时默认拒绝执行，必须显式加 --overwrite 且存在 secrets.env 才允许覆盖，防止把旧实例的加密密钥刷掉导致文件全部不可读。

部署前需要满足的硬件与网络条件（官方 README Deployment 一节，2026-10-30）：至少 2 vCPU、2 GB 内存的服务器；域名 A/AAAA 记录指向服务器；开放 80/443（Web 与 API）、7881/TCP 与 50000-50100/UDP（语音 RTC）端口。官方 README 还给出了 ufw 防火墙的逐条放行命令与 SSH 加固建议。

最小验证路径：浏览器打开 https://your.domain → 注册账号 → 创建服务器 → 发送第一条消息。更完整的带实测回显的部署流程见 《Stoat 0.15.5 Docker Compose 部署指南》（含本站实测的注册、建服、发消息验证），各配置项含义见 《Stoat 0.15.5 配置参数详解》，注册/登录/建服/发消息的 REST API 调用见 《Stoat 0.15.5 API 使用详解》。

六、适用场景与限制

适合的场景：

  • 朋友圈、兴趣社区、游戏公会等 Discord 式社区：需要服务器/频道/角色、语音房间、表情文化，且希望数据完全自己掌控。
  • 已被 Discord 收费/政策变动困扰、想迁移到开源自托管方案的小型社区（Stoat 的产品形态与 Discord 最接近）。
  • 想在 Revolt 生态基础上做定制开发（改功能、换品牌、对接内部系统）的团队：AGPL 允许修改并要求回馈源码，Rust 单仓多 crate 结构对二次开发相对友好。
  • 内网/隔离环境部署：全栈服务均可离线加载，唯一外部依赖是可选的 Tenor GIF Key 与推送通道。

限制与注意（均为官方文档明示，查询日期 2026-10-30）：

  • 官方移动端 App 与多数客户端不支持自托管实例，实际可用的只有 Web/PWA 与带 --force-server 参数的桌面端；对"手机 App 优先"的社区是硬伤。
  • 邮箱验证、密码找回依赖自配 SMTP，默认配置不启用，注册环节的账号找回能力需要自行补齐。
  • 语音视频要求公网直开 7881/TCP 与 50000-50100/UDP，NAT 后的内网部署会损失音视频功能（可关闭 video 配置降级为纯文字社区）。
  • 自托管编排版本滞后于后端最新 release（本次溯源：编排钉 v0.15.5，后端已到 v0.16.2），追新需自行调整镜像标签并承担联调风险。
  • AGPL-3.0 许可证对商业化改造有传染性义务。
  • 全家桶 16 个服务的资源与运维成本不低，官方建议起步 2 vCPU/2GB，长期运行建议更高规格并做好 MongoDB 与对象存储的数据备份（secrets.env 丢失会导致加密文件永久不可读，官方 README 反复强调要备份）。

七、同类选型对比

选取三个有代表性的同类进行量化对比：上游 Revolt（同基因的对照项）、Mattermost（企业协作型代表）、Rocket.Chat（团队协作+客服全功能型代表）。星数与许可证均于 2026-10-30 经 shields.io 徽章接口与各仓库 LICENSE 原文取证；Stoat 版本数据来自 releases.atom，同为 2026-10-30。

维度StoatRevolt（上游）MattermostRocket.Chat
GitHub 星数后端 3.4k；self-hosted 2.7krevolt 仓 2.3k；backend 仓 3.4kmattermost-server 39k46k
许可证AGPL-3.0-or-later后端同 AGPL 系（backend 仓 LICENSE）编译版 MIT；源码 AGPL/商业双授权MIT（ee 目录另有商业授权）
技术栈Rust 后端 + Elixir 新网关 + TS 前端Rust 后端 + TS 前端Go 服务端 + ReactNode.js/Meteor + React
产品定位朋友圈/社区聊天（Discord 形态）同左企业协作与办公集成团队协作 + 全渠道客服
部署形态官方 compose 全家桶（16 服务：Mongo/Valkey/RabbitMQ/对象存储/Caddy/8 个应用服务）类似的分服务编排单服务 + 数据库为主，另有高可用模式单服务 + MongoDB/数据库为主
起步资源官方建议 2 vCPU/2GB与 Stoat 相当官方建议 2 vCPU/4GB 级官方建议 2 vCPU/2GB 级
语音视频LiveKit SFU 内置（自托管可开）历史上有过自研/Coturn 方案，自托管支持不稳定内置（企业版特性为主）内置（Jitsi 集成）
自托管客户端Web/PWA + 桌面端 --force-server；移动端暂不支持Web 为主全端（含移动 App 指向自托管）全端（含移动 App 指向自托管）
版本节奏（本次溯源窗口）2026-09~10 两月 5 个 release（v0.15.5→v0.16.2）活跃（backend 仓持续迭代）月度企业发布节奏高频社区发布节奏
中文资料与生态少，官方文档英文少丰富，企业案例多丰富，国内使用广

关键差异与选型建议：

  • 要 Discord 的产品形态（服务器/频道/角色/语音房间/表情文化）且接受 Web 客户端为主 → Stoat 或 Revolt；两者代码同源，Stoat 的差异点在于社区接续维护、2026 年后独立发版、以及官方自托管编排更新更勤（16 服务全家桶开箱即用）。在官方渠道可访问性与维护节奏存疑时，Stoat 是 Revolt 生态的实际延续选项。
  • 要企业办公集成（SSO/合规/审计/Office 生态/大量插件）→ Mattermost，其企业化能力与运维成熟度远超 Stoat；代价是全家桶商业授权边界要理清。
  • 要团队 IM + 客服/全渠道（多渠道接入、CRM 对接、livechat 挂件）→ Rocket.Chat，生态与中文资料最全，MIT 主许可对改造最友好。
  • 要手机 App 体验优先 → Mattermost 与 Rocket.Chat 的自托管移动端均开箱可用，Stoat/Revolt 目前只有 Web/PWA，选型时需如实评估社区使用习惯。
  • 站内同类产品的横向参考：团队协作型可读 《Rocket.Chat 8.9 介绍与选型指南》；联邦式去中心化社交网络可读 《Mastodon 4.7.3 介绍与选型指南》；另一款轻量自托管即时通讯可读 《SAMA 0.37 介绍与选型指南》。

八、参考链接