升级你的 LaTeX 编辑器：Overleaf 维护与更新全指南

唠唠闲话

overleaf 是一款开源的在线实时协作 latex 编辑器，深受学术界和技术行业的青睐。虽然 overleaf 在 www.overleaf.com 上提供了托管版本，用户也可以选择在本地部署自己的 overleaf 服务器，以满足特定的隐私和定制需求。

本教程旨在为本地服务器部署 latex 编辑环境的提供详细的安装与配置指导。教程将覆盖从基础安装到进阶配置的全过程，内容基于 overleaf 的官方文档和实践经验编写：

官方文档参考：

• overleaf wiki – home
• toolkit 使用教程：quick-start guide
• texlive 升级教程：community edition: upgrading texlive
• 数据迁移指南：
  • data and backups
  • full project history migration

尽管 overleaf 提供了独立的 docker-compose.yaml 文件，但推荐使用官方提供的封装脚本，尤其在处理 mongo 数据库配置时，这种方式可以避免许多潜在的问题。

本教程基于 overleaf 版本 5.0.3。通过本教程的步骤，用户可以在本地搭建一个完全可控的 latex 编辑平台，有效提升文档处理的效率和安全性。

环境准备

服务器环境如下：

❯ docker-compose --version
docker compose version v2.23.3
❯ docker --version
# docker version 24.0.2, build cb74dfc

安装 overleaf

获取配置文件

通过以下命令克隆 overleaf 工具包并进入相应目录：

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

目录结构

使用 tree 命令可以查看到 overleaf 工具包的目录结构，了解其中每个部分的作用：

❯ tree -l 2
.
├── bin
│   ├── backup-config
...省略...
│   ├── start
│   ├── stop
│   ├── up
│   └── upgrade
├── changelog.md
├── config
├── data
├── doc
│   ├── ce-upgrading-texlive.md
...省略...
│   └── upgrading.md
├── lib
│   ├── config-seed
│   ├── default.rc
│   ├── docker-compose.base.yml
│   ├── docker-compose.git-bridge.yml
│   ├── docker-compose.mongo.yml
...省略...
│   └── shared-functions.sh
├── license
└── readme.md

目录说明：

• bin：脚本文件夹，包含启动、停止和升级 overleaf 的脚本。
• config：存放用户修改的配置文件，不被版本控制跟踪。
• data：用于存放挂载的数据。
• doc：相关文档，提供更多指导和信息。
• lib：包含主要的 docker 配置文件。

配置初始化

运行下列命令来初始化配置文件，此步骤将 lib/config-seed 目录下的配置文件复制到 config 目录：

bin/init

在 lib/ 目录下，每个 docker-compose 配置文件都对应一个 docker 容器的配置。这里只需关注几个关键的配置文件：

• docker-compose.base.yml：基础服务配置。
• docker-compose.mongo.yml：mongodb 服务配置。
• docker-compose.redis.yml：redis 服务配置。

这些配置文件中用 $ 标记的参数可以在 config/overleaf.rc 文件中修改，这些参数包括但不限于：

# overleaf_image_name=sharelatex/sharelatex
overleaf_data_path=data/overleaf
server_pro=false
overleaf_listen_ip=127.0.0.1
overleaf_port=80 # 建议修改

默认镜像名为 sharelatex/sharelatex，我们升级 texlive 后，将修改该参数。

启动容器

在部署之前更新 docker 镜像，然后启动 overleaf：

# 更新镜像
docker pull sharelatex/sharelatex:latest
# 启动
bin/up

用户管理

在部署 overleaf 后，访问 /launchpad 路径设置管理员，实测只有通过 localhost 才能有效访问。可以借助 vscode 的端口转发功能实现本地访问。一旦配置完成，overleaf 服务便可以通过域名或 ip 地址正常访问。

创建和管理用户

执行以下命令，创建管理员账户，如果用户已存在则升级将其升级为管理员：

youremail="填写账号邮箱"
bin/docker-compose exec sharelatex /bin/bash -ce "cd /overleaf/services/web && node modules/server-ce-scripts/scripts/create-user --admin --email=$youremail"

执行此命令后，系统将生成一个激活链接，用户通过此链接来设置密码并激活账户：

