TeXlyre 自托管部署指南:搭建私有 WebRTC 信令服务器与 TeX Live 包服务

原创2026-10-22 21:49:461,905 阅读

TeXlyre 自托管部署指南:搭建私有 WebRTC 信令服务器与 TeX Live 包服务

TeXlyre 是一款 local-first(本地优先)的 LaTeX & Typst 实时协作 Web 编辑器,支持 WebRTC 点对点协作与离线编辑。本文带你从零完成 TeXlyre 自托管部署:搭建私有 WebRTC 信令服务器、TeX Live 按需包服务与 FilePizza 文件同步服务,让你的团队数据完全留在自己的服务器内。

TeXlyre 自托管部署主界面:左侧 Typst 源码,右侧实时编译输出

为什么需要自托管?

TeXlyre 的默认部署由以下几类后端服务支撑(项目方使用开源信令服务器 + Cloudflare Tunnel 对外提供服务):

服务 作用
Y-WebRTC 信令服务器 协助两台浏览器建立 WebRTC 点对点连接
PeerJS 信令服务器 备用信令通道
FilePizza 文件同步服务器 协作间大文件点对点传输的信令
TeX Live 2020 包下载服务器 SwiftLaTeX 引擎按需下载 TeX Live 2020 宏包
TeX Live 2026 包下载服务器 BusyTeX 引擎按需下载 TeX Live 2026 宏包

自建这些服务后,你可以:

  • 🔒 数据隐私:信令服务器只中转连接信息,不经过第三方;
  • ⚡ 更低的协作延迟:信令服务器部署在局域网内,建连更快;
  • 📦 离线宏包能力:TeX Live 包服务内网可访问时,浏览器端 WASM 编译器(SwiftLaTeX / BusyTeX)无需依赖公网。

💡 关键概念:WebRTC 需要"信令服务器"来帮两个浏览器交换连接参数,但文档内容本身走点对点直连,不经过服务器。

部署前准备

  • Node.js 20+:TeXlyre 前端基于 Vite 构建;
  • 现代浏览器:Chrome / Edge 功能最全(支持 File System Access API 与 WebRTC);
  • 一台可长期运行的服务器:用于托管信令与包下载服务。

克隆代码仓库:

git clone https://gitcode.com/gh_mirrors/te/texlyre
cd texlyre

第一步:部署 TeXlyre 前端

在仓库根目录执行构建与启动:

npm install
npm run start

启动后访问 http://localhost:4173,创建新项目即可开始编辑。分享形如 http://你的域名/#yjs:abc123 的链接,协作者打开即自动加入同一个 Yjs 协作房间。

项目根目录的 texlyre.config.ts 是自托管的核心配置文件,其中 userdata.local.settings 段落已内置了一组"全部指向本机服务"的地址:

local: {
    settings: {
        collabSignalingServers: 'ws://localhost:4444/',   // WebRTC 信令
        fileSyncServerUrl: 'http://localhost:8080',      // FilePizza 文件同步
        latexBusytexEndpoint: 'http://localhost:8070',   // TeX Live 2026 包服务
        latexTexliveEndpoint: 'http://localhost:5004',   // TeX Live 2020 包服务
    }
}

对照修改为你的服务器地址后,npm run start 构建出的前端就会默认连接你的私有服务。配置优先级为 default < local < mobile,详见 texlyre.config.ts。

第二步:搭建私有 WebRTC 信令服务器

TeXlyre 基于 y-webrtc 实现协作同步。浏览器端在 src/extensions/yjs/CollabWebrtc.ts 中创建 WebrtcProvider 时,会把设置的信令服务器列表传给 Yjs,由其完成 SDP 交换、建立 P2P 通道。

信令地址对应的设置项注册在 src/settings/registerCollabSettings.ts,关键配置如下:

设置 ID 说明
collab-provider-type webrtc(点对点,默认)或 websocket(经服务器中转)
collab-signaling-servers Yjs WebRTC 信令服务器 URL,逗号分隔支持多节点
collab-websocket-server 使用 websocket 模式时的服务器地址
collab-awareness-timeout 判定其他用户离线的超时秒数,默认 30
collab-auto-reconnect 断线后是否自动重连

TeXlyre 设置面板中的 Signaling servers 信令服务器配置项

