Overleaf 升级 5.0 时容器因残留 SHARELATEX_ 环境变量拒绝启动该如何迁移【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf如果你把 Overleaf Community Edition 的 docker compose 部署从 4.x 升级到 5.0 及以上版本后主容器反复退出、日志里反复打印一段关于 ShareLaTeX to Overleaf rebranding 的横幅并且提示 Refusing to startup, exiting in 10s.原因就是配置里还残留SHARELATEX_前缀的环境变量。5.0 起 Overleaf 不再支持这些旧品牌变量容器在启动自检阶段发现它们后会主动拒绝启动。本文说明如何把这些变量迁移到OVERLEAF_前缀让 5.0 实例正常启动。容器为什么拒绝启动Overleaf CE 的 Docker 镜像在构建时会把server-ce/init_scripts/目录下的启动脚本拷贝进容器见 server-ce/Dockerfile其中 000_check_for_old_env_vars_5.sh 是每次容器启动时最先执行的自检脚本逻辑如下读取容器当前环境变量名筛出所有包含SHARELATEX的项如果一项都没有脚本直接以退出码 0 结束启动流程继续只要有残留项脚本就打印横幅逐条列出这些旧变量提示将其替换为OVERLEAF_前缀例如SHARELATEX_MONGO_URL - OVERLEAF_MONGO_URL或从配置中删除并给出可用的迁移脚本路径然后sleep 10后以退出码101退出容器拒绝启动。所以横幅里列出的变量名就是需要迁移的完整清单不需要另查资料如果横幅没列全你担心的变量可以对照启动横幅重新核对一遍。主路径用仓库自带脚本重命名 compose 文件中的变量适用于 legacy docker compose 部署和水平扩展部署。脚本是 server-ce/bin/rename-env-vars-5-0.sh升级到 5.0 版本代码git pull拉取新版发布代码后即可使用# 在仓库根目录执行默认处理 docker-compose.yml server-ce/bin/rename-env-vars-5-0.sh如果旧变量写在docker-compose.override.yml或其他命名的覆盖文件里把文件名作为第一个参数传入server-ce/bin/rename-env-vars-5-0.sh docker-compose.override.yml执行前要知道这个脚本的副作用它会就地修改指定文件用sed -i s/SHARELATEX_/OVERLEAF_/g把文件中所有SHARELATEX_替换为OVERLEAF_修改前会先创建一份带时间戳的备份形如docker-compose.yml.2026.09.13-02.54.00脚本会打印 Creating backup file ... 提示备份路径如果指定文件不存在脚本报错 Expected to find $FILE, are you in the wrong directory? 并以退出码 2 结束不会修改任何文件。修改完成后重启 compose 服务让新配置生效。替代路径手工重命名或删除旧变量如果部署方式不方便运行脚本按启动横幅的提示手工处理把配置中的SHARELATEX_变量逐个替换为OVERLEAF_前缀例如SHARELATEX_MONGO_URL - OVERLEAF_MONGO_URL对不再使用的旧条目也可以直接从配置中删除。横幅中还提到了两条对应场景的路径供对照Overleaf toolkit 部署使用 toolkit 仓库中的bin/upgrade或bin/rename-env-vars-5-0.sh属于 toolkit 项目不在本仓库内其他部署方式横幅的建议是使用 docker compose 迁移脚本或联系官方支持。注意脚本只替换SHARELATEX_前缀如果变量以其他形式引用旧品牌例如未带下划线后缀的SHARELATEX脚本不会处理这类情况需手工确认。验证迁移结果验证分两层均有仓库内文档依据1. 启动自检通过。自检脚本的判断条件就是容器环境中不存在任何SHARELATEX环境变量名此时脚本静默以退出码 0 结束见 000_check_for_old_env_vars_5.sh 中OLD_ITEMS为空即exit 0的分支。也就是说容器不再打印 rebranding 横幅、不再 10 秒后退出而是继续执行后续启动流程即可确认迁移生效。2. 升级后数据仍可用。仓库的升级测试 server-ce/test/upgrading.spec.ts 模拟了旧版本使用旧品牌变量SHARELATEX_SITE_URL、SHARELATEX_MONGO_URL、SHARELATEX_REDIS_HOST升级到新版本的完整路径成功标准是升级后旧项目仍然可以列出、打开编译产物正常能渲染出编译后的页面项目历史History中此前的版本记录完整保留。迁移完成后用你的真实项目做同样的检查打开一个升级前就存在的项目确认编译成功且历史版本可回看。限制与边界本迁移针对的是 4.x → 5.0 的品牌变量更名不涉及 5.0 其他升级内容升级流程中若还有其他前置步骤例如特定版本间的二进制文件迁移以对应版本的发布说明为准本文不覆盖。server-ce/bin/rename-env-vars-5-0.sh一次只处理一个 compose 文件如果环境变量分散在多个文件compose 文件加.env等需要对每个文件分别处理脚本参数只接受单个文件名。启动自检拒绝启动的行为是 5.0 引入的固定逻辑不能通过忽略横幅或改脚本绕过正确做法是清除所有SHARELATEX_变量。【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考