改动没生效，多数不是文件写错，而是被读取的时机不对。LibreChat 里模型接入相关的配置（自定义端点、密钥、模型清单）通常由服务端进程在启动时读取，改完重启容器即可；而界面文案、按钮标签、默认展示这类内容，往往已经被前端打包进静态产物，改源文件不重新构建就不会出现在页面上。先判断这次改动属于哪一层，比反复刷新页面有效得多。

判断依据只有一条：这个值是服务端进程启动时读取的，还是前端打包时写进静态产物的。前者改完重启容器，看模型下拉和端点列表是否变化；后者改完要走前端构建流程，看页面文案是否变化。两层混着改，容易出现「改了没反应」和「重启后回退」两种假象，先用最小改动分别验证，再动大改动。

分清哪些改动重启容器就生效、哪些必须重新构建

建立分层意识的目的很直接：减少无效改动。判断一个值属于运行时还是构建期，看它是被谁、在什么时刻读取的——服务端进程启动时读取的，就是运行时配置；被前端打包工具读进去、写进静态产物再被浏览器加载的，就是构建期改动。

按常见改动归类，大致是三类：

• 模型接入：自定义端点、baseURL、密钥引用、模型清单、端点显示名。通常写在配置文件和 .env 里，由服务端加载，属于运行时配置，改完重启容器生效。
• 界面文案：菜单名、按钮文字、提示语、多语言文案等。通常位于前端源码与语言资源目录，构建时才被打包，属于构建期改动，改完需要重新构建前端。
• 默认参数：默认模型、默认温度、系统提示、注册开关等。这一类最容易混——写进服务端环境变量的偏向运行时，写在前端默认配置常量里的偏向构建期。判断方法仍是回到代码里看读取位置，不要靠猜。

需要结合环境确认的一点：容器名、配置文件挂载路径、构建产物如何进入镜像，在不同部署方式下不一样。以下命令里的服务名以本机编排文件为准，不要照抄。

在配置文件里加一个模型并验证下拉更新

用最小改动验证运行时这条路径，改动越少，越容易判断到底哪一层生效了。下面只是通用接入骨架，字段名和层级请对照当前版本自带的示例配置，不要直接覆盖已有内容。

# 追加到一个自定义端点下，name 与 baseURL 按实际服务填写
endpoints:
  custom:
    - name: "MyLocal"
      apiKey: "${MY_LOCAL_KEY}"
      baseURL: "http://host.docker.internal:8000/v1"
      models:
        default: ["your-model-id"]
        fetch: false
      modelDisplayLabel: "MyLocal"

操作顺序建议是：先备份配置文件，追加条目；如果密钥走 .env，在环境变量文件里补上同名变量；保存后重启承载服务端的容器，例如：

docker compose restart api
# 服务名以本机编排文件为准，查看日志确认启动无配置报错
docker compose logs `--tail`=50 api

验证点有三个，按顺序看：一是容器日志里没有因配置格式导致的启动失败；二是打开页面新建对话，模型选择下拉里出现新端点的显示名；三是把 name 或 modelDisplayLabel 改成一个容易识别的字符串再重启，下拉里的名字跟着变，说明这条路径确实是重启生效的。整个过程中不要重新构建前端，否则会把变量混进来。

如果重启后下拉没有变化，先检查配置文件是否真的挂载进了容器、路径与环境变量指向是否一致，再检查 YAML 缩进和字段层级。这一层排查和前端无关。

改前端文案后走构建流程并确认页面变化

验证构建期这条路，要单独走一遍，不要和模型接入的改动混在同一次操作里。前端代码通常放在项目的前端目录，文案多集中在语言资源文件里；构建脚本定义在项目根目录的 package.json 的 scripts 里，常见的是一个负责构建前端的脚本。具体命令名以项目脚本为准，不要凭记忆硬套。

# 在项目根目录查看可用脚本，找到前端构建那一条
npm run
# 执行前端构建（脚本名以 package.json 中的定义为准）
npm run frontend

产物替换方式取决于部署形态：如果是自己构建镜像，构建出的静态产物需要在镜像构建阶段被拷进镜像，然后重建镜像并重启容器；如果是把产物目录挂载到容器里，则构建完成后由容器直接读取新产物。两种方式都不要只执行构建命令就以为万事大吉。

验证动作可以直接观察：找一个改动幅度明显的文案，比如某个菜单项或按钮文字，构建并让容器使用新产物后，用无痕窗口打开页面确认文字变化。用无痕窗口是为了排除浏览器缓存干扰，比起反复强刷更省事。如果换了个文案页面没有任何变化，先确认容器用的到底是不是你构建出来的那份产物，这是最容易出错的一步。

记录改错层的典型现象用于自查

把失败表现固定下来，下次遇到同样症状可以直接跳到对应层级，不用从头猜。以下现象都是改完文件加刷新或重启就能观察到的。

• 改了配置文件和密钥，刷新页面没反应。 正确层级是运行时：重启服务端容器，而不是清缓存或重建前端。
• 重启容器后模型列表还是旧的，甚至回到改动前的状态。 说明改的文件没有真正进入容器读取的路径，或者被镜像内旧文件覆盖。要在挂载和路径上排查，仍属运行时配置层。
• 改了前端文案，页面还是旧文字，刷新和清缓存都没用。 正确层级是构建期：需要重新构建前端，并让容器使用新产物。
• 改完前端文件只重启了容器，页面反而回到旧外观。 因为容器使用的是已构建好的静态产物，重启不会重新打包，源文件改动被覆盖掉。要先构建、再让容器加载新产物。
• 重新构建了前端，模型下拉里的条目依然不变。 改错层了，模型接入不经过前端构建，回到配置文件与重启这条路径。
• 一次操作里同时改了两层，结果好坏参半说不清原因。 这是最常见的自坑：把改动拆成两次，一次只动一层，每次只用一个观察点验证。

自查时可以先问一句：这个值是谁在什么时刻读的。答得出来，就知道该重启还是该构建；答不出来，就先在代码里找到读取它的位置，再动手。改动拆分、观察点单一，比一次性改一大堆更快定位问题。