唠唠闲话

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

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

官方文档参考：

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

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

环境准备

服务器环境如下：

1
2
3
4
❯ docker-compose --version
Docker Compose version v2.23.3
❯ docker --version
# Docker version 24.0.2, build cb74dfc

安装 Overleaf

获取配置文件

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

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

目录结构

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
❯ 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 目录：

1
bin/init

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

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

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

1
2
3
4
5
# 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 后，将修改该参数。

此外，推荐修改下边的参数：

1
2
3
4
# 网站域名
OVERLEAF_SITE_URL=https://yourdomain.com
# 主页左侧标题
SHARELATEX_NAV_TITLE=Your Title here

启动容器

在部署之前更新 Docker 镜像，然后启动 Overleaf：

1
2
3
4
# 更新镜像
docker pull sharelatex/sharelatex:latest
# 启动
bin/up

在部署 Overleaf 后，访问 /launchpad 路径设置管理员。实测在不设置 OVERLEAF_SITE_URL 的情况下，只能通过 localhost 才能有效访问，用 IP 或域名只能访问到站点，不能访问该链接。通常可以借助 VSCode 的端口转发功能实现本地访问。

用户管理

Overleaf 的管理员界面主要提供用户创建功能，其他功能需使用脚本操作。

创建和管理用户

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

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

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

1
2
3
4
5
6
7
8
❯ 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.

  1. 注意将 localhost 替换为你的域名或 IP 地址，如果设置过 OVERLEAF_SITE_URL 则不需要

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

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

    1
    2
    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 服务来实现邮件找回密码。

ShareLatex 容器中的用户管理脚本只有三个：

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

错误排查

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

1
bin/doctor

升级 TeXLive

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

进入容器

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

1
bin/shell

安装 TeXLive 完整版

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

1
tlmgr install scheme-full

处理 tlmgr 版本问题

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

1
tlmgr update --self

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

1
2
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。在容器内执行：

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

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

1
tlmgr update --self

完成 TeXLive 安装

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

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

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

1
tlmgr update --all

保存新的镜像

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

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

更新配置文件

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

1
OVERLEAF_IMAGE_NAME=sharelatex/sharelatex:with-texlive-full

当然，也可以手动修改 docker-compose.base.yml 文件，替换镜像名称。

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

数据迁移

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

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

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

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

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

数据库迁移

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

从旧版本的 MongoDB 导出数据

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

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

导入数据到新版本的 MongoDB

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

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

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

1
2
3
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 文件，填写或修改以下参数：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 发件人地址
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 作为邮件服务提供商，示例如下：

1
2
3
4
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 变量来实现。比如添加联系信息、版权声明或其他有用的用户信息：

1
OVERLEAF_CUSTOM_EMAIL_FOOTER=<div>Your custom footer here</div>

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

邮件截图示例：

20240429011138

Overleaf 升级指南

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

标准升级流程

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

1
bin/upgrade

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

自定义了 TeXLive 镜像

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

1
2
3
# 备份旧数据
cp -rp path/to/old_overleaf/data path/to/backup_overleaf/data
# 或者直接备份整个文件夹

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

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

部署新版本

按照先前的教程重新部署服务。

注意从 Overleaf 的旧版本（例如 4.x）升级到新版本（例如 5.x）时，配置文件中的参数有所变更：

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

数据迁移

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

1
2
3
sudo cp -rp old_overleaf/data new_overleaf/data
cd new_overleaf/data
sudo cp -rp sharelatex overleaf

测试和验证

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

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