Horizon 实时后端平台深入解析:架构、核心服务与快速上手实践
Horizon 实时后端平台深入解析:架构、核心服务与快速上手实践
Horizon 是一个开源的实时后端开发平台,专为 JavaScript 应用设计,让开发者无需编写任何后端代码即可构建、部署和管理复杂的实时 Web 与移动应用。本文以仓库根目录的 README.md 为核心骨架,结合 server、client、cli 三大组件的源码实现,系统讲解 Horizon 的架构组成、四大核心服务(Subscribe、Auth、Identity、Permissions)、与 RethinkDB 的集成方式,以及从初始化项目到运行实时应用的完整实战路径。
什么是 Horizon?
Horizon 是一个开源开发者平台,用于构建复杂的实时应用。它提供了一个完整的后端解决方案,显著简化了构建、部署、管理和扩展 JavaScript Web 与移动应用的过程。Horizon 具有可扩展性,与 Node.js 技术栈天然集成,支持构建现代且任意复杂的应用。
Horizon 构建在 RethinkDB 之上。选择 RethinkDB 作为底层存储引擎,意味着一旦应用复杂到需要在后端编写自定义业务逻辑,开发者可以在应用开发周期的任何阶段增量地加入后端代码(参见 README.md 的 "Why Horizon?" 一节),而不必推翻已有架构——数据始终存放在同一个 RethinkDB 数据库中。
Horizon 由以下组件构成:
| 组件 | 职责 | 仓库位置 |
|---|---|---|
| Horizon server | 中间件服务器,连接并构建在 RethinkDB 之上,向前端应用暴露简单的 API/协议 | server |
| Horizon client library | JavaScript 客户端库,将 Horizon server 的协议包装成面向前端开发者的便捷 API | client |
Horizon CLI(hz) |
命令行工具,辅助项目脚手架搭建、开发与部署 | cli |
| GraphQL 支持 | 为 server 提供 GraphQL 适配器,便于无后端代码地构建 React/Relay 应用 | 计划中,v1 不包含 |
其中 GraphQL 支持是官方路线图中的规划项:README 明确说明它 不会随 v1 发布,但官方会在发布后快速跟进(参见 README.md 中的服务列表说明)。
核心服务:实时应用的一站式后端
Horizon 目前向开发者提供以下全部服务:
- ✅ Subscribe —— 流式 API,可直接在浏览器中构建实时应用,无需编写任何后端代码。
- ✅ Auth —— 认证 API,连接 Facebook、Google、GitHub 等常见认证提供商。
- ✅ Identity —— 用于列出和操作用户账户的 API。
- ✅ Permissions —— 安全模型,允许开发者保护数据免受未授权访问。
下面结合源码逐一展开。
Subscribe:实时数据流的核心
Subscribe 服务是 Horizon 实时能力的基石。其客户端实现位于 client/src/ast.js,TermBase.watch() 方法通过 _sendRequest('subscribe', query) 向服务器发起订阅请求;服务端对应的处理逻辑位于 server/src/endpoint/subscribe.js,它复用查询端点(make_reql,定义于 server/src/endpoint/query.js)生成 ReQL 查询,并调用 RethinkDB 的 changes() changefeed:
reql.changes({ include_initial: true,
include_states: true,
include_types: true,
include_offsets: Boolean(raw_request.options.order) &&
Boolean(raw_request.options.limit) })
订阅启动后会持续推送数据变更,直到收到 "state": "complete"。客户端侧则在 client/src/ast.js 的 makePresentable 与 applyChange 函数中,将服务器推送的增量变更(add/remove/change/initial/state)合成为完整的结果数组,这正是 .watch() 回调能直接拿到"整个结果集最新快照"的原理——开发者可以直接用新数组替换前端框架(如 Vue、React)中的状态,无需手工做差异计算。
Auth:多提供商 OAuth 认证
Auth 服务让用户使用已有社交账号登录。当前仓库 server/src/auth 目录下实现了以下提供商:
- Auth0(auth0.js)
- Facebook(facebook.js)
- GitHub(github.js)
- Google(google.js)
- Slack(slack.js)
- Twitch(twitch.js)
- Twitter(twitter.js)
认证的核心实现位于 server/src/auth.js。它基于 JWT(JSON Web Token):JWT 类使用 token_secret(Base64 解码后)以 HS512 算法签发和校验令牌,令牌负载结构为 { id: <uuid>, provider: <string> },默认有效期 duration = '1d'(参见 server/src/schema/server_options.js 的 auth 校验规则)。
认证方式在 WebSocket 握手中完成,支持三种方法(对应 server/src/auth.js 的 handshake()):
unauthenticated:不关联任何用户(需allow_unauthenticated开启);anonymous:创建一个无外部认证提供商的匿名新账户(需allow_anonymous开启),用户 id 由r.uuid()生成;token:用已有的 Horizon access token 关联用户。
注意:使用认证功能 必须启用 TLS(HTTPS/WSS),否则密钥与令牌在网络上明文传输,存在安全隐患。
Identity:用户账户管理
Identity 服务提供用户账户的列出与操作能力。在客户端,通过 horizon.currentUser() 获取当前用户的查询 Term,实现位于 client/src/ast.js 的 UserDataTerm:它会先等待握手中携带的用户 id(handshake.id),再对 users 集合执行 find(userId) 查询(fetch() 或 watch())。未认证用户没有用户文档,此时 fetch() 会抛出 Unauthenticated users have no user document 错误。
在服务端,用户数据存放在 RethinkDB 数据库的 users 表中。新用户创建时(server/src/auth.js 的 new_user_row())会写入:
{
id, // r.uuid() 生成的 id
groups: [ 'default', 'authenticated' ], // 默认组 + 新用户组
'$hz_v$': 0 // 版本字段
}
Permissions:细粒度的安全模型
Permissions 服务基于"组(group)+ 规则(rule)"的安全模型。权限规则用**模板(template)**表达,模板是一段可执行的 JavaScript 表达式,运行在隔离的 vm 沙箱中(见 server/src/permissions/template.js 的 make_template())。模板中可以调用 collection(...)、any()、anyObject()、anyArray()、userId() 等辅助函数来构造匹配模式。
一条规则由 template(必填)和可选的 validator(自定义校验函数)组成,定义与校验逻辑位于 server/src/permissions/rule.js 与 server/src/permissions/validator.js。当客户端发起请求时,server/src/request.js 的 evaluate_rules() 会遍历该用户所属组的全部规则,凡是模板匹配该请求的规则都被加入本次请求的规则集;若规则集为空,请求直接以 Operation not permitted. 被拒绝。查询与订阅过程中,返回的每条数据还会逐条经过 ruleset.validate(context, item) 校验,防止越权读取(参见 server/src/endpoint/query.js)。
默认生成的权限 schema(见 cli/src/init.js 的 makeDefaultSchema())为 admin 组配置了全量权限:
[groups.admin]
[groups.admin.rules.carte_blanche]
template = "any()"
为什么选择 Horizon?
虽然 RethinkDB 和 WebSocket 等技术已经让构建实时应用成为可能,但实践经验表明,大多数开发者仍然面临过高的摩擦:构建实时应用需要理解并手动编排软件栈中的多个系统、理解分布式流处理、学习如何部署和扩展实时系统——学习曲线陡峭,且最初的大量工作都是与"构建实时应用"这一核心任务相去甚远的样板代码。
Horizon 的目标正是解决这一问题:开发者可以使用自己偏好的前端框架,通过 Horizon 的 API 直接开始构建应用,而无需编写任何后端代码。同时,因为数据存放在 RethinkDB 中,当应用复杂到需要后端业务逻辑时,开发者可以在任何阶段增量加入后端代码,实现平滑演进。
快速上手:从初始化到实时应用
安装与项目初始化
通过 npm 全局安装 Horizon:
$ npm install -g horizon
然后初始化一个新项目:
$ hz init example-app
hz init 会创建如下目录结构:
example-app/
├── dist/
│ └── index.html
├── .hz/
│ ├── config.toml
│ ├── schema.toml
│ └── secrets.toml
└── src/
dist/:静态文件输出目录,Horizon 会将其作为静态资源直接对外服务(默认配置serve_static = "dist");src/:源码目录,仅作约定,Horizon 不会触碰其中任何文件;.hz/config.toml:TOML 格式的服务器配置;.hz/schema.toml:权限与集合(collection)schema;.hz/secrets.toml:存放token_secret等机密信息(生成时权限为0o600,仅当前用户可读写,参见 cli/src/init.js)。
hz 命令行的完整子命令定义在 cli/src/main.js,目前包括:init、serve、version、create-cert、make-token、schema、migrate。
启动服务器:hz serve 与 hz serve --dev
运行 hz serve 主要做三件事:
- 启动 Horizon Server 节点应用,对外提供 Horizon Client API / WebSocket 端点;
- 对外提供
horizon.js客户端库; - 服务
dist目录下的所有静态文件(若当前目录存在该目录)。
hz serve 与 hz serve --dev 的差异(详见 GETTING-STARTED.md):
| 功能 | hz serve |
hz serve --dev |
对应命令行标志 |
|---|---|---|---|
| 启动 Horizon Server | ✅ | ✅ | |
| 启动 RethinkDB Server | ❌ | ✅ | --start-rethinkdb |
| 非安全模式(无 HTTPS/WSS) | ❌ | ✅ | --insecure |
| 自动创建表 | ❌ | ✅ | --auto-create-table |
| 自动创建索引 | ❌ | ✅ | --auto-create-index |
从源码看,--dev 标志实际启用的选项记录在 cli/src/serve.js 的 argparse 定义中,它会设置 --secure=no、--permissions=no、--auto-create-collection=yes、--auto-create-index=yes、--start-rethinkdb=yes、--allow-unauthenticated=yes、--allow-anonymous=yes 以及 --serve-static=./dist。
hz serve --dev 会在当前目录启动一个专供 Horizon 使用的 RethinkDB 实例,并创建 rethinkdb_data 文件夹;表与索引的自动创建让你无需关心底层数据模型,快速进入业务开发。
安全提示:使用认证功能必须配合 TLS。正式环境请使用
hz serve(不带--dev),并配置--key-file与--cert-file。
配置文件 .hz/config.toml
Horizon Server 通过 .hz/config.toml(TOML 格式)进行配置。hz serve 默认在当前工作目录查找该文件。配置文件的核心参数(生成模板见 cli/src/init.js):
| 配置项 | 默认值 | 说明 |
|---|---|---|
bind |
["localhost"] |
监听的本地网络接口 |
port |
8181 |
监听端口 |
secure |
true |
是否启用 HTTPS/WSS;false 则降级为 HTTP |
key_file / cert_file |
./horizon-key.pem / ./horizon-cert.pem |
TLS 密钥与证书路径 |
project_name |
当前目录名 | 存储应用数据的 RethinkDB 数据库名 |
serve_static |
无 | 静态文件服务目录 |
auto_create_collection / auto_create_index |
false |
请求需要时是否自动创建集合/索引 |
connect / start_rethinkdb |
无 | 连接已有 RethinkDB 实例 / 启动内置实例,二者互斥 |
rdb_timeout |
无 | 连接 RethinkDB 的超时秒数 |
token_secret |
无 | 签名 JWT 的密钥(建议放 .hz/secrets.toml) |
allow_anonymous / allow_unauthenticated |
false |
是否允许匿名/未认证连接 |
auth_redirect |
/ |
认证完成后的跳转地址 |
access_control_allow_origin |
"" |
允许访问认证设置的前端主机 |
配置优先级(由 cli/src/utils/config.js 的 processConfig() 实现):命令行标志 > 环境变量 > 配置文件 > 默认值。环境变量以 HZ_ 前缀命名(如 HZ_TOKEN_SECRET),认证提供商则形如 HZ_AUTH_{PROVIDER}_{OPTION}。此外,connect 既支持传统的 HOST:PORT(如 localhost:28015)也支持 rethinkdb://user:pass@host:port/db 形式的 URI(parse_connect 会从中解析出用户、密码与数据库名)。
配置 OAuth 认证
在对应提供商(Facebook、GitHub、Google、Twitch、Twitter 等)的开发者平台创建应用,拿到 client_id 与 client_secret 后,填入 .hz/config.toml。以 GitHub 为例:
[auth.github]
id = "your_client_id"
secret = "your_client_secret"
配置完成后重启 hz serve,访问 https://localhost:8181/horizon/auth_methods 即可看到当前可用的认证方式列表,例如:
{
github: "/horizon/github"
}
浏览器访问 /horizon/github 将开始认证流程;认证成功后浏览器会带着 ?horizon_token= 查询参数重定向回开发服务器根路径,用户即被视为已认证。若认证失败,则会在查询参数中携带错误信息返回。
使用客户端库构建实时应用
hz init 生成的 dist/index.html 已经引入了由 Horizon Server 托管的客户端库,并完成了基本连接:
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<script src="/horizon/horizon.js"></script>
<script>
var horizon = Horizon();
horizon.onReady(function() {
document.querySelector('h1').innerHTML = 'It works!'
});
horizon.connect();
</script>
</head>
<body>
<marquee><h1></h1></marquee>
</body>
</html>
Horizon() 构造函数定义于 client/src/index.js,返回一个可调用的函数对象:horizon('messages') 即创建名为 messages 的集合。客户端 API 基于 RxJS Observable 设计,fetch() 返回一次性的结果流,watch() 返回持续推送的实时流。核心集合操作(实现于 client/src/ast.js):
- 存储:
.store(docs)完全替换或插入;.insert()仅在文档不存在时插入;.upsert()更新或插入;.update()更新(要求存在);.replace()整体替换(要求存在);.remove(id)/.removeAll([ids])删除。 - 查询:
.find(obj)精确匹配单个文档;.findAll(...objs)按索引批量匹配;.order(fields, dir)排序;.above(spec, bound)/.below(spec, bound)范围边界(bound为closed或open);.limit(n)限制条数。
一个完整的实时聊天数据层示例:
let chats = [];
// 订阅整个集合的实时变更,每次变更返回完整结果数组
chat.watch().subscribe(chats => {
renderChats(chats) // 直接用新数组替换前端状态
}, error => console.log(error))
// 存储一条新消息
chat.store({ text: 'Hello Horizon!', datetime: new Date() })
.subscribe(result => console.log(result), error => console.log(error))
// 按时间升序获取快照
chat.order('datetime').fetch().subscribe(
newChats => { chats = chats.concat(newChats) },
error => console.log(error),
() => console.log('All results received!'))
连接状态可通过 horizon.onReady() 与 horizon.onDisconnected() 订阅;清除本地所有认证令牌则调用 Horizon.clearAuthTokens()(参见 client/README.md)。
将现有应用接入 Horizon
如果你的项目已有独立的前端构建流程,不必把所有文件搬进 dist。两种接入方式:
- 直接引用服务器托管的客户端库(最简单):页面加载
localhost:8181/horizon/horizon.js,并指定连接主机:
const horizon = Horizon({host: 'localhost:8181'});
- 作为 npm 依赖安装:
npm install @horizon/client,适用于 webpack 等模块化构建。
推荐方式 1 的原因:客户端库版本始终与当前运行的服务器版本保持一致,避免版本错配。
协议与扩展能力
WebSocket 协议
Horizon 客户端与服务器之间通过 WebSocket 通信,协议定义在 protocol.md,连接使用的协议名为 rethinkdb-horizon-v0(见 server/src/server.js)。任何请求都必须先完成握手(handshake),握手消息携带 request_id、认证 method(unauthenticated/anonymous/token)及可选的 token,服务器在握手响应中返回与该连接绑定的 access token(参见 protocol.md 与 server/src/auth.js)。
常规请求统一为 { request_id, type, options } 结构,type 为 query、subscribe、store、insert、update、upsert、replace、remove、end_subscription 或 keepalive。服务端使用 Joi 对每条消息进行严格校验(server/src/schema/horizon_protocol.js),客户端在 client/src/socket.js 的 hzRequest() 中负责将响应流转换为 Observable,并处理 synced/complete 状态、错误与心跳(keepalive,默认每 60 秒一次,可在 Horizon({keepalive}) 中调整)。
扩展 Horizon Server
当应用超出纯客户端 API 的需求时,可以用流行的 Node Web 框架扩展 Horizon Server。仓库 examples 提供了三种集成示例:
- express-server(Express)
- hapi-server(Hapi)
- koa-server(Koa)
同时,examples 目录还包含 CycleJS、RiotJS、React、Vue 等多种前端框架的聊天/待办应用示例(如 react-chat-app、vue-chat-app),可直接参考其集成方式。
路线图:即将推出的服务
README 列出了未来版本可能推出的服务:
- Session management —— 管理浏览器会话与会话信息;
- Geolocation —— 简化构建位置感知应用的 API;
- Presence —— 检测指定用户的在线状态并与其他用户共享;
- Plugins —— 以一致、可发现的方式用用户自定义服务扩展 Horizon;
- Backend —— 将自定义后端代码与 Horizon server/client 集成的 API/协议。
以上均为官方规划中的能力,尚未在当前仓库中实现,请以仓库实际内容为准。
开源与参与贡献
Horizon server、client 与 cli 均以 MIT 许可证开源(见 LICENSE 与 README.md 的 FAQ)。社区贡献者可以通过 CONTRIBUTING.md 了解参与方式。仓库同时提供 Dockerfile 与 docker-compose.dev.yml / docker-compose.prod.yml,便于容器化部署;circle.yml 则用于持续集成。
结语
Horizon 的核心价值在于:把"实时应用后端"从复杂的多系统编排中抽象出来,通过 Subscribe、Auth、Identity、Permissions 四大服务,配合 hz 命令行与 RxJS 风格的客户端 API,让前端开发者专注于业务本身。而 RethinkDB 作为底层存储与 changefeed 引擎,为实时数据流提供了可靠的支撑,也为应用后续演进到自定义后端保留了清晰路径。理解其架构(server 中间件 + client 协议包装 + CLI 工具链)与配置体系(.hz/config.toml、.hz/schema.toml、.hz/secrets.toml),是高效使用 Horizon 的关键起点。