LobeChat本地部署：Docker、环境变量与反向代理实战

1. 先把聊天界面从模型里拆出来，这件事本身就值得做

很多人第一次接触本地聊天机器人，顺序是反的：先去折腾模型权重、量化精度、显存占用，结果折腾了三天，模型跑起来了，却只能对着终端敲curl，连个能看历史会话的界面都没有。我在几个小项目里反复验证过一件事——把界面层和模型层解耦，是让一套本地聊天机器人真正能用起来的前提。LobeChat 就是这样一个东西：它是一个开源的聊天机器人前端框架，你可以把它理解成"一层皮 + 一堆胶水"，皮负责会话、话题、助手、插件、文件上传、语音这些交互，胶水负责把你的模型接口、数据库、对象存储、登录体系粘在一起。

它能解决什么问题？说得直白点：你想让家里那台旧机器上的小模型有个像样的门面，你想让团队几个人共用一个模型入口而不是各自装一堆客户端，你想把不同厂商的模型放在同一个界面里对比效果，你想给某些场景预设一批助手和提示词模板。这些需求，一个纯前端界面 + 一套可配置的环境变量就能覆盖掉大半。适合谁看？写过几条docker run、知道环境变量是什么、能改配置文件但不算运维老手的人，读完可以直接照着搭起来；完全没碰过命令行的读者，也能从选型那几节里搞清楚每一层在干什么、为什么这么排。

我要强调的是，本地运行部署这四个字里，"本地"指的是控制权在你手里，不等于"必须在断网的机器上"。这两件事经常被混为一谈。你可以把它跑在一台内网的小服务器上，只在局域网访问；也可以跑在公网，但把访问口令和登录体系配好。选择的自由度是这个方案最大的价值，同时也是最容易出问题的地方面——自由度越高，配置项越多，能配错的地方就越多。所以我下面不会只给你一串命令，而是把每个参数为什么这么填、填错的后果是什么，一并说清楚。

另外提前打个预防针：这类开源项目迭代很快，环境变量的名字、镜像的标签、数据库迁移的方式，几个月就可能变一次。我在文中给出的配置是"某个时间点上的常见实践"，思路和结构是稳定的，具体字段名请以你手上那个版本的配置说明为准。这个提醒不是免责声明，而是实操经验——照着半年前的教程抄配置，是新手最常见的翻车原因之一。

2. 部署路径选型：三条路各自的代价，先想清楚再动手

2.1 容器一键启动：先用二十分钟确认这个东西值不值得投入

如果你只是想验证"这套界面能不能对接我的模型"，不要碰源码，直接用容器。一条命令起一个实例，端口映射到本机 3210，模型密钥和访问口令通过环境变量注入：

docker run -d --name lobe-chat \ -p 3210:3210 \ -e OPENAI_API_KEY=sk-your-key \ -e OPENAI_PROXY_URL=https://your-endpoint/v1 \ -e ACCESS_CODE=change-me-please \ -e OLLAMA_PROXY_URL=http://host.docker.internal:11434 \ --restart unless-stopped \ lobehub/lobe-chat:latest

启动后浏览器打开http://127.0.0.1:3210，输入ACCESS_CODE就能进。这套路径的优势非常明确：它把数据库、迁移、构建这些环节全部绕过去了。很多版本的镜像默认使用浏览器端嵌入式数据库，数据存在你本机浏览器的 IndexedDB 里，关掉浏览器换个设备就没了——这不是缺陷，这是刻意设计的轻量模式。

我建议所有第一次接触的人都先走这条路，原因不是它简单，而是它能让你在二十分钟内回答一个关键问题：这个界面交互我到底顺不顺手。如果不顺手，后面所有关于数据库、对象存储、反向代理的功夫都是白费。反过来，如果你连容器都起不来，那说明你的运行环境有问题（比如端口被占、镜像拉不下来、宿主机架构是 ARM 而镜像只有 x86），这些问题在简单模式下暴露出来，比在复杂配置里排查要省事十倍。

