Overleaf 6.x私有化部署全解析：从Docker Compose到平滑迁移

这两年问我 Overleaf 私有化部署的人肉眼可见地变多了。大部分人的路径都一样：公共版用着用着，某天一篇快写完的论文卡在排队里，或者被文件数量上限逼到反复删临时文件，又或者几个合作者同时改稿，修订模式的记录一多，整个编辑界面都跟着变慢，这才意识到服务器不在自己手里到底意味着什么。我这边一直在维护 xuhe2/sharelatex-ce 这个私有化部署方案，前几天刚把整套项目同步到了 Overleaf 6.x 的最新结构，这篇文章就顺着这次大升级，聊聊 6.x 的变化、部署方式，以及从旧版迁移过来需要注意的事情。

这篇内容不挑基础。你如果是从零开始，照着后面给的 docker-compose 配置一步步来，多半能跑起来；你如果已经跑过老版本，那迁移部分可以直接跳到第 4 节。当然，如果你只是想搞清楚私有化部署和公共版到底差在哪，前两节也能帮我把账算明白。先把丑话说在前面：自建 Overleaf 不是装个镜像点个启动就完事，它背后是 Mongo、Redis、多个 Node 服务、LaTeX 编译集群在一套编排里协同工作。但正因为这样，部署完之后的掌控感也是公共版给不了的——编译资源你说了算，数据在你自己的盘里，修订记录、分享链接这些协作功能一个不少。

1. 为什么还要自建一套 Overleaf

1.1 公共版真正让人难受的几个点

我接触到的大多数用户，最初都是 Overleaf 公共版的免费用户，用得挺顺手，直到某一个瞬间被卡住。最常见的触发点是编译超时。公共版对单次编译有严格的时长限制，平时写个小文档没感觉，一到论文季，整个平台的编译队列排得老长，编译点击去先是转圈，转到最后直接给你一个 timeout。这时候你连项目都保存不了，心态很容易崩。

第二个痛点是项目规模和文件数量限制。期刊模板、学位论文模板这些，动辄几十上百个 .tex、.sty、.bib 和图片文件堆在一起，再塞几轮修改稿和标注 PDF，免费额度很快就不够用了。我见过一个博士生因为文件数超限，不得不把论文拆成三个项目分别编译，引用和交叉引用全部乱掉，那种体验真的很难受。

第三个痛点更隐蔽但更要命——数据隐私。手稿还没发表，审稿意见还没返回，所有内容就先躺在别人的服务器上。很多课题组明确不允许成员把未发表的工作传到外部平台，但大家又离不开 Overleaf 的协作体验。于是私有化部署就成了唯一能兼顾“好用”和“合规”的答案。

至于修订模式，公共版在多人大文档协作时确实会卡。修订模式本身是 Overleaf 最有价值的协作功能之一，几个人轮流改稿、批注，逐条接受或拒绝修订，这个流程本身非常好用，但文档一大、修订记录一多，公共版的编辑界面和文档同步就会明显变慢。你以为是网络问题，其实是平台资源配额在起作用。

1.2 私有化部署到底图什么

自建 Overleaf，核心诉求无非四条。

第一是数据自主权。文档、编译产物、修订记录、用户信息，全部落在自己的服务器上。你随时可以备份、导出、迁移，不存在“平台倒了数据没了”的担忧。

第二是编译可控。私有化之后，编译超时不是平台说了算，而是你自己说了算。机器的 CPU、内存给足，超时时间放宽，大文档、重模板也能从容处理。需要的话还可以挂多台编译节点，把编译压力分出去。

第三是账号体系可对接。企业内部用的时候，可以对接 LDAP、OAuth、邮箱认证，不用再让团队记住一套新密码。这一点在很多团队落地的过程中比想象中重要。

第四是协作能力完整保留。很多人误以为自建版是“阉割版”，其实不是。修订模式、评论、实时协同编辑、分享链接，这些在 Overleaf 6.x 的开源版本里全部都有。尤其是分享链接——你可以给项目生成一个带 token 的链接，发给合作者，对方不用注册就能在限定权限下查看或编辑，这个能力在私有化环境里依然工作得很好。

我维护的 xuhe2/sharelatex-ce 项目，本质就是把 Overleaf 官方开源的 Community Edition 整理成一套更容易部署、更容易升级、更适合国内服务器和中小团队使用的发行版。Overleaf 这个名字你熟，ShareLaTeX 你如果经历过早期学术圈可能也听说过——其实 Overleaf 就是当年 ShareLaTeX 和 Overleaf 合并后的产品，开源版本一直沿用 sharelatex 这个包名，所以镜像名里带 sharelatex 一点也不奇怪。

