SWUFE-DB-Group/TexLite · 上手攻略

  • 仓库：SWUFE-DB-Group/TexLite
  • 链接：https://github.com/SWUFE-DB-Group/TexLite
  • 分类：academic-writing
  • 作者：Jay
  • 更新：2026-08-31

是什么

TexLite 是西南财经大学 DB 研究组开源的轻量级自托管协作 LaTeX 编辑器，旨在为小型可信研究团队提供 Overleaf 的本地替代方案。核心技术栈：React 前端 + CodeMirror 编辑器 + Fastify API + SQLite 本地持久化 + Yjs 实时协作 + PM2 进程管理。默认配置仅需 Node.js 进程、SQLite 数据库和本地文件，不依赖 Redis、MongoDB 或反向代理。

⚠️ 版本注意：README 要求 Node.js 24 或更新版本（截至 2026 年 8 月，Node.js 24 仍处于_CURRENT 分支，TLS 截止日期为 2026-10-28，生产环境需确认 Node.js 24 已为 LTS，或关注官方 release 动态）。

解决什么问题

Overleaf 的痛点： - 共享托管版：高峰期队列排队、响应慢、可能超时 - Overleaf Community Edition（开源版）：Docker 部署路径较复杂，部分高级功能（如 source comments）属于 Server Pro 功能

TexLite 对应的解决思路： - 团队完全掌控数据存储位置、TeX 更新节奏和协作流程 - 不要求庞大的 Docker 镜像栈，适合小团队内网/私有服务器部署 - 支持源码级评论（source comments）——Overleaf 免费版不支持的功能 - 提供项目历史记录与可选的 Git/GitHub 备份

快速安装

依赖要求

依赖 说明 必要性
Node.js 24+ npm 全局安装用 必须
latexmk LaTeX 编译协调工具 必须
pdflatex / xelatex / lualatex 任选一种 TeX 引擎 必须
Git GitHub 备份集成用 可选
harper-cli 拼写/语法检查 可选

安装前检查命令：

texlite requirements
# 或手动逐一检查：
node --version        # 需要 Node.js 24+
npm --version
latexmk --version
xelatex --version     # 或 pdflatex / lualatex
git --version         # 可选

npm 全局安装（推荐）

npm install --global texlite
texlite init          # 初始化配置、创建首个管理员账户
texlite start         # 启动服务（后台 PM2 托管）
texlite status        # 查看运行状态

服务启动后访问：http://127.0.0.1:3000

初始化时需要创建第一个管理员账户（无公开注册入口，需要通过 init 创建管理员后再添加其他用户）。

升级与运维

npm update --global texlite
texlite restart

texlite logs          # 查看日志
texlite stop
texlite restart

texlite doctor        # 详细诊断表（必填/可选依赖状态）
texlite config        # 打印当前生效的配置路径与值

Docker 部署（无 Node.js / TeX 环境时）

git clone https://github.com/SWUFE-DB-Group/TexLite-Docker.git
cd texlite-docker
cp deployment.example.json deployment.json
# 编辑 deployment.json（必填项：端口、数据路径等）
./scripts/compose.sh pull
./scripts/compose.sh up -d
# 访问 http://127.0.0.1:3040

⚠️ Docker 镜像 bundls Node.js、TeX Live、Git 等运行时依赖，镜像体积更大（约数 GB），适合没有预装 TeX 环境的服务器。

核心用法

项目管理

  • 创建项目（支持文件夹结构）
  • ZIP 导入/导出
  • 项目标签（tags）、私有/共享设置
  • 项目所有权转移
  • 归档

编辑功能

  • CodeMirror 编辑器，支持 LaTeX / BibTeX 语法高亮、折叠、自动补全
  • 可选 Vim 模式
  • 格式化（tex-fmt WASM，在浏览器端执行，无需 host 二进制）
  • 拼写/语法检查：可选 host harper-cli，缺失时回退到浏览器原生英文拼写检查
  • SyncTeX 导航：源码 ↔ PDF 双向跳转

实时协作

# 协作者无需特殊配置，打开同一项目 URL 即可实时同步
# Yjs + y-websocket 驱动，y-codemirror.next 渲染
  • 在线用户 presence（谁正在编辑）
  • 源码级评论（comment）：锚定到具体源码位置，评论者可 reply、resolve；支持权限控制（评论者不能修改源码）
  • 多人同时编辑同一文件

LaTeX 编译

# 项目级 latexmkrc 可自定义编译流程
# 可选引擎：pdflatex（默认）/ xelatex / lualatex
# 编译结果（PDF）缓存在项目目录，成功编译后直接提供下载