容器模式下有三点容易忽略。第一，--restart unless-stopped一定要加，否则宿主机重启后服务就没了，你会以为是程序崩了。第二，ACCESS_CODE不要留空，哪怕只在内网，因为一旦你哪天做端口转发测试，空口令的实例就是个敞开的入口。第三，镜像标签建议锁版本号而不是用latest，latest会在你某次重启后悄悄换掉底层实现，导致行为变化。

2.2 源码构建：可控性的代价是时间和依赖地狱

什么时候必须走源码？我的判断标准是三条：需要改界面文案或主题、需要接入项目自己的登录体系、需要给界面加内部专用的功能入口。这三条只要占一条，容器方案就会变得别扭——你可以挂载环境变量，但你改不了代码。

源码路径的典型流程是装依赖、构建、启动：

git clone <项目仓库地址> lobe-chat-src cd lobe-chat-src corepack enable pnpm install cp .env.example .env # 编辑 .env，填入模型与数据库配置 pnpm build pnpm start

这里有几个真实踩过的坑。Node 版本必须对齐，很多前端项目对 Node 主版本有硬要求，版本低了构建阶段会报语法错误，版本高了某些依赖的原生模块编译不过；用corepack管理包管理器版本能省掉一半的"我本地能跑服务器跑不了"的问题。内存要留够，Next.js 这类框架的构建阶段是内存大户，2G 内存的小机器大概率会在构建中途被系统杀掉进程，表现是"毫无征兆地退出"，很多人误以为是代码问题，其实是 OOM。构建机上我一般保证 4G 以上可用内存，实在不够就加 swap。

还有一点：构建产物和运行环境要一致。你在 A 机器上pnpm build，把产物拷到 B 机器上pnpm start，如果两边的 Node 主版本不同，很可能起不来或者行为诡异。所以我更推荐"在目标机器上构建"或者"用多阶段 Dockerfile 构建"，而不是手工搬运产物。这也解释了为什么绝大多数生产部署最终都会回到容器——不是容器多高级，是它把环境一致性这件事标准化了。

2.3 先定数据库还是先定存储：配置顺序错了会返工

这是我在多个项目里见过最多的返工点。正确的顺序是：先想清楚"要不要多用户"，再决定数据库；先想清楚"要不要传文件"，再决定对象存储。

如果只是自己一个人用，会话数据放在浏览器本地完全够用，不需要数据库。但只要出现下面任一情况，就必须上服务端数据库：多人共用一个实例、希望换设备后会话还在、要用知识库检索功能（向量数据必须有地方存）。数据库选型上，PostgreSQL 是这类项目的默认答案，因为知识库检索需要向量扩展，而 PostgreSQL 的向量扩展生态最成熟。

对象存储同理。纯文本对话不需要它，但只要你打算上传图片、文档、音频，就必须配一套兼容 S3 协议的对象存储，否则上传会在最后一步失败——界面看起来一切正常，点上传转两圈然后报错，非常打击人。

我给出的建议顺序是这样的：

按这个顺序推进，每一步都是可验证的，不会出现"一口气配了八个变量，起不来也不知道是哪个错了"的局面。

3. 环境变量怎么填：分档、算参数、少踩坑

3.1 把变量分成三档，排查时按档位砍

环境变量动辄二三十个，一次性全填是灾难。我的做法是分三档，出问题时从第三档往回砍。

第一档：不起就白搭。访问口令、模型接口地址、模型密钥。这三个决定"能不能打开"和"能不能说话"。

第二档：决定功能是否完整。数据库连接串、数据库驱动类型、密钥库加密串、鉴权密钥。这几个决定"数据能不能留住"和"登录状态稳不稳"。

第三档：锦上添花但容易配错。对象存储的四五个参数、语音服务地址、时区、日志级别。这些配错了不会导致启动失败，但会在具体功能上表现异常，最难排查。

下面是一份我常用的变量清单，字段名以你手上版本为准：

