企业官网建设流程全解析

1. Windows 本地部署 FastGPT 知识库问答：从 Docker 到 deepseek 模型接入的完整链路

FastGPT 是一套开源的本地知识库问答系统，能把你手头的 PDF、Word、Markdown 文档切片、向量化，再配合大语言模型做检索增强问答。它适合谁？适合不想把内部资料传到公有云、又希望有类似 ChatGPT 体验的开发者和小团队。整套系统跑在 Windows 上，靠 Docker 拉起 FastGPT、PostgreSQL(pgvector)、One API 三个容器，模型调用则通过 One API 统一转发到 deepseek。

我这次的目标很明确：在 Windows 上从零搭出一套能用的本地知识库问答，语言模型用 deepseek-chat，向量模型用 embedding-2，所有模型请求都经过 One API 这个统一网关。为什么非要加 One API 这一层？因为 FastGPT 本身只认 OpenAI 格式的接口，而 deepseek、智谱这些厂商的地址和鉴权方式各不相同，One API 把它们统一成一套 Base URL + Key + Model ID，后面换模型、加渠道都不用动 FastGPT 的配置。

整条链路的关键节点有三个：Docker 环境能正常拉镜像、One API 渠道测试通过、FastGPT 的 config.json 里模型名和 One API 令牌范围对得上。这三个任意一个出问题，最后的表现都是「知识库创建时模型下拉框是空的」或者「对话报错 reading choices」。下面按顺序把每一步的可复制配置和验证方法写清楚。

需要提前说明的是，模型调用通道除了直连厂商，也可以用 TaoToken 这类统一 Key/API 通道来管理，它把多家模型的调用收敛到一个入口，省去在多个平台之间切换密钥的麻烦。本文的配置以 One API 为网关，你可以在 One API 里把上游指向任意兼容 OpenAI 协议的服务。

2. 前置环境：Docker Desktop 与 WSL2 在 Windows 上的配置要点

这一章解决的是「容器跑不起来」的根因问题。FastGPT 官方推荐用 Docker Compose 部署，Windows 上跑 Linux 容器依赖 WSL2 后端，所以 Docker Desktop 和 WSL2 必须都装好、都更新到较新版本。

先装 Docker Desktop。去 Docker 官网下载 AMD64 版本，安装完重启电脑，启动 Docker Desktop。首次启动如果卡在登录界面，直接跳过登录进主界面即可，本地开发不需要账号。装完后确认左下角或状态栏显示 Engine running。

接着处理 WSL2。WSL 全称 Windows Subsystem for Linux，是在 Windows 上运行原生 Linux 二进制的兼容层，Docker 的 Linux 容器就靠它。打开 PowerShell 或 cmd，执行：

wsl --update

这条命令会自动拉取最新版内核并检查更新。然后进入「启用或关闭 Windows 功能」，确认「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两项已勾选，没勾就勾上再重启。回到 Docker Desktop 的设置里，General 中确认 Use the WSL 2 based engine 已开启。

镜像拉取慢是另一个高频卡点。在 Docker Desktop 的 Settings → Docker Engine 里，把配置改成带镜像加速的版本：

{ "debug": true, "experimental": false, "insecure-registries": [], "registry-mirrors": [ "https://docker.unsee.tech", "https://docker.m.daocloud.io" ] }

改完点 Apply & restart，再重启一次 Docker Desktop。如果状态栏提示 Docker Engine Stopped，按顺序排查：任务管理器服务里确认 com.docker.service 在运行；确认 Hyper-V 已勾选；以管理员身份打开终端执行bcdedit，看最后一行 hypervisorlaunchtype 是否为 Auto，不是就执行下面这条再重启电脑：

bcdedit /set hypervisorlaunchtype auto

最后确认 WSL 已更新、镜像地址配置正确。这几步做完，docker info能正常输出、docker pull hello-world能拉下来，前置环境就算过关了。踩过的坑基本都集中在 WSL 内核版本旧和镜像地址失效这两处，先解决它们能省掉后面大量误判。

3. 可复制配置：docker-compose.yml 与 config.json 的模型对接

