2026/8/20 19:10:23
FEATURED · 精选文章 
y-websocket 服务端部署指南LevelDB 持久化与 HTTP 回调配置详解【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websockety-websocket 是 Yjs 生态中经典的WebSocket 服务端连接器Websocket Connector for Yjs负责在多个客户端之间实时同步共享文档、光标等协作信息。本文面向新手手把手讲解y-websocket 服务端部署、LevelDB 持久化配置与HTTP 回调配置三大核心环节帮你用最快速度搭建一个数据不丢失、可对接业务系统的实时协作后端。为什么需要自建 y-websocket 服务端y-websocket 采用经典的客户端-服务端模型所有客户端连接同一个 WebSocket 端点服务端负责把文档更新document updates和 awareness 信息如在线光标分发给其他客户端。自建服务端的好处很直接集中鉴权WebSocket 会携带 Header 和 Cookie可直接复用你现有的登录认证体系️数据落地配合 LevelDB 把文档持久化到磁盘刷新页面、重启服务数据都不丢业务打通通过 HTTP 回调把文档变更实时推送给你的后端服务便于做保存、索引、通知官方仓库的默认实现是内存版后端可持久化到数据库但不适合大规模横向扩展。如果团队规模较大可再评估 y-redis 方案绝大多数中小项目直接用 y-websocket 自带服务端即可。部署前的环境准备y-websocket 服务端运行在 Node.js 环境中官方要求依赖版本要求Node.js≥ 16.0.0npm≥ 8.0.0先用命令确认环境node -v npm -v然后克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/yw/y-websocket cd y-websocket npm install快速启动y-websocket 服务端基础部署服务端入口是bin/server.cjs它基于ws库创建 WebSocket Server并用 HTTP 服务器处理升级请求。直接启动HOSTlocalhost PORT1234 npm start启动后终端会输出running at localhost on port 1234。默认端口 1234默认主机 localhost都可以通过环境变量覆盖。一个最简单的客户端连接示例import * as Y from yjs import { WebsocketProvider } from y-websocket const doc new Y.Doc() const wsProvider new WebsocketProvider(ws://localhost:1234, my-roomname, doc) wsProvider.on(status, event { console.log(event.status) // connected / disconnected })客户端源码在 src/y-websocket.js核心逻辑由WebsocketProvider类完成包括自动重连指数退避、状态事件、跨标签页 BroadcastChannel 通信等。开启 LevelDB 持久化让协作数据不丢失 默认服务端把文档放在内存里进程一重启所有数据就没了。要持久化只需设置一个环境变量YPERSISTENCE指向 LevelDB 数据目录HOSTlocalhost PORT1234 YPERSISTENCE./dbDir node ./node_modules/y-websocket/bin/server.cjsLevelDB 持久化配置要点存储内容所有文档的增量更新updatesYjs 通过 CRDT 结构天然支持增量合并目录选择./dbDir会自动创建生产环境建议放到独立磁盘或挂载卷组合使用可以同时开启 LevelDB 持久化和 HTTP 回调两者互不冲突验证是否生效很简单服务端写入几个文档后重启进程再用客户端重新连接同一房间历史内容会自动同步回来说明数据已经落盘。持久化依赖是可选安装的y-leveldb包无需额外配置。多节点高可用场景下可进一步研究 y-redis 方案见仓库 README 说明。HTTP 回调配置详解把更新推送给业务服务 如果你需要在文档更新时通知自己的后端比如自动保存、触发索引、通知用户开启 HTTP 回调即可。它的工作方式是文档收到更新后防抖debounce发送一个 POST 请求到指定 URL并在请求体中携带共享对象的最新数据。最小 HTTP 回调配置CALLBACK_URLhttp://localhost:3000/ CALLBACK_OBJECTS{prosemirror:XmlFragment} npm start这条命令的含义是文档更新 2 秒后默认防抖等待向localhost:3000POST 一个 JSON其中包含名为prosemirror的XmlFragment类型共享对象的序列化内容。回调参数速查环境变量作用默认值CALLBACK_URL回调服务器地址必填不填则回调关闭无CALLBACK_DEBOUNCE_WAIT更新后等待多久再回调毫秒2000CALLBACK_DEBOUNCE_MAXWAIT防抖期间最长等待时间毫秒10000CALLBACK_TIMEOUTHTTP 请求超时时间毫秒5000CALLBACK_OBJECTS指定要读取的共享对象 JSON{对象名:对象类型}{}支持的共享对象类型Array、Map、Text、XmlFragment、XmlElement。回调请求体格式服务端 POST 的 JSON 结构如下{ room: my-roomname, data: { prosemirror: { type: XmlFragment, content: { ...: 序列化后的文档内容 } } } }注意官方实现没有重试机制如果CALLBACK_URL不可用请求会直接失败超时由CALLBACK_TIMEOUT控制。回调与防抖逻辑的源码在 bin/callback.cjs其中callbackHandler负责组装数据callbackRequest负责发起 POST 请求。环境变量总览一张表看懂全部配置变量用途默认值HOST监听主机localhostPORT监听端口1234YPERSISTENCELevelDB 持久化目录不设置则不持久化无CALLBACK_URLHTTP 回调地址无CALLBACK_DEBOUNCE_WAIT回调防抖等待2000msCALLBACK_DEBOUNCE_MAXWAIT回调最大等待10000msCALLBACK_TIMEOUT回调超时5000msCALLBACK_OBJECTS回调携带的共享对象{}用 Docker 一键部署 y-websocket 服务端 仓库自带 Dockerfile基于node:12-alpine暴露 1234 端口。构建镜像docker build -t y-websocket .运行并开启 LevelDB 持久化 HTTP 回调docker run -d -p 1234:1234 \ -e YPERSISTENCE/data/db \ -e CALLBACK_URLhttp://your-server:3000/callback \ -e CALLBACK_OBJECTS{prosemirror:XmlFragment} \ -v yws-data:/data \ y-websocket提示通过-v挂载卷可以保证容器重启后持久化数据依然存在建议把CALLBACK_URL指向内网地址避免回环。常见问题排查 Q1启动后客户端连不上检查 HOST/PORT 是否与客户端 URL 一致确认防火墙放行了对应端口。HOST 建议使用0.0.0.0以便外部访问。Q2重启后数据丢了确认已设置YPERSISTENCE且目录有写权限Docker 场景务必挂载数据卷。Q3回调没触发先确认CALLBACK_URL已设置且可访问再确认CALLBACK_OBJECTS里写的共享对象名称、类型与客户端创建的一致。由于没有重试逻辑建议回调端先保证可用再观察日志。Q4想在 Node.js 客户端连接WebSocket Provider 需要 WebSocket 对象可用ws包 polyfill{ WebSocketPolyfill: require(ws) }。总结y-websocket 服务端部署并不复杂一个npm start即可跑通实时协作加上YPERSISTENCE环境变量就能获得 LevelDB 持久化能力再配合CALLBACK_URL系列变量即可与业务系统打通。按照本文的配置步骤你可以在半小时内搭建一个具备持久化与回调能力的生产级协作后端为 Yjs 实时编辑应用提供稳定可靠的服务端支撑。【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
y-websocket 服务端部署指南：LevelDB 持久化与 HTTP 回调配置详解
y-websocket 服务端部署指南LevelDB 持久化与 HTTP 回调配置详解【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websockety-websocket 是 Yjs 生态中经典的WebSocket 服务端连接器Websocket Connector for Yjs负责在多个客户端之间实时同步共享文档、光标等协作信息。本文面向新手手把手讲解y-websocket 服务端部署、LevelDB 持久化配置与HTTP 回调配置三大核心环节帮你用最快速度搭建一个数据不丢失、可对接业务系统的实时协作后端。为什么需要自建 y-websocket 服务端y-websocket 采用经典的客户端-服务端模型所有客户端连接同一个 WebSocket 端点服务端负责把文档更新document updates和 awareness 信息如在线光标分发给其他客户端。自建服务端的好处很直接集中鉴权WebSocket 会携带 Header 和 Cookie可直接复用你现有的登录认证体系️数据落地配合 LevelDB 把文档持久化到磁盘刷新页面、重启服务数据都不丢业务打通通过 HTTP 回调把文档变更实时推送给你的后端服务便于做保存、索引、通知官方仓库的默认实现是内存版后端可持久化到数据库但不适合大规模横向扩展。如果团队规模较大可再评估 y-redis 方案绝大多数中小项目直接用 y-websocket 自带服务端即可。部署前的环境准备y-websocket 服务端运行在 Node.js 环境中官方要求依赖版本要求Node.js≥ 16.0.0npm≥ 8.0.0先用命令确认环境node -v npm -v然后克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/yw/y-websocket cd y-websocket npm install快速启动y-websocket 服务端基础部署服务端入口是bin/server.cjs它基于ws库创建 WebSocket Server并用 HTTP 服务器处理升级请求。直接启动HOSTlocalhost PORT1234 npm start启动后终端会输出running at localhost on port 1234。默认端口 1234默认主机 localhost都可以通过环境变量覆盖。一个最简单的客户端连接示例import * as Y from yjs import { WebsocketProvider } from y-websocket const doc new Y.Doc() const wsProvider new WebsocketProvider(ws://localhost:1234, my-roomname, doc) wsProvider.on(status, event { console.log(event.status) // connected / disconnected })客户端源码在 src/y-websocket.js核心逻辑由WebsocketProvider类完成包括自动重连指数退避、状态事件、跨标签页 BroadcastChannel 通信等。开启 LevelDB 持久化让协作数据不丢失 默认服务端把文档放在内存里进程一重启所有数据就没了。要持久化只需设置一个环境变量YPERSISTENCE指向 LevelDB 数据目录HOSTlocalhost PORT1234 YPERSISTENCE./dbDir node ./node_modules/y-websocket/bin/server.cjsLevelDB 持久化配置要点存储内容所有文档的增量更新updatesYjs 通过 CRDT 结构天然支持增量合并目录选择./dbDir会自动创建生产环境建议放到独立磁盘或挂载卷组合使用可以同时开启 LevelDB 持久化和 HTTP 回调两者互不冲突验证是否生效很简单服务端写入几个文档后重启进程再用客户端重新连接同一房间历史内容会自动同步回来说明数据已经落盘。持久化依赖是可选安装的y-leveldb包无需额外配置。多节点高可用场景下可进一步研究 y-redis 方案见仓库 README 说明。HTTP 回调配置详解把更新推送给业务服务 如果你需要在文档更新时通知自己的后端比如自动保存、触发索引、通知用户开启 HTTP 回调即可。它的工作方式是文档收到更新后防抖debounce发送一个 POST 请求到指定 URL并在请求体中携带共享对象的最新数据。最小 HTTP 回调配置CALLBACK_URLhttp://localhost:3000/ CALLBACK_OBJECTS{prosemirror:XmlFragment} npm start这条命令的含义是文档更新 2 秒后默认防抖等待向localhost:3000POST 一个 JSON其中包含名为prosemirror的XmlFragment类型共享对象的序列化内容。回调参数速查环境变量作用默认值CALLBACK_URL回调服务器地址必填不填则回调关闭无CALLBACK_DEBOUNCE_WAIT更新后等待多久再回调毫秒2000CALLBACK_DEBOUNCE_MAXWAIT防抖期间最长等待时间毫秒10000CALLBACK_TIMEOUTHTTP 请求超时时间毫秒5000CALLBACK_OBJECTS指定要读取的共享对象 JSON{对象名:对象类型}{}支持的共享对象类型Array、Map、Text、XmlFragment、XmlElement。回调请求体格式服务端 POST 的 JSON 结构如下{ room: my-roomname, data: { prosemirror: { type: XmlFragment, content: { ...: 序列化后的文档内容 } } } }注意官方实现没有重试机制如果CALLBACK_URL不可用请求会直接失败超时由CALLBACK_TIMEOUT控制。回调与防抖逻辑的源码在 bin/callback.cjs其中callbackHandler负责组装数据callbackRequest负责发起 POST 请求。环境变量总览一张表看懂全部配置变量用途默认值HOST监听主机localhostPORT监听端口1234YPERSISTENCELevelDB 持久化目录不设置则不持久化无CALLBACK_URLHTTP 回调地址无CALLBACK_DEBOUNCE_WAIT回调防抖等待2000msCALLBACK_DEBOUNCE_MAXWAIT回调最大等待10000msCALLBACK_TIMEOUT回调超时5000msCALLBACK_OBJECTS回调携带的共享对象{}用 Docker 一键部署 y-websocket 服务端 仓库自带 Dockerfile基于node:12-alpine暴露 1234 端口。构建镜像docker build -t y-websocket .运行并开启 LevelDB 持久化 HTTP 回调docker run -d -p 1234:1234 \ -e YPERSISTENCE/data/db \ -e CALLBACK_URLhttp://your-server:3000/callback \ -e CALLBACK_OBJECTS{prosemirror:XmlFragment} \ -v yws-data:/data \ y-websocket提示通过-v挂载卷可以保证容器重启后持久化数据依然存在建议把CALLBACK_URL指向内网地址避免回环。常见问题排查 Q1启动后客户端连不上检查 HOST/PORT 是否与客户端 URL 一致确认防火墙放行了对应端口。HOST 建议使用0.0.0.0以便外部访问。Q2重启后数据丢了确认已设置YPERSISTENCE且目录有写权限Docker 场景务必挂载数据卷。Q3回调没触发先确认CALLBACK_URL已设置且可访问再确认CALLBACK_OBJECTS里写的共享对象名称、类型与客户端创建的一致。由于没有重试逻辑建议回调端先保证可用再观察日志。Q4想在 Node.js 客户端连接WebSocket Provider 需要 WebSocket 对象可用ws包 polyfill{ WebSocketPolyfill: require(ws) }。总结y-websocket 服务端部署并不复杂一个npm start即可跑通实时协作加上YPERSISTENCE环境变量就能获得 LevelDB 持久化能力再配合CALLBACK_URL系列变量即可与业务系统打通。按照本文的配置步骤你可以在半小时内搭建一个具备持久化与回调能力的生产级协作后端为 Yjs 实时编辑应用提供稳定可靠的服务端支撑。【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