关于DATABASE_DRIVER这个变量，值得单独说一句。这是最容易漏的一项：很多人配了DATABASE_URL，以为大功告成，结果数据还是存在浏览器里。原因是驱动类型没切，程序仍然走本地存储分支。这个设计其实挺合理——让不配数据库的人也能用——但对配置者来说就是个隐形陷阱。判断方法很简单：换个浏览器打开，如果会话列表是空的，说明你还在用本地存储，数据库根本没生效。

3.2 两个密钥的生成：长度不够会埋雷

KEY_VAULTS_SECRET和NEXT_AUTH_SECRET这两项，最常见的错误是随手敲一串abc123。前者用于加密你在界面上填的模型密钥，后者用于签名登录会话。它们有两个共同特性：长度有下限，一旦定下来就不能随便改。

生成方式用系统自带工具就行：

# 32 字节随机数，base64 编码后长度足够 openssl rand -base64 32 # 或者用 /dev/urandom head -c 32 /dev/urandom | base64

为什么强调"不能随便改"？因为KEY_VAULTS_SECRET变更后，之前用它加密存储的模型密钥全部失效。表现出来就是：服务启动正常，界面能打开，但一发消息就报错说密钥无效，你去设置页看，密钥那一栏是空的或者显示异常。这时候很多人以为是密钥过期了，重新填一遍，填完发现还是不行——因为写入时用的是新密钥，读取旧数据时用的也是新密钥，旧密文永远解不开。正确做法是：定下一个值之后写进你的配置管理里，别每次部署重新生成。

注意：如果你是从"试用模式"迁移到"正式配置"，中途改过加密串，那历史会话里保存的密钥类数据基本就废了，需要重新填一遍。这不是 bug，是加密的必然结果，迁移前心里要有数。

3.3 模型接入：本地服务和云端接口混着用的实操细节

LobeChat 的核心价值之一是多模型并存。你可以同时挂本地的小模型和远端的大模型，界面上直接切换。这里的关键是两套变量不要互相干扰。

接本地模型服务（比如常见的那套本地推理工具），地址填宿主机上的服务端口。这里有个几乎人人都会踩的坑：如果你把界面跑在容器里，那么容器内的127.0.0.1指的是容器自己，不是宿主机。所以本地模型的地址不能填http://127.0.0.1:11434，要填http://host.docker.internal:11434（macOS 和部分 Windows 环境），或者宿主机的网桥地址（Linux 下常见是172.17.0.1）。填错的症状是模型列表一直空白，日志里能看到连接被拒。

第二个坑是跨域限制。本地推理服务默认只允许本机来源的请求，而你的界面在浏览器里是从http://127.0.0.1:3210发起的，来源对不上就会被拦。解决办法是在启动本地推理服务时放行来源，通常通过一个环境变量配置允许的域名列表，把界面地址加进去再重启服务。

接远端兼容接口时，地址末尾的/v1是高频错误点。有的接口要求带，有的会自动补，带重了会变成/v1/v1/chat/completions，报 404。排查这类问题时，不要盯着界面看，直接在宿主机上用curl打一次接口，能通再回来配界面，能省掉大量猜测。

还有一个实用技巧：给不同模型配不同的"助手"。与其每次聊天手动切模型、改参数，不如为常用场景各建一个助手，把模型、温度、系统提示词一次性定好。温度这个参数值得按场景调：写代码和做结构化输出时压到 0.2 以下，追求稳定复现；头脑风暴和写文案时放到 0.7 到 0.9，让输出有变化。我见过太多人所有场景都用默认值，然后抱怨"这模型怎么一会儿好一会儿傻"，其实问题在参数不在模型。

4. 从零到可访问：一条能复现的完整链路

4.1 编排文件与目录结构

真正要长期跑，我建议用编排文件而不是裸docker run，因为你要同时管理界面、数据库、对象存储三个服务，手敲命令很难保持一致。目录结构我一般这样放：

/srv/lobe/ ├── docker-compose.yml ├── .env └── data/ ├── postgres/ └── minio/

编排文件里，界面服务依赖数据库健康检查，避免界面先起来连不上库然后一直报错：