❯ youremail="hello@example.com"
bin/docker-compose exec sharelatex /bin/bash -ce "cd /overleaf/services/web && node modules/server-ce-scripts/scripts/create-user --admin --email=$youremail"
using default settings from /overleaf/services/web/config/settings.defaults.js
...省略
successfully created hello@example.com as an admin user.
please visit the following url to set a password for hello@example.com and log in:
  http://localhost/user/activate?token=41d3cdc8a81bcfa68dc2c5d89cec17b8f03ef05040e7f8058ad55948560ded33&user_id=662e6c1f29ae166bd25b041a
done.

注意将 localhost 替换为你的域名或 ip 地址。

若移除 --admin 参数，则可创建普通用户。

同样地，用户的删除可以通过下列命令完成：

youremail="填写账号邮箱"
bin/docker-compose exec sharelatex /bin/bash -ce "cd /overleaf/services/web && node modules/server-ce-scripts/scripts/delete-user --email=$youremail"

功能与限制

overleaf 的管理员界面主要提供用户创建功能，并不支持密码重置等操作。如果用户忘记了密码，并且注册邮箱是真实有效的，可以通过配置 smtp 服务来实现邮件找回密码。容器中可用的管理脚本只有三个：

• create-user.js: 创建用户或提升为管理员。
• delete-user.js: 删除用户。
• upgrade-user-features.js: 升级用户的功能特性。

错误排查

使用 overleaf 提供的 bin/doctor 脚本进行错误排查，该脚本可以检查容器的状态和配置信息：

bin/doctor

升级 texlive

在默认的 sharelatex 镜像中，texlive 的安装是最小化的，可能导致一些 latex 依赖无法正常编译。为解决这个问题，本节将详细介绍如何升级 texlive，确保 latex 项目的顺利编译和运行。

进入容器

首先，使用 overleaf 工具包提供的 bin/shell 命令进入运行中的容器：

bin/shell

安装 texlive 完整版

在容器内，使用 texlive 的包管理器 tlmgr 来安装完整版的 texlive。执行以下命令：

tlmgr install scheme-full

处理 tlmgr 版本问题

安装过程中，通常会提示 tlmgr 版本过旧，需要更新。尝试使用以下命令更新 tlmgr：

tlmgr update --self

如果遇到跨版本更新的问题，错误信息如下：

tlmgr: local tex live (2023) is older than remote repository (2024). cross release updates are only supported with
update-tlmgr-latest(.sh/.exe) --update see https://tug.org/texlive/upgrade.html for details.

这种情况需要使用专门的脚本来更新 tlmgr。在容器内执行：

wget https://mirror.ctan.org/systems/texlive/tlnet/update-tlmgr-latest.sh
sh update-tlmgr-latest.sh -- --upgrade

更新完成后，再次执行自我更新：

tlmgr update --self

完成 texlive 安装

安装完整版的 texlive 可能需要较长时间：

tlmgr install scheme-full # 可能需要较长时间

如果安装过程中某些包更新失败，可以通过以下命令尝试重新更新所有包：

tlmgr update --all

保存新的镜像

更新完 texlive 后，为了确保不丢失环境配置，建议将更新后的容器状态保存为新的 docker 镜像：

docker commit sharelatex sharelatex/sharelatex:with-texlive-full

更新配置文件

最后，更新 config/overleaf.rc 文件，以使用新创建的镜像：

overleaf_image_name=sharelatex/sharelatex:with-texlive-full

这样，每次启动 overleaf 服务时，都将使用包含完整 texlive 的镜像，保证 latex 项目的兼容性和功能性。

数据迁移

搭建新版的 overleaf 后，如果需要从旧版迁移数据，这个过程可以通过覆盖数据目录来完成。首先，需要对旧版的数据目录进行打包，例如 sharelatex_data、mongo_data 和 redis_data：

tar --create --file backup-old-server.tar ~/sharelatex_data ~/mongo_data ~/redis_data

使用 scp 或 rsync 将打包文件传输到新服务器上，然后解压这个文件，并覆盖新版本的相应数据目录：

tar --extract --file backup-old-server.tar

挂载路径可在 config/overleaf.rc 文件中查看或进行修改，拷贝文件时，可以用 cp -rp 保留原有权限。

数据库迁移

在迁移 mongodb 数据时，如果新旧 mongo 的版本不匹配，可能会导致服务启动失败。为了解决这个问题，可使用 mongodump 和 mongorestore 工具来迁移数据。

