Skip to content
tursomPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

分布式通知服务

支持多主可写、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 在握手时自动识别

功能与接口

HTTP API

方法 路径 说明
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)

Docker 部署

# 准备配置和数据目录
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.sh

smoke.sh 会编译临时二进制,启动单节点,验证 GET /healthz、登录、运维状态、指标、创建用户、自收消息和事件列表等最小可用路径。

当前 CI 默认运行的是不带 zeromq build tag 的测试集;如果本机已安装 libzmq 开发库,还可以额外执行:

go test -tags zeromq ./... -count=1

zsh 补全

source <(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 中的注释。

文档索引

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages