企业官网建设流程全解析

简介：这份压缩包围绕 LobeChat 与 DeepSeek R1 的集成场景整理，面向希望研究聊天应用如何接入 DeepSeek R1、并借鉴成熟前端工程配置的开发者与学习者。内容以项目源码和配套配置为主，可用于本地代码阅读、环境搭建参考、接口联调前的结构梳理，也适合作为全栈项目工程化实践的对照材料。包内共2000个文件，压缩后约18.67MB，主要包含741个 tsx 与667个 ts 源文件、482个 json 配置/数据文件，以及 Markdown 文档、YAML 部署配置、SQL 脚本和少量样式、测试快照与脚本文件，覆盖界面组件、业务逻辑、数据层和构建配置等层面。已有150人学习下载。读者可从中获得较完整的目录结构、环境变量示例、国际化与代码质量工具配置、提交规范、发布流程和变更日志规则等参考，便于快速理解项目组织方式、复用工程配置并减少搭建与排错成本。

1. 一个聊天框接上 DeepSeek R1 之后，我才看清推理模型的真实脾气

上周有个朋友把他自建的 LobeChat 截图发我，界面上问的是同一道逻辑题，DeepSeek R1 在对话框里憋了十几秒，然后一串"思考中"折叠起来，答案干净利落地摆在下面。他问的是"为什么我这边只有一坨没有折叠的纯文本"。差别不在模型，在于接入方式、字段透传和前端渲染三处细节。LobeChat 本身是个开源的对话壳子，多模型、插件、知识库、本地会话都齐，把 DeepSeek R1 这类推理模型接进去，价值就在于你能自己控制 API 出口、留存上下文、按项目隔离会话，而不是被某个网页端的口径绑住。这篇写的就是我实际搭过一遍的路径：三种接法怎么选、环境变量怎么填、哪些参数会影响思维链的展示，以及我踩过的那几个坑。适合准备自托管聊天入口、又要接推理模型的开发者。

2. 先把链路拆开：LobeChat 是壳，DeepSeek R1 是脑，协议是血管

动手之前得先把这条链路上有哪几个环节想清楚，不然后面报错了你连是哪一层出的问题都判断不了。很多人一上来就复制 docker run，跑起来发现模型列表里压根没有 R1，就开始怀疑是不是镜像拉错了。其实就是少填了一个 URL，或者模型 ID 写成了聊天模型的别名。

2.1 三个角色各自负责什么

LobeChat 这一层是纯前端 + 轻服务端。浏览器里的对话、会话历史、提示词库、插件调用、文件上传都在这一层消化，真正发出去的只有一个标准的 Chat Completions 请求。它自己不含任何模型权重，也不做推理，所以它的"智能"完全取决于你给它配了哪个上游。

DeepSeek R1 这一层是模型服务。它可以跑在模型官方的 API 上，也可以跑在你自己机房的推理服务里，还可以跑在本地 Ollama 里。R1 和普通聊天模型最大的区别是它会把推理过程单独放在一个字段里返回，OpenAI 兼容协议下一般是reasoning_content，正文仍然是content。这个字段能不能被前端正确读到、能不能折叠展示，取决于中间那一层有没有把它透传下来。

协议层是血管。LobeChat 对上游的抽象基本就是 OpenAI 的 Chat Completions 格式，这意味着只要某个服务对外暴露/v1/chat/completions，理论上就能接进来。官方 API、Ollama、vLLM、各类第三方兼容网关，走的都是这一条路。

理清这三层之后，排查就有了顺序：先确认上游服务本身通不通，再确认协议字段对不对，最后才看前端配置。反过来做，你会在一堆无关的地方浪费时间。

2.2 三条接入路线的取舍

路线选择本质上是三件事的权衡：数据出不出你的机器、首 token 延迟能不能接受、以及钱包鼓不鼓。

我一般的做法是分两段走：先用官方 API 把 LobeChat 的界面、会话、插件全部跑通，确认交互没问题；然后再把上游换成本地蒸馏版，观察同样的提示词在 7B、14B、32B 上的差距。这样出问题时能立刻区分是"壳的问题"还是"脑的问题"。

