1. FastGPT 本地部署到底解决什么问题适合哪些人FastGPT 是一个基于大语言模型的知识库问答系统能把你自己的文档、手册、产品资料喂进去然后对外提供一个能回答问题的对话入口。它和直接调云端 API 最大的区别在于数据留在你自己的服务器上知识库的切分、向量化、检索策略都由你控制。对于手里有一堆内部文档、又不想把内容传到别人服务器上的团队来说这是刚需。我这次要跑通的链路是FastGPT 用 Docker Compose 在本地起一套完整服务含 PostgreSQL、MongoDB、Redis、AI Proxy、Sandbox然后把模型推理这一层接到硅基流动的免费 AI 接口上。这样做的直接好处是知识库和对话记录都在本地只有「提问 检索到的片段」会发到模型接口成本能压到很低因为硅基流动有 Qwen2.5-7B 这类永久免费模型可用。适合谁看这篇一是有自己服务器哪怕是 8GB 内存的轻量云主机的开发者二是想给团队搭一个内部知识库问答、又不想每月付大额 Token 费的人三是已经在用 FastGPT 但卡在模型接入这一步、报错看不懂的人。如果你只是想体验一下对话不想折腾部署那直接用在线服务更省事这篇的流程对你来说偏重。需要提前说清楚一个概念FastGPT 本身不产出模型能力它是个「编排 检索 对话管理」的框架。模型从哪来取决于你给它配的接口地址和 Key。所以部署分两段第一段是把 FastGPT 这套容器跑起来第二段是把它指向一个可用的模型接口。两段都通了知识库问答才算真正跑通。环境要求我实测下来是这样的Ubuntu 22.04 最省心Docker 24.0 以上、Docker Compose 2.20 以上。内存 8GB 是底线因为 Mongo、PG、Redis、FastGPT 主进程、AI Proxy 加起来占用不小如果还要跑本地向量模型16GB 更稳。GPU 不是必须的因为模型推理走的是外部接口本地只做向量化和业务逻辑CPU 也能跑只是文档切分和向量化会慢一些。下面我会按「先起容器 → 再配模型接口 → 再验证 → 再排错」的顺序写每一步都给可复制的命令和配置。你照着做中间遇到报错可以对照第 5 节。2. 部署前的前置准备Docker 环境与模型接口 Key 怎么拿这一节解决两个前置条件一是服务器上得有能用的 Docker 和 Docker Compose二是得有一个可调用的模型接口。很多人卡在第一步的镜像拉取上第二步则是不知道该去哪申请 Key。先说 Docker。如果你用的是 Ubuntu官方脚本最直接curl -fsSL https://get.docker.com | sh sudo systemctl enable docker sudo systemctl start docker docker --version docker compose versiondocker compose version能打印出 2.20 以上就行。注意现在 Compose 是 Docker 的子命令用docker compose中间空格而不是老的docker-compose两者在部分系统上行为有差异后面命令我统一用docker compose。如果你在国内服务器上拉镜像慢可以配一个镜像加速。编辑/etc/docker/daemon.json{ registry-mirrors: [ https://docker.1panel.live ] }然后sudo systemctl daemon-reload sudo systemctl restart docker。这一步不是必须的但能明显减少拉取超时的概率。FastGPT 官方 compose 里也提供了阿里云镜像地址的注释行拉不动的时候把image:换成注释里那条阿里云地址即可。再说模型接口。FastGPT 需要一个兼容 OpenAI 协议的接口地址和 Key。我这次用的是 TaoToken 提供的接口它的 Base URL 是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions调用格式模型 ID 可以按需选择。你需要先去控制台创建一个 API Key路径在 API Keys 页面创建后复制保存后面填进环境变量。这里有个容易踩的坑Base URL 到底填到哪一层。OpenAI 兼容接口的完整请求地址是https://taotoken.net/api/v1/chat/completions但在 FastGPT 的配置里通常只需要填到/v1这一层也就是https://taotoken.net/api/v1剩下的路径由程序自己拼。填多了或填少了都会导致 404 或连接失败第 5 节会专门讲这个报错。模型 ID 这块你要根据自己账号里可用的模型来填。FastGPT 在配置模型时会让你填一个「模型名」这个名字要和接口侧认识的模型 ID 一致否则会返回 model not found。建议先在模型对话页面确认一下你要用的模型 ID 拼写再填进 FastGPT。前置准备做完你应该手里有两样东西一台装好 Docker 的服务器一个可用的 API Key 和确定的模型 ID。接下来就可以起容器了。3. 可复制的 docker-compose.yml 与环境变量配置这一节是全文的核心给你一份能直接用的docker-compose.yml以及需要改动的环境变量。FastGPT 官方仓库的deploy/docker/目录下有多个版本我选的是 pgvector 版本因为知识库向量检索依赖它。先建目录并下载官方配置文件mkdir -p /home/fastgpt cd /home/fastgpt curl -O https://raw.githubusercontent.com/labring/FastGPT/main/projects/app/data/config.json curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-pgvector.yml如果 raw.githubusercontent.com 拉不动可以手动创建这两个文件内容用下面这份精简后的 compose。这份是我实际跑通的版本去掉了不必要的暴露端口保留了核心服务version: 3.3 services: pg: image: pgvector/pgvector:0.8.0-pg15 container_name: pg restart: always 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 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); do echo Waiting for MongoDB to start... sleep 2 done mongo -u myusername -p mypassword --authenticationDatabase admin /data/initReplicaSet.js wait $$! redis: image: redis:7.2-alpine container_name: redis networks: - fastgpt restart: always command: redis-server --requirepass mypassword --loglevel warning --maxclients 10000 --appendonly yes --save 60 10 --maxmemory 4gb --maxmemory-policy noeviction volumes: - ./redis/data:/data sandbox: container_name: sandbox image: ghcr.io/labring/fastgpt-sandbox:v4.9.6 networks: - fastgpt restart: always fastgpt: container_name: fastgpt image: ghcr.io/labring/fastgpt:v4.9.6 ports: - 3000:3000 networks: - fastgpt depends_on: - mongo - pg - sandbox restart: always environment: - FE_DOMAIN - DEFAULT_ROOT_PSW1234 - AIPROXY_API_ENDPOINThttp://aiproxy:3000 - AIPROXY_API_TOKENaiproxy - DB_MAX_LINK30 - TOKEN_KEYany - ROOT_KEYroot_key - FILE_TOKEN_KEYfiletoken - MONGODB_URImongodb://myusername:mypasswordmongo:27017/fastgpt?authSourceadmin - PG_URLpostgresql://username:passwordpg:5432/postgres - REDIS_URLredis://default:mypasswordredis:6379 - SANDBOX_URLhttp://sandbox:3000 - LOG_LEVELinfo - STORE_LOG_LEVELwarn - WORKFLOW_MAX_RUN_TIMES1000 - WORKFLOW_MAX_LOOP_TIMES100 - USE_IP_LIMITfalse - CHAT_FILE_EXPIRE_TIME7 volumes: - ./config.json:/app/data/config.json aiproxy: image: ghcr.io/labring/aiproxy:v0.1.7 container_name: aiproxy restart: unless-stopped depends_on: aiproxy_pg: condition: service_healthy networks: - fastgpt environment: - ADMIN_KEYaiproxy - LOG_DETAIL_STORAGE_HOURS1 - SQL_DSNpostgres://postgres:aiproxyaiproxy_pg:5432/aiproxy - RETRY_TIMES3 - BILLING_ENABLEDfalse - DISABLE_MODEL_CONFIGtrue healthcheck: test: [CMD, curl, -f, http://localhost:3000/api/status] interval: 5s timeout: 5s retries: 10 aiproxy_pg: image: pgvector/pgvector:0.8.0-pg15 restart: unless-stopped container_name: aiproxy_pg volumes: - ./aiproxy_pg:/var/lib/postgresql/data networks: - fastgpt environment: TZ: Asia/Shanghai POSTGRES_USER: postgres POSTGRES_DB: aiproxy POSTGRES_PASSWORD: aiproxy healthcheck: test: [CMD, pg_isready, -U, postgres, -d, aiproxy] interval: 5s timeout: 5s retries: 10 networks: fastgpt:这份配置里数据库账号密码都是占位值正式用之前建议改掉并且注意「改一处不够」——Mongo 的账号密码同时出现在MONGO_INITDB_ROOT_USERNAME和MONGODB_URI里PG 的出现在POSTGRES_PASSWORD和PG_URL里Redis 的出现在command和REDIS_URL里三处都要同步改否则连不上。模型接口的配置有两种方式。一种是在 FastGPT 界面里配置另一种是通过 AI Proxy 统一代理。我推荐先在界面里配直观且好排查。启动容器后登录 FastGPT进入「模型配置」新增一个模型渠道填三个关键项{ base_url: https://taotoken.net/api/v1, api_key: 你的_API_Key, model_id: 你确认可用的模型ID }这三个值就是接入的三件套Base URL、Key、Model ID。Base URL 填到/v1Key 填控制台创建的密钥Model ID 填接口侧认识的模型名。填完保存FastGPT 会做一次连通性测试。如果你更习惯用环境变量方式也可以在fastgpt服务的 environment 里加- OPENAI_BASE_URLhttps://taotoken.net/api/v1 - CHAT_API_KEY你的_API_Key但要注意FastGPT 较新版本更推荐在界面里管理模型渠道环境变量方式在部分版本上优先级较低可能不生效。所以以界面配置为准环境变量作为备选。配置改完启动docker compose up -d docker compose psdocker compose ps里所有服务状态是 running 或 healthy 就对了。Mongo 首次启动会初始化副本集日志里可能出现一次MongoServerError: Unable to read from a snapshot due to pending collection catalog changes这是初始化过程中的正常提示不影响使用可以忽略。4. 验证请求与成功结果从容器状态到知识库问答容器起来不等于链路通了这一节教你一步步验证直到知识库能真正回答问题。第一步确认 FastGPT 主服务可访问。浏览器打开http://你的服务器IP:3000能看到登录页就说明前端起来了。默认用户名root密码是 compose 里DEFAULT_ROOT_PSW的值我上面填的是1234。首次登录后建议立刻改密码。如果打不开先在服务器上本地验证curl -I http://localhost:3000返回 200 或 302 说明服务本身没问题那就是防火墙或安全组没放行 3000 端口。云服务器要去控制台的安全组里加一条入站规则放行 TCP 3000。第二步验证模型接口连通性。这一步很关键因为 FastGPT 界面能打开不代表模型能调通。你可以直接在服务器上用 curl 测接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_API_Key \ -H Content-Type: application/json \ -d { model: 你确认可用的模型ID, messages: [{role: user, content: 你好请回复一句话}], max_tokens: 50 }如果返回里choices[0].message.content有内容说明 Key、Base URL、Model ID 三件套都对。如果返回 401是 Key 的问题返回 404多半是 Base URL 路径不对返回 model not found是 Model ID 拼错。这三种报错第 5 节会详细拆。第三步在 FastGPT 里建知识库。进入「知识库」→「新建知识库」上传一个 PDF 或 TXT 文档。系统会让你选向量模型如果本地没配向量模型可以用接口提供的 embedding 模型或者先用默认的。上传后等待切分和向量化完成文档状态变成「已就绪」。第四步建一个应用并关联知识库。进入「应用」→「新建应用」选择「知识库问答」类型把刚才建的知识库挂上去模型选你配置好的那个。保存后进入对话测试问一个只有你文档里才有的问题比如文档里写了「本产品保修期是 36 个月」你就问「保修期多久」。如果回答是 36 个月说明整条链路——文档切分、向量检索、模型调用——全部跑通了。实测下来从上传文档到能问答一份 20 页的 PDF 大概需要一两分钟完成向量化取决于服务器性能。如果卡在「向量化中」很久去看docker compose logs fastgpt的日志通常是向量模型接口没配好。到这里一个可用的本地知识库问答就搭好了。你可以继续加文档、调检索参数、改提示词这些都在 FastGPT 界面里完成不用再动容器。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节把部署和接入过程中最容易撞上的几类报错集中拆一遍每个都给判断方法和处理动作。401 Unauthorized。这个最直接就是 Key 不对。可能的原因有三个Key 复制时带了空格或换行Key 已经失效或被删除请求头里Authorization格式写错。检查方法是用第 4 节的 curl 命令单独测接口如果 curl 也 401那就是 Key 本身的问题回控制台重新创建一个。注意Bearer和 Key 之间是一个空格别多也别少。local proxy failed / connection refused。这个报错通常出现在 FastGPT 调 AI Proxy 或调外部接口时。如果是容器之间的调用失败检查AIPROXY_API_ENDPOINT是不是http://aiproxy:3000容器名要对得上因为 Docker 内部是用服务名做 DNS 的。如果是调外部接口失败检查服务器能不能出网curl -I https://taotoken.net/api/v1如果这条命令在服务器上超时说明是网络出口问题不是配置问题。另外aiproxy服务有 healthcheck如果它一直 unhealthyFastGPT 会连不上它用docker compose logs aiproxy看具体原因常见的是aiproxy_pg还没 ready 就启动了。reading choices 相关报错。典型的是Cannot read properties of undefined (reading choices)意思是程序期望接口返回里有choices字段但实际返回的结构不对。原因通常是 Base URL 填错了层级比如填成了https://taotoken.net/api而没带/v1或者填成了完整的/v1/chat/completions导致路径重复拼接。正确做法是 Base URL 只填到https://taotoken.net/api/v1。还有一种情况是接口返回了错误信息比如额度不足、模型不存在但程序没处理好错误分支也会报这个。先用 curl 确认接口返回正常再回来看配置。OAuth / 登录相关报错。如果你在登录 FastGPT 时遇到 OAuth 回调失败或者配置了第三方登录后跳转异常先确认FE_DOMAIN这个环境变量。它用于自动补全文件资源路径和回调地址如果留空在纯 IP 访问的场景下一般没问题但如果你用了域名或反向代理FE_DOMAIN必须填成外部可访问的完整地址比如https://fastgpt.yourdomain.com不能填 localhost。填错会导致回调地址拼错登录流程中断。MongoDB 副本集未初始化。表现是 FastGPT 启动后连不上 Mongo日志报not primary或replica set not initialized。这是因为 Mongo 需要先初始化副本集才能用。我给的 compose 里 entrypoint 已经带了初始化脚本正常情况下会自动完成。如果失败手动进容器执行docker exec -it mongo mongosh -u myusername -p mypassword --authenticationDatabase admin进去后执行rs.status()看状态如果没初始化执行rs.initiate({_id:rs0,members:[{_id:0,host:mongo:27017}]})。端口冲突。如果 3000 端口被占用docker compose up会报port is already allocated。改 compose 里 fastgpt 的端口映射比如8080:3000然后重新 up。注意改完要用新端口访问。排查的核心思路就一条先确认单个组件自己能工作curl 接口、curl 本地服务再看组件之间的连接容器名、网络、依赖顺序。把问题范围缩小到某一层就好办了。6. 后续怎么用把这条链路变成长期可用的知识库服务容器跑起来只是开始真正要用起来还得考虑几件事。第一是数据持久化。我给的 compose 里PG、Mongo、Redis 的数据都挂到了宿主机的./pg/data、./mongo/data、./redis/data。这意味着你docker compose down再up数据还在。但如果你执行docker compose down -v卷会被删掉数据就没了。所以升级或迁移前先备份这几个目录。第二是模型渠道的维护。FastGPT 支持配多个模型渠道你可以把对话模型和向量模型分开配。对话用能力强的向量用便宜或免费的。如果某个渠道的 Key 失效了在界面里换掉即可不用重启容器。这也是为什么我推荐在界面里配模型而不是写死在环境变量里——灵活。第三是访问方式。默认是 IP:3000 直接访问正式用建议套一层 Nginx 做域名和 HTTPS。Nginx 配置里把proxy_pass指向http://127.0.0.1:3000并设置好FE_DOMAIN环境变量为你的域名。这样文件资源和回调地址都能正确生成。第四是知识库的迭代。FastGPT 的知识库支持增量上传和重新索引。文档更新后重新上传或触发重新向量化即可。检索参数比如相似度阈值、返回条数可以在知识库设置里调调完立即生效不用重启。如果你后面要做更复杂的编排比如多轮对话、条件分支、调用外部工具FastGPT 的工作流功能可以覆盖。工作流里的模型节点同样走你配好的渠道所以只要渠道通了工作流就能用。最后提醒一句免费模型接口适合验证和小规模使用如果知识库文档量大、并发高还是要评估一下接口的速率限制和稳定性。本地部署的价值在于数据可控和架构自主模型接口只是其中一个可替换的零件哪天想换别的接口改一下 Base URL 和 Key 就行FastGPT 这套容器不用动。