从旧版本的 mongodb 导出数据

首先，在旧版本的服务器上，通过 docker 容器执行数据导出操作：

# 在容器内创建备份
docker exec mongodb_old mongodump --out=/data/dump
# 将备份从容器复制到本地目录
docker cp mongodb_old:/data/dump /data/dump

导入数据到新版本的 mongodb

将数据传输到新服务器后，可以将其导入到新的 mongodb 容器中：

# 将本地备份复制到新容器的指定目录
docker cp /data/dump mongodb_new:/data/dump
# 在新容器内导入备份数据
docker exec mongodb_new mongorestore /data/dump

如果是跨服务器进行迁移，可以将 mongodb 数据打包后上传，并在目标服务器上解包：

tar --create --file backup-mongo.tar /data/mongo
...
tar --extract --file backup-mongo.tar

完整的项目历史迁移

如果希望进行更彻底的迁移，包括团队项目的完整历史等信息，建议参阅官方文档：full project history migration。

smtp 邮箱配置

为了使 overleaf 能够发送邮件，例如密码重置或通知邮件，需要配置 smtp 邮箱。这可以通过编辑 config/variables.env 文件并设置相关的 smtp 参数来完成。

编辑 smtp 配置

首先打开 config/variables.env 文件，填写或修改以下参数：

# 发件人地址
overleaf_email_from_address=team@example.com
# 回复地址
# overleaf_email_reply_to=noreply@example.com

# smtp 服务器地址和端口
overleaf_email_smtp_host=
overleaf_email_smtp_port=

# 发送通知的邮箱和密码
overleaf_email_smtp_user=
overleaf_email_smtp_pass=
# overleaf_custom_email_footer=

示例配置：使用 outlook

如果选择使用 outlook.com 作为邮件服务提供商，示例如下：

overleaf_email_smtp_host=smtp.office365.com
overleaf_email_smtp_port=587
overleaf_email_smtp_user=your-email@outlook.com
overleaf_email_smtp_pass=your-app-password

详细配置可以参考：开启微软 outlook 邮箱 pop, imap, smtp 服务和获取服务密码(授权码)

自定义邮件尾部

如果希望在发送的每封邮件底部添加自定义文本，可以使用 overleaf_custom_email_footer 变量来实现。比如添加联系信息、版权声明或其他有用的用户信息：

overleaf_custom_email_footer=<div>your custom footer here</div>

确保所有参数正确无误后，保存文件并重新启动 overleaf 服务以应用新的配置。这样，overleaf 就能通过配置的 smtp 服务器发送电子邮件了。

邮件截图示例：

overleaf 升级指南

下面介绍如何升级 overleaf，以使用最新功能。

标准升级流程

如果未对 sharelatex 镜像进行修改，未安装 with-texlive-full 镜像，升级过程相对简单：

bin/upgrade

这个命令会自动处理大部分升级所需的步骤。

自定义了 texlive 镜像

如果之前升级了 texlive，例如安装了完整的 texlive 环境，则需要手动重新部署。为避免在升级过程中丢失数据，建议先备份当前的工作区：

# 备份旧数据
cp -rp path/to/old_overleaf/data path/to/backup_overleaf/data

接下来，更新配置文件和 docker 镜像：

# 在 overleaf-toolkit 目录内执行
git checkout master
git pull
docker pull sharelatex/sharelatex:latest

部署新版本

按照先前的教程重新部署服务。注意从 overleaf 的旧版本（例如 4.x）升级到新版本（例如 5.x）时，配置文件中的一些参数有所变更：

• 配置文件中的 sharelatex_ 前缀更改为 overleaf_。
• 数据存储路径从 data/sharelatex 更新为 data/overleaf。

数据迁移

服务启动后，将旧数据迁移到新的数据目录。使用 -p 参数以保留文件和目录的原始权限：

sudo cp -rp old_overleaf/data new_overleaf/data
cd new_overleaf/data
sudo cp -rp sharelatex overleaf

测试和验证

完成升级后，进行彻底的测试以确保所有功能按预期工作，特别是那些涉及到自定义配置或数据迁移的部分。

通过遵循这些步骤，确保 overleaf 平台的升级过程既安全又高效，从而最小化升级对用户的影响。

---

以上，就是 overleaf 升级的详细步骤。有任何问题或疑问，欢迎留言讨论。