编译诊断信息结构化呈现；失败时清晰报错。

历史与备份

# 每个项目独立历史记录
# 可选：Git 本地备份 + GitHub REST API 推送到远程仓库
# Git 仅在启用集成时检查，不需要始终存在

个人引用库（BibTeX）

  • 每人独立的私有引用库，存储在 SQLite，与项目文件独立
  • .bib 编辑器 tab：浏览器端解析完整 BibTeX 条目，保存时保留原文格式
  • 引用 key 大小写不敏感，同一 key 不能重复创建
  • 并发修改冲突检测（基于 revision 字段）

典型适用场景

  1. 小型研究团队内网部署：实验室/课题组有自己的服务器，不希望文档上云
  2. Overleaf 替代：对源码评论（source comments）有需求，且不想付 Server Pro 费用
  3. 数据安全合规：论文投稿前文档不能离开内网环境
  4. TeX 环境自主管理：团队希望自己控制 TeX Live 版本更新，不受 Overleaf 更新节奏影响
  5. 已有 TeX 环境：团队成员本机已有完整 TeX Live 安装，TexLite 直接复用，无需额外配置

不适合：大型团队需要多实例横向扩展、公网无认证部署（安全边界不适配）、需要 Overleaf 高级功能（如 track-changes 企业版）场景。

坑与注意

⚠️ 安全边界（最重要）

TexLite is not a compiler sandbox: LaTeX and an enabled project latexmkrc can execute powerful local behaviour. Keep the default 127.0.0.1 bind unless you add the authentication, network controls, and isolated compiler environment appropriate for an untrusted deployment.

  • 默认绑定 127.0.0.1，不暴露到公网
  • 无内置认证（需要自己配网络层认证）
  • 不能用于不可信用户环境：latexmkrc 可以执行任意本地命令
  • 如果需要公网暴露，必须额外配置：认证 + 网络隔离 + 编译器沙箱

⚠️ Node.js 24 依赖

  • README 明确要求 Node.js 24+，但截至 2026-08-31 Node.js 24 尚不是 LTS
  • 如果服务器 OS 包管理器 Node.js 版本低于 24，需通过 nvm / fnm 安装 Node.js 24
  • npm install --global texlite 全局安装后，PM2 随包 bundls，无需单独安装 PM2

⚠️ 单实例限制

  • 不支持集群/多进程：协作房间、编译队列、SQLite 数据库均为进程本地
  • 启动时通过 .texlite.lock 文件做单实例互斥；第二个进程会被拒绝
  • 多台机器共享同一 LaTeX 项目场景不适用

⚠️ 协作文档规模

  • 设计目标为"小型可信研究团队"，非企业级多团队协作
  • 协作者数量建议控制在 5-10 人以内（性能未明确测试上限，但无分布式设计）

⚠️ 引用库不共享

  • 每位用户的引用库是私有的，其他用户无法查看/搜索/导入/编辑
  • 团队共享参考文献需要通过 .bib 文件导入项目，而非共享引用库

其他限制

  • 不支持 track-changes（Overleaf 企业版功能）
  • 编译速度依赖 host 的 TeX 引擎性能
  • 历史记录是 TexLite 自身记录，非 Git diff，Git 备份可补充提供真正的版本历史

与同类对比

维度 TexLite Overleaf（托管版） Overleaf CE（开源版） VS Code + LaTeX Workshop
部署方式 自托管（轻量） SaaS 自托管（Docker heavy） 本地桌面
协作 ✅ Yjs 实时 ✅ 实时 ✅ 实时 ❌（需配合 Liveshare）
源码评论 ✅ ❌（免费版无） ❌（Server Pro） ❌
依赖复杂度 低（仅 Node.js + SQLite） 无需管理 高（Overleaf Toolkit） 中（VS Code + TeX Live）
数据控制 完全自主 在 Overleaf 服务器 完全自主 完全自主
适用规模 小团队（~5-10人） 任意规模 中型团队 个人桌面为主
高级功能 基础协作+历史 丰富生态+模板 同托管版 丰富插件生态
适合场景 内网/数据合规 即开即用 自托管+功能全 个人开发者

一句话推荐结论

自托管 LaTeX 协作编辑器，轻量级单进程 + SQLite，推荐给有内网/数据合规需求、团队规模 10 人以内、不需要 Overleaf 企业功能的学术写作团队。 ⚠️ 注意安全边界（默认仅本地访问）和 Node.js 24 依赖，生产部署前验证兼容性。