2. 这次 6.x 升级，到底改了哪些东西

2.1 部署形态：从“一个大容器”到“一组服务”

Overleaf 的老版本，尤其是 3.x、4.x 时代，官方镜像几乎是全家桶式设计——一个 sharelatex 容器里把 Web 服务、编译服务、实时协同、文档存储这些全塞进去，外面挂 Mongo 和 Redis 就算完整部署了。好处是简单，坏处是牵一发动全身：编译负载一高，整个容器都跟着抖，想单独扩一个服务也没法扩。

到了 6.x，官方把核心服务彻底拆开了。这里说的“拆开”是指逻辑服务分离和配置项隔离，部署的时候不一定要求你每个服务单独起容器，但组件之间已经能互不干扰地独立扩容。整个体系里大致有这么几个角色：

表格里前面五个是核心，强烈建议都部署；后面几个可以按需取舍。官方 6.x 的 docker-compose 示例里，默认就把这些服务分得很清楚，每个服务有自己的容器、自己的配置段，日志也是独立的。

2.2 Mongo、Redis 与存储接口的调整

6.x 在数据层的要求比老版本高了一截。Mongo 版本至少需要 4.4 以上，官方 6.x 的测试环境普遍用 5.0 或 6.0；Redis 版本也不能太旧，6.x 以上比较稳。这不是随便写的数字，而是因为新版代码在事务、索引、过期策略上用了不少新特性，老版本数据库跑起来要么报兼容性错误，要么出现偶发 bug。

存储方面，filestore 默认仍然走本地磁盘，把上传的文件二进制、编译后的 PDF 直接落盘。如果你有对象存储，6.x 也支持透传 S3 兼容接口。这里有个实际好处：filestore 和 docstore 数据分离之后，备份策略可以做得更细——文档内容走 Mongo 备份，大文件二进制走磁盘快照或对象存储，互不干扰。

修订模式的数据结构也有变化。track-changes 服务独立之后，修订记录在 Mongo 里有了自己独立的集合，和文档正文分开存。这个设计对迁移影响很大：从旧版升级时，老版本里的修订记录可能散落在文档快照里，新版不会自动帮你搬过去。我已经踩过这个坑，后面迁移部分会详细说。

2.3 这次升级对部署者最直接的影响

从我实际跑 6.x 的感受来说，最大的变化不是功能，而是部署成本的真实上升。镜像数量变多，磁盘占用从原来的 2-3GB 涨到 5-6GB 是正常的；内存占用也有了明显增长，因为 web、document-updater、clsi 这些服务如果是单容器多进程模式，内部并发和缓存都会多吃一部分内存。

但你换来的东西也实在。编译负载高的时候，可以单独给 clsi 加资源；实时协同卡顿的时候，可以单独扩 real-time；某个服务崩了，只会影响局部功能，不会把整个站带走。对于实验室、编辑部这种需要稳定服务的环境，这个价值非常大。

另外，官方 6.x 的文档比老版本完善了很多，尤其是环境变量说明和排错指南，不少老版本里要自己翻源码查的配置项，现在文档里直接写清楚了。这对维护者来说省了不少时间。

3. 基于 Docker Compose 的部署全流程

3.1 服务器配置与基础环境准备

部署前先把机器准备好。我这些年帮不同团队搭过各种规模的实例，给一个比较实用的配置参考表：

注意一个细节：磁盘尽量选 SSD，LaTeX 编译会产生大量临时文件，机械盘在编译高峰期 IO 会成为瓶颈。系统我建议用 Ubuntu 22.04 或 Debian 12，这两个系统对 Docker 的支持最省心。

Docker 的安装就不啰嗦了，装好 Docker Engine 20.10 以上版本，同时把 Compose 插件装上。装完之后可以顺手验证一下：

bash复制docker --version
docker compose version

如果 Compose 命令提示不存在，说明你还用的是旧版 docker-compose，建议升级到 docker compose 插件版，写法上有细微差别，新版更推荐。

3.2 目录结构与 docker-compose.yml 详解

我的部署习惯是建一个独立的目录放所有配置文件，不散落在 root 家目录里。目录结构大致是这样：

bash复制/opt/overleaf/
├── docker-compose.yml
├── .env
├── nginx/
│   └── overleaf.conf
└── backups/

docker-compose.yml 是一个简化但完整的版本，你可以直接保存使用：

yaml复制version: "3.8"