需要提醒的是，蒸馏版和满血版 R1 不是一回事。7B、14B 这类小参数蒸馏模型在数学和代码上表现会明显弱一截，上下文长度和稳定性也不一样。拿它做演示没问题，拿它当生产推理后端要先做一轮自己的评测。

2.3 起手前的环境对齐

正式动手之前，有三样东西要先对齐，能省掉后面一大半的玄学问题。

第一是 Node 版本。源码方式跑 LobeChat 需要比较新的 Node，建议 20 LTS 以上，pnpm 走 9 以上。版本太老会在安装依赖阶段就报各种 peer 冲突，那种报错看起来像网络问题，实际是运行时版本不匹配。

第二是端口占用。LobeChat 默认 3210，Ollama 默认 11434，vLLM 默认 8000。这三个端口在本机上很容易和别的服务撞车，尤其 8000 被一堆 Python 项目占着。起服务前先ss -lntp看一眼。

第三是显存预算。本地跑蒸馏版时，模型权重要占一份，KV Cache 还要再占一份，上下文开得越长后者越大。8GB 显存跑 7B 的 4bit 量化勉强够，但上下文一开到 32K 就会 OOM。这个账要提前算，不要等跑到一半炸了再回头改。

3. 起服务：Docker Compose 与源码两条路，选一条走通

LobeChat 的部署方式大致分容器和源码两类。容器省事，适合把它当成一个长期在线的服务；源码适合你要改前端、加自定义 provider 或者调样式。两条路我都走过，下面把关键命令和参数说明摆出来。

3.1 用 compose 文件把 LobeChat 拉起来

我习惯用 compose 而不是一长串 docker run，原因是环境变量多，写在文件里好改好留档。下面这份是最小可用版本，包含 LobeChat 本体和一个本地的 PostgreSQL（用数据库模式才能多端同步会话，纯本地模式可以不要数据库）。

# docker-compose.yml services: lobe-chat: image: lobehub/lobe-chat:latest container_name: lobe-chat restart: unless-stopped ports: - "3210:3210" # 宿主机端口:容器端口，撞车就改左边 environment: - ACCESS_CODE=change_me_please # 访问口令，公网部署必须改 - OPENAI_API_KEY=sk-xxxxxxxx # 上游密钥，本地 Ollama 可随便填 - OPENAI_PROXY_URL=https://api.deepseek.com/v1 # 上游地址，注意结尾 /v1 - OPENAI_MODEL_LIST=-all,+deepseek-reasoner,+deepseek-chat depends_on: - postgres postgres: image: pgvector/pgvector:pg16 container_name: lobe-postgres restart: unless-stopped environment: - POSTGRES_PASSWORD=lobe_dev_pwd - POSTGRES_USER=lobe - POSTGRES_DB=lobe volumes: - ./data/postgres:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U lobe -d lobe"] interval: 10s retries: 5

这份文件里真正影响能不能跑通的是三个变量。OPENAI_PROXY_URL决定了请求打到哪，官方 API 是https://api.deepseek.com/v1（也可以不带/v1，但带了更保险，能避开一部分路径拼接问题）；OPENAI_API_KEY是鉴权头，本地 Ollama 不校验，填个占位串即可；OPENAI_MODEL_LIST是模型白名单，语法是逗号分隔的增删指令，-all表示先清空默认列表，后面用+逐个加回来。不写这一行，界面上会冒出一堆你可能根本没权限的默认模型，选错了就是 404。

起服务：

# 前台起，方便看日志；确认没问题后加 -d 转后台 docker compose up # 看容器日志里有没有拉取模型列表失败的报错 docker compose logs -f lobe-chat | grep -i "model\|error"

日志这一句很关键。LobeChat 启动时会尝试拉一次上游的模型清单，如果OPENAI_PROXY_URL写错了或者密钥无效，日志里会出现明显的连接错误或 401。很多人不看日志，直接开浏览器，看到模型列表空的就懵了。

3.2 源码方式：pnpm 安装到 dev 启动

