Overleaf 6.3.1 配置参数详解

目标：面向已完成 Overleaf 6.3.1 部署的运维人员，按分类逐项详解 Toolkit 两个配置文件（variables.env 应用参数、overleaf.rc 编排参数）的作用、默认值、生效条件与常见误配，并给出按团队规模分档的生产配置模板，全部参数均在 Ubuntu 22.04 实测环境核对。

一、环境信息

• 实测日期：2026-10-22
• 实测环境：Ubuntu 22.04 LTS，Docker Engine 29.8.1，Docker Compose v5.5.1
• 软件版本：Overleaf Community Edition 6.3.1（sharelatex/sharelatex:6.3.1）、MongoDB 8.0.34、Redis 7.4
• 部署目录：/opt/overleaf-toolkit（官方 Overleaf Toolkit）
• 参数来源：实测环境 config/overleaf.rc 与 config/variables.env 原文、容器内 /etc/overleaf/settings.js 源码、官方 doc/overleaf-rc.md
• 关联文档：部署流程见 《Overleaf 6.3.1 Docker Compose 部署指南》，选型背景见 《Overleaf 介绍与选型指南》

二、前置条件

1. 已按部署指南完成 Overleaf 6.3.1 部署并能正常访问（服务未部署时本文的「查看生效值」命令无法执行）。
2. 服务器上存在 Toolkit 配置目录 /opt/overleaf-toolkit/config/，内含 overleaf.rc、variables.env、version 三个文件。
3. 对 Docker Compose 的「重建容器才应用新配置」机制有基本了解（下文第三章展开）。

三、参数查看与修改方式

Overleaf 6.3.1 的配置分三层，修改入口与生效路径完全不同：

3.1 第一层：config/variables.env（应用参数）

站点名称、URL、邮件、功能开关等应用行为参数，以 KEY=value 行书写，# 开头为注释。Toolkit 通过 compose env_file 机制把它整体注入主容器进程环境。

查看宿主机文件：

cat /opt/overleaf-toolkit/config/variables.env

查看容器内实际生效值（实测回显，bin/docker-compose exec -T sharelatex env | grep -E "^OVERLEAF_|^EMAIL|^ENABLE" 排序后）：

EMAIL_CONFIRMATION_DISABLED=true
ENABLED_LINKED_FILE_TYPES=project_file,project_output_file
ENABLE_CONVERSIONS=true
EXTERNAL_AUTH=none
OVERLEAF_APP_NAME=Quzuo Overleaf
OVERLEAF_CONFIG=/etc/overleaf/settings.js
OVERLEAF_INVITE_TOKEN_SECRET=M/ubG0tRcZsHQ1P2b6e7JoewCKmjgIbwt+p8KLcw7jg=
OVERLEAF_MONGO_URL=mongodb://mongo/sharelatex
OVERLEAF_REDIS_HOST=redis
OVERLEAF_SITE_URL=http://192.168.1.80
REDIS_HOST=redis
REDIS_PORT=6379

注：OVERLEAF_MONGO_URL、OVERLEAF_REDIS_HOST、OVERLEAF_CONFIG（指向容器内 /etc/overleaf/settings.js）三条不由 variables.env 书写，是 compose 合成时自动注入的容器互联变量，不要手工添加覆盖。

3.2 第二层：config/overleaf.rc（编排参数）

监听地址/端口、数据目录、镜像版本、组件开关等决定 compose 编排本身的参数。

查看当前生效值最快的方式是用 Toolkit 自带体检命令（实测节选）：

bin/doctor

- config/overleaf.rc
    - status: present
    - values
        - OVERLEAF_DATA_PATH: data/overleaf
        - OVERLEAF_LOG_PATH: not set, keeping logs in container
        - SERVER_PRO: false
        - SIBLING_CONTAINERS_ENABLED: false
        - OVERLEAF_LISTEN_IP: 0.0.0.0
        - OVERLEAF_PORT: 80
        - MONGO_ENABLED: true
        - MONGO_IMAGE: mongo
        - MONGO_VERSION: 8.0
        - REDIS_ENABLED: true
        - REDIS_IMAGE: redis:7.4
        - REDIS_AOF_PERSISTENCE: true

3.3 第三层：/etc/overleaf/settings.js（镜像内置，只读理解）

容器内 /etc/overleaf/settings.js 是应用真正的配置装载文件，它逐条读取环境变量并填入内部配置对象，例如（实测源码摘录）：

