1. Windows 下 FastGPT 本地部署到底难在哪FastGPT 是一个开箱即用的知识库问答系统能上传文档、自动切分、向量检索再配合大模型做 RAG 对话。它适合想在自己电脑上跑一套私有知识库的人不想把公司文档传到别人服务器又想体验接近线上产品的问答效果。问题在于FastGPT 官方推荐 Linux Docker 部署而大多数人的主力机是 Windows直接装 Docker Desktop 又会遇到 WSL2 没开、端口冲突、模型 Key 不知道填哪等一堆坑。我自己第一次在 Windows 上折腾 FastGPT卡了整整一个下午。最开始的报错是docker compose up之后 fastgpt 容器反复重启日志里刷MongoServerSelectionError原因是 MongoDB 副本集没初始化成功后来换成手动初始化又碰到OPENAI_BASE_URL填错导致对话一直转圈。真正让我省事的是把模型调用统一到一个 API 通道上不用在 OneAPI、FastGPT、config.json 三处来回改 Key。这篇就按我实际跑通的顺序把 WSL2 准备、docker-compose 配置、模型接入、请求验证整条链路写清楚你照着复制命令就能落地。核心检索词先明确FastGPT 本地部署、Windows WSL2、docker-compose、TaoToken 统一 Key。整条链路分四段WSL2 与 Docker 环境、FastGPT 项目文件、模型通道配置、一次对话验证。下面从环境开始。2. WSL2 与 Docker 环境准备wsl --install 报错排查Windows 上跑 FastGPT第一步不是装 FastGPT而是把 Linux 运行环境准备好。WSL2 是微软官方的 Linux 子系统Docker Desktop 可以直接基于它运行不需要额外开虚拟机。很多人卡在wsl --install报错或者装完发现默认还是 WSL1容器起不来。先以管理员身份打开 PowerShell。注意是 PowerShell不是 CMD。依次执行下面几条命令作用是启用两个 Windows 功能并设置默认版本dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart wsl --set-default-version 2 wsl --update执行完前两条后建议重启一次电脑否则wsl --set-default-version 2可能提示功能未启用。重启后再跑后两条。wsl --update是更新 WSL 内核老版本 Windows 11 不更新内核会出现 Docker 启动后网络不通的情况。接着列出发行版并安装 Ubuntuwsl -l -o wsl --install -d Ubuntu-22.04wsl -l -o会列出可安装的发行版Ubuntu-22.04 兼容性最好。安装完成后会要求设置 Linux 用户名和密码这个密码后面sudo会用到记牢。如果wsl --install卡在下载可以用手动方式Invoke-WebRequest -Uri https://aka.ms/wslubuntu2204 -OutFile Ubuntu.appx -UseBasicParsing Add-AppxPackage .\Ubuntu.appx装完在 PowerShell 里执行wsl -l -v确认 VERSION 列是 2。如果是 1执行wsl --set-version Ubuntu-22.04 2转换。这一步很关键WSL1 不支持 Docker 需要的部分内核特性容器会起不来。然后装 Docker Desktop。官网下载安装包安装时勾选 “Use WSL 2 instead of Hyper-V”。装完打开 Docker Desktop设置里 Resources → WSL Integration把 Ubuntu-22.04 的开关打开。这样在 Ubuntu 终端里就能直接用docker命令不用再装一遍 Docker。验证 Docker 是否可用docker --version docker compose version两条都能输出版本号就说明环境通了。如果docker compose提示找不到命令说明 Docker Desktop 版本较老用docker-compose带横杠代替或者升级 Docker Desktop。这里有个常见坑WSL 里执行docker ps报Cannot connect to the Docker daemon多半是 Docker Desktop 没启动或者 WSL Integration 没开。先确认 Docker Desktop 托盘图标是运行状态再检查 Integration 设置。环境准备好后WSL2 里的 Ubuntu 和 Windows 是共享文件系统的Windows 的 C 盘挂载在/mnt/c。但 FastGPT 的数据卷建议放在 Linux 文件系统里也就是~/fastgpt不要放/mnt/c下否则 MongoDB 和 PostgreSQL 的磁盘 IO 会非常慢容器启动能拖到几分钟。这一点我踩过放在/mnt/c下时 pg 容器初始化要等很久换到~/fastgpt后十几秒就起来了。3. FastGPT 项目文件与 docker-compose.yml 配置环境通了接下来准备 FastGPT 的项目目录和两个核心文件docker-compose.yml和config.json。这两个文件决定了容器怎么起、模型怎么接。在 WSL 的 Ubuntu 终端里操作mkdir -p ~/fastgpt cd ~/fastgpt然后创建docker-compose.yml。下面是精简后可用的版本去掉了注释里容易误导的部分保留了 pg、mongo、sandbox、fastgpt、mysql、oneapi 六个服务。注意数据库账号密码只在首次运行时生效改完要删数据卷重启。version: 3.3 services: pg: image: pgvector/pgvector:0.7.0-pg15 container_name: pg restart: always ports: - 5432:5432 networks: - fastgpt environment: - POSTGRES_USERusername - POSTGRES_PASSWORDpassword - POSTGRES_DBpostgres volumes: - ./pg/data:/var/lib/postgresql/data mongo: image: mongo:5.0.18 container_name: mongo restart: always ports: - 27017:27017 networks: - fastgpt command: mongod --keyFile /data/mongodb.key --replSet rs0 environment: - MONGO_INITDB_ROOT_USERNAMEmyusername - MONGO_INITDB_ROOT_PASSWORDmypassword volumes: - ./mongo/data:/data/db entrypoint: - bash - -c - | openssl rand -base64 128 /data/mongodb.key chmod 400 /data/mongodb.key chown 999:999 /data/mongodb.key echo const isInited rs.status().ok 1 if(!isInited){ rs.initiate({ _id: rs0, members: [ { _id: 0, host: mongo:27017 } ] }) } /data/initReplicaSet.js exec docker-entrypoint.sh $$ until mongo -u myusername -p mypassword --authenticationDatabase admin --eval print(waited for connection) /dev/null 21; do echo Waiting for MongoDB to start... sleep 2 done mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js wait $$! sandbox: container_name: sandbox image: ghcr.io/labring/fastgpt-sandbox:latest networks: - fastgpt restart: always fastgpt: container_name: fastgpt image: ghcr.io/labring/fastgpt:v4.8.9 ports: - 3000:3000 networks: - fastgpt depends_on: - mongo - pg - sandbox restart: always environment: - DEFAULT_ROOT_PSW1234 - OPENAI_BASE_URLhttp://oneapi:3000/v1 - CHAT_API_KEYsk-fastgpt - DB_MAX_LINK30 - TOKEN_KEYany - ROOT_KEYroot_key - FILE_TOKEN_KEYfiletoken - MONGODB_URImongodb://myusername:mypasswordmongo:27017/fastgpt?authSourceadmin - PG_URLpostgresql://username:passwordpg:5432/postgres - SANDBOX_URLhttp://sandbox:3000 - LOG_LEVELinfo - STORE_LOG_LEVELwarn volumes: - ./config.json:/app/data/config.json mysql: image: mysql:8.0.36 container_name: mysql restart: always ports: - 3306:3306 networks: - fastgpt command: --default-authentication-pluginmysql_native_password environment: MYSQL_ROOT_PASSWORD: oneapimmysql MYSQL_DATABASE: oneapi volumes: - ./mysql:/var/lib/mysql oneapi: container_name: oneapi image: ghcr.io/songquanpeng/one-api:v0.6.7 ports: - 3001:3000 depends_on: - mysql networks: - fastgpt restart: always environment: - SQL_DSNroot:oneapimmysqltcp(mysql:3306)/oneapi - SESSION_SECREToneapikey - MEMORY_CACHE_ENABLEDtrue - BATCH_UPDATE_ENABLEDtrue - BATCH_UPDATE_INTERVAL10 - INITIAL_ROOT_TOKENfastgpt volumes: - ./oneapi:/data networks: fastgpt:这里有个关键点fastgpt服务的OPENAI_BASE_URL指向http://oneapi:3000/v1CHAT_API_KEY填的是 OneAPI 的令牌。也就是说 FastGPT 不直接调模型而是通过 OneAPI 这个中间层转发。这样做的好处是模型 Key 只在 OneAPI 里配一次FastGPT 侧只认 OneAPI 的令牌。但 OneAPI 本身也要配渠道渠道里填的才是真正的模型 API 地址和 Key。如果你不想维护 OneAPI 这一层也可以让 FastGPT 直接指向统一的 API 通道。TaoToken 提供的就是这种统一 Key 能力一个 Base URL 加一个 Key就能调用多种模型省掉 OneAPI 的渠道配置。下面config.json里我会把模型名和向量模型都列出来你按需保留。创建config.json重点是llmModels和vectorModels两段。向量模型必须至少有一个否则知识库会报错。下面是一个精简可用的版本{ feConfigs: { lafEnv: https://laf.dev }, systemEnv: { vectorMaxProcess: 15, qaMaxProcess: 15, pgHNSWEfSearch: 100 }, llmModels: [ { model: gpt-4o-mini, name: gpt-4o-mini, avatar: /imgs/model/openai.svg, maxContext: 125000, maxResponse: 16000, quoteMaxToken: 120000, maxTemperature: 1.2, charsPointsPrice: 0, censor: false, vision: true, datasetProcess: true, usedInClassify: true, usedInExtractFields: true, usedInToolCall: true, usedInQueryExtension: true, toolChoice: true, functionCall: false, customCQPrompt: , customExtractPrompt: , defaultSystemChatPrompt: , defaultConfig: {} } ], vectorModels: [ { model: text-embedding-3-small, name: text-embedding-3-small, avatar: /imgs/model/openai.svg, charsPointsPrice: 0, defaultToken: 512, maxToken: 3000, weight: 100, defaultConfig: {} } ], reRankModels: [], audioSpeechModels: [], whisperModel: {} }llmModels里的model字段要和 OneAPI 渠道里配置的模型名一致name是 FastGPT 界面展示的别名不能带冒号。vectorModels的model同理。如果你用 TaoToken 的统一通道模型名按通道支持的写Base URL 和 Key 在 OneAPI 渠道或 FastGPT 环境变量里填。文件准备好后启动容器cd ~/fastgpt docker compose up -d第一次会拉镜像时间取决于网络。拉完后docker compose ps看状态六个服务都应该是 Up。如果 fastgpt 反复重启先看日志docker compose logs -f fastgpt常见的是 mongo 没起来导致 fastgpt 连不上等 mongo 初始化完再重启 fastgpt 即可。4. 模型接入与 TaoToken 统一 Key 配置容器起来后浏览器打开http://127.0.0.1:3000用 root / 1234 登录 FastGPT。但这时候对话还不能用因为模型通道没配。打开http://127.0.0.1:3001进 OneAPI初始账号 root密码 123456登录后强制改密码。在 OneAPI 里添加渠道渠道类型选 OpenAI 兼容Base URL 填模型服务的地址Key 填对应的 API Key。如果你用 TaoToken 的统一通道Base URL 填https://taotoken.net/apiKey 填在控制台创建的 API Key。模型名按通道支持的填比如gpt-4o-mini。添加后点测试返回成功即可。然后添加令牌OneAPI 左侧“令牌” → 新建随便起个名额度设大一点。创建后复制这个令牌它就是 FastGPT 要用的CHAT_API_KEY。回到docker-compose.yml把 fastgpt 服务的两个环境变量改成你的实际值- OPENAI_BASE_URLhttp://oneapi:3000/v1 - CHAT_API_KEYsk-你的OneAPI令牌如果你跳过 OneAPI直接让 FastGPT 调 TaoToken就把OPENAI_BASE_URL改成https://taotoken.net/api/v1CHAT_API_KEY填 TaoToken 的 Key。注意/v1不能少FastGPT 走的是 OpenAI 兼容协议。改完重启docker compose down docker compose up -d这里有个容易忽略的点config.json里的模型名必须和渠道里配置的模型名对得上。比如渠道里模型名写的是gpt-4o-miniconfig.json 里llmModels[0].model也必须是gpt-4o-mini否则 FastGPT 界面选模型时会报“模型不存在”。向量模型同理text-embedding-3-small要和渠道里的 embedding 模型名一致。如果你要接的是国产模型比如 DeepSeek 或通义模型名按服务商文档写。TaoToken 的好处是这些模型可以走同一个 Base URL 和 Key不用为每个模型单独建渠道。在 OneAPI 里建一个渠道模型名填多个用逗号分隔就能一次配好。配置完成后FastGPT 界面里“应用” → 新建一个简易应用模型选你配的那个就能开始对话了。但先别急着聊下一步用命令行验证一下请求是否真的通。5. 验证请求与常见报错排查验证分两步先确认 OneAPI 通道本身能通再确认 FastGPT 能通过 OneAPI 调模型。先直接测 OneAPI 的接口。在 WSL 终端里执行curl http://127.0.0.1:3001/v1/chat/completions \ -H Authorization: Bearer sk-你的OneAPI令牌 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }返回里有choices字段和内容说明通道通了。如果返回 401检查令牌是否正确、有没有空格如果返回model not found检查渠道里的模型名和请求里的 model 是否一致。再测 FastGPT 侧。打开http://127.0.0.1:3000新建应用选模型发一句“你好”。如果转圈很久然后报错看 fastgpt 容器日志docker compose logs -f fastgpt下面是我实际遇到过的几个报错和对应处理报错关键字原因处理MongoServerSelectionErrormongo 副本集没初始化删./mongo/data重启或手动执行rs.initiate401 UnauthorizedCHAT_API_KEY 填错或令牌失效重新复制 OneAPI 令牌确认无空格local proxy failedOPENAI_BASE_URL 地址不对容器内用服务名oneapi不是127.0.0.1reading choices为空模型名不匹配或渠道未启用核对 config.json 与渠道模型名OAuth相关渠道类型选错选 OpenAI 兼容不要选 OAuth 类型connect ECONNREFUSED目标服务没起docker compose ps看对应容器状态重点说local proxy failed。这个报错在 FastGPT 里很常见原因是OPENAI_BASE_URL填了http://127.0.0.1:3001/v1。在容器内部127.0.0.1指的是 fastgpt 容器自己不是宿主机所以连不上 OneAPI。正确写法是用 docker-compose 里的服务名http://oneapi:3000/v1。如果你直接调 TaoToken就填https://taotoken.net/api/v1这是外部地址容器能访问。另一个坑是reading choices报错日志里显示Cannot read properties of undefined (reading choices)。这通常是模型返回了非预期格式或者渠道返回了错误信息但 FastGPT 没解析到。先确认渠道测试通过再确认 config.json 里llmModels的model和请求的模型名一致。如果用的是 embedding 模型做对话也会出这个错检查应用里选的模型是不是对话模型。还有OAuth相关报错一般是 OneAPI 渠道类型选成了需要 OAuth 的类型。FastGPT 走的是标准 OpenAI 协议渠道类型选“OpenAI”或“自定义 OpenAI 兼容”即可不要选带 OAuth 的。验证通过后你可以在 FastGPT 里上传一个 PDF 或 Markdown 文档建知识库选向量模型等索引完成再在应用里关联知识库提问。如果知识库报错多半是向量模型没配或datasetProcess没设 true。config.json里llmModels至少有一个模型的datasetProcess为 true否则知识库处理会失败。6. 部署完成后的实用建议与接入入口跑通之后有几个地方值得再调一下。第一数据库密码别用默认的username/password正式用之前改掉改完记得同步改MONGODB_URI和PG_URL只改一处不生效。第二DEFAULT_ROOT_PSW和 OneAPI 的 root 密码都改掉别留 1234 和 123456。第三config.json里的pgHNSWEfSearch设 100 精度够用调大更准但更慢按机器性能取舍。如果你后面要接更多模型或者想让多个应用共用一套 Key统一 API 通道会省很多事。TaoToken 的模型对话入口在 https://taotoken.net/apiAPI Key 在控制台创建Base URL 填https://taotoken.net/api/v1就能被 FastGPT 直接调用。需要长期跑编码或 Agent 场景的可以看 Coding Plan只想先验证模型效果的用模型对话页试一句就行。接入文档里有各语言的示例排障时对照着看比翻日志快。最后提醒一句FastGPT 的数据卷都在~/fastgpt下备份直接打包这个目录即可。迁移到另一台机器时把目录拷过去docker compose up -d就能恢复不用重新建知识库。