services: chat: image: lobehub/lobe-chat:latest container_name: lobe-chat restart: unless-stopped ports: - "3210:3210" env_file: - .env depends_on: db: condition: service_healthy networks: - lobe-net db: image: pgvector/pgvector:pg16 container_name: lobe-db restart: unless-stopped environment: POSTGRES_USER: lobe POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_DB: lobedb TZ: Asia/Shanghai volumes: - ./data/postgres:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U lobe -d lobedb"] interval: 10s timeout: 5s retries: 10 networks: - lobe-net storage: image: minio/minio:latest container_name: lobe-storage restart: unless-stopped command: server /data --console-address ":9001" environment: MINIO_ROOT_USER: ${S3_ACCESS_KEY_ID} MINIO_ROOT_PASSWORD: ${S3_SECRET_ACCESS_KEY} volumes: - ./data/minio:/data ports: - "9000:9000" - "9001:9001" networks: - lobe-net networks: lobe-net: driver: bridge

配套的.env里，数据库地址要用服务名而不是127.0.0.1，因为在同一个自定义网络里，容器之间靠服务名互相解析：

# 数据库 DATABASE_URL=postgresql://lobe:${DB_PASSWORD}@db:5432/lobedb DATABASE_DRIVER=node # 密钥与访问 ACCESS_CODE=replace-with-a-long-code KEY_VAULTS_SECRET=replace-with-openssl-output NEXT_AUTH_SECRET=replace-with-another-openssl-output # 模型 OPENAI_API_KEY=sk-your-key OPENAI_PROXY_URL=https://your-endpoint/v1 OLLAMA_PROXY_URL=http://host.docker.internal:11434 # 对象存储 S3_ACCESS_KEY_ID=lobe-storage-admin S3_SECRET_ACCESS_KEY=replace-with-strong-password S3_ENDPOINT=http://storage:9000 S3_BUCKET=lobe-files S3_PUBLIC_DOMAIN=http://127.0.0.1:9000 S3_ENABLE_PATH_STYLE=1 TZ=Asia/Shanghai

S3_ENABLE_PATH_STYLE=1这一项非常关键。自建对象存储通常使用路径风格的访问方式（http://host/bucket/key），而云厂商多是虚拟主机风格（http://bucket.host/key）。不设这个参数，上传会返回莫名其妙的 400。这也是"自建存储和云存储不能无脑替换"的典型例子。

4.2 数据库初始化与向量维度这个隐形约束

数据库第一次起来时，业务表需要初始化。多数版本会在服务启动时自动执行迁移脚本，你只要保证连接串正确、数据库已就绪即可。如果启动日志里没有迁移记录，且页面功能异常，就手动跑一次迁移命令（具体命令看项目脚本定义，通常是包管理器加db:migrate之类的子命令）。

这里有个必须提前想清楚的问题：向量维度。知识库功能会把文档切片、转向量、存进数据库的向量列。向量列的维度在建表时就固定了，之后不能随便改。常见嵌入模型的输出维度有 768、1024、1536 等，如果你先用了某模型的 1536 维建表，后来想换一个 1024 维的模型，写入会直接失败，报维度不匹配。

所以我的建议是：建库之前就定好你打算用哪个嵌入模型，并且短期内不换。真要换，方案是新建一张表或者重建库再导入数据，成本不低。这一点在任何文档里都不显眼，但返工的时候特别疼。

另外顺带说一句资源规划。界面服务本身是 Node 常驻进程，空闲内存占用大概两三百兆；数据库 500 兆起步，量大了一千兆也正常；对象存储看文件量。一台 2 核 4G 的小机器跑这三件套是够的，但如果同时在这台机器上跑本地模型推理，那显存和内存就得分开算——推理服务和这三件套抢资源是常见事故，表现是聊天回复突然变慢甚至超时。

4.3 反向代理：流式输出被缓冲，是最隐蔽的故障

直接用IP:端口访问当然可以，但一旦要加域名、加证书、做统一入口，就得挂反向代理。这里的配置有一个绝对不能漏的参数：