services:
  mongo:
    image: mongo:6.0
    restart: always
    volumes:
      - mongo_data:/data/db
    networks:
      - sharelatex

  redis:
    image: redis:7
    restart: always
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - sharelatex

  sharelatex:
    image: xuhe2/sharelatex-ce:latest
    restart: always
    depends_on:
      - mongo
      - redis
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      SHARELATEX_APP_NAME: "My Overleaf"
      SHARELATEX_MONGO_URL: "mongodb://mongo/sharelatex"
      SHARELATEX_REDIS_HOST: "redis"
      SHARELATEX_REDIS_PORT: "6379"
      SHARELATEX_SECRET: "replace-with-a-long-random-string"
      SHARELATEX_IS_CE: "true"
    volumes:
      - sharelatex_data:/var/lib/sharelatex
      - sharelatex_wiki:/var/lib/overleaf
    networks:
      - sharelatex

volumes:
  mongo_data:
  redis_data:
  sharelatex_data:
  sharelatex_wiki:

networks:
  sharelatex:

这个配置里有一个细节值得特意说一下：我把 sharelatex 的端口映射到了 127.0.0.1:3000:3000，只在本机回环地址暴露 3000 端口。这样做的好处是安全——对外访问完全交给 Nginx 处理，不让裸端口暴露在公网。你如果还没有 Nginx，可以先临时改成 3000:3000 直接访问，等配好了 Nginx 再收回来。

数据卷的路径说明一下：不同版本镜像内置的持久化路径可能有差异，部署后第一时间进入容器确认 /var/lib/sharelatex 有没有被写入，以实际镜像说明为准。我在项目 README 里放的是当前 6.x 镜像实际使用的路径，如果你用的是其他镜像，记得做一次验证。

3.3 环境变量逐项说明

环境变量是 Overleaf 配置的核心，我列几个关键项，每一个都说清楚是干什么的：

这里 SHARELATEX_SECRET 是最容易被忽略的一项。很多人照着示例一路复制，secret 保持一致，结果就是所有部署实例共享同一个签名密钥。密钥一旦泄露，攻击者可以伪造会话 Cookie，把别人的登录态拿过来。这个不是危言耸听，我早期部署的时候吃过亏。生成方式很简单：

bash复制python3 -c "import secrets; print(secrets.token_urlsafe(64))"

把输出的字符串填进去，然后记住：迁移环境、恢复备份后，这个值一旦变了，所有用户的登录态都会失效，需要重新登录。所以平时一定要把它写进 .env 文件，而不是写死在 compose 里。

3.4 初始化管理员账号与功能验证

启动之前，先确认 .env 文件配置好了，然后在 /opt/overleaf 目录下执行：

bash复制docker compose up -d
docker compose logs -f sharelatex

第一次启动需要拉镜像、初始化数据库、迁移索引，过程会持续一两分钟。看到类似 HTTP server listening on port 3000 的日志，说明服务起来了。

打开浏览器访问 http://你的服务器IP:3000，先注册一个账号。注意：Overleaf 的规则是系统中第一个注册的用户自动成为管理员，所以首个注册的账号要留给真正的管理员，不要随便测一个废弃账号。注册完成后，管理员可以在管理后台看到用户列表、系统占用量，还能禁用异常账号。

功能验证我建议按这个顺序走一遍：

1. 新建一个空白项目，随便写几行 LaTeX，点击 Recompile，确认编译出 PDF。
2. 打开修订模式（Track Changes），改几处文字，确认增量 diff 能正常保存和展示。
3. 把项目分享给一个测试账号或匿名链接，确认分享链接能打开，权限控制生效。
4. 上传一个稍大的 zip 压缩包试试导入，确认文件上传和路径解析正常。

3.5 接入 Nginx 与 HTTPS

自建服务一定要走 HTTPS，尤其是带登录功能的系统。HTTP 明文传输会把登录密码和 LaTeX 文档内容全部暴露在网络上，这在学术场景里尤其不合适。

Nginx 配置我直接给一份可用的参考：

nginx复制server {
    listen 80;
    server_name overleaf.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name overleaf.example.com;

    ssl_certificate     /etc/nginx/certs/overleaf.example.com.pem;
    ssl_certificate_key /etc/nginx/certs/overleaf.example.com.key;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;

        # WebSocket 支持，实时协同和修订模式都依赖它
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
    }
}

client_max_body_size 我习惯设成 500M，防止传大 zip 或 PDF 的时候被 Nginx 拦掉。如果你经常传大型项目压缩包或超大 PDF 附件，这个值可以再调大。

