Overleaf 6.3.1 Docker Compose 部署指南

目标：面向需要在 Ubuntu 22.04 服务器上以 Docker Compose 自托管 Overleaf Community Edition 6.3.1 的运维人员，提供从官方 Toolkit 获取、配置、启动、管理员初始化、TeX Live 增补到编译验证的完整部署流程，覆盖数据持久化、环境变量与配置参数、等价 docker run 命令及部署过程中全部实测排障记录。

一、环境信息

本文全部命令与输出均在以下环境实测（实测日期 2026-10-22），读者在同等环境操作可直接复现：

认知与选型背景（产品定位、架构、同类对比）见本专栏 《Overleaf 介绍与选型指南》；配置参数逐项详解见 《Overleaf 6.3.1 配置参数详解》；Toolkit 全部 bin 命令逐条用法见 《Overleaf 6.3.1 常用 CLI 命令与工具详解》。

二、镜像选型说明

Overleaf 官方部署方案是 Overleaf Toolkit（github.com/overleaf/toolkit），它用 docker compose 编排三个容器，无需手写 compose 文件：

版本选型要点（均实测验证）：

• 主镜像版本由 config/version 文件决定，不由 compose 文件写死：bin/init 初始化时自动写入当时最新稳定版 6.3.1。想固定版本，检查该文件内容即可：cat /opt/overleaf-toolkit/config/version → 6.3.1。
• MongoDB 版本由 config/overleaf.rc 的 MONGO_VERSION 决定（toolkit 当前默认 8.0）。Overleaf 6.x 要求 MongoDB 以副本集模式运行（toolkit 自动加 --replSet overleaf 参数并自动完成初始化，实测 rs.conf() 返回单成员 mongo:27017），不要自行降到官方文档不再支持的 4.x/5.x。
• Redis 版本由 REDIS_IMAGE 决定（toolkit 当前默认 redis:7.4，AOF 持久化默认开启）。
• Community Edition 镜像免费（AGPLv3）；Server Pro 镜像为 quay.io/sharelatex/sharelatex-pro，需商业授权，由 overleaf.rc 的 SERVER_PRO=true 切换。本文只覆盖 CE。

三、前置条件

1. 硬件：内存 ≥ 4GB（实测三容器常驻 + 一次编译在 4GB 机器可运行，多人协作建议 8GB）；磁盘 ≥ 10GB 空闲（主镜像实测 4.74GB，再加 MongoDB 数据与编译缓存）。
2. 软件：
   • Docker Engine 24+（本文实测 29.8.1）与 Docker Compose v2+ 插件（实测 v5.5.1）。安装方法见 Docker 官方文档，或使用 Ubuntu 仓库 docker.io + docker-compose-plugin。
   • git（拉取 Toolkit）、curl（健康检查）。
3. 网络：能访问 Docker Hub 拉取镜像。内网拉取缓慢时可配置镜像加速或 HTTP 代理（systemd drop-in 方式为 docker 服务添加 HTTP_PROXY/HTTPS_PROXY 环境变量后 daemon-reload + restart docker，实测可用）。
4. 端口：默认监听 80（OVERLEAF_PORT 可改）。若 80 被占用，先改配置再启动（见第十一章 FAQ）。
5. 目录：本文统一使用 /opt/overleaf-toolkit，数据落在其下 data/ 子目录（见第五章），不散落其他路径。

部署前可先跑 Toolkit 自带体检命令确认环境（bin/doctor 逐项检查依赖与配置，完整输出解读见本专栏命令篇），关键段实测回显：

====== Overleaf Doctor ======
- Host Information
    - Linux
- Dependencies
    - docker
        - status: present
        - version info: Docker version 29.8.1, build 4a63305
    - docker compose
        - status: present
        - version info: Docker Compose version v5.5.1
- Docker Daemon
    - status: up
    - server version: 29.8.1
====== Configuration ======
- config/version
    - status: present
    - version: 6.3.1

四、部署步骤

4.1 获取 Overleaf Toolkit 并初始化

git clone https://github.com/overleaf/toolkit.git /opt/overleaf-toolkit
cd /opt/overleaf-toolkit
bin/init

bin/init 实测输出：

Copying config files to 'config/'

初始化后在 /opt/overleaf-toolkit/config/ 生成 4 个文件（ls -la config/ 实测）：

其中 variables.env 已自动生成一个随机密钥（实测内容形如）：