这一章是全文的核心，交付两份能直接用的配置文件片段。先在磁盘上新建一个空文件夹，比如D:\FastGPT，所有配置和启动命令都在这个目录里执行。

第一份是docker-compose.yml。FastGPT 官方仓库的files/docker/目录下有 pgvector 版本，可以直接下载：

curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/files/docker/docker-compose-pgvector.yml

下载后重点改两个环境变量，它们决定 FastGPT 去哪里调模型：

environment: - OPENAI_BASE_URL=http://host.docker.internal:3001/v1 - CHAT_API_KEY=sk-你的OneAPI令牌

注意 Base URL 结尾必须带/v1，这是 OpenAI 兼容接口的约定。容器内访问宿主机的 One API，用host.docker.internal代替 localhost；如果 FastGPT 和 One API 在同一个 Docker 网络里，也可以直接写服务名加端口。CHAT_API_KEY填的是 One API 里生成的令牌，不是 deepseek 官方的 key，这一点最容易搞混。

第二份是config.json，它告诉 FastGPT 有哪些模型可用。语言模型加进llmModels，向量模型加进vectorModels：

{ "llmModels": [ { "provider": "OneAPI", "model": "deepseek-chat", "name": "deepseek-chat", "maxContext": 16000, "maxResponse": 4000, "quoteMaxToken": 12000, "maxTemperature": 1, "vision": false, "functionCall": false, "defaultSystemChatPrompt": "" } ], "vectorModels": [ { "provider": "OneAPI", "model": "embedding-2", "name": "embedding-2", "defaultToken": 500, "maxToken": 3000 } ] }

这里的model字段必须和 One API 渠道里填写的模型名完全一致，大小写都不能差。provider写 OneAPI 表示走统一网关。改完两份文件后，在 FastGPT 目录下执行：

docker-compose pull docker-compose up -d

pull会拉取镜像，耗时较长属正常。up -d后台启动后，用docker ps确认三个容器都是 Up 状态。FastGPT 映射到 3000 端口，One API 映射到 3001 端口，浏览器访问http://localhost:3000即可。FastGPT 默认账号 root、密码 1234，One API 默认账号 root、密码 123456，首次登录 One API 会强制改密码。

如果你希望模型调用通道更集中，可以在 One API 的上游渠道里指向 TaoToken 提供的统一 API 入口，这样密钥和额度管理都在一个面板里完成，FastGPT 侧完全不用改。

4. 验证请求：One API 渠道测试与知识库问答全链路确认

配置写完不代表通了，这一章用实际请求验证每一环。先验证 One API 到 deepseek 的链路。登录http://localhost:3001，进入「渠道」→「创建新的渠道」，类型选 deepseek，模型填deepseek-chat，密钥填 deepseek 官方申请的 sk，代理地址填https://api.deepseek.com，提交后点「测试」。如果返回响应时间（比如 800ms），说明渠道通了；如果报错，先检查密钥和地址。

接着去「令牌」→「添加新的令牌」，模型范围勾选deepseek-chat，提交后复制生成的 sk 保存好。这个令牌就是前面CHAT_API_KEY要填的值。一个令牌可以覆盖多个渠道的模型，后面加 embedding-2 时把范围一起勾上即可。

验证 FastGPT 侧。重启服务让配置生效：

docker-compose down docker-compose up -d

进入http://localhost:3000，在工作台新建一个应用，AI 模型下拉框里应该能看到deepseek-chat。如果看不到，说明 config.json 的模型名和令牌范围没对上，或者容器没重启。选中模型后，在右侧对话框发一句「你好，介绍一下你自己」，能正常流式返回就说明语言模型链路通了。

再验证向量模型。去智谱开放平台申请 embedding-2 的密钥，在 One API 里新建渠道，模型填embedding-2，把该模型加入令牌范围。回到 config.json 的vectorModels确认配置无误，重启服务。进入 FastGPT 的「知识库」→「新建知识库」，两个模型下拉框分别选 deepseek-chat 和 embedding-2，都能选中才说明向量链路也通了。

最后做端到端测试：在知识库里上传一份自己的文档，等切片和向量化完成；回到工作台新建应用，类型选「知识库+对话引导」，关联刚才的知识库，把「问题优化」模型设为 deepseek-chat，保存。然后问一个只有文档里才有答案的问题，比如文档里写了某个内部流程的步骤，看回答是否引用了文档内容。能引用并给出正确步骤，整套本地知识库问答系统就算跑通了。