WebSocket 的配置不能省。Overleaf 的实时协同、光标同步、修订模式里的实时 diff，都是通过 socket.io 走 WebSocket 通道实现的。如果 Upgrade 和 Connection 头没配好，你会发现编辑器页面加载出来了，但一有第二个人进来，文档同步就卡住，修订模式的更新也不实时。这类问题排查起来非常隐蔽，因为页面不报错，就是功能不工作。

分享链接在小标题里已经出现过了，这里顺带说透：Overleaf 的分享链接是一个带 token 的完整 URL，比如 https://overleaf.example.com/project/5f8e2c1a...?token=abcdef。这个链接能不能正常打开，取决于三件事：域名解析正常、HTTPS 证书有效、token 在分享者的项目权限配置里没被关闭。访问者打开链接后，系统会先判断是否已登录——如果没登录，会先让访问者以匿名身份进入项目视图，此时只有分享者授权的权限范围。

4. 从旧版本平滑迁移到 6.x

4.1 迁移前的检查清单

如果你已经有一套老版本的 Overleaf 在跑，升级前一定要按顺序做这几件事：

1. 备份 Mongo 数据。文档正文、用户信息、修订记录、项目权限都在这。
2. 备份 filestore 数据卷。上传的原始文件和编译产物一般在数据卷里，不跟着 Mongo 走。
3. 备份 .env 文件和 docker-compose.yml，记录当前使用的镜像版本。
4. 检查磁盘剩余空间。6.x 镜像体积更大，数据迁移需要临时空间。
5. 确认 Mongo 和 Redis 的版本。如果当前还是 Mongo 4.0、Redis 5.x，需要先把数据库升到一个兼容版本，再迁移 Overleaf 应用。

这五步里，备份这一步我经历过太多翻车案例。有一次我图省事，没备份 filestore，直接停了旧容器拉新镜像，启动后发现所有历史项目的 PDF 都没了，但文档正文还在。后来排查清楚是 filestore 数据卷没映射对，新容器挂了个空目录。从那以后我再也不敢跳过备份步骤。

4.2 数据迁移的两种实用方式

第一种方式：沿用旧数据卷。如果你的旧版 Overleaf 已经用命名数据卷管理 Mongo 和 filestore，而且数据库版本没有跨大版本升级，那么迁移可以简单到令人吃惊——停掉旧容器，把 docker-compose.yml 里的镜像换成 6.x 版本，保持数据卷名称不变，再 docker compose up -d。Mongo 容器启动后会自动检测到旧的 /data/db 目录里有数据，Overleaf 应用也能在新代码里读到旧数据。

这个方式的优点是快，几乎没有拷贝过程；缺点也有，就是旧应用如果已经被卸载或容器重建过，数据卷不一定还在。所以迁移前先执行 docker volume ls 看看。

第二种方式：转储导入。适合数据卷已经丢失、或者要跨服务器迁移的场景。在旧机器上执行：

bash复制docker exec 旧容器名 mongodump --archive=/tmp/overleaf.archive
docker cp 旧容器名:/tmp/overleaf.archive ./

把归档文件拷贝到新机器后，在新容器里执行：

bash复制docker cp overleaf.archive 新容器名:/tmp/
docker exec 新容器名 mongorestore --archive=/tmp/overleaf.archive --drop

需要注意，--drop 参数会先清空目标数据库里的同名集合，避免新旧数据混在一起。如果目标库里已经有数据，使用前务必确认。

4.3 迁移后验证清单

数据迁移完成后，先别急着让团队成员登录。按照我自己的经验，一步步验证：

1. 用管理员账号登录，确认用户列表完整，老用户的头像和邮箱在。
2. 打开一个历史项目，确认目录结构、文件内容、PDF 预览都还在。
3. 进入项目的历史版本页面，确认修订记录能正常回放。
4. 如果一个项目之前生成了分享链接，打开链接，确认匿名访问和权限控制正常。
5. 用管理员后台触发一次全量编译，确认 clsi 服务正常响应。

有一个坑要特别提醒：老版本里的修订记录和新版 track-changes 的数据结构不完全一致。如果你的旧版本比较老，迁移后打开修订模式，历史修订记录可能只能看到部分。这不是迁移失败，而是数据结构升级导致历史数据处理不完整。我在 6.x 的更新说明里也提到了这一点，建议迁移完成后，让团队成员把重要的历史修订自己核对一遍，确认关键内容没有丢失。

5. 部署与日常维护中的常见问题

5.1 编译超时怎么办

