很多写论文、做数学建模、投稿期刊的人都会在某个时刻遇到同一个尴尬换了一台电脑LaTeX 环境却装不回来了。本地装 TeX Live 动辄几个 GBVSCode 插件版本不匹配模板编译到一半报缺少宏包最后只能登录在线工具又遇到文件数量限制和编译超时。TexLite 这类“轻量级 self-hosted LaTeX workspace”之所以值得关注不只是因为它能跑 LaTeX而是它把“环境一致性”和“工作区所有权”放到了开发者手里。自托管意味着团队可以把论文、模板、编译环境统一放在自己的服务器或内网里浏览器打开就能写换电脑不再是一个问题。这篇文章会从痛点出发讲清楚 LaTeX workspace 是什么、为什么需要自托管再给出完整的部署、使用和排错路径。即使你之前没有接触过自托管工具也能照着跑通一个可用的 LaTeX 工作区。1. 这篇文章真正要解决的问题先说结论TeX Live VSCode LaTeX Workshop 依然是本地写作的可靠方案但它在“多人协作、跨设备、模板复用、环境隔离”四个方面都存在明显的工程成本。如果你遇到过下面任何一个场景就需要关注 TexLite 这类工具团队里每个人都装了一遍 TeX Live版本不一致编译结果却不一样。期刊模板、毕设模板、数学建模模板散落在不同电脑里换机器后忘记安装对应宏包。想用 Overleaf但免费版的项目数和编译时长有限付费价格又不低。公司或高校有数据安全要求文档不能放在外部公共平台上。偶尔写 LaTeX 的人不想为了一个文档花半天时间配置本地环境。TexLite 想解决的并不是“LaTeX 语法怎么用”而是“LaTeX 编译环境和项目该放在哪里”。它把编辑器、编译器和文件系统统一成一个 workspace通过浏览器访问让环境作为一种服务存在而不是每台电脑上的重复劳动。这篇文章适合研究生、科研人员、数学建模参赛者、期刊排版负责人、以及所有想搭建团队级 LaTeX 基础设施的技术人员。2. TexLite 是什么轻量自托管 LaTeX 工作区要理解 TexLite先拆解三个关键词。2.1 LaTeXLaTeX 不是所见即所得的 Word而是一种基于 TeX 的排版系统。你写的是带命令的纯文本源文件通过编译引擎生成 PDF。它的优势是数学公式、参考文献、交叉引用和版式控制极其精确因此成为学术论文和理工科文档的事实标准。2.2 WorkspaceWorkspace 直译是“工作区”在 LaTeX 场景下它不只是存放 .tex 文件的文件夹而是“项目文件 编译环境 编辑界面 构建输出”的集合。本地模式下workspace 散落在你的硬盘里依赖你手动维护。而 TexLite 把 workspace 放在服务器端你通过浏览器访问统一的界面。启动一个 workspace相当于远程启动了一个带有完整 LaTeX 编译链的隔离环境。2.3 Self-hostedSelf-hosted 指软件部署在自己控制的服务器或内网环境中而不是使用 SaaS 云服务。数据、权限、版本升级都由自己管理。这三个词组合起来TexLite 的定位可以概括为一个部署在你自有服务器上、通过浏览器访问、专门用于 LaTeX 项目创建与编译的轻量级工作区。“轻量”意味着它不会像本地完整 TeX Live 那样占用几个 GB 的桌面环境也不需要你手动配置大量系统依赖而是把 TeX 发行版和编辑器集成到服务端。2.4 和 Overleaf 的对比对比项OverleafTexLite自托管部署方式官方云服务自己服务器 / 内网数据归属第三方平台完全由自己控制成本免费版受限Pro 需订阅服务器成本 维护成本编译环境官方统一维护自己维护可定制网络要求需要访问外部服务内网可用离线可用适合场景个人快速写作团队协作、数据敏感、模板固定这里真正容易被忽略的是Overleaf 解决的是“不用安装环境”的烦恼TexLite 解决的是“环境由谁控制”的问题。如果只是偶尔写一篇小论文公共云服务更省心如果是长期、团队化、模板复杂的场景自托管才有价值。3. 为什么需要自托管 LaTeX传统方案的核心痛点很多人的第一个 LaTeX 环境是本地安装 TeX Live 或 MiKTeX 开始的。这个方案不是不能用但有几个问题会在长期使用中暴露出来。3.1 环境安装成本高跨平台不一致TeX Live 完整安装包体积大安装时间长。Windows、macOS、Linux 三个平台的依赖不同即使是同一份 LaTeX 源码在不同系统上编译也可能因为宏包版本差异而出现不同的警告或报错。团队协作时最容易出现的情况是“我这边编译正常你那边报错”最后发现是 tlmgr 宏包版本不一致。3.2 模板和宏包的“搬家”成本期刊模板、毕设模板往往包含自定义 .cls 文件、.bst 参考文献样式和特定版本的宏包。本地维护这些文件一旦换电脑或重装系统很容易丢失。很多人去 Overleaf 用模板也是因为这个原因——它把模板和运行环境绑在一起免去了本地配置。但 Overleaf 免费版有限制项目数量、编译时长、协作人数都受控。对于需要长期维护的团队项目公共免费服务并不是稳定选择。3.3 云 IDE 工作区的启动等待如果你用过在线 IDE 或云工作区一定见过“workspace still starting”“isolated linux environment is booting”这类提示。它本质上是服务端在每次会话开始时临时启动一个隔离容器加载环境。网络差或资源不足时等待时间会很长。TexLite 这类自托管的优势之一是你可以提前预置好环境把容器启停策略、资源限制都掌握在自己手里。启动慢不慢取决于你的服务器配置而不是外部平台。3.4 安全与合规对高校课题组、公司文档组来说论文草稿、技术报告、专利文档可能涉及内部数据。外部在线 LaTeX 平台在便捷的同时也意味着文件经过第三方服务器。自托管能把数据留在内网访问权限由自己控制这是很多团队选择自建 workspace 的最直接原因。4. 环境准备与前置条件部署 TexLite 之前先准备运行环境。这里只写通用要求具体版本以项目仓库和官方文档为准。4.1 服务器自托管服务必须有一台 24 小时可访问的服务器或内网机器。建议条件操作系统Ubuntu 22.04 / Debian 12 等主流 Linux 发行版CPU 与内存至少 2 核 4GB推荐 4 核 8GB 以上磁盘空间至少 20-30GBLaTeX 发行版、宏包和编译缓存都会占用空间网络开启 HTTP/HTTPS 端口如果纯内网使用可不开公网如果服务器资源很小后面启动工作区和编译大型文档时会明显吃力。这不是 TexLite 本身的 bug而是 LaTeX 编译本身就吃资源。4.2 Docker自托管工具最常见的部署方式是 Docker。Docker 可以隔离环境方便备份和回滚。在服务器上安装 Docker 后确认 Docker Compose 也可用docker --version docker compose version4.3 域名与 HTTPS可选但推荐如果希望外网访问建议准备一个域名并用 Nginx 或 Caddy 做反向代理配置 HTTPS。自托管工具通常自带简单的登录认证但在公网环境下更稳妥的方案是在前面加一层 HTTPS 和访问控制不要把管理端口直接暴露到公网。4.4 客户端要求用户端只需要一个现代浏览器。不需要安装 TeX Live不需要 VSCode 插件也不需要额外配置环境变量。这也是 workspace 模式下最直接的收益。5. 部署步骤从零搭建 TexLite下面用 Docker Compose 的方式演示部署思路。不同版本的项目结构可能不同请以官方仓库为准。这里给出的是一个安全、可理解的模板。5.1 获取项目先在你的工作目录下创建项目文件夹mkdir -p /opt/texlite cd /opt/texlite然后从项目仓库获取源码或配置。如果是 git 仓库可以执行git clone 你的TexLite仓库地址 。这一步会拿到项目源码、默认配置和可能的 docker-compose 文件。5.2 编写 docker-compose.yml如果项目未附带 compose 文件或你想自定义可以创建如下模板# 文件路径/opt/texlite/docker-compose.yml version: 3.8 services: texlite: image: 你的TexLite镜像地址:最新版本 container_name: texlite restart: unless-stopped ports: - 8080:8080 volumes: - ./workspaces:/data/workspaces - ./templates:/data/templates environment: - TZAsia/Shanghai - DATA_DIR/data - COMPILE_TIMEOUT120 networks: - texlite-net networks: texlite-net: driver: bridge关键点说明ports把容器内端口映射到宿主机例如 8080。volumesworkspace 数据目录和模板目录必须挂载到宿主机否则容器重建后数据会丢失。environment时区、数据目录、编译超时等按项目文档配置。我这里写的是常见的命名方式不能保证与你使用的版本完全一致以实际文档为准。5.3 启动服务配置文件就绪后启动服务docker compose up -d docker compose ps等待容器状态变为 running。如果是首次启动拉取镜像并初始化环境需要一些时间。你可以通过日志观察启动过程docker compose logs -f texlite看到服务监听端口的日志后用浏览器访问http://服务器IP:8080如果页面能打开说明基本部署成功。5.4 配置 HTTPS 反向代理公网访问时不建议直接通过 IP 加端口。更稳妥的方式是用 Nginx 做反向代理。# 文件路径/etc/nginx/conf.d/texlite.conf server { listen 80; server_name tex.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }之后用 certbot 签发 HTTPS 证书。如果你不希望直接暴露服务可以在 Nginx 层增加 Basic Auth 或配置防火墙只允许特定 IP 访问这比依赖应用层认证更安全。5.5 初始化管理员账号与工作区不同版本的自托管工具在初始化方式上差别很大。普遍的做法是首次访问页面时创建一个管理员账号。进入管理后台新建一个 workspace。在 workspace 内新建 .tex 文件。如果你用的版本提供了 CLI 初始化命令也可以在服务器上执行docker exec -it texlite 你的初始化命令这里不要编造具体命令。请打开项目 README按文档操作。真正容易踩坑的地方是很多用户跳过了“创建管理员账号”这一步导致访问到的页面全是只读或空白。遇到这种情况优先看初始化文档而不是改代码。6. LaTeX 工作区核心使用与编译验证部署完成后接下来是最重要的部分在 TexLite 里真正跑通一个 LaTeX 文档的编译。6.1 新建一个 LaTeX 项目进入 TexLite 后新建项目例如demo-paper。项目目录下会有一个用于存放 .tex 源文件的文件夹。习惯上主文档命名为main.tex因为编译器的默认根文件规则通常指向这个名字。6.2 编写 main.tex下面给一份可直接编译的最小示例包含标题、作者、摘要、一个小节和一个表格。文件路径为项目根目录的main.tex% 文件路径demo-paper/main.tex \documentclass[11pt]{article} \usepackage[UTF8]{ctex} \usepackage{booktabs} \usepackage{array} \title{基于 TexLite 的 LaTeX 工作区实践} \author{你的名字} \date{\today} \begin{document} \maketitle \begin{abstract} 本文通过一个最小示例演示在自托管 LaTeX 工作区中完成文档编写与编译验证的全过程。 \end{abstract} \section{引言} 自托管 LaTeX 工作区把编辑器和编译器统一部署在服务端。用户通过浏览器访问 不必在本地安装完整 TeX 发行版即可完成论文写作和 PDF 生成。 \section{表格排版示例} 在 LaTeX 中表格列宽和对齐方式由导言区或表格参数控制。 下面是一个使用 \texttt{p} 列类型控制列宽的示例。 \begin{table}[htbp] \centering \begin{tabular}{p{3cm}p{5cm}r} \toprule \textbf{参数} \textbf{说明} \textbf{默认值} \\ \midrule p\{width\} 固定宽度自动换行 — \\ m\{width\} 垂直居中对齐 — \\ b\{width\} 底部对齐 — \\ \bottomrule \end{tabular} \caption{常见列类型与对齐方式} \end{table} \section{结论} 本文验证了最小 LaTeX 项目在 TexLite 中的编译流程。 后续可以在此基础之上加入参考文献、图表和自定义模板。 \end{document}这个示例中包含几个关键点使用了ctex宏包支持中文对应 XeLaTeX 或 LuaLaTeX 编译方式。表格部分使用了p{width}控制固定列宽用r实现右对齐。booktabs宏包提供了更美观的横线。6.3 选择编译引擎并执行编译在 workspace 界面中找到编译按钮或使用内置终端执行编译命令。推荐使用latexmk自动判断编译次数latexmk -xelatex main.tex如果你的文档是纯英文也可以换用latexmk -pdf main.tex编译完成后工作区会生成main.pdf点击即可预览或下载。6.4 观察日志并定位错误如果编译失败第一时间不是改代码而是看日志。LaTeX 报错一般会指出行号和宏包名。常见错误提示File not found缺少某个宏包或样式文件。Undefined control sequence命令拼写错误。! LaTeX Error: Unicode character ...字体或编码不支持常见于中文文档未正确使用ctex宏包。在自托管工作区中编译日志一般可以直接在页面里查看。如果页面没有显示日志就看容器日志docker compose logs texlite --tail 1006.5 如何验证编译成功验证标准很简单工作区中出现main.pdf且 PDF 内容里中文、表格、公式显示正常。值得提醒的是编译成功不等于排版正确你仍然需要打开 PDF 检查页面边界、图表位置、引用编号是否正常。7. 与本地 VSCode LaTeX Workshop 方案的对比很多读者已经在使用 VSCode LaTeX Workshop这套本地方案其实也很成熟。为什么要切换到自托管 workspace对比维度本地 VSCode LaTeX Workshop自托管 TexLite环境安装需安装 TeX Live体积大服务端统一安装客户端零配置跨设备每台设备都要配置浏览器访问即可团队协作需要借助 Git配合较麻烦统一环境天然适合多人复用编译隔离依赖本地宏包工作区独立可配置性能取决于本地硬件取决于服务器离线使用完全离线可用内网部署后离线可用调试体验本地查看日志方便需要熟悉页面日志或容器日志我的判断是个人快速写作时VSCode 依然是很好的选择尤其是你已经把环境配好了的情况下。但如果有 3 人以上的团队或者有多个固定模板需要长期维护把 LaTeX 环境做成自托管服务会明显减少“帮别人调环境”的时间。8. 常见问题与排查思路自托管 LaTeX 工作区的坑主要集中在部署、编译和数据持久化三个方面。下面是常见问题对照表问题现象可能原因排查方式解决方案容器启动失败端口被占用或镜像不存在查看启动日志检查端口占用更换端口号或修正镜像地址首次打开工作区提示启动中服务端正在初始化隔离环境等待并观察容器状态和日志如果是小内存服务器增加内存或调低并发打开页面空白反代配置错误或数据目录无权限检查 Nginx 日志和容器日志修正proxy_pass检查挂载目录权限中文编译报错未使用 XeLaTeX/LuaLaTeX或缺少 ctex 宏包查看编译器类型和宏包日志改用latexmk -xelatex编译编译超时文档过复杂或宏包过多看编译日志是否卡在某个包按项目文档调大COMPILE_TIMEOUT或优化宏包加载容器重建后文件消失未挂载数据卷到宿主机检查 compose 文件中 volumes把工作区数据挂载到宿主机目录网页能访问但无法登录管理员账号未初始化查看初始化文档和容器日志执行初始化命令或重新创建管理员排查时记住一个原则自托管服务的日志就是第一现场。无论是容器日志、反代日志还是应用日志都要学会从日志倒推问题而不是盲目重装。9. 最佳实践与工程建议如果你决定把 TexLite 作为团队的基础设施下面的建议可以直接用。9.1 目录规范建议在服务器上建立统一的数据目录结构/opt/texlite/ ├── docker-compose.yml ├── .env ├── workspaces/ └── templates/workspaces存放所有用户工作区必须挂载数据卷。templates存放团队公共模板例如期刊模板、毕业论文模板、课程报告模板。9.2 备份与恢复工作区里的 .tex 源文件是核心资产PDF 是编译产物。备份时优先备份源文件和数据卷不必备份编译缓存。tar -czvf texlite-backup-$(date %Y%m%d).tar.gz /opt/texlite/workspaces建议在服务器上配置定时备份任务并把备份文件同步到其他存储位置。对团队来说还可以要求成员使用 Git 管理 .tex 源文件这样即使服务器数据丢失也可以从代码仓库恢复。9.3 模板库管理把常用模板上传到templates目录并在用户新建项目时统一分发。模板内的宏包版本要和编译环境绑定测试避免出现“模板在 A 项目能编译在 B 项目报错”的情况。实际上模板管理才是 LaTeX 团队协作里最容易踩坑的地方。很多团队的问题不是环境装不上而是模板版本混乱。建议为模板目录建立明确的版本号并保持一份“模板使用说明”。9.4 用 CI 自动验证模板LaTeX 文档适合用自动化脚本验证。如果团队使用 Git可以在提交时自动编译校验。下面是一个 GitHub Actions 的示例# 文件路径.github/workflows/latex-build.yml name: Build LaTeX on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Compile LaTeX document uses: xu-cheng/latex-actionv3 with: root_file: main.tex latexmk_use_xelatex: true这个示例适用于团队用 Git 管理文档的场景。它的意义在于每次提交代码前自动验证模板和文档能否正常编译避免问题积压到发布阶段。9.5 安全与访问控制自托管工具暴露到公网时必须考虑安全边界。建议措施必须使用 HTTPS不直接裸奔 HTTP。在前置 Nginx 层增加访问控制例如 IP 白名单。定期更新镜像和容器版本保持补丁同步。不要用默认账号密码。如果应用本身提供强认证机制可配合 OAuth、LDAP 或 SSO 使用具体以项目文档支持情况为准。这些建议适用于几乎所有自托管工具不限于 TexLite。9.6 升级与回滚升级前先备份数据卷和 compose 文件。记录当前使用的镜像版本方便回滚。docker compose pull docker compose up -d如果升级后出现问题可以切回上一版本docker compose down docker compose up -d --force-recreate回滚只能解决代码版本问题不能解决数据问题。所以升级前备份数据是永远要做的第一步。10. 总结与下一步行动TexLite 这类轻量自托管 LaTeX 工作区本质上不是在和本地 IDE 抢用户而是在提供一个更可控的工作方式编译环境统一放在服务器项目文件集中管理用户通过浏览器访问数据归团队自己所有适合长期维护、模板复杂、多人协作的场景。对个人用户来说如果已经配好了 VSCode LaTeX Workshop不必急着迁移。但如果你想减少“换电脑重装环境”的烦恼或者团队里经常有人在编译和宏包上卡壳建议先在一台最低配置的 Linux 服务器上把 TexLite 跑通用一个小文档验证中文、表格、公式和 PDF 生成再逐步迁移模板和团队项目。下一步值得深入的方向有三个一是把 LaTeX 模板库版本化利用 Git 或 CI 自动校验模板可编译性二是把自托管工作区和团队现有的 Git 仓库打通让文档源文件进入版本管理三是在安全层面接入统一认证把访问控制与团队账号体系结合起来。自托管不是一次部署就结束的事。它后面跟着的是备份、升级、权限和模板管理。把 LaTeX 环境当成一个需要持续维护的软件资产来对待会比每次出了问题都重新安装环境靠谱得多。
自托管 LaTeX 工作区：从环境一致性到团队协作的工程实践
很多写论文、做数学建模、投稿期刊的人都会在某个时刻遇到同一个尴尬换了一台电脑LaTeX 环境却装不回来了。本地装 TeX Live 动辄几个 GBVSCode 插件版本不匹配模板编译到一半报缺少宏包最后只能登录在线工具又遇到文件数量限制和编译超时。TexLite 这类“轻量级 self-hosted LaTeX workspace”之所以值得关注不只是因为它能跑 LaTeX而是它把“环境一致性”和“工作区所有权”放到了开发者手里。自托管意味着团队可以把论文、模板、编译环境统一放在自己的服务器或内网里浏览器打开就能写换电脑不再是一个问题。这篇文章会从痛点出发讲清楚 LaTeX workspace 是什么、为什么需要自托管再给出完整的部署、使用和排错路径。即使你之前没有接触过自托管工具也能照着跑通一个可用的 LaTeX 工作区。1. 这篇文章真正要解决的问题先说结论TeX Live VSCode LaTeX Workshop 依然是本地写作的可靠方案但它在“多人协作、跨设备、模板复用、环境隔离”四个方面都存在明显的工程成本。如果你遇到过下面任何一个场景就需要关注 TexLite 这类工具团队里每个人都装了一遍 TeX Live版本不一致编译结果却不一样。期刊模板、毕设模板、数学建模模板散落在不同电脑里换机器后忘记安装对应宏包。想用 Overleaf但免费版的项目数和编译时长有限付费价格又不低。公司或高校有数据安全要求文档不能放在外部公共平台上。偶尔写 LaTeX 的人不想为了一个文档花半天时间配置本地环境。TexLite 想解决的并不是“LaTeX 语法怎么用”而是“LaTeX 编译环境和项目该放在哪里”。它把编辑器、编译器和文件系统统一成一个 workspace通过浏览器访问让环境作为一种服务存在而不是每台电脑上的重复劳动。这篇文章适合研究生、科研人员、数学建模参赛者、期刊排版负责人、以及所有想搭建团队级 LaTeX 基础设施的技术人员。2. TexLite 是什么轻量自托管 LaTeX 工作区要理解 TexLite先拆解三个关键词。2.1 LaTeXLaTeX 不是所见即所得的 Word而是一种基于 TeX 的排版系统。你写的是带命令的纯文本源文件通过编译引擎生成 PDF。它的优势是数学公式、参考文献、交叉引用和版式控制极其精确因此成为学术论文和理工科文档的事实标准。2.2 WorkspaceWorkspace 直译是“工作区”在 LaTeX 场景下它不只是存放 .tex 文件的文件夹而是“项目文件 编译环境 编辑界面 构建输出”的集合。本地模式下workspace 散落在你的硬盘里依赖你手动维护。而 TexLite 把 workspace 放在服务器端你通过浏览器访问统一的界面。启动一个 workspace相当于远程启动了一个带有完整 LaTeX 编译链的隔离环境。2.3 Self-hostedSelf-hosted 指软件部署在自己控制的服务器或内网环境中而不是使用 SaaS 云服务。数据、权限、版本升级都由自己管理。这三个词组合起来TexLite 的定位可以概括为一个部署在你自有服务器上、通过浏览器访问、专门用于 LaTeX 项目创建与编译的轻量级工作区。“轻量”意味着它不会像本地完整 TeX Live 那样占用几个 GB 的桌面环境也不需要你手动配置大量系统依赖而是把 TeX 发行版和编辑器集成到服务端。2.4 和 Overleaf 的对比对比项OverleafTexLite自托管部署方式官方云服务自己服务器 / 内网数据归属第三方平台完全由自己控制成本免费版受限Pro 需订阅服务器成本 维护成本编译环境官方统一维护自己维护可定制网络要求需要访问外部服务内网可用离线可用适合场景个人快速写作团队协作、数据敏感、模板固定这里真正容易被忽略的是Overleaf 解决的是“不用安装环境”的烦恼TexLite 解决的是“环境由谁控制”的问题。如果只是偶尔写一篇小论文公共云服务更省心如果是长期、团队化、模板复杂的场景自托管才有价值。3. 为什么需要自托管 LaTeX传统方案的核心痛点很多人的第一个 LaTeX 环境是本地安装 TeX Live 或 MiKTeX 开始的。这个方案不是不能用但有几个问题会在长期使用中暴露出来。3.1 环境安装成本高跨平台不一致TeX Live 完整安装包体积大安装时间长。Windows、macOS、Linux 三个平台的依赖不同即使是同一份 LaTeX 源码在不同系统上编译也可能因为宏包版本差异而出现不同的警告或报错。团队协作时最容易出现的情况是“我这边编译正常你那边报错”最后发现是 tlmgr 宏包版本不一致。3.2 模板和宏包的“搬家”成本期刊模板、毕设模板往往包含自定义 .cls 文件、.bst 参考文献样式和特定版本的宏包。本地维护这些文件一旦换电脑或重装系统很容易丢失。很多人去 Overleaf 用模板也是因为这个原因——它把模板和运行环境绑在一起免去了本地配置。但 Overleaf 免费版有限制项目数量、编译时长、协作人数都受控。对于需要长期维护的团队项目公共免费服务并不是稳定选择。3.3 云 IDE 工作区的启动等待如果你用过在线 IDE 或云工作区一定见过“workspace still starting”“isolated linux environment is booting”这类提示。它本质上是服务端在每次会话开始时临时启动一个隔离容器加载环境。网络差或资源不足时等待时间会很长。TexLite 这类自托管的优势之一是你可以提前预置好环境把容器启停策略、资源限制都掌握在自己手里。启动慢不慢取决于你的服务器配置而不是外部平台。3.4 安全与合规对高校课题组、公司文档组来说论文草稿、技术报告、专利文档可能涉及内部数据。外部在线 LaTeX 平台在便捷的同时也意味着文件经过第三方服务器。自托管能把数据留在内网访问权限由自己控制这是很多团队选择自建 workspace 的最直接原因。4. 环境准备与前置条件部署 TexLite 之前先准备运行环境。这里只写通用要求具体版本以项目仓库和官方文档为准。4.1 服务器自托管服务必须有一台 24 小时可访问的服务器或内网机器。建议条件操作系统Ubuntu 22.04 / Debian 12 等主流 Linux 发行版CPU 与内存至少 2 核 4GB推荐 4 核 8GB 以上磁盘空间至少 20-30GBLaTeX 发行版、宏包和编译缓存都会占用空间网络开启 HTTP/HTTPS 端口如果纯内网使用可不开公网如果服务器资源很小后面启动工作区和编译大型文档时会明显吃力。这不是 TexLite 本身的 bug而是 LaTeX 编译本身就吃资源。4.2 Docker自托管工具最常见的部署方式是 Docker。Docker 可以隔离环境方便备份和回滚。在服务器上安装 Docker 后确认 Docker Compose 也可用docker --version docker compose version4.3 域名与 HTTPS可选但推荐如果希望外网访问建议准备一个域名并用 Nginx 或 Caddy 做反向代理配置 HTTPS。自托管工具通常自带简单的登录认证但在公网环境下更稳妥的方案是在前面加一层 HTTPS 和访问控制不要把管理端口直接暴露到公网。4.4 客户端要求用户端只需要一个现代浏览器。不需要安装 TeX Live不需要 VSCode 插件也不需要额外配置环境变量。这也是 workspace 模式下最直接的收益。5. 部署步骤从零搭建 TexLite下面用 Docker Compose 的方式演示部署思路。不同版本的项目结构可能不同请以官方仓库为准。这里给出的是一个安全、可理解的模板。5.1 获取项目先在你的工作目录下创建项目文件夹mkdir -p /opt/texlite cd /opt/texlite然后从项目仓库获取源码或配置。如果是 git 仓库可以执行git clone 你的TexLite仓库地址 。这一步会拿到项目源码、默认配置和可能的 docker-compose 文件。5.2 编写 docker-compose.yml如果项目未附带 compose 文件或你想自定义可以创建如下模板# 文件路径/opt/texlite/docker-compose.yml version: 3.8 services: texlite: image: 你的TexLite镜像地址:最新版本 container_name: texlite restart: unless-stopped ports: - 8080:8080 volumes: - ./workspaces:/data/workspaces - ./templates:/data/templates environment: - TZAsia/Shanghai - DATA_DIR/data - COMPILE_TIMEOUT120 networks: - texlite-net networks: texlite-net: driver: bridge关键点说明ports把容器内端口映射到宿主机例如 8080。volumesworkspace 数据目录和模板目录必须挂载到宿主机否则容器重建后数据会丢失。environment时区、数据目录、编译超时等按项目文档配置。我这里写的是常见的命名方式不能保证与你使用的版本完全一致以实际文档为准。5.3 启动服务配置文件就绪后启动服务docker compose up -d docker compose ps等待容器状态变为 running。如果是首次启动拉取镜像并初始化环境需要一些时间。你可以通过日志观察启动过程docker compose logs -f texlite看到服务监听端口的日志后用浏览器访问http://服务器IP:8080如果页面能打开说明基本部署成功。5.4 配置 HTTPS 反向代理公网访问时不建议直接通过 IP 加端口。更稳妥的方式是用 Nginx 做反向代理。# 文件路径/etc/nginx/conf.d/texlite.conf server { listen 80; server_name tex.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }之后用 certbot 签发 HTTPS 证书。如果你不希望直接暴露服务可以在 Nginx 层增加 Basic Auth 或配置防火墙只允许特定 IP 访问这比依赖应用层认证更安全。5.5 初始化管理员账号与工作区不同版本的自托管工具在初始化方式上差别很大。普遍的做法是首次访问页面时创建一个管理员账号。进入管理后台新建一个 workspace。在 workspace 内新建 .tex 文件。如果你用的版本提供了 CLI 初始化命令也可以在服务器上执行docker exec -it texlite 你的初始化命令这里不要编造具体命令。请打开项目 README按文档操作。真正容易踩坑的地方是很多用户跳过了“创建管理员账号”这一步导致访问到的页面全是只读或空白。遇到这种情况优先看初始化文档而不是改代码。6. LaTeX 工作区核心使用与编译验证部署完成后接下来是最重要的部分在 TexLite 里真正跑通一个 LaTeX 文档的编译。6.1 新建一个 LaTeX 项目进入 TexLite 后新建项目例如demo-paper。项目目录下会有一个用于存放 .tex 源文件的文件夹。习惯上主文档命名为main.tex因为编译器的默认根文件规则通常指向这个名字。6.2 编写 main.tex下面给一份可直接编译的最小示例包含标题、作者、摘要、一个小节和一个表格。文件路径为项目根目录的main.tex% 文件路径demo-paper/main.tex \documentclass[11pt]{article} \usepackage[UTF8]{ctex} \usepackage{booktabs} \usepackage{array} \title{基于 TexLite 的 LaTeX 工作区实践} \author{你的名字} \date{\today} \begin{document} \maketitle \begin{abstract} 本文通过一个最小示例演示在自托管 LaTeX 工作区中完成文档编写与编译验证的全过程。 \end{abstract} \section{引言} 自托管 LaTeX 工作区把编辑器和编译器统一部署在服务端。用户通过浏览器访问 不必在本地安装完整 TeX 发行版即可完成论文写作和 PDF 生成。 \section{表格排版示例} 在 LaTeX 中表格列宽和对齐方式由导言区或表格参数控制。 下面是一个使用 \texttt{p} 列类型控制列宽的示例。 \begin{table}[htbp] \centering \begin{tabular}{p{3cm}p{5cm}r} \toprule \textbf{参数} \textbf{说明} \textbf{默认值} \\ \midrule p\{width\} 固定宽度自动换行 — \\ m\{width\} 垂直居中对齐 — \\ b\{width\} 底部对齐 — \\ \bottomrule \end{tabular} \caption{常见列类型与对齐方式} \end{table} \section{结论} 本文验证了最小 LaTeX 项目在 TexLite 中的编译流程。 后续可以在此基础之上加入参考文献、图表和自定义模板。 \end{document}这个示例中包含几个关键点使用了ctex宏包支持中文对应 XeLaTeX 或 LuaLaTeX 编译方式。表格部分使用了p{width}控制固定列宽用r实现右对齐。booktabs宏包提供了更美观的横线。6.3 选择编译引擎并执行编译在 workspace 界面中找到编译按钮或使用内置终端执行编译命令。推荐使用latexmk自动判断编译次数latexmk -xelatex main.tex如果你的文档是纯英文也可以换用latexmk -pdf main.tex编译完成后工作区会生成main.pdf点击即可预览或下载。6.4 观察日志并定位错误如果编译失败第一时间不是改代码而是看日志。LaTeX 报错一般会指出行号和宏包名。常见错误提示File not found缺少某个宏包或样式文件。Undefined control sequence命令拼写错误。! LaTeX Error: Unicode character ...字体或编码不支持常见于中文文档未正确使用ctex宏包。在自托管工作区中编译日志一般可以直接在页面里查看。如果页面没有显示日志就看容器日志docker compose logs texlite --tail 1006.5 如何验证编译成功验证标准很简单工作区中出现main.pdf且 PDF 内容里中文、表格、公式显示正常。值得提醒的是编译成功不等于排版正确你仍然需要打开 PDF 检查页面边界、图表位置、引用编号是否正常。7. 与本地 VSCode LaTeX Workshop 方案的对比很多读者已经在使用 VSCode LaTeX Workshop这套本地方案其实也很成熟。为什么要切换到自托管 workspace对比维度本地 VSCode LaTeX Workshop自托管 TexLite环境安装需安装 TeX Live体积大服务端统一安装客户端零配置跨设备每台设备都要配置浏览器访问即可团队协作需要借助 Git配合较麻烦统一环境天然适合多人复用编译隔离依赖本地宏包工作区独立可配置性能取决于本地硬件取决于服务器离线使用完全离线可用内网部署后离线可用调试体验本地查看日志方便需要熟悉页面日志或容器日志我的判断是个人快速写作时VSCode 依然是很好的选择尤其是你已经把环境配好了的情况下。但如果有 3 人以上的团队或者有多个固定模板需要长期维护把 LaTeX 环境做成自托管服务会明显减少“帮别人调环境”的时间。8. 常见问题与排查思路自托管 LaTeX 工作区的坑主要集中在部署、编译和数据持久化三个方面。下面是常见问题对照表问题现象可能原因排查方式解决方案容器启动失败端口被占用或镜像不存在查看启动日志检查端口占用更换端口号或修正镜像地址首次打开工作区提示启动中服务端正在初始化隔离环境等待并观察容器状态和日志如果是小内存服务器增加内存或调低并发打开页面空白反代配置错误或数据目录无权限检查 Nginx 日志和容器日志修正proxy_pass检查挂载目录权限中文编译报错未使用 XeLaTeX/LuaLaTeX或缺少 ctex 宏包查看编译器类型和宏包日志改用latexmk -xelatex编译编译超时文档过复杂或宏包过多看编译日志是否卡在某个包按项目文档调大COMPILE_TIMEOUT或优化宏包加载容器重建后文件消失未挂载数据卷到宿主机检查 compose 文件中 volumes把工作区数据挂载到宿主机目录网页能访问但无法登录管理员账号未初始化查看初始化文档和容器日志执行初始化命令或重新创建管理员排查时记住一个原则自托管服务的日志就是第一现场。无论是容器日志、反代日志还是应用日志都要学会从日志倒推问题而不是盲目重装。9. 最佳实践与工程建议如果你决定把 TexLite 作为团队的基础设施下面的建议可以直接用。9.1 目录规范建议在服务器上建立统一的数据目录结构/opt/texlite/ ├── docker-compose.yml ├── .env ├── workspaces/ └── templates/workspaces存放所有用户工作区必须挂载数据卷。templates存放团队公共模板例如期刊模板、毕业论文模板、课程报告模板。9.2 备份与恢复工作区里的 .tex 源文件是核心资产PDF 是编译产物。备份时优先备份源文件和数据卷不必备份编译缓存。tar -czvf texlite-backup-$(date %Y%m%d).tar.gz /opt/texlite/workspaces建议在服务器上配置定时备份任务并把备份文件同步到其他存储位置。对团队来说还可以要求成员使用 Git 管理 .tex 源文件这样即使服务器数据丢失也可以从代码仓库恢复。9.3 模板库管理把常用模板上传到templates目录并在用户新建项目时统一分发。模板内的宏包版本要和编译环境绑定测试避免出现“模板在 A 项目能编译在 B 项目报错”的情况。实际上模板管理才是 LaTeX 团队协作里最容易踩坑的地方。很多团队的问题不是环境装不上而是模板版本混乱。建议为模板目录建立明确的版本号并保持一份“模板使用说明”。9.4 用 CI 自动验证模板LaTeX 文档适合用自动化脚本验证。如果团队使用 Git可以在提交时自动编译校验。下面是一个 GitHub Actions 的示例# 文件路径.github/workflows/latex-build.yml name: Build LaTeX on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Compile LaTeX document uses: xu-cheng/latex-actionv3 with: root_file: main.tex latexmk_use_xelatex: true这个示例适用于团队用 Git 管理文档的场景。它的意义在于每次提交代码前自动验证模板和文档能否正常编译避免问题积压到发布阶段。9.5 安全与访问控制自托管工具暴露到公网时必须考虑安全边界。建议措施必须使用 HTTPS不直接裸奔 HTTP。在前置 Nginx 层增加访问控制例如 IP 白名单。定期更新镜像和容器版本保持补丁同步。不要用默认账号密码。如果应用本身提供强认证机制可配合 OAuth、LDAP 或 SSO 使用具体以项目文档支持情况为准。这些建议适用于几乎所有自托管工具不限于 TexLite。9.6 升级与回滚升级前先备份数据卷和 compose 文件。记录当前使用的镜像版本方便回滚。docker compose pull docker compose up -d如果升级后出现问题可以切回上一版本docker compose down docker compose up -d --force-recreate回滚只能解决代码版本问题不能解决数据问题。所以升级前备份数据是永远要做的第一步。10. 总结与下一步行动TexLite 这类轻量自托管 LaTeX 工作区本质上不是在和本地 IDE 抢用户而是在提供一个更可控的工作方式编译环境统一放在服务器项目文件集中管理用户通过浏览器访问数据归团队自己所有适合长期维护、模板复杂、多人协作的场景。对个人用户来说如果已经配好了 VSCode LaTeX Workshop不必急着迁移。但如果你想减少“换电脑重装环境”的烦恼或者团队里经常有人在编译和宏包上卡壳建议先在一台最低配置的 Linux 服务器上把 TexLite 跑通用一个小文档验证中文、表格、公式和 PDF 生成再逐步迁移模板和团队项目。下一步值得深入的方向有三个一是把 LaTeX 模板库版本化利用 Git 或 CI 自动校验模板可编译性二是把自托管工作区和团队现有的 Git 仓库打通让文档源文件进入版本管理三是在安全层面接入统一认证把访问控制与团队账号体系结合起来。自托管不是一次部署就结束的事。它后面跟着的是备份、升级、权限和模板管理。把 LaTeX 环境当成一个需要持续维护的软件资产来对待会比每次出了问题都重新安装环境靠谱得多。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
