TeXlyre 自托管部署指南:搭建私有 WebRTC 信令服务器与 TeX Live 包服务
TeXlyre 自托管部署指南:搭建私有 WebRTC 信令服务器与 TeX Live 包服务
TeXlyre 是一款 local-first(本地优先)的 LaTeX & Typst 实时协作 Web 编辑器,支持 WebRTC 点对点协作与离线编辑。本文带你从零完成 TeXlyre 自托管部署:搭建私有 WebRTC 信令服务器、TeX Live 按需包服务与 FilePizza 文件同步服务,让你的团队数据完全留在自己的服务器内。
为什么需要自托管?
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 |
断线后是否自动重连 |
部署建议(3 个要点):
- 选择信令服务器:TeXlyre 官方基础设施提供基于 y-webrtc 的 Y-WebRTC Signaling、基于 peerjs-server 的 PeerJS Signaling 两类实现,按其基础设施仓库的说明用 Docker 部署即可;
- 对外暴露:官方使用 Cloudflare Tunnel 把本地服务暴露为
wss://地址;你也可以用 Nginx + 证书做反向代理,记得放行 WebSocket(Upgrade头); - 配置到 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) |
部署建议:
- 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"中填入你的地址即可。
部署完成后的验证清单
按顺序逐项确认,全部通过即代表私有环境搭建成功:
- ✅ 打开项目链接,协作者的彩色光标实时出现(WebRTC 信令连通);
- ✅ 编译一个使用了较多宏包的 LaTeX 文档,宏包从你的包服务按需下载成功(TeX Live 服务连通);
- ✅ 在协作会话中发送一张图片,接收方自动出现在文件树中(FilePizza 连通);
- ✅ 断网重连后,勾选了自动重连的项目恢复同步(
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 实时协作体验,而文档内容始终以点对点与本地优先的方式流转。



