Overleaf 6.3.1 常用 CLI 命令与工具详解

目标：面向运维 Overleaf 6.3.1 的工程师，逐条实测官方 Toolkit 的 bin 命令（生命周期、日志、体检、升级、镜像、shell、数据库、维护脚本、配置备份）与容器内常用工具（mongodump、tlmgr 等）的用法、参数与真实回显，作为日常运维的命令速查手册。

一、环境信息

实测日期：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、TeX Live 2026
命令目录：/opt/overleaf-toolkit/bin/（本文所有 bin/* 命令均在 /opt/overleaf-toolkit 目录下执行）
关联文档：部署过程见《Overleaf 6.3.1 Docker Compose 部署指南》，配置参数见《Overleaf 6.3.1 配置参数详解》

二、工具概览

Toolkit 的全部入口在 /opt/overleaf-toolkit/bin/（ls bin/ 实测）：

backup-config  dev          docker-compose  doctor
error-logs     images       init            logs
mongo          rename-env-vars-5-0          rename-rc-vars
run-script     shell        start           stop
up             upgrade

按用途分组：

分组	命令	作用
生命周期	`init` / `up` / `start` / `stop` / `docker-compose`	初始化、启动、停止与 compose 直通
日志排查	`logs` / `error-logs`	查看/跟踪服务日志、只看错误级日志
体检与升级	`doctor` / `upgrade`	环境体检、toolkit 与镜像升级
镜像管理	`images`	列出本机 Overleaf 相关镜像
调试入口	`shell` / `mongo`	进主容器 shell、进 MongoDB shell
维护工具	`run-script` / `backup-config`	运行内置维护脚本、备份配置文件
版本迁移	`rename-env-vars-5-0` / `rename-rc-vars`	老版本（4.x→5.0）配置变量改名助手
开发辅助	`dev/`	Toolkit 自身开发用目录，非运维命令

三、前置条件

已完成部署（未部署时只有 init/doctor 有意义）。
当前目录为 /opt/overleaf-toolkit：所有 bin/* 脚本按相对路径定位 config/ 与 lib/，在其他目录执行会找不到配置。
需要 root 或 docker 用户组权限。

四、各工具详解

4.1 bin/init —— 初始化配置目录

首次部署执行，从模板复制生成 config/（overleaf.rc、variables.env、version），并自动生成 OVERLEAF_INVITE_TOKEN_SECRET 随机密钥。实测输出：

Copying config files to 'config/'

config/ 已存在时再次运行会保留现有配置不覆盖（版本升级后新增的配置项按需合并）。

4.2 bin/up —— 启动服务

bin/up -d

-d 后台运行。实测输出（首次运行会先拉取镜像）：

 Container redis Starting
 Container redis Started
 Container mongo Waiting
 Container mongo Healthy
 Container sharelatex Starting
 Container sharelatex Started

启动顺序固定：redis → mongo（等健康检查通过）→ sharelatex。bin/up 每次执行都会按 config/overleaf.rc 重新合成 compose 定义，因此改配置后用 bin/up -d 才能应用。首次启动后主容器内部初始化约 1~2 分钟，Web 就绪以 curl http://localhost/status 返回 web is alive (web) 为准。

4.3 bin/start / bin/stop —— 启停既有容器

bin/stop

实测输出：

 Container sharelatex Stopped
 Container redis Stopping
 Container mongo Stopping
 Container mongo Stopped
 Container redis Stopped

bin/start

实测输出：

 Container redis Started
 Container mongo Waiting
 Container mongo Healthy
 Container sharelatex Starting
 Container sharelatex Started

停止后 bin/docker-compose ps 容器列表为空（NAME/IMAGE 表头无数据行）。start/stop 只启停既有容器、不重新合成配置，改配置场景见注意事项。

4.4 bin/docker-compose —— compose 直通

对底层 docker compose 的透传封装，前面会自动带上 toolkit 的配置文件与项目名。常用子命令（均实测）：

bin/docker-compose ps        # 查看容器状态
bin/docker-compose config    # 查看合成后的最终 compose 定义（含环境变量、挂载、网络）
bin/docker-compose down      # 删除容器与网络（数据目录保留）
bin/docker-compose exec sharelatex bash   # 进入主容器（等价 bin/shell）

bin/docker-compose ps 正常运行时实测：

NAME         IMAGE                         COMMAND                  SERVICE      CREATED         STATUS                    PORTS
mongo        mongo:8.0                     "docker-entrypoint.s…"   mongo        6 minutes ago   Up 11 seconds (healthy)   27017/tcp
redis        redis:7.4                     "docker-entrypoint.s…"   redis        6 minutes ago   Up 11 seconds             6379/tcp
sharelatex   sharelatex/sharelatex:6.3.1   "/sbin/my_init"          sharelatex   6 minutes ago   Up Less than a second     0.0.0.0:80->80/tcp

config 子命令的典型用途是核对配置修改是否按预期合成（environment、volumes、ports 三段），排查「改了没生效」类问题。

4.5 bin/logs / bin/error-logs —— 日志查看

bin/logs 无参数运行显示用法（实测）：

Usage: bin/logs [OPTIONS] [SERVICES...]

Services:  chat, clsi, contacts, docstore, document-updater, filestore,
           git-bridge, mongo, notifications, real-time, redis, spelling,
           tags, track-changes, web, history-v1, project-history

Options:
  -f              follow log output
  -n {number}     number of lines to print (default 20)
                  use '-n all' to show all log lines

要点：

服务名即上表 17 项；编译问题先看 clsi，页面异常先看 web，数据库问题看 mongo。
bin/logs web -n 50：web 服务最近 50 行；bin/logs -f：跟踪全部服务实时日志。
实测日志样例（notifications 服务的无害警告）：

notifications | (node:184) [DEP0040] DeprecationWarning: The `punycode` module is deprecated.

bin/error-logs 只输出错误级日志，系统健康时实测输出为空（退出码 0），适合放进巡检脚本判断。

4.6 bin/doctor —— 环境体检

逐项检查宿主机依赖、Docker 状态与配置文件，实测输出（节选，完整输出含全部依赖检查）：

====== Overleaf Doctor ======
- Host Information
    - Linux
- Dependencies
    - bash
        - status: present
        - version info: 5.2.21(1)-release
    - 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
- 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
        ...
====== Warnings ======
! Detected SIBLING_CONTAINERS_ENABLED=false. When not using Sibling containers,
users have full read and write access to the 'sharelatex' container resources
(filesystem, network, environment variables) when running LaTeX compiles.
Only use this mode in environments where all users are trusted and no
isolation of users is required.
====== End ======

三个使用场景：部署前预检（第三章）、改配置后确认生效值、异常时收集诊断信息（末尾 Warnings 段直接给出整改提示）。

4.7 bin/upgrade —— 升级 toolkit 与镜像

检查 toolkit 代码更新与镜像版本变化并执行升级。无新版本时的实测输出：

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

退出码 0。有新版本时会拉取 toolkit 代码与对应镜像，并提示 config/version 变化；气隙环境在 overleaf.rc 设 PULL_BEFORE_UPGRADE=false 跳过镜像拉取。版本升级的兼容性与顺序要求见官方 upgrading 文档。

4.8 bin/images —— 镜像清单

按四个分区列出本机 Overleaf 相关镜像（实测）：

---- Community Edition Images ----
IMAGE                         ID             DISK USAGE   CONTENT SIZE   EXTRA
sharelatex/sharelatex:6.3.1   0c659950e27f       4.74GB         1.04GB   U
---- Server Pro Images ----
IMAGE   ID             DISK USAGE   CONTENT SIZE   EXTRA
---- TexLive Images ----
IMAGE   ID             DISK USAGE   CONTENT SIZE   EXTRA
---- Git Bridge Images ----

CE 环境只有第一区有内容；EXTRA 列的 U 表示该镜像正被使用。用它核对升级前后镜像与磁盘占用。

4.9 bin/shell —— 进入主容器

bin/shell

打开主容器内 root shell（交互式），进去后可直接使用容器内工具：

root@<容器ID>:/# whoami
root
root@<容器ID>:/# tlmgr --version
tlmgr using installation: /usr/local/texlive/2026
TeX Live (https://tug.org/texlive) version 2026

⚠️ 只支持交互式：bin/shell -c "命令" 不存在。脚本化等价命令（实测可用）：

bin/docker-compose exec -T sharelatex bash -c 'whoami && tlmgr --version | tail -1'

4.10 bin/mongo —— MongoDB shell

bin/mongo

直接连入 sharelatex 库的 mongosh 交互会话（实测连接头）：

Current Mongosh Log ID:  6ad90bd3f64da3d429251e67
Connecting to:   mongodb://127.0.0.1:27017/sharelatex?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.13.0
Using MongoDB:   8.0.34

常用查询（交互会话内）：

db.users.countDocuments({})     // 用户数
db.projects.countDocuments({})  // 项目数
db.users.find({email: "admin@quzuo.net"}).pretty()   // 查用户

⚠️ 同样只支持交互式，脚本化用等价命令（实测回显 users=1、projects=1）：

bin/docker-compose exec -T mongo mongosh sharelatex --quiet \
  --eval "db.getSiblingDB('sharelatex').users.countDocuments({})" | xargs -I{} echo "users={}"

4.11 bin/run-script —— 内置维护脚本

运行 Overleaf 主容器内置的维护脚本（迁移、修复、清理类）：

bin/run-script ls          # 列出全部可用脚本

实测 ls 输出为数十个脚本（节选）：

scripts/mark_migration.mjs
scripts/force_doc_flush.mjs
scripts/clear_project_tokens.mjs
scripts/convert_doc_to_file.mjs
scripts/soft_delete_project.mjs
scripts/fix_oversized_docs.mjs
scripts/invalidate_tokens.mjs
scripts/purge_non_logged_in_sessions.mjs
...

执行单个脚本（官方用法示例格式）：

bin/run-script scripts/soft_delete_project.mjs --project-id=<项目ID>
bin/run-script -e 'VAR1=value' scripts/xxx.mjs   # 需要环境变量时用 -e

⚠️ 这些脚本直接操作数据库，执行前先做 mongodump 备份（见 4.13），并先读脚本源码确认行为（脚本位于主容器 /overleaf/services/web/scripts/）。

4.12 bin/backup-config —— 配置备份

备份 config/ 三个配置文件到目标目录（用法实测）：

Usage: bin/backup-config [OPTIONS] [DESTINATION]

Backup configuration files, to DESTINATION

Options:
  -m              mode: zip | tar | copy (default=copy)

实测 bin/backup-config /tmp/overleaf-config-backup（copy 模式）无标准输出、退出码 0，目标目录生成 overleaf.rc、variables.env、version 三个文件。-m zip/-m tar 输出压缩包。variables.env 含密钥，备份文件注意权限（600）与存放位置。

4.13 容器内工具：mongodump（数据库备份）

MongoDB 逻辑备份走 mongo 容器（实测）：

bin/docker-compose exec -T mongo mongodump --archive --gzip --db sharelatex > /tmp/overleaf-mongo-backup.gz

实测退出码 0，备份日志尾部：

2026-10-21T19:01:05.199+0000  done dumping sharelatex.oauthAccessTokens (0 documents)
2026-10-21T19:01:05.200+0000  done dumping sharelatex.userfeatureusages (0 documents)
2026-10-21T19:01:05.200+0000  done dumping sharelatex.subscriptions (0 documents)

产物 8246 字节（1 用户 1 项目的空库基线）。-T 关闭伪终端是为了二进制重定向不被污染，脚本中不要省略。恢复用 mongorestore --archive --gzip --nsFrom='sharelatex.*' --nsTo='sharelatex.*' < 文件。完整备份策略（含 data/ 目录文件备份）见部署指南第五章。

4.14 容器内工具：tlmgr / kpsewhich（TeX Live 管理）

经 bin/shell 进入主容器后使用。CE 镜像内置 TeX Live 2026 minimal 方案，宏包管理三连（实测）：

tlmgr update --self              # 自更新基础组件（首次安装宏包前必做）
tlmgr install <包名>             # 安装宏包，如 tikzlings
kpsewhich <文件名>               # 验证宏包是否可被编译器找到

实测 kpsewhich tikzlings.sty 返回：

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

tlmgr path add 把 TeX Live 工具链挂到 PATH（实测后 which pdflatex → /usr/local/bin/pdflatex）。首次安装报 Terminating 的排障与 scheme-full 全量安装见部署指南 4.9。

五、注意事项

工作目录：所有 bin/* 命令在 /opt/overleaf-toolkit 下执行，脚本按相对路径读取 config/。
改配置 ≠ 重启：bin/stop+bin/start 与 bin/docker-compose restart 都不会应用新配置；改 overleaf.rc/variables.env 必须 bin/docker-compose down && bin/up -d。
交互式限制：bin/shell、bin/mongo 只有交互模式，自动化脚本用 4.9/4.10 的等价 exec 命令。
-T 与重定向：exec 输出重定向到文件时必须加 -T，否则伪终端控制字符会混入备份文件。
run-script 直接写库：先备份再执行；脚本名以后续版本的 bin/run-script ls 输出为准。
backup-config 含密钥：variables.env 中有自动生成的密钥与 SMTP 密码，备份产物按敏感文件管理。
健康判断：bin/docker-compose ps 显示 Up 不等于 Web 就绪，以 curl http://localhost/status 返回 web is alive (web) 为准（/health_check 端点在 6.x 已移除）。

六、常见问题（FAQ）

Q1：bin/shell -c "cmd" 报错或没执行 bin/shell 不接受命令参数，脚本化改用 bin/docker-compose exec -T sharelatex bash -c 'cmd'。

Q2：bin/logs 里找不到某次报错 日志默认存容器内，容器重建后旧日志丢失。需要日志落盘时在 overleaf.rc 设 OVERLEAF_LOG_PATH=data/logs。

Q3：bin/docker-compose down 会不会丢数据 不会删数据目录（data/ 下的 bind mount 保留），只删除容器与网络；但容器文件系统内的改动（如 tlmgr 装的宏包）会丢。

Q4：bin/upgrade 提示 "No code update available" 但想固定/回退版本 直接改 config/version 为目标版本号，再 bin/upgrade 拉取镜像（官方升级路径要求逐版本推进，跨大版本先读官方 upgrading.md 的 mongo 版本要求）。

Q5：编译失败先看哪个日志 bin/logs clsi -n 100 看编译服务；配合 Web 界面编译结果中的 log 文件定位缺失宏包（缺 .sty 用 tlmgr 补装）。

Q6：bin/mongo 连接被拒 mongo 容器未就绪（Up 但未 healthy）。bin/docker-compose ps 确认 healthy 后重试；刚启动需等约 10~30 秒。

七、参考链接

本专栏系列：《Overleaf 介绍与选型指南》｜《Overleaf 6.3.1 Docker Compose 部署指南》｜《Overleaf 6.3.1 配置参数详解》
Overleaf Toolkit 官方仓库：https://github.com/overleaf/toolkit（`doc/the-doctor.md`、`doc/upgrading.md`）
MongoDB 备份官方手册：https://www.mongodb.com/docs/database-tools/mongodump/
TeX Live 管理工具 tlmgr：https://tug.org/texlive/tlmgr.html