# Secret generated at bin/init time
OVERLEAF_INVITE_TOKEN_SECRET=M/ubG0tRcZsHQ1P2b6e7JoewCKmjgIbwt+p8KLcw7jg=

该密钥用于邀请令牌签名，保留自动生成的值即可，不要泄露。

4.2 修改基础配置

默认配置只监听本机回环地址，需要改两处（编辑 /opt/overleaf-toolkit/config/overleaf.rc）：

# overleaf.rc：默认 OVERLEAF_LISTEN_IP=127.0.0.1，改为 0.0.0.0 允许外部访问
sed -i 's/^OVERLEAF_LISTEN_IP=127.0.0.1/OVERLEAF_LISTEN_IP=0.0.0.0/' config/overleaf.rc

再编辑 config/variables.env，设置站点地址与应用名（原文件中 OVERLEAF_SITE_URL 行默认被注释）：

OVERLEAF_APP_NAME="Quzuo Overleaf"
OVERLEAF_SITE_URL=http://192.168.1.80

⚠️ OVERLEAF_SITE_URL 是必改项：登录 Cookie、邮件中的链接都基于它生成。填 http://<服务器IP> 或 https://<域名>，末尾不带 /。

4.3 启动服务

bin/up -d

实测输出（首次会自动拉取三个镜像，约 5GB 下载量）：

 Image sharelatex/sharelatex:6.3.1 Pulled
 Container mongo Running
 Container redis Creating
 Container redis Created
 Container sharelatex Creating
 Container sharelatex Created
 Container redis Starting
 Container redis Started
 Container mongo Waiting
 Container mongo Healthy
 Container sharelatex Starting
 Container sharelatex Started

注意启动顺序：mongo 健康检查通过（Healthy）后 sharelatex 才启动（compose depends_on: condition: service_healthy），首次启动主容器内部还要做初始化（建库、建索引），约 1~2 分钟后 Web 才可访问。

4.4 处理社区版 Sibling Containers 警告（实测排障）

首次 bin/up -d 时，日志中会出现这样一条警告（实测原文）：

Sibling containers are not available in Community Edition, ... Falling back
using insecure in-container compiles. Set SIBLING_CONTAINERS_ENABLED=false
in config/overleaf.rc to silence this warning.

原因：「Sibling Containers」（每个编译任务单独起一个沙箱容器）是 Server Pro 特性，CE 不支持。若 overleaf.rc 中 SIBLING_CONTAINERS_ENABLED=true（新克隆的 toolkit 默认值），CE 会退回容器内直接编译并向你提示这一点。

修复：把 config/overleaf.rc 中该行改为 false，然后重建容器：

bin/docker-compose down
bin/up -d

重建后警告消失。SIBLING_CONTAINERS_ENABLED=false 表示编译在主容器内进行，用户对主容器文件系统有完全访问权限，仅适合全员可信的内部环境；这也是 CE 的唯一工作模式。

4.5 健康检查验证

容器 Up 之后，先确认服务真正就绪（实测）：

curl http://localhost/status

返回 web is alive (web)（HTTP 200）即就绪。

⚠️ 实测排障记录：旧版文档/博客常见 curl http://localhost/health_check，在 6.3.1 实测返回 404 Not found —— 该端点在 6.x 已不存在。正确健康端点是 /status。做负载均衡或监控探针时务必用 /status。

再验证入口页（实测 HTTP 200）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost/launchpad

4.6 创建管理员账号

首次访问 http://<服务器IP>/launchpad 会进入管理员注册页（仅数据库中还没有管理员时开放），填写：

• Email：admin@quzuo.net
• Password：设置强密码并妥善保管

提交后自动以该账号登录，进入项目列表页。launchpad 注册窗口只在首个管理员创建前有效，之后访问会跳转登录页；后续新建用户由管理员在「Account Settings → 管理用户」中邀请，或由用户自助注册（需开启注册，见配置篇）。

4.7 登录并创建项目

浏览器打开 http://<服务器IP>，用上一步管理员账号登录。点击 New Project → Blank Project，命名 hello-latex，进入在线编辑器。左侧源码编辑区默认已有 main.tex，可直接点击 Recompile 编译，右侧应出现 PDF 预览。

4.8 编译验证与 PDF 下载

默认模板自带一段示例文字与 \maketitle，Recompile 成功即代表整条链路（web → clsi 编译 → filestore 存储 → PDF 回传）正常。点击 PDF 预览上方的下载图标可保存 output.pdf（实测下载文件为合法 PDF，头部 %PDF-1.7）。