要改代码就走源码。装依赖这一步最容易卡住，我把关键命令列出来，附带每一步该看什么。

# 1. 拉代码并进入目录（换成你自己的仓库地址） git clone <your-lobe-chat-repo> lobe-chat && cd lobe-chat # 2. 锁死 Node 版本，避免 peer 依赖地狱 nvm use 20 || nvm install 20 node -v # 期望 v20.x # 3. 用 corepack 启用 pnpm，版本以 package.json 的 packageManager 字段为准 corepack enable corepack prepare pnpm@latest --activate pnpm -v # 4. 装依赖。这里最容易卡在原生依赖编译 pnpm install # 5. 准备环境变量文件 cp .env.example .env.local 2>/dev/null || touch .env.local # 6. 开发模式启动，默认 3210 pnpm dev

pnpm install这一步如果卡在某个包上超过五分钟，先看是不是原生模块在编译。常见的处理是确认本机装了 build-essential（或者对应平台的编译工具链）和 python3。pnpm dev起来之后，终端会打印本地地址，改代码会热更新。

.env.local里的内容跟上面的 compose 环境变量是对应的，写成一行一个键值即可：

# .env.local ACCESS_CODE=change_me_please OPENAI_API_KEY=sk-xxxxxxxx OPENAI_PROXY_URL=https://api.deepseek.com/v1 OPENAI_MODEL_LIST=-all,+deepseek-reasoner,+deepseek-chat

源码方式还有一个好处：你可以在 provider 注册的地方打断点，看清楚模型列表到底是怎么拼出来的、reasoning_content这个字段在解析时有没有被丢掉。我当初排查思维链不显示的问题，就是在这个位置定位到的。

3.3 关键环境变量一张表

变量多的时候表格比代码块好查，下面这几个是我实际用到的，按重要性从高到低排。

最后一条要专门说一下。客户端模式下，上游密钥会被打包进浏览器能看到的请求里，只要有人打开开发者工具就能捞走。公网部署一律用服务端模式，请求由 LobeChat 的服务端代发，密钥留在服务器上。

ACCESS_CODE也别偷懒不设。我见过有人把服务挂在自己的云主机上忘了加口令，几天后被扫到，密钥被刷掉了不少额度。这种事没有后悔药，起服务的第一条命令就该把它设上。

4. 接入 DeepSeek R1：三种 provider 的填法与自检

服务起来只是有了壳，真正决定体验的是上游怎么接。这一章按三条路线分别写填法，每条都给能直接抄的配置，最后讲怎么自检。

4.1 OpenAI 兼容口：BaseURL + 模型 ID 两处别写错

官方 API 这条路最短。LobeChat 的界面里，设置 → 语言模型 → OpenAI，填两样东西：API Key 和接口代理地址。这里有个常识但经常被忽略的点——接口地址要带版本号路径，模型 ID 要写 R1 对应的那个而不是聊天模型的。

# 先用 curl 确认上游本身是通的，排除 LobeChat 的干扰 curl https://api.deepseek.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -d '{ "model": "deepseek-reasoner", "messages": [{"role": "user", "content": "9.11 和 9.8 哪个大"}], "stream": false }'

返回里除了choices[0].message.content，还会多出一个reasoning_content字段，这就是思考过程。如果你拿到的 JSON 里完全没有这个键，先怀疑模型 ID 写成了聊天模型——聊天模型不会返回推理字段，表现就是"思考过程消失但答案正常"。

模型 ID 这块，官方 API 上 R1 对应deepseek-reasoner，通用对话对应deepseek-chat。这两个别搞混，写反了不会报错，只是行为不符合预期，属于最难排查的那类问题。

stream建议先用false测一遍，确认结构对了再开流式。流式下响应是按 chunk 拼的，reasoning_content会分散在多个 chunk 里，肉眼很难看出哪一段丢了。

4.2 Ollama 本地跑蒸馏版：显存、量化与上下文长度

想把数据留在自己机器上，Ollama 是最省事的起点。拉模型和起服务两条命令：

