唠唠闲话

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_datamongo_dataredis_data

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

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

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

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

数据库迁移

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

从旧版本的 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 升级的详细步骤。有任何问题或疑问,欢迎留言讨论。