“Overleaf 编译超时”是搜索热词里出现频率很高的问题，私有化部署之后虽然权限大了，但照样会遇到。原因通常有两类：一类是项目本身太大，模板、图片、宏包全部加载，编译时间确实长；另一类是服务器配置太低，CPU 和内存被其他服务挤占，编译进程饿死。

解决方案按优先级顺序排列：

1. 先优化项目。把不常用的宏包注释掉，图片压缩到合适分辨率，不要一次性编译全部章节，用 \input 分段调试。
2. 拆分编译。把主文档拆成多个子文件，先用单独的子文件编译验证错误，最后再整合。
3. 调整服务器资源。给 clsi 容器多分配一些 CPU 配额，把编译进程的优先级调高。
4. 修改超时配置。CLSI 服务内部有一个超时时间参数，默认值在大型项目上不够用。你可以进容器找到 clsi 的配置文件，把超时时间从默认值调大，然后重启 clsi 进程。

如果你的镜像是我维护的 xuhe2/sharelatex-ce，超时参数的调整方式在项目 README 里写得很清楚，直接看文档就行。用其他镜像的话，记得改完配置先验证小项目正常，再让团队开始用。

5.2 修订模式与分享链接失效

修订模式功能异常，十次里有八次是 track-changes 服务没起来，或者它的存储模块没初始化成功。排查方法很简单：看容器状态，再进 Mongo 看 dedicated 的修订记录集合有没有在写入。命令大致是：

bash复制docker compose ps
docker compose logs track-changes

如果日志里有数据库连接错误，多半是 Mongo 连接串没配对。修订模式在默认配置下是开启的，如果你的部署看不到修订图标，检查是否在 SHARELATEX_IS_CE 之外又额外设置了关闭修订功能的开关。

分享链接失效的情况，主要集中在三个地方：

• HTTPS 配置有问题，证书过期导致链接打不开。
• Nginx 没转对 Host 头，导致系统生成的链接用了内网 IP。
• 系统里 SHARELATEX_APP_NAME 和实际域名不一致，生成的链接域名是错的。

第一个和第三个是最好查的，直接看分享链接的 URL 域名是不是你期望的那个，不是就查 Nginx 的 proxy_set_header Host 和站点名称配置。

5.3 国内网络环境下的三个实际坑

国内部署这一块，我遇到过的真实问题挺典型。

第一个是 Docker 镜像拉取慢。Overleaf 6.x 拆出来的服务多了，要拉的基础镜像也就多了。解决办法是给 Docker Daemon 配置 registry mirror，把几个可用的公共镜像加速地址写进 /etc/docker/daemon.json，然后重启 Docker。这一步可以在部署前就做，能省下大量等待时间。

第二个是服务器上的 LaTeX 宏包下载慢。安装新版 TexLive 或新增宏包时，如果默认走官方 CTAN 镜像，在国内网络环境下经常会把安装过程拖到怀疑人生。配置一个国内可访问的 CTAN 镜像源，把 TeX 发行版的包管理器指向它，下载速度会快很多。具体配置方法看你用的 TeX Live 版本，不同版本写法略不一样。

第三个是 SMTP 邮件发不出去。Overleaf 默认会发注册确认、密码重置、项目分享提醒这些邮件，如果你的服务器用的公共 SMTP 服务不稳定，很可能发信延迟甚至失败。部署时建议把 SMTP 环境变量配好，用你自己可用的邮箱服务。这个配置没做好，用户会误以为系统坏了，其实只是邮件没到。

还有人会问“怎么用 Overleaf 打开现有的 zip 文件”。这里也顺带说明：私有化部署之后，这个能力和公共版完全一致，直接在项目列表里点 New Project -> Upload Project，选择 zip 文件上传，系统会自动解压并识别 .tex 主文件。需要注意 zip 里如果包含中文文件名或中文路径，部分版本在解析时会有兼容问题，建议上传前把文件名规范化一下。

5.4 问题速查表

把上面这些坑整理成一个速查表，部署和维护的时候对着看很方便：

这套方案我在实验室、小型团队和几个朋友的自用服务器上都跑过，整体下来的体会是：Overleaf 6.x 的底层架构比之前成熟不少，服务拆开后虽然上手成本高了一点，但遇到编译高峰期只需要单独给 clsi 加资源，不再需要把整个站点重启一遍。如果你也在准备迁移，最后再提醒一句：先备份，再动手，别嫌麻烦。我早期就是因为跳过备份直接升级，结果丢了一周的修订记录，那种教训一次就够了。