# 拉一个蒸馏版，标签按你自己的显存选：1.5b / 7b / 8b / 14b / 32b / 70b ollama pull deepseek-r1:7b # 启动服务，默认监听 127.0.0.1:11434 # OLLAMA_HOST=0.0.0.0 是给容器内的 LobeChat 访问用的 OLLAMA_HOST=0.0.0.0 ollama serve # 验证模型能跑通 ollama run deepseek-r1:7b "用一句话解释二分查找的前提条件"

三个参数决定体验。OLLAMA_HOST控制监听地址，如果你用 Docker 跑 LobeChat，容器里的localhost指的是容器自己，必须让 Ollama 监听0.0.0.0并在 LobeChat 里填宿主机的内网 IP 或者host.docker.internal。OLLAMA_NUM_PARALLEL控制并发请求数，默认值偏保守，多人同时用会排队。上下文长度则通过 Modelfile 里的num_ctx调整，默认值通常比你想象的短，长文档场景必须显式改。

在 LobeChat 里的填法是把 provider 选成 Ollama，地址填http://<宿主机IP>:11434，注意这里不要带/v1，Ollama 的原生接口路径和 OpenAI 兼容路径是两套。如果你坚持走 OpenAI 兼容口，地址要写成http://<宿主机IP>:11434/v1，模型 ID 写deepseek-r1:7b。

一个容易翻车的细节是模型名带冒号。某些版本的 URL 拼接逻辑没有对冒号做编码，导致请求路径变成非法格式。稳妥做法是先在终端用 curl 打一次兼容口：

curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-r1:7b","messages":[{"role":"user","content":"ping"}],"stream":false}'

这条通了，界面里基本就不会有大问题。不通的话，问题一定在 Ollama 侧，跟 LobeChat 无关。

4.3 自托管推理服务：并发和上下文长度的两个旋钮

团队用的话，Ollama 的吞吐会不够。常见做法是换 vLLM 这类推理服务，它对外同样暴露 OpenAI 兼容接口，LobeChat 这边几乎不用改配置，只换地址和模型名。

# vLLM 起一个 OpenAI 兼容服务 python -m vllm.entrypoints.openai.api_server \ --model /models/DeepSeek-R1-Distill-Qwen-14B \ --served-model-name deepseek-r1-14b \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 16384 \ --gpu-memory-utilization 0.90 \ --tensor-parallel-size 1

--max-model-len是上下文窗口，直接决定 KV Cache 的显存占用，开太大容易 OOM，开太小长文档会被截断，建议先按业务实际需要给，不要一上来就拉满。--gpu-memory-utilization控制显存占用比例，0.9 是常见值，留一点余量给其他进程。--tensor-parallel-size是多卡切分，单卡填 1，双卡填 2，填错会直接起不来。--served-model-name是你自己起的对外名字，LobeChat 里模型 ID 就填这个。

推理参数上还有一个和普通聊天模型不一样的地方：R1 的输出里思考过程会占掉大量 token，max_tokens给小了会出现"思考到一半被截断、正文为空"的现象。这个现象很像模型坏了，实际是配额不够。建议起步给 4096，宽松一点给 8192。

4.4 双通道自检：curl 通了页面不一定通

我养成的一个习惯是接完之后走两遍自检，一遍在命令行，一遍在浏览器。命令行看结构，浏览器看渲染，两遍都能过才算接好。

命令行的检查点是三段：HTTP 状态码是 200、返回 JSON 里有choices、模板里如果开了思考字段，reasoning_content非空。缺哪一段就对应哪一层的问题。

浏览器这边的检查点是：模型列表里能看到你配置的那个模型名、发消息后首 token 有时间、流式输出不中途断、思考过程能折叠。这四个里任何一个不对，回头去看第 5 章对应的小节。

提示：自检用的提示词别用"你好"这种。用一道需要几步推理的小题，比如带单位的换算或者简单逻辑题，这样你才能看出思考过程到底有没有被触发。用闲聊测试，思考字段可能本来就是空的，白白浪费一轮排查。

5. 避坑与排查：接完 R1 之后最容易翻车的五件事

