进六月之后我手上几篇论文的返修时间都很紧结果正是从那个时候开始公共版 Overleaf 的编译排队变得让人血压飙升。下午三四点一个文档改完点“Recompile”少则等二十秒多则直接给你一个“Timed Out”。好不容易编译过了浏览器又提示链接断开重新登录后刚才的改动竟然没保存完整。那几天我反复在“已保存”和“云端不同步”之间横跳最后痛下决心把自己维护了好几年的私有化 Overleaf 方案整体翻新。正好赶上 xuhe2/sharelatex-ce 这个镜像完成对 Overleaf 6.x 的支持适配这篇就把我这段时间的升级过程、部署细节和踩坑经历完整记录下来给同样在做 Overleaf 私有化部署的人一个参考。1. 公共版 Overleaf 用久了为什么还是得自己维护一套1.1 免费方案背后的隐性成本远比想象中高很多人一开始接触 Overleaf都是看中它免安装、能实时协作、编译环境开箱即用。这个优点在写课程论文、做毕业设计阶段完全成立真正开始写期刊返修稿、学位论文初稿这种长文档之后问题就一个个冒出来。我遇到最典型的场景是编译超时。公共版给的是共享编译资源高峰期提交编译任务要排队单次编译又有时间限制。硕士论文动辄一百多页加上 TikZ 绘图、各种自定义宏包一次完整编译经常要跑半分钟以上。如果还有交叉引用和参考文献plain 编译器可能要跑两三遍很容易触发超时。超时之后界面不会告诉你具体是哪个步骤超了只显示“Compilation Timed Out”这种提示对排查问题没有任何帮助。更让人心里不踏实的是文档隐私。未发表的论文、合作者还没同意的数据结果、评审意见的回复稿这些内容放在第三方服务器上虽然有访问控制但我始终觉得不够稳妥。我们实验室之前被合作方问过“数据在哪存的”那时候我没法给出一个让人放心的答案。再加上网络因素。我在国外访问还好国内不少同事用公共版 Overleaf 经常遇到连接不稳定、编辑器光标飘、历史记录回不到旧版本的情况。协作时几个人同时在线偶尔还会碰到文档锁冲突改了半天发现保存的是别人的版本。这些问题的根源不在 Overleaf 本身而是公共 SaaS 服务没法针对你的团队做网络优化和资源保障。1.2 从 ShareLaTeX 到 Overleaf社区版的开源底子这里要捋一下历史。Overleaf 的前身之一就是 ShareLaTeX后来 Overleaf 收购了 ShareLaTeX 团队技术底座也整合在了一起。所以你会看到很多老教程仍在提“ShareLaTeX”现在的 Overleaf 社区版仓库里代码组织方式依然保留了 sharelatex 的痕迹。社区版对应的开源项目官方路径是直接拉overleaf/toolkit来做整套部署工具包里打包了 MongoDB、Redis、CLSI 编译服务、文档存储这些组件。但官方 toolkit 更偏向“全家桶式”部署版本节奏慢自定义空间相对受限。于是社区里出现了不少第三方整合镜像xuhe2/sharelatex-ce就是其中之一。这类镜像解决的问题很直接把原本需要多个容器配合、手工配置一堆环境变量的部署方式压缩成一条相对简单的启动链路同时对 TeX Live 版本、中文支持、字体、常用宏包做了预设。简单说你自己从零搭一套能用的环境可能要折腾两三天用这种镜像配合标准化配置半天内就能把服务跑起来后面维护也是跟着镜像版本走省心不少。1.3 升级到 Overleaf 6.x 的动机不只是追新之前我的实例还停留在基于 Overleaf 社区版 4.x/5.x 的旧方案一直没升的原因也很实在服务跑得好好的手上论文没写完不敢动。但这次不得不升因为几个合作者开始用到新版里才有的修订模式和更细的权限控制旧版本的编辑体验明显跟不上。Overleaf 6.x 这一代在新版本发布说明里提到的改动集中在几个方向编辑器交互层的调整、后端服务对长文档编译的资源管理优化、对 TeX Live 新版本的支持、以及一大批涉及的 bug 修复。这些在公共版里可能感知不强自建之后就能明显体会到——新版本对项目的结构解析更稳了大型文档来回切换章节不会频繁重新加载修订模式下的批注同步更流畅几个人同时审稿时评论不会互相覆盖另外就是编译服务的稳定性同等配置下挂掉的概率比旧版小很多。至于数学公式LaTeX 本身就是最强大的公式排版工具。自建环境里只要确保 TeX Live 宏包齐全amsmath、amssymb、mathtools 这些常用包都能直接用像\begin{equation}这类公式环境在私有化部署下和公共版体验没什么差别。我们实验室经常处理统计模型推导公式多、宏包杂私有化部署反而更方便因为可以往 TeX Live 里预装自己需要的宏包不用每次去公共版里碰运气式地加载。2. 这次大升级本质上改了什么2.1 前端编辑器和服务端架构的联动变化Overleaf 前端表面看还是一个网页版 LaTeX 编辑器但 6.x 这一代把编辑器的渲染层和文档同步机制重构了不少。最直观的感受是输入延迟降低尤其是大文档里滚动、查找、多光标编辑时不会再像旧版本那样明显卡顿。服务端层面的变化对自建者更重要。编译服务 CLSI 对资源隔离和镜像管理的逻辑有调整对单次编译的内存、CPU 限制方式也更清晰。自建环境下这意味着你可以通过调整容器资源配额来控制团队成员的编译占用量不用再担心某个人编译一个超复杂文档把整台服务器拖垮。同时文档存储和历史记录模块的交互方式也有变化。新版把项目快照的生成频率和存储结构做了优化恢复历史版本更细粒度。实际使用中我在升级后误删过一个章节直接从 History 里把十分钟前的版本拉了回来整个过程非常顺滑。2.2 镜像分层与 TeX Live 预装策略xuhe2/sharelatex-ce这版镜像的核心升级在于两点基础镜像跟随 Overleaf 6.x 的服务端代码更新TeX Live 层做了大幅扩充。镜像里预装了中文字体、常见 CJK 宏包、以及大量数学相关宏包。对于国内用户来说这一点特别值——很多教程里要手动装的ctex、xeCJK、zhnumber这些宏包镜像里已经打好编译中文文档时不需要反复报错再补救。镜像分层也做了优化。新版本把texlive基础层和sharelatex应用层拆得更开好处是升级应用版本时不需要重新下载整个 TeX Live 层拉取体积比旧版本小不少。我实测下来新镜像完整拉取时间比旧版少了一半左右这对服务器带宽一般的实验室来说很友好。2.3 版本升级后真正用得上的新特性单独列一下我这段时间高强度使用下来感受最明显的几个点修订模式更稳多人协作审阅时修订轨迹的锁定、接受/拒绝操作的同步明显更快。旧版本偶尔出现的修订内容错乱问题这版基本没有再出现。历史版本恢复更灵活可以按时间点预览不同快照之间的差异再决定恢复哪个版本这个功能在返修阶段非常实用。数学公式输入体验提升编辑器的公式自动补全和错误定位更准确特别是复杂的矩阵、多行公式报错信息能直接指向具体行不用再靠肉眼在大段公式里找问题。编译资源限制更清晰容器编排时可以直接限定每次编译的超时时间和内存上限比如设置SHARELATEX_COMPILE_TIMEOUT避免个别项目拖垮整个服务。这些功能组合在一起让我觉得这次升级不是简单的版本号变化而是整个私有化方案值得整体翻新的契机。3. 部署与升级实操从备份到跑通第一个文档3.1 服务器与目录规划先说我的基础环境一台 4 核 8G 的云服务器系统是 Ubuntu 22.04Docker 和 Docker Compose 插件已经装好。如果你在实验室或学校内网也可以直接用一台普通工作站只要保证磁盘空间充足即可。磁盘规划上主要考虑三个部分项目库存储、MongoDB 数据、编译缓存。建议把这三个目录放在独立的数据盘或至少有独立分区的路径下避免和系统盘抢占空间。我的目录结构是/data/overleaf/ ├── sharelatex_data/ # ShareLaTeX 自身数据 ├── mongo_data/ # MongoDB 数据文件 └── redis_data/ # Redis 持久化如果是全新部署直接创建这些目录即可。如果是像我一样从旧版本迁移保险起见先对旧 data 目录做一次完整快照再动服务。3.2 Compose 配置与启动步骤我基于xuhe2/sharelatex-ce维护了一套自己的docker-compose.yml核心结构如下version: 3.8 services: sharelatex: image: xuhe2/sharelatex-ce:latest container_name: sharelatex restart: always depends_on: - mongo - redis ports: - 8080:80 environment: SHARELATEX_APP_NAME: My Overleaf SHARELATEX_SITE_URL: https://latex.example.edu.cn SHARELATEX_MONGO_URL: mongodb://mongo/sharelatex SHARELATEX_REDIS_HOST: redis SHARELATEX_SECURE_COOKIE: true SHARELATEX_BEHIND_PROXY: true SHARELATEX_COMPILE_TIMEOUT: 180 SHARELATEX_ALLOW_PUBLIC_ACCESS: false volumes: - /data/overleaf/sharelatex_data:/var/lib/sharelatex - /data/overleaf/texlive:/usr/local/texlive mongo: image: mongo:6.0 container_name: mongo restart: always volumes: - /data/overleaf/mongo_data:/data/db redis: image: redis:7 container_name: redis restart: always command: redis-server --appendonly yes volumes: - /data/overleaf/redis_data:/data启动命令很简单cd /data/overleaf docker compose up -d首次启动后访问http://服务器IP:8080/launchpad设置管理员账号。这一步完成之后整个服务就基本可用了。这里解释一下几个关键环境变量的作用SHARELATEX_SITE_URL对外访问地址。如果后面要用 Nginx 反代或者配置 HTTPS这里要填最终域名否则 OAuth 登录、邮件里的链接地址都会不对。SHARELATEX_COMPILE_TIMEOUT单次编译超时时间单位秒。我设置 180 秒是因为实验室论文经常需要跑多轮latexmk如果写太短大型文档很容易超时。SHARELATEX_BEHIND_PROXY表示前面有反向代理让服务端正确识别客户端真实 IP日志和访问控制才能正常工作。3.3 从旧版本迁移的注意事项如果和我一样是从旧版 Overleaf/ShareLaTeX 实例升级不建议直接在原数据目录上拉新镜像强启。我建议的稳妥步骤是记录旧环境的版本号和关键环境变量尤其是SHARELATEX_MONGO_URL、站点 URL、管理员账号信息。停止旧容器对数据目录做完整备份cp -a /data/overleaf /data/overleaf_backup或者用tar打成归档放到另外一个磁盘。用新镜像启动服务但保持数据目录不变。启动后观察日志docker logs -f sharelatex如果日志里有 MongoDB 兼容性报错用mongo容器对旧库执行一次修复性检查或者先升级 MongoDB 版本再启动主服务。需要提醒的是社区版新老版本之间部分数据的 schema 会有迁移逻辑。绝大多数情况下新版服务启动时能自动完成迁移但如果中间跨的版本太大比如从很古老的版本直接跳到 6.x中间可能出现数据不一致。这种情况就只能按段升级先升到中间版本等迁移完成后再升到最新版。3.4 编译超时和资源限制的调优技巧编译超时是私有化部署里最常被问到的问题。旧版默认的编译超时常控制在 60 秒左右团队里一旦有人写大文档就很容易踩线。升级后我通过两处配置解决了这个事一是在环境变量里把SHARELATEX_COMPILE_TIMEOUT调到 180 秒。这里补充一个逻辑不是所有项目都需要这么长但调长的代价是并发编译时任务堆积的可能性增加。如果你们团队只有几个人用180 秒完全没问题。二是调整容器本身的资源限制。在docker-compose.yml的service.sharelatex下增加deploy: resources: limits: cpus: 3.5 memory: 6G这样即使某个项目触发了异常编译也不会把整个宿主机的内存吃光。对于同时运行 MongoDB 和 Redis 的机器来说给 app 容器预留足量的 CPU 上限很关键不能把所有核心都分给它否则数据库响应会变慢。数学公式相关的编译也多和超时挂钩。有些复杂的 TikZ 图或者超大矩阵编译本身耗时会长这时候超时和内存限制要一起调内存不够会导致编译进程直接被系统杀掉日志里看不到任何 LaTeX 报错只有 CLSI 返回的Failed to compile。4. 升级后的高发问题与完整排查链路4.1 现象一镜像拉取后服务启动失败升级后第一次启动我遇到的现象是容器反复重启docker ps里状态一直是Restarting。看日志发现报错信息指向 MongoDB 连接不通。排查链路先查 MongoDB 容器是否正常docker logs mongo结果显示 Mongo 在正常 listening。然后在sharelatex容器里手动pingMongo 容器名docker exec -it sharelatex ping mongo容器名解析没问题。继续排查应用层连接发现旧版配置里的SHARELATEX_MONGO_URL写的是mongodb://mongo:27017/sharelatex新版默认用户认证方式有变化导致认证失败。解决方法是把 MongoDB 的连接串改成带用户名和密码的格式或者直接在 compose 里关掉 Mongo 的认证内网可信环境才能这么干。我最后选择了给 Mongo 创建独立用户并调整连接串毕竟服务要长期对外开不能裸奔。4.2 现象二项目文件全部消失或无法读取另一个让我后背发凉的问题启动成功后登录管理后台发现之前的老项目列表还在但点进项目后编辑器空白文件列表加载不出来。这个问题的根因通常不在数据库而在文件存储。ShareLaTeX 的项目文件存储在sharelatex_data目录下新版启动时如果对目录结构做了调整而旧数据没有同步迁移就会找不到文件。排查链路是看应用日志里有没有文件路径相关的EACCES或ENOENT错误。我日志里出现的是文件权限错误。原因是我旧数据目录是从另一台机器拷贝过来的属主是原来的 UID新容器用不同的用户身份启动没有权限访问。解决方法是把数据目录的所有者改成容器内运行的用户chown -R node:node /data/overleaf/sharelatex_data改完后重启服务项目文件正常恢复。4.3 现象三编译报错缺少字体或宏包服务恢复后我拿一篇中文论文测试编译结果直接报ctex宏包找不到。这有点意外因为镜像说明里写了预装中文支持。排查后发现问题出在我设置了独立的 TeX Live 数据卷/data/overleaf/texlive:/usr/local/texlive。这个挂载在升级时出了岔子——旧镜像的 TeX Live 与新镜像的版本结构不完全一致旧目录里的文件覆盖了新镜像预装的内容。因为镜像里的texlive目录已经挂载出来了新镜像自带的宏包更新根本没有生效。解决方法是删掉旧的挂载点让新镜像重新生成docker compose down rm -rf /data/overleaf/texlive docker compose up -d但这意味着之前手动安装过的宏包会丢。为了避免每次都手动补我把常用宏包装成一个额外的脚本镜像或者直接在容器启动后写一个初始化脚本在首次运行时自动执行tlmgr install安装需要的宏包。这样重新部署后只要跑一遍脚本环境就回来了。顺便提一下数学公式环境。TeX Live 基础版一般带amsmath但像braket、physics、mathtools、algorithmicx这类常用扩展包不一定全。建议在镜像或初始化脚本里一次性装齐tlmgr install amsmath mathtools braket physics algorithm algorithmicx booktabs multirow装一次后续编译各种公式和表格都踏实。4.4 现象四修订模式功能不可用或同步异常升级后修订模式偶尔会出现批注闪烁、部分修订记录不显示。这个功能依赖后端的 TrackChanges 服务而社区版中该服务默认可能未完整启用。排查方式确认部署时是否设置了SHARELATEX_TRACK_CHANGEStrue同时检查跟踪变更所需的 Mongo 集合是否存在。如果你在升级前用的是旧版而旧版里没有初始化 TrackChanges 的集合新版启动后会报索引相关错误。处理方式是进入 Mongo 手动清理或重建相关集合的索引docker exec -it mongo mongosh sharelatex db.trackchanges.createIndex({ project_id: 1, version: 1 })重建索引后重新打开项目修订模式恢复正常。5. 部署不是终点后面这些事比“跑起来”更重要5.1 定期备份恢复演练私有化部署最致命的不是部署失败而是数据丢了找不到备份。Overleaf 的数据由 MongoDB 文件存储组成备份思路是两者都要覆盖。我现在的备份方案是每周日凌晨用docker exec导 Mongo 数据并打包 sharelatex_datadocker exec mongo mongodump --archive/tmp/mongo_backup.gz --gzip docker cp mongo:/tmp/mongo_backup.gz /backup/ tar -czf /backup/sharelatex_data_$(date %F).tar.gz /data/overleaf/sharelatex_data备份文件定期同步到另一台机器或对象存储。但备份只是第一步更重要的是真做过恢复演练。我吃过亏积累了一点经验没验证过的备份等于没有备份。建议每三个月找一台临时服务器用备份数据在新环境里完整跑一遍确认能正常登录、打开项目、编译通过。5.2 升级节奏与灰度策略既然这次升到了 6.x后面再有大版本升级不建议第一时间跟。我的习惯是先看镜像发布说明等运行一周没有明显 issue 再动。实验室或小团队场景没有专门的测试环境就用一个“非核心项目”先试升级验证能编译、协作、历史记录正常后再切换对外域名。升级前一定把docker compose down之后的目录备份做好记住旧镜像的 tag不要覆盖。这样如果新版有问题可以立刻把镜像 tag 倒回旧版本、数据目录恢复几分钟内完成回滚。5.3 从 Overleaf 私有化扩散出去的一套运维经验最后说点我自己的心得体会。运维 Overleaf 私有化一年后我发现很大一部分经验可以复用到其他自建服务上一套稳定的 Docker Compose 编排、一份可靠的备份机制、一个“出了问题先看日志”的排查习惯以及“不要盲目追新”的升级节奏。这套思路后来又帮我部署了 Dify 类的私有化工具和几个内网知识库项目底层逻辑都一样——服务代码可以换数据和应用必须分层管理镜像可以随时重建数据必须在自己手里。这种感觉恰恰是当初做 Overleaf 私有化部署时最想要的安全感。如果你正在用公共版 Overleaf被编译超时、网络抖动、数据隐私这些问题困扰不妨也试试自建一套。先拿一台小服务器把xuhe2/sharelatex-ce跑起来导入一个不重要的文档试试水。等真正把整套服务跑顺之后你会发现在自建环境里写 LaTeX体验其实比公共版更可控。