siteUrl: (siteUrl = process.env.OVERLEAF_SITE_URL || 'http://localhost'),
appName: process.env.OVERLEAF_APP_NAME || 'Overleaf Community Edition',
secureCookie: process.env.OVERLEAF_SECURE_COOKIE != null,

日常运维不需要也不应该改这个文件（容器重建即丢），它的价值在于确认「某个环境变量是否被消费、默认值是什么」。

3.4 修改与生效规则

两类文件的修改都必须重建容器（官方 overleaf-rc.md 原文要求）：

bin/docker-compose down
bin/up -d

bin/stop + bin/start 只启停既有容器，不会把新配置合成进 compose 定义，改完配置只 restart 是「改了不生效」的第一大原因。改配置前建议先备份 config/ 目录（bin/backup-config 命令可用）。

四、参数总览

6.3.1 Toolkit 配置面全景（数量按实测文件与官方模板统计）：

CE（Community Edition）下实际可用约 40 项；LDAP/SAML、Git Bridge、Sibling Containers 三族为 Server Pro 专属，CE 配置了也不生效。

五、核心参数分类详解

5.1 站点基础参数（variables.env）

5.2 安全与代理参数

variables.env 侧：

overleaf.rc 侧（官方 TLS 代理容器，NGINX_ENABLED=true 启用）：

5.3 邮件参数（variables.env SMTP 组）

自托管实例默认不发邮件（密码找回、邀请通知都不可用），需要邮件时按实测模板逐项填写：

配套：配置 SMTP 后可删除 EMAIL_CONFIRMATION_DISABLED=true（见 5.5），恢复邮箱验证流程。

5.4 存储后端参数（fs / S3）

文件实体与项目历史的存储后端由两个总开关决定（bin/doctor 实测 CE 默认值）：

- SHARELATEX_FILESTORE_BACKEND: fs
- SHARELATEX_HISTORY_BACKEND: fs
- OVERLEAF_FILESTORE_BACKEND: fs
- OVERLEAF_HISTORY_BACKEND: fs

fs 模式（默认）：文件与历史落在 OVERLEAF_DATA_PATH 对应目录，随 bind mount 持久化。

s3 模式：官方模板提供完整参数组，分 AWS S3 与自建 S3（MinIO 等）两套：

内网 MinIO 场景必须同时设置 ENDPOINT 与 PATH_STYLE="true"（MinIO 默认路径式寻址）；filestore 与 history 的凭据/端点是两套独立变量，迁移时容易只配一半。

5.5 功能开关参数（variables.env）

5.6 认证参数（EXTERNAL_AUTH，Server Pro 边界）

CE 配置 LDAP/SAML 参数不会生效：LDAP/SAML 模块仅包含在 Server Pro 镜像中。CE 需要外部认证只能靠反向代理层方案（自担风险）。

5.7 编译与 TeX Live 参数

CE 下的宏包扩展不走这组参数，而是直接在主容器内 tlmgr 安装（流程与持久化见部署指南 4.9）。

5.8 编排层参数（overleaf.rc：监听、目录、项目名）

5.9 数据库与缓存参数（overleaf.rc：MONGO/REDIS）

六、生产配置模板（按团队规模分档）

以下模板按 1050 人科研团队档给出（内存 8GB / 磁盘 200GB / 单机；变量值中 <...> 为必填占位）。小团队（≤10 人）：8GB 内存可降为 4GB、磁盘 100GB，其余不变；**大团队（50200 人）**：建议 16GB 内存 + 独立 MongoDB 实例（MONGO_ENABLED=false）+ 对象存储后端（5.4 的 S3 组）。

config/overleaf.rc 生产模板：

PROJECT_NAME=overleaf

OVERLEAF_DATA_PATH=data/overleaf
OVERLEAF_LOG_PATH=data/logs            # 显式落盘日志，便于采集与审计
SERVER_PRO=false
OVERLEAF_LISTEN_IP=0.0.0.0             # 若前置 nginx/TLS 代理改回 127.0.0.1
OVERLEAF_PORT=80

SIBLING_CONTAINERS_ENABLED=false       # CE 唯一合法值
DOCKER_SOCKET_PATH=/var/run/docker.sock

MONGO_ENABLED=true
MONGO_DATA_PATH=data/mongo
MONGO_IMAGE=mongo
MONGO_VERSION=8.0

REDIS_ENABLED=true
REDIS_DATA_PATH=data/redis
REDIS_IMAGE=redis:7.4
REDIS_AOF_PERSISTENCE=true

GIT_BRIDGE_ENABLED=false