下面这五条都是我自己或者身边人真实撞过的，按"现象 → 原因 → 解决"的顺序写。每一条我都尽量把定位方法写清楚，因为知道"看哪里"比知道"改什么"更有用。

5.1 现象是消息发出去很久没有反应，最后弹超时

先分清是上游慢还是链路慢。打开终端，直接 curl 上游同一个提示词，掐表看响应时间。如果 curl 也慢，问题在模型服务侧；如果 curl 很快而页面慢，问题在中间层。

上游慢的常见原因有三个。一是推理服务在排队，--max-num-seqs或者 Ollama 的并行数设得太小，请求全挤在队列里。二是上下文窗口开得太大，KV Cache 占满显存后触发换页，速度断崖式下跌。三是 R1 本身思考链偏长，复杂问题思考几千 token 是正常的，前端如果超时设成 30 秒就会被掐断。

解决上，前端超时和上游并发要一起调。把 LobeChat 的请求超时放宽，同时给推理服务加并发额度，再把max_tokens控制在一个合理范围，避免模型无止境地思考下去。还有一种情况是反向代理层（nginx 之类）默认的读超时只有 60 秒，流式输出被它先掐了，这种情况要改代理的proxy_read_timeout，光改应用层没用。

定位这类问题的关键是看日志的时间戳：请求什么时候进来、第一个 token 什么时候吐出、最后一个 token 什么时候结束。三个时间点一看，卡在哪一段就清楚了。

5.2 现象是答案出来了，但思考过程那一栏是空的或者显示成一坨纯文本

思考过程不显示分两种。一种是数据层面就没有，另一种是数据有但前端没渲染。

先确认数据。用 curl 打一次同样的请求，看返回的 JSON 里有没有推理字段。没有的话，八成是模型 ID 写成了聊天模型，或者你接的那条线本身就不透传这个字段——部分中转网关只转content，把reasoning_content直接丢了。这种情况换直连或者换网关，应用层怎么调都没用。

数据有但显示成纯文本，是解析层的问题。某些版本对推理字段的识别是按模型名匹配的，你的模型名不在它的白名单里，就被当成普通内容拼进正文了。解决办法要么把模型 ID 改成它认识的写法，要么在自定义 provider 里显式声明这个模型属于推理模型。

还有一种更隐蔽的情况：流式输出时，思考内容在第一个 chunk 就到了，正文在很后面的 chunk 才到，前端的占位逻辑如果只认第一个 chunk，就会把思考内容当正文渲染，看起来像"答案是一段自言自语"。这种情况要么关掉流式对比一下，要么升级到修复过这个逻辑的版本。

5.3 现象是流式输出到一半卡住，最后渲染出半截话

流式中断的诱因比非流式多得多，我一共遇到过三次，原因各不相同。

第一次是反向代理开了缓冲。nginx 默认会缓冲上游响应，导致前端的 chunk 不是实时到达而是攒一批发一批，看起来就是卡住然后一次性蹦出来。关掉proxy_buffering之后正常。

第二次是响应里出现了非标准的字符序列，前端的 SSE 解析器在某一行抛异常，整个连接就断了。这种情况要看浏览器控制台的报错，会明确指出解析失败的行。修复思路是在服务端对内容做一次清洗，或者升级解析库。

第三次最坑，是推理服务侧的连接保活问题。思考过程长时间没有输出正文，中间的代理认为连接空闲把它断了。解决是在服务端定期发心跳，或者干脆把代理的空闲超时拉长。

判断方法很简单：浏览器开发者工具的 Network 面板里看那条流式请求，如果状态一直是 pending 但没有任何 chunk 进来，是缓冲问题；如果 chunk 进来一部分之后连接状态变成 failed，是被中途掐断；如果报解析错误，就是格式问题。这三种看一眼就知道该往哪查。

5.4 现象是长对话聊到十几轮之后开始胡言乱语或者答非所问

这大概率是上下文被悄悄截断了，而界面上没有任何提示。