部署建议(3 个要点):

  1. 选择信令服务器:TeXlyre 官方基础设施提供基于 y-webrtc 的 Y-WebRTC Signaling、基于 peerjs-server 的 PeerJS Signaling 两类实现,按其基础设施仓库的说明用 Docker 部署即可;
  2. 对外暴露:官方使用 Cloudflare Tunnel 把本地服务暴露为 wss:// 地址;你也可以用 Nginx + 证书做反向代理,记得放行 WebSocket(Upgrade 头);
  3. 配置到 TeXlyre:在设置面板"Collaboration → Real-time Synchronization"中,把 Signaling servers 填成你的地址,例如 ws://signaling.your-domain.com/。多个地址用逗号分隔可实现故障转移——代码中会用 split(',') 拆分为数组(见 src/services/CollabService.ts)。

⚠️ 若两端浏览器都处于复杂 NAT 后、P2P 打洞失败,可把 collab-provider-type 切换为 websocket,改走服务器中转,代价是延迟略高。

第三步:部署 TeX Live 包服务

TeXlyre 在浏览器内用 WASM 引擎编译 LaTeX(SwiftLaTeX 对应 TeX Live 2020,BusyTeX 对应 TeX Live 2026),但宏包太大无法全部打进前端,因此会按文档实际用到的 \usepackage 向"包下载服务器"按需请求。

相关设置项定义在 src/settings/registerLatexSettings.ts:

设置 ID 默认值 说明
latex-texlive-endpoint http://texlive.localhost:8082 TeX Live 2020 按需包下载地址(SwiftLaTeX 引擎使用),留空即禁用
latex-busytex-endpoint http://texlive2026.localhost:8082 TeX Live 2026 按需包下载地址(BusyTeX 引擎使用)
latex-busytex-bundles recommended BusyTeX 预载包集合,更大的集合离线覆盖更多宏包但下载更慢
latex-engine pdftex 可选 pdfTeX / XeTeX(2020)或 BusyTeX 的 pdfTeX / XeTeX / LuaTeX(2026)

TeXlyre 编译选项面板:选择 XeTeX 引擎进行 LaTeX 编译

部署建议:

  • TeX Live 2020 服务基于 SwiftLaTeX 的 Texlive-On-Demand 项目,TeX Live 2026 服务是 TeXlyre 的定制实现,两者都是"静态包仓库 + HTTP 下载"的轻量服务,用 Docker 或 Nginx 托管静态目录即可;
  • 服务器建议只暴露 HTTPS 只读访问,无需写权限;
  • 部署完成后在编译选项中选择引擎(如 XeTeX),编译时若提示宏包缺失,检查 latex-texlive-endpoint / latex-busytex-endpoint 是否指向了正确的服务。

附赠:FilePizza 文件同步服务器

协作时传输图片、字体等大文件,TeXlyre 使用 FilePizza 走 P2P 通道,同样需要一个信令服务器。设置项 file-sync-server-url 注册在 src/settings/registerFileSyncSettings.ts,对应 texlyre.config.ts 中的 fileSyncServerUrl。官方实现基于 filepizza-server(PeerJS 内核)。部署后在"Collaboration → File Synchronization"中填入你的地址即可。

TeXlyre 文件同步服务就绪后提示已准备完成文件下载

部署完成后的验证清单

按顺序逐项确认,全部通过即代表私有环境搭建成功:

  1. ✅ 打开项目链接,协作者的彩色光标实时出现(WebRTC 信令连通);
  2. ✅ 编译一个使用了较多宏包的 LaTeX 文档,宏包从你的包服务按需下载成功(TeX Live 服务连通);
  3. ✅ 在协作会话中发送一张图片,接收方自动出现在文件树中(FilePizza 连通);
  4. ✅ 断网重连后,勾选了自动重连的项目恢复同步(collab-auto-reconnect 生效)。

小结

TeXlyre 的自托管 = 静态前端 + 信令服务 + 包下载服务三件套:

  • 前端:npm run start,用 texlyre.config.ts 的 local 段统一指向私有地址;
  • WebRTC 信令:部署 y-webrtc 服务器,填入 collab-signaling-servers,支持逗号分隔多节点;
  • TeX Live 包服务:分别部署 2020/2026 两套按需下载服务,对应 latex-texlive-endpoint 与 latex-busytex-endpoint。

完成后,团队即可在内网享受完整的 LaTeX / Typst 实时协作体验,而文档内容始终以点对点与本地优先的方式流转。

登录后查看全文
texlyre