NGINX_ENABLED=false                    # 启用官方 TLS 代理改 true 并配置证书
NGINX_CONFIG_PATH=config/nginx/nginx.conf
NGINX_HTTP_PORT=80
NGINX_HTTP_LISTEN_IP=127.0.1.1
NGINX_TLS_LISTEN_IP=127.0.1.1
TLS_PRIVATE_KEY_PATH=config/nginx/certs/overleaf_key.pem
TLS_CERTIFICATE_PATH=config/nginx/certs/overleaf_certificate.pem
TLS_PORT=443

config/variables.env 生产模板：

OVERLEAF_APP_NAME="Corp Overleaf"
OVERLEAF_SITE_URL=https://overleaf.example.com   # 必填，HTTPS 域名推荐
OVERLEAF_INVITE_TOKEN_SECRET=<保留 bin/init 自动生成值>

OVERLEAF_ADMIN_EMAIL=support@example.com
OVERLEAF_NAV_TITLE=Corp Overleaf

# 邮件（建议生产必配，找回密码依赖）
OVERLEAF_EMAIL_FROM_ADDRESS=overleaf@example.com
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
OVERLEAF_EMAIL_SMTP_USER=<用户名>
OVERLEAF_EMAIL_SMTP_PASS=<密码>
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true

# HTTPS 环境两项必开（HTTP 环境勿开 SECURE_COOKIE）
OVERLEAF_BEHIND_PROXY=true
OVERLEAF_SECURE_COOKIE=true

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file
ENABLE_CONVERSIONS=true
EMAIL_CONFIRMATION_DISABLED=true   # SMTP 稳定后删除此行，恢复邮箱验证

模板应用后重建容器并跑一遍验证：bin/docker-compose down && bin/up -d → curl http://localhost/status 返回 web is alive (web) → bin/doctor 无新增警告。

七、常见问题（FAQ）

Q1：改了 variables.env / overleaf.rc 不生效 两类文件都必须 bin/docker-compose down && bin/up -d 重建容器。bin/stop/bin/start 不会重新合成配置。

Q2：设置 OVERLEAF_SECURE_COOKIE=true 后无法登录 该参数要求 HTTPS。HTTP 明文环境下 Cookie 带 Secure 标记不会回传，登录循环失败。HTTP 环境删除该行。

Q3：OVERLEAF_SITE_URL 用了 localhost 或 IP:端口 与实际访问地址不一致 Cookie 域、邮件里找回密码链接、OAuth 回调全部基于该值，必须与浏览器实际访问地址完全一致（含协议、域名/IP、端口）。

Q4：CE 配置了 LDAP/SAML 没反应 LDAP/SAML、Git Bridge、Sibling Containers 是 Server Pro 功能，CE 镜像不含对应模块，配置项会被忽略。

Q5：想保留日志但容器重建后丢失 overleaf.rc 设置 OVERLEAF_LOG_PATH=data/logs 后重建。默认未设置时日志仅存在于容器文件系统。

Q6：MONGO_VERSION 能不能写 8.0.34？ 官方 overleaf-rc.md 要求该值为「主版本号.次版本号」格式（如 6.0，允许 6.0-with-suffix 这类带后缀形式），本文实测值为 8.0；完整小版本号不在官方支持范围内。

Q7：OVERLEAF_INVITE_TOKEN_SECRET 是什么，可以改吗 模板注释标注「Secret generated at bin/init time」，是 bin/init 自动生成的随机密钥，用于邀请令牌签名。保留自动生成值即可；若需轮换，改成新随机值后重建容器（轮换影响未实测，操作后建议立即验证一次邀请流程）。

Q8：如何确认某个参数最终注入容器没有 bin/docker-compose config 查看合成后的完整 compose 定义（environment 段），或进容器 bin/docker-compose exec sharelatex env | grep <关键词> 对比。

八、参考链接

• 本专栏系列：《Overleaf 介绍与选型指南》 ｜ 《Overleaf 6.3.1 Docker Compose 部署指南》 ｜ 《Overleaf 6.3.1 常用 CLI 命令与工具详解》
• 官方 overleaf.rc 参数文档：https://github.com/overleaf/toolkit/blob/master/doc/overleaf-rc.md
• 官方 configuration 文档：https://github.com/overleaf/toolkit/blob/master/doc/configuration.md
• 官方 TLS 代理文档：https://github.com/overleaf/toolkit/blob/master/doc/tls-proxy.md
• 官方 S3 存储说明：https://github.com/overleaf/overleaf/wiki/S3
• 官方数据与备份说明：https://github.com/overleaf/overleaf/wiki/Data-and-Backups