原因有两层。第一层是模型服务侧的上下文窗口限制，超过max-model-len的部分会被直接丢弃，丢弃策略通常是保留开头和结尾、砍掉中间，于是模型看不到中间的关键信息。第二层是应用侧的会话历史条数限制，LobeChat 本身有历史消息裁剪策略，条数或者 token 超了就只发最近几条上去。

解决上，先把上游的上下文窗口调到能覆盖你的典型场景，再在应用侧确认历史条数设置。长文档问答这类场景，更稳的做法是走知识库或者文件上传，让检索来补上下文，而不是把所有内容硬塞进对话历史。

还有一个细节容易被忽略：R1 的思考过程也占上下文。如果服务端把历史里的思考内容也原样带上去，token 消耗会翻倍甚至更多，挤占本就不宽裕的窗口。我一般会在持久化时把历史中的推理字段剥掉，只留正文，这样同样的窗口能多聊好几轮。

5.5 现象是本机跑得好好的，一挂到公网就各种失败

本机和公网最大的差别在访问链路和鉴权，问题也集中在这两块。

第一类是跨域。浏览器直接请求上游接口时，如果上游没开 CORS，请求会被浏览器拦下来。解决方案是走服务端模式，让 LobeChat 的服务端代发请求，浏览器只跟同源的服务端通信，跨域问题自然消失。

第二类是地址填错。容器里的localhost不等于宿主机的localhost，这是新手最容易踩的一个。容器连宿主机的服务要用宿主机的内网 IP 或者宿主机的特殊域名，具体看你用的容器运行时。

第三类是鉴权头被覆盖。有些反向代理会重写Authorization头，或者在某些路径下剥离它。表现是上游一直返回 401，但你在服务器上用 curl 打同一个地址是通的。解决是抓一次实际发出去的请求头，对比一下有没有丢。

第四类是 HTTPS 混合内容。页面走 HTTPS，而它请求的后端地址是 HTTP，浏览器会直接拦截。这种情况要么给后端也配上证书，要么统一走同源的相对路径由服务端转发。

这五条捋下来你会发现，真正属于"模型不行"的情况极少，绝大多数是链路配置和字段透传。所以排查顺序永远是：先上游、再协议、最后前端。

6. 进阶：让 R1 的思考过程真正可用，参数、提示词与成本

接入跑通之后，剩下的就是把体验调顺手。这块没有标准答案，只有一些我反复验证过的取值习惯。

先说参数。R1 这类推理模型对温度不敏感，但也不是完全无所谓。做代码和数学，我一般把温度压到 0.3 以下，让输出更确定；做头脑风暴或者文案发散，放到 0.8 左右。max_tokens要给够，因为思考过程算在里面，4096 是下限，长任务直接给 8192。top_p保持默认即可，不要和温度一起大改，两个都动会让结果变得难以复现。

再说提示词。R1 的思考过程是模型自己生成的，你在提示词里加"请一步一步思考"往往没有正收益，甚至可能让它在思考里绕圈子。反过来，明确的输出格式约束是有用的，比如"最终答案只输出 JSON，不要解释"。我一般的写法是把任务描述和输出格式分开写，中间空一行，模型对这个结构比较敏感。

第三件事是成本。按 token 计费的线路下，思考过程的费用经常被低估，一次复杂推理的思考部分可能是正文的三到五倍。两个做法能压下来：一是把历史对话里的思考字段在持久化时剥掉，只留正文，这样多轮对话的输入 token 不会滚雪球；二是批量任务别走对话接口，走离线批处理，省掉重复的系统提示词开销。

最后说一个我踩过的坑。早期我为了看完整思考过程，把max_tokens调得很大，结果遇到模型思考停不下来，一路写到窗口边缘，正文一个字没有。后来我改成一个死规矩：所有接入 R1 的环境，先把max_tokens设成一个能覆盖思考和正文的总预算，再用一句"请给出最终答案"做兜底约束。从那以后我每次接新的推理模型，都强制先用一道小题跑一遍"思考长度 / 正文长度"的比值，心里有数了再放到正式场景里用。这个习惯帮我省了不少返工。希望帮到你。

本文还有配套的精品资源，点击获取