进六月之后，我手上几篇论文的返修时间都很紧，结果正是从那个时候开始，公共版 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.04，Docker 和 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_backuptar打成归档，放到另外一个磁盘。 - 用新镜像启动服务，但保持数据目录不变。启动后观察日志：
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_CHANGES=true，同时检查跟踪变更所需的 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_data：
docker 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，体验其实比公共版更可控。