server { listen 80; server_name chat.example.internal; # 文件上传需要放宽体积限制 client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:3210; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 流式输出必须关掉缓冲 proxy_buffering off; proxy_cache off; # 长连接，避免模型思考途中被掐断 proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }

不关proxy_buffering的症状很有意思：界面能打开，模型列表能拉，发一条短消息也正常，但一旦回复变长，就会卡住不动，等十几秒后整段文字突然全出来。新手看到这个现象，第一反应是"模型太慢了"，去换模型、调参数，全是无用功。真正的原因是代理把流式响应攒成一坨再转发，前端收不到分片。

client_max_body_size也是同类问题。传文档做知识库的时候，稍微大一点的 PDF 就会被代理直接拒掉，接口返回 413，界面上的表现是上传进度条走到一半消失。这个参数默认值往往只有 1m，对聊天够用，对文件上传完全不够。

提示：如果你的代理层还挂了别的网关或 CDN，记得把缓冲、超时、体积限制同步放开，只改一层往往不够。

4.4 进来之后先做这四件事，别急着聊天

服务能打开只是开始。第一次进去，我按固定顺序做四件事，能省掉后面大量麻烦。

第一件，改访问口令并且确认生效。用无痕窗口开一次，看是不是还要求输入口令。有些部署方式会把口令固化在构建产物里，改了环境变量不重启不生效，你以为改了，其实是旧值。

第二件，在设置里确认模型可用。不要只发一句"你好"，要发一条长一点的、需要推理的请求，观察是否完整流式输出。这一步同时验证了接口连通性、密钥有效性和代理缓冲配置。

第三件，建一个助手并把参数定死。选好模型，把温度、上下文轮数、系统提示词填上，取个名字保存。后续所有重复性工作都从这里进，而不是每次从默认会话开始。

第四件，做一次完整的上传测试。传一张图片、一份文档，然后刷新页面确认文件还在。刷新后消失说明对象存储的持久化目录没挂对，或者公有访问域名配错了。

5. 排查实录：这些坑我一个个趟过来的

5.1 症状到原因的快查表

遇到问题别慌，先按症状对号，多数情况能直接定位到配置层，不用翻代码。

5.2 三个文档里不会写但会让你卡半天的细节

第一个，数据库密码里的特殊字符。连接串是 URL 格式，密码里如果有@、:、/、#这些字符，会被解析成结构分隔符，导致连接串被截断。症状是"用户名密码明明对，就是连不上"。解决办法有两个：密码只用字母数字加下划线，或者对特殊字符做百分号编码。我一般直接选前者，省事。

第二个，容器重启策略和健康检查的配合。如果你的界面服务先于数据库就绪，它会启动失败然后按重启策略反复重启。加了depends_on的条件等待之后，这个循环会消失。但如果数据库本身挂了健康检查没通过，界面会一直处于"等待中"状态，日志里看不到明显报错。判断方法是单独docker logs看数据库容器，别只看界面容器。

第三个，备份要备份两样东西，不是一样。数据库里的会话是逻辑数据，对象存储里的文件是二进制数据，两个都要备。我见过只备数据库的，恢复之后所有历史会话里的图片全变成裂图，因为文件根本不在。备份策略上，小规模场景用"定时导出数据库 + 直接复制存储目录"就够，注意复制存储目录前先停一下写入，否则可能拷到半个文件。

还有一个不吐不快的经验：别在生产实例上试新版本。这类项目版本迭代快，新版本可能改了环境变量名、改了数据库结构、改了接口路径。要升级就先把当前的数据目录整个复制一份，在副本上把新版本跑通、确认会话能读、文件能传、知识库能检索，再动正式那份。我第一次图省事直接升级，结果数据库迁移不可逆，回滚版本之后老代码读不了新表结构，折腾了一整晚重建。

最后分享一个我在长期使用里形成的小习惯：给每个助手写一句"使用说明"放在描述里，写清楚这个助手吃什么输入、输出什么格式、温度多少。三个月后你自己都记不住当初为什么把温度设成 0.3，但描述里写着，就不用猜了。这套东西的价值不在于搭起来那一刻有多惊艳，而在于半年后它还在稳定地替你干活。