服务器侧也可复核编译产物（实测，编译产物在数据目录下按项目 ID 组织）：

find /opt/overleaf-toolkit/data/overleaf/output -name "*.pdf" | head

4.9 TeX Live 发行版增补（可选）

CE 镜像内置 TeX Live 2026 的 minimal 方案（实测 tlmgr --version 回显 TeX Live (https://tug.org/texlive) version 2026），够跑大多数论文模板，但缺大量常用宏包（如 biblatex、tikzlings 等）。缺包时编译报 ! LaTeX Error: File 'xxx.sty' not found.，按下面步骤增补。

第一步：自更新 tlmgr（必做，实测跳过必失败）

直接 tlmgr install <包名> 实测失败：tlmgr 提示本地 TeX Live 基础组件落后于远端 CTAN 仓库（实测仓库 https://mirror.ox.ac.uk/sites/ctan.org/systems/texlive/tlnet，状态 verified），最后以 Terminating; please see warning above! 终止安装，并提示可通过 update-tlmgr-latest.sh 自更新。

原因：镜像内置的 texlive.infra 基础组件落后于 CTAN 远端仓库，必须先自更新：

tlmgr update --self

实测输出：

[1/1] update: texlive.infra [461k] (79982 -> 80683) ... done

第二步：安装缺失宏包（以 tikzlings 为例，会连带安装 pgf/xcolor 等 5 个依赖）：

tlmgr install tikzlings

验证（实测）：

kpsewhich tikzlings.sty
# /usr/local/texlive/2026/texmf-dist/tex/latex/tikzlings/tikzlings.sty

第三步（可选）：把 tlmgr 安装的命令行工具挂到 PATH：

tlmgr path add
which pdflatex xelatex latexmk
# /usr/local/bin/pdflatex
# /usr/local/bin/xelatex
# /usr/local/bin/latexmk

一步到位方案：安装 scheme-full（完整发行版，实测共 5077 个包、耗时 8 分 47 秒）：

tlmgr install scheme-full

⚠️ 实测排障记录：scheme-full 装到 5077/5077 全部包完成后，收尾的格式文件生成步骤可能报错（实测原文）：

fmtutil [ERROR]: multiple commands found: byengine byfmt byhyphen
tlmgr: An error has occurred. See above messages. Exiting.

这是 tlmgr 一次性传给 fmtutil 的选择器参数过多所致，宏包文件本身已全部装完，主流引擎不受影响（实测 pdfLaTeX/XeLaTeX/LuaLaTeX 编译正常，kpsewhich 能命中 biblatex/fontspec 等新装宏包）。如需补齐个别引擎格式，分引擎单独执行即可：

fmtutil-sys --byengine xetex

（单选择器调用实测正常，--byengine pdftex / --byengine xetex / --byengine luatex 按需执行。）

重要：增补结果不会随容器重建保留。tlmgr 装的内容写进主容器文件系统，bin/docker-compose down && bin/up -d 重建容器后会全部丢失（data/ 目录只持久化项目数据，见第五章）。官方给定的固化方案是把装好的容器提交为新镜像并让 toolkit 使用它：

docker commit sharelatex sharelatex/sharelatex:6.3.1-with-texlive-full
echo "sharelatex/sharelatex:6.3.1-with-texlive-full" > /opt/overleaf-toolkit/config/version
bin/docker-compose down && bin/up -d

4.10 数据备份验证

MongoDB 是全部项目数据的最终存储，部署完成后应立即验证一次备份链路（实测命令与回显）：

bin/docker-compose exec -T mongo mongodump --archive --gzip --db sharelatex > /tmp/overleaf-mongo-backup.gz
ls -l /tmp/overleaf-mongo-backup.gz
# -rw-r--r-- 1 root root 8246 Oct 21 19:01 /tmp/overleaf-mongo-backup.gz

exit=0 且日志出现 done dumping sharelatex.users 等集合输出即备份成功。定期备份策略与恢复演练见本专栏运维文档。

五、数据持久化说明

Toolkit 通过 bind mount 把三个数据目录从宿主机挂进容器，重建容器数据不丢。实测目录结构（du -sh 于部署并建 1 个项目后）：

要点（均为实测或官方文档结论）：

1. 备份这三层才算完整：data/mongo（元数据）、data/overleaf（文件实体）、data/redis（状态缓存，重要性最低）。生产环境推荐用 4.10 的 mongodump 逻辑备份 + 文件目录快照。
2. 日志默认不落地：OVERLEAF_LOG_PATH 默认未设置，应用日志只写进容器内部（docker logs/bin/logs 可读），重建容器即丢。要保留日志，在 overleaf.rc 设置 OVERLEAF_LOG_PATH=data/logs（或绝对路径），重启后日志挂载到宿主机。
3. 数据目录属主是 root：容器以 root 运行，宿主机上 data/ 子目录由 root 创建（drwxr-xr-x root root），外部改动需 root 权限。
4. 迁移服务器：停服后整体打包 /opt/overleaf-toolkit（含 config/ 与 data/）到新机同路径，bin/up -d 即可恢复，版本保持 config/version 一致。
5. git-bridge 目录：data/git-bridge 在 CE 下不会被使用（GIT_BRIDGE_ENABLED=false），仅为目录占位。

六、环境变量表

以下变量写在 config/variables.env，通过 compose env_file 注入主容器。下表为 6.3.1 官方 variables.env 模板中实际存在、且在本次部署中核对过的变量（标注「默认」为模板原始状态）：

修改 variables.env 后需重建容器生效：bin/docker-compose down && bin/up -d（官方 overleaf-rc.md 明确说明 rc 与 env 的修改都要重建）。

七、配置参数说明

以下参数写在 config/overleaf.rc，决定 compose 编排本身（监听、目录、镜像、组件开关）。改 rc 后必须 bin/docker-compose down && bin/up -d 重建容器。表内默认值为 6.3.1 Toolkit 实测（bin/init 生成文件 + bin/doctor 回显）：

两处易踩坑（官方文档明示，实测核对）：

• OVERLEAF_LISTEN_IP=0.0.0.0 与 NGINX_HTTP_LISTEN_IP=0.0.0.0 组合会端口冲突；启用 TLS 代理时主容器建议保留 127.0.0.1 监听。
• MONGO_VERSION 必须是「主版本.次版本」格式（如 8.0），不能直接写完整镜像 tag。

八、配置文件挂载

Toolkit 的配置注入方式与手写 compose 不同，理解后才能正确改配置：

1. config/variables.env → 注入为主容器环境变量。compose 定义中 env_file: ../config/variables.env，容器内进程读环境变量得到全部应用配置。
2. config/overleaf.rc → 在生成 compose 文件时消费，不挂载进容器。bin/up 每次都会根据 rc 重新合成 compose 定义（基础定义在 lib/docker-compose.*.yml），所以改 rc 后必须 down+up 才会体现。
3. config/version → 决定主镜像 tag，同样在合成时消费。
4. 数据目录挂载（渲染后 bin/docker-compose config 实测值）：

  sharelatex:
    volumes:
      - source: /opt/overleaf-toolkit/data/overleaf
        target: /var/lib/overleaf
  mongo:
    volumes:
      - source: /opt/overleaf-toolkit/data/mongo
        target: /data/db
  redis:
    volumes:
      - source: /opt/overleaf-toolkit/data/redis
        target: /data

5. 追加自定义挂载/配置用 override 文件：创建 config/docker-compose.override.yml，compose 会自动叠加。官方 persistent-data.md 给出的典型用法是把 MongoDB 数据改存到 named volume（Windows/macOS 上 bind mount 会导致 WiredTiger 报 Operation not permitted；Linux bind mount 无此问题）。想核对最终生效的完整定义：

bin/docker-compose config

九、等价 docker run 命令

Toolkit 本质是 docker compose 封装。以下给出与实测渲染结果等价的 docker run 命令（用于理解编排关系或在无 toolkit 的极简场景手工复刻；生产仍建议用 toolkit，否则失去升级/体检/日志等封装能力）。

先建网络（对应 compose 项目网络 overleaf_default）：

docker network create overleaf_default

MongoDB（副本集模式 + 数据目录）：

docker run -d --name mongo --restart always --network overleaf_default \
  -v /opt/overleaf-toolkit/data/mongo:/data/db \
  mongo:8.0 --replSet overleaf

Redis（AOF 持久化）：

docker run -d --name redis --restart always --network overleaf_default \
  -v /opt/overleaf-toolkit/data/redis:/data \
  redis:7.4 redis-server --appendonly yes

Overleaf 主容器（env-file 注入 variables.env，另补两条容器互联变量）：

docker run -d --name sharelatex --restart always --network overleaf_default \
  -p 0.0.0.0:80:80 \
  -v /opt/overleaf-toolkit/data/overleaf:/var/lib/overleaf \
  --env-file /opt/overleaf-toolkit/config/variables.env \
  -e OVERLEAF_MONGO_URL=mongodb://mongo/sharelatex \
  -e OVERLEAF_REDIS_HOST=redis \
  sharelatex/sharelatex:6.3.1

与 toolkit 行为的三点差异（实测/渲染结果对照）：

1. toolkit 版 mongo 带 healthcheck（db.stats().ok），主容器等 mongo Healthy 才启动；手工 run 需自行控制启动顺序（先 mongo 后 sharelatex）。
2. 副本集初始化：toolkit 部署实测已自动完成（rs.conf() 返回 _id: "overleaf" 单成员）；手工部署若 web 连不上 mongo，进入 mongo 容器执行一次 mongosh --eval 'rs.initiate()' 再重启 sharelatex。
3. 主容器 stop_grace_period: 60s（渲染值 1m0s），手工 run 对应为 --stop-timeout 60。

十、常用运维命令

以下全部在 /opt/overleaf-toolkit 目录下执行，逐条实测（更完整的逐参数说明与更多回显见本专栏 《Overleaf 6.3.1 常用 CLI 命令与工具详解》）：

bin/upgrade 在无新版本时的实测输出：

Checking for code update...
No code update available for download
No change to docker image version
Done

十一、常见问题（FAQ）

Q1：启动日志报 "Sibling containers are not available in Community Edition" 见 4.4：CE 不支持沙箱编译，把 SIBLING_CONTAINERS_ENABLED=false 后 bin/docker-compose down && bin/up -d。

Q2：curl http://localhost/health_check 返回 404 6.x 已移除该端点，改用 /status（返回 web is alive (web) 为正常）。

Q3：容器 Up 但浏览器打不开页面 首次启动初始化需 1~2 分钟；先 bin/logs web -n 50 看 web 是否就绪，再确认 OVERLEAF_LISTEN_IP 与防火墙（ufw status）。云服务器还需放行安全组。

Q4：tlmgr install 报 "Terminating; please see warning above!" 先 tlmgr update --self 自更新基础组件，再安装目标包，见 4.9。

Q5：改了 overleaf.rc / variables.env 不生效 两个文件的修改都必须重建容器：bin/docker-compose down && bin/up -d（官方 overleaf-rc.md 明确要求）。仅 bin/stop + bin/start 只是启停既有容器，不会把新配置合成进去。

Q6：80 端口被占用 overleaf.rc 改 OVERLEAF_PORT=8080 重建，访问地址相应变为 http://<IP>:8080；或前置 nginx 反代（此时主容器监听回环地址，设 OVERLEAF_BEHIND_PROXY=true）。

Q7：日志里大量 punycode DeprecationWarning Node.js 运行时提示（The punycode module is deprecated），6.3.1 上游已知现象，不影响功能，升级版本后消失。

Q8：mongo 启动日志有 "Access control is not enabled" / "Soft rlimits too low" 警告 官方 mongo 镜像的通用提示：前者因单机内网部署未启用认证（容器端口仅内部网络可达，不对外暴露 27017）；后者建议调高文件描述符限制与调低 swappiness，单机自托管场景可接受，要求严格时可自行调优。

Q9：tlmgr 安装的宏包重启/升级后消失 宏包装在容器文件系统内，重建容器即丢。固化方案见 4.9 的 docker commit 三步。

Q10：升级 Overleaf 版本 改 config/version 为目标版本 → bin/upgrade → 官方要求按小版本顺序逐版升级并观察 mongo 版本要求；bin/upgrade 会同时拉取 toolkit 代码更新与镜像。实测当前 6.3.1 为最新，无需升级动作。

十二、参考链接

• 本专栏系列：《Overleaf 介绍与选型指南》 ｜ 《Overleaf 6.3.1 配置参数详解》 ｜ 《Overleaf 6.3.1 常用 CLI 命令与工具详解》
• Overleaf Toolkit 官方仓库与文档：https://github.com/overleaf/toolkit（`doc/quick-start-guide.md`、`doc/overleaf-rc.md`、`doc/persistent-data.md`、`doc/ce-upgrading-texlive.md`）
• Overleaf CE 开源主仓库：https://github.com/overleaf/overleaf
• 官方镜像：https://hub.docker.com/r/sharelatex/sharelatex
• 官方数据备份指南：https://github.com/overleaf/overleaf/wiki/Data-and-Backups
• TeX Live 与 tlmgr：https://tug.org/texlive/