5. 常见报错排查：401、local proxy failed 与 reading choices 的定位方法

这一章按真实报错对照排查，覆盖接入过程中最常撞见的几类问题。

401 Unauthorized。表现是 One API 渠道测试或 FastGPT 对话返回鉴权失败。根因通常是密钥填错或令牌范围不含该模型。排查顺序：确认 One API 渠道里的上游密钥是厂商原始 sk；确认 FastGPT 的CHAT_API_KEY填的是 One API 令牌而非厂商密钥；确认令牌的模型范围勾选了对应模型。三者任一错位都会 401。

local proxy failed / connection refused。表现是 FastGPT 容器日志里出现连接 One API 失败。根因是OPENAI_BASE_URL地址不对。容器内不能用localhost指代宿主机，要写host.docker.internal；端口要确认是 One API 实际映射的 3001；结尾的/v1不能漏。改完必须docker-compose down && docker-compose up -d重启，环境变量不会热加载。

reading choices 报错。表现是对话时后端抛异常，提示读取 choices 字段失败。这通常意味着上游返回的不是标准 OpenAI 格式，或者模型名在 One API 里不存在。检查 One API 渠道里模型名是否和 config.json 完全一致，检查渠道测试是否真的通过。如果用的是非 OpenAI 兼容的上游，需要在 One API 里做格式转换。

OAuth / 登录相关报错。One API 首次登录强制改密码，如果跳过或改密失败，后续接口调用会鉴权异常。重新登录http://localhost:3001完成改密流程即可。FastGPT 侧如果改了DEFAULT_ROOT_PSW环境变量，要重启容器才生效。

知识库创建时模型下拉框为空。这是配置类问题里最典型的。根因是 config.json 的模型名、One API 令牌范围、渠道模型三者没有对齐。按「渠道模型名 = 令牌范围 = config.json 的 model 字段」这条等式逐个核对，改完重启。另外注意 config.json 是 JSON 格式，多一个逗号或少一个引号都会导致解析失败，模型列表直接为空。

排查时善用日志：docker logs -f fastgpt看 FastGPT 报错，docker logs -f oneapi看网关转发情况。大部分问题在日志里都有明确指向，比盲目改配置高效得多。

6. 把模型调用收敛到一个入口：TaoToken 统一 Key 与 API 通道管理

整套系统跑起来后，你会发现模型密钥散落在多个地方：deepseek 一个、智谱一个，以后再加别的厂商还要继续加。One API 已经做了一层收敛，但上游渠道的密钥管理、额度查看、多项目隔离仍然需要一套更顺手的通道。

TaoToken 提供的统一 Key/API 通道，可以把多家模型的调用收敛到一个入口。在 One API 里新建渠道时，把上游地址指向 TaoToken 的 API 入口，密钥填 TaoToken 生成的 Key，模型名按需填写，这样 FastGPT 侧完全不用感知上游是哪家厂商。想换模型时，只改 One API 渠道，FastGPT 的 config.json 和令牌范围都不用动。

具体操作上，先到 TaoToken 控制台创建一个 API Key，然后在 One API 的渠道配置里，代理地址填https://taotoken.net/api，密钥填刚创建的 Key，模型填你要用的模型 ID。提交后测试连接，返回响应时间即成功。之后 FastGPT 的CHAT_API_KEY依然填 One API 令牌，整条链路不变。

如果你更习惯直接调模型做验证，可以打开模型对话页面发一条测试消息，确认 Key 和通道可用；需要长期跑编码或 Agent 类任务，可以了解 Coding Plan 的额度方案；密钥和通道的日常管理在控制台完成；接入细节和参数说明看接入文档。把这几处入口记下来，后面加模型、换通道、查额度都不用再翻配置。

最后留一个实用习惯：每次改完docker-compose.yml或config.json，先docker-compose down再up -d，然后用docker ps确认容器状态，再进 FastGPT 验证模型下拉框。这套动作固定下来，配置类问题基本不会反复出现。