支持多主可写、WebSocket 长连接互联、Protobuf 协议同步的分布式通知服务。
设计目标:
- 任意节点可写,本地提交后异步复制
- 用户数据最终完全一致;消息数据按每节点每用户最近 N 条(默认 500)最终一致
- 字段级 LWW 冲突收敛 + 反熵快照修复 + 断线事件日志补发
- 多传输层支持(WebSocket / 原生 TCP+mTLS / ZeroMQ / libp2p)
当前已完成本地存储内核、HTTP/JSON API、客户端 WebSocket + Protobuf 接口、集群同步链路、事件日志补发、多主冲突收敛、消息窗口收敛、反熵同步与快照修复、认证安全控制,以及运维观测能力。
cp ./config.example.toml ./config.toml # 按需编辑
go run ./cmd/turntf serve也可显式指定配置文件:
go run ./cmd/turntf serve -c ./config.toml生成 bcrypt 密码哈希:
go run ./cmd/turntf hash --password 'secret'
printf 'secret' | go run ./cmd/turntf hash --stdin| 术语 | 说明 |
|---|---|
node_id |
节点首次启动时生成的稳定数字身份,完整写入 HLC 时间戳,集群内必须唯一 |
| HLC | Hybrid Logical Clock,结合物理时间、逻辑计数和 node_id,提供贴近真实时间的稳定排序 |
| 最终一致 | 写入在本地提交后异步复制;网络恢复后数据最终收敛 |
| 收敛 | 不同节点经复制、重放、冲突处理后得到一致结果 |
| LWW | Last Write Wins,字段级比较版本时间,较新值覆盖较旧值 |
| 幂等 | 同一事件重复投递只生效一次,通过 applied_events 按 (source_node_id, event_id) 去重 |
| 反熵 | anti-entropy,定期比对摘要并修补差异,补偿实时广播 + 增量补拉的遗漏 |
| 快照修复 | 按分片传输当前数据快照并增量合并,修复事件补拉不足以解决的差异 |
| peer | 当前节点已知的其他节点,至少包含一个可拨号 url;远端 node_id 在握手时自动识别 |
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/auth/login |
公开登录 |
POST |
/users |
管理员创建用户 |
GET |
/users |
查询当前用户可通讯用户列表(支持 name / uid 过滤) |
GET |
/nodes/{node_id}/users/{user_id} |
查询用户(本人或管理员) |
PATCH |
/nodes/{node_id}/users/{user_id} |
管理员更新用户 |
DELETE |
/nodes/{node_id}/users/{user_id} |
管理员删除用户 |
POST |
/nodes/{node_id}/users/{user_id}/messages |
发送消息(需登录) |
GET |
/nodes/{node_id}/users/{user_id}/messages?limit=N |
查询消息 |
GET |
/nodes/{node_id}/users/{user_id}/metadata |
扫描用户元数据(用户本人/管理员,或频道管理员/管理员) |
GET |
/nodes/{node_id}/users/{user_id}/metadata/{key} |
查询用户元数据(用户本人/管理员,或频道管理员/管理员) |
PUT |
/nodes/{node_id}/users/{user_id}/metadata/{key} |
写入用户元数据(用户本人/管理员,或频道管理员/管理员) |
DELETE |
/nodes/{node_id}/users/{user_id}/metadata/{key} |
删除用户元数据(用户本人/管理员,或频道管理员/管理员) |
GET |
/nodes/{node_id}/users/{user_id}/attachments |
查询用户附件(本人或管理员) |
PUT |
/nodes/{node_id}/users/{user_id}/attachments/{attachment_type}/{subject_node_id}/{subject_user_id} |
写入用户附件 |
DELETE |
/nodes/{node_id}/users/{user_id}/attachments/{attachment_type}/{subject_node_id}/{subject_user_id} |
删除用户附件 |
POST |
/nodes/{node_id}/users/{user_id}/subscriptions |
管理订阅 |
DELETE |
/nodes/{node_id}/users/{user_id}/subscriptions/{channel_node_id}/{channel_user_id} |
取消订阅 |
GET |
/nodes/{node_id}/users/{user_id}/subscriptions |
查询订阅 |
POST |
/nodes/{node_id}/users/{user_id}/blacklist |
拉黑普通用户 |
DELETE |
/nodes/{node_id}/users/{user_id}/blacklist/{blocked_node_id}/{blocked_user_id} |
取消拉黑普通用户 |
GET |
/nodes/{node_id}/users/{user_id}/blacklist |
查询黑名单 |
GET |
/cluster/nodes |
已连接集群节点列表(需登录) |
GET |
/cluster/nodes/{node_id}/logged-in-users |
查询指定节点当前已登录用户(需登录) |
GET |
/events?after=0&limit=100 |
事件列表(管理员) |
GET |
/ops/status |
节点运维快照(管理员) |
GET |
/metrics |
Prometheus 文本指标(管理员) |
GET |
/healthz |
健康检查(公开) |
支持通过 sync_mode: force_sync 或 no_sync 控制单条消息的 Pebble 持久化方式(仅 store.engine = "pebble" 时生效)。
GET /users 默认返回“当前用户可通讯的活跃用户集合”。可选的 name 参数会在该集合内做大小写不敏感子串匹配;普通用户只匹配 username 与 profile.display_name/displayName,管理员和超级管理员额外匹配 login_name。可选的 uid 参数使用 node_id:user_id 格式做精确过滤。普通用户返回的其他联系人会隐藏 login_name,管理员和超级管理员仍可看到完整字段。若目标用户或频道显式写入 metadata system.visible_to_others=false,它会从普通用户的可见集合中隐藏,但不影响已知 uid 时继续发消息。
GET /nodes/{node_id}/users/{user_id}/messages 在 limit 之外,还支持同时传入 peer_node_id 和 peer_user_id,按“目标用户与 peer 之间的会话”筛选消息;此时管理员、目标用户本人,或会话另一端的 peer 本人都可以查询。
/metadata 现支持所有非系统保留用户作为 owner:普通用户、管理员、超级管理员和 channel 都可挂 metadata;broadcast / node 等系统保留用户仍不允许。HTTP JSON 在保留原始 value 字段的同时,新增可选 typed_value 视图,便于按 bool|string|number|json|bytes 读写 metadata;WebSocket / protobuf 仍只传输原始字节数组。
对“本人作用域”的 HTTP 接口,路径中的 {node_id,user_id} 还支持使用 /nodes/0/users/0 表示“当前 Bearer token 对应的登录用户”。仅完整的 0/0 组合有效;0/x、x/0、负数或非数字仍会返回 400。该快捷写法适用于查询本人信息、本人消息、本人元数据、本人附件、本人订阅和本人黑名单,不适用于 PATCH /users、DELETE /users 或 POST /messages 这类目标地址型接口。
- WebSocket
/ws/client:首帧发送LoginRequest,支持历史消息补发、持久消息/瞬时包,以及除 HTTP 登录之外的主要客户端与运维 RPC - WebSocket
/ws/realtime:首帧同样发送LoginRequest,保留list_cluster_nodes、list_node_logged_in_users、resolve_user_sessions这类在线态查询,以及delivery_kind=transient的瞬时流量;不会补发历史消息,也不支持持久化或管理类 RPC - ZeroMQ:启用后通过
zmq+tcp://host:port连接,首包发送ZeroMQMuxHello{role=CLIENT},之后复用与 WebSocket 相同的ClientEnvelope/ServerEnvelope协议
客户端登录同时支持 node_id + user_id + password 与 login_name + password 两种选择器;LoginResponse 会返回 session_ref,客户端可先用 resolve_user_sessions 查询在线会话,再通过瞬时消息里的 target_session 精确投递到某个在线会话。
详见 客户端全流程接入文档 和 客户端 WebSocket 接口。
- WebSocket:
/internal/cluster/ws(固定路径,集群模式自动挂载) - ZeroMQ:与客户端共用
services.zeromq.bind_url,首包发送ZeroMQMuxHello{role=CLUSTER} - 原生 TCP+mTLS:仅集群使用
tcp+tls://host:port/nodeID,严格双向证书与节点身份绑定,默认关闭;启用后优先 TCP,WSS 热备用并自动恢复切回 - libp2p:仅服务节点间通信,不新增业务客户端入口
发往 (node_id, 3) 的消息为瞬时包:不写事件日志,不参与 Ack / 补拉 / 快照,经 mesh 逐跳转发到目标节点在线用户。支持 best_effort 和 route_retry 两种模式。
- 登录支持
node_id + user_id + password或login_name + password;长连接首次认证后会签发短期reconnect_token,后续重连可跳过 bcrypt。两类签名 token 都可在共享auth.token_secret的节点间验证,但重连 token 不能用于 HTTP Bearer 鉴权 user_id = 1:保底超级管理员 (role=super_admin),管理面高风险动作只能由super_admin执行;系统保留用户仍不可通过管理接口修改或删除user_id = 2:系统广播地址 (role=broadcast),不可登录、不可删除user_id = 3:系统节点入口地址 (role=node),不可登录、不可删除user_id ≤ 1024:保留区间,普通用户和 channel 从 1025 开始分配role=channel:不可登录的组播地址,订阅后接收订阅时间之后的 channel 消息role=admin:保留大部分管理能力,但不能创建/提升/修改/删除管理员用户- 集群内部
Envelope收发两端均使用cluster.secret做 HMAC 鉴权
权限矩阵:
| 操作 | 权限要求 |
|---|---|
| 健康检查、登录 | 公开 |
| 查询本人信息、本人消息、本人元数据、管理本人订阅或黑名单 | 登录用户 |
| 发送消息到可登录用户或已授权 channel | 登录用户 |
发送瞬时包到 (node_id, 3) |
登录用户 |
| 查询集群节点、查询指定节点当前已登录用户 | 登录用户 |
| 创建普通用户、管理普通用户和 channel、事件查询、运维/监控 | admin 或 super_admin |
创建 role=admin、管理员升降权、修改或删除管理员用户 |
仅 super_admin |
- 本地写入成功后异步广播对应事件;对端应用后返回
Ack(仅表示"对端已应用",非全局提交) - 未校时时拒绝本地写入(返回 503);首次校时成功后才放开
- 重连后按
origin_cursors对比远端origin_progress,自动补拉未追平事件 - 历史事件被裁剪时,优先请求快照分片再从新 cursor 继续补拉
- 重复事件被
applied_events幂等吸收 - 反熵按用户全量分片
users/full和消息分片messages/{node_id}对比摘要 message_window_size不一致的节点间只修复用户分片,避免消息分片反复互拉- 消息在本地写入和复制应用时均裁剪到最近 N 条(默认 N=500)
# 准备配置和数据目录
cp ./config.example.toml ./config.toml
mkdir -p ./data
# 构建并启动
docker build -t turntf .
docker run --rm -p 8080:8080 \
-v "$PWD/config.toml:/app/config.toml:ro" \
-v "$PWD/data:/app/data" \
turntf
# 或使用 Compose
docker compose up -d --build预构建镜像:ghcr.io/tursom/turntf:latest
镜像标签规则:推送到 main 或 master 会生成对应分支标签与 sha-<commit>,其中 latest 只在 main/master 上发布;版本标签 v1.2.3 生成同名标签。
go test ./... -count=1
./scripts/smoke.shsmoke.sh 会编译临时二进制,启动单节点,验证 GET /healthz、登录、运维状态、指标、创建用户、自收消息和事件列表等最小可用路径。
当前 CI 默认运行的是不带 zeromq build tag 的测试集;如果本机已安装 libzmq 开发库,还可以额外执行:
go test -tags zeromq ./... -count=1source <(go run ./cmd/turntf completion zsh)持久安装:
mkdir -p ~/.zsh/completions
turntf completion zsh > ~/.zsh/completions/_turntf然后确保 ~/.zshrc 中启用:
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit同时支持 bash、fish、powershell 补全。
cp ./config.example.toml ./config.toml # 完整配置模板主要配置段:
| 配置段 | 说明 |
|---|---|
services.http |
HTTP API 监听地址,默认 :8080;集群入口 /internal/cluster/ws 固定挂载在此监听器 |
services.tcp_mtls |
原生集群 TCP+mTLS,默认关闭;CA、节点证书、白名单、帧上限与握手超时 |
services.zeromq |
ZeroMQ 传输,需 enabled = true,支持 none 和 curve 安全模式 |
services.libp2p |
libp2p 集群传输,支持 DHT、mDNS、relay、hole punching、Gossipsub |
store |
存储引擎 (sqlite / pebble)、消息窗口大小(默认 500)、事件日志裁剪策略 |
auth |
token 签名密钥、有效期、保底超级管理员 bcrypt 密码哈希 |
cluster |
集群密钥、时钟偏差容忍、静态 peer 列表;省略则单节点运行 |
logging |
日志级别 (debug/info/warn/error) 和可选 JSON 行日志文件路径 |
完整字段说明见 config.example.toml 中的注释。