开篇问题上一篇我们拆解了 FastGPT 的 monorepo 结构知道了projects/app是主应用packages/global、packages/service、packages/web是核心共享包sdk则承载可独立构建的基础能力。但真正开始本地开发时新的问题很快出现为什么一个 Next.js 项目启动前还要准备 MongoDB、Redis、PG、MinIO、代码沙盒、AI Proxy为什么pnpm dev前要先build:workers为什么 Docker Compose 开发文件里没有 FastGPT 本体这些问题背后反映的是 FastGPT 的平台属性。它不是只调用模型的前端应用而是一个包含知识库、工作流、文件服务、异步处理、代码执行和模型代理的 AI 应用平台。因此本地开发不只是启动一个 Web 服务还需要准备一组支撑服务。本文聚焦本地开发和启动链路目标是帮你建立一张可执行的开发地图需要什么 Node 和 pnpm 版本。根目录脚本和 app 脚本分别做什么。.env.template中哪些配置最关键。为什么主应用启动前要构建 workers。本地源码开发和 Docker 部署有什么差异。遇到启动失败时应该先排查什么。本地开发的整体链路FastGPT 本地源码开发可以概括为下面这条链路安装依赖 - 构建 SDK - 准备环境变量 - 启动依赖服务 - 构建 workers - 启动 Next.js 主应用 - 访问 http://localhost:3000对应的典型命令是chmod-Rx ./scripts/pnpmipnpmbuild:sdks# 准备环境变量按本机依赖服务地址调整cpprojects/app/.env.template projects/app/.env.local# 启动开发依赖服务开发 compose 不包含 FastGPT 本体dockercompose-fdeploy/dev/docker-compose.yml up-d# 启动主应用pnpm--filterfastgpt/app dev也可以使用 Makefilemakedevnameappmake dev nameapp本质上会执行pnpm--filterfastgpt/app dev所以两种方式的差异不大。前者更直接后者更统一适合同时管理app、admin等项目。版本要求根package.json和projects/app/package.json都声明了运行要求项目要求Node.js20.19.0pnpm10.xpackageManagerpnpm10.33.4如果本地 Node 版本过低可能出现依赖安装失败、Next.js 构建失败或 TypeScript 工具链异常。建议先确认版本node-vpnpm-v如果你同时维护多个 Node 项目建议使用 nvm、fnm 或 Volta 管理 Node 版本避免不同项目之间互相影响。根目录脚本与 app 脚本的区别FastGPT 是 monorepo根目录和主应用都有自己的package.json。理解这两个脚本层级很重要。根目录脚本偏“仓库级调度”脚本作用pnpm i安装整个 workspace 的依赖pnpm build:sdks构建sdk/storage、sdk/otel、sdk/sandbox-adapterpnpm test执行 workspace 测试pnpm test:app只执行主应用测试pnpm test:service只执行服务端共享包测试pnpm lint通过 Turbo 执行 lintpnpm gen:deploy生成部署配置projects/app脚本偏“主应用运行”脚本作用pnpm dev先构建 workers再启动next devpnpm build先构建 workers再执行next build --debugpnpm start启动 Next.js 生产服务pnpm test执行 app 的 Vitest 测试pnpm typecheck执行 TypeScript 类型检查pnpm lintlintprojects/app/srcpnpm build:workers执行 worker 预编译因此在根目录执行pnpm--filterfastgpt/app dev和进入 app 目录执行cdprojects/apppnpmdev最终都会走主应用的dev脚本。为什么要先构建 SDK根目录build:sdks会构建三个 SDKfastgpt-sdk/storage fastgpt-sdk/otel fastgpt-sdk/sandbox-adapter主应用和服务端共享包会通过workspace:*依赖这些 SDK。尤其是fastgpt-sdk/otel存在 subpath exports例如fastgpt-sdk/otel/logger fastgpt-sdk/otel/metrics fastgpt-sdk/otel/tracing如果 SDK 没有生成dist和类型文件开发或构建过程中可能出现模块解析失败。这也是 Dockerfile 中先执行pnpmbuild:sdks再执行pnpm--filterapp build的原因。本地开发时如果安装依赖后没有自动触发 postinstall或者你清理过sdk/*/dist建议手动执行pnpmbuild:sdks为什么主应用启动前要构建 workersprojects/app/package.json中的dev脚本是{dev:pnpm run build:workers next dev}这说明主应用启动前会先执行 worker 预编译。worker 源码位于packages/service/worker构建输出位于projects/app/worker当前 worker 包含文件解析、HTML 转 Markdown、文本切块、token 统计等能力。这些任务有几个特点特点说明CPU 或 IO 开销较大文件解析、文本切块不适合阻塞主请求线程依赖 Node 环境worker 以 Node 平台构建有运行时外部依赖例如llamaindex/liteparse包含 N-API 和动态库Docker runner 需要复制产物Dockerfile 会把projects/app/worker复制到运行镜像build-workers.ts使用 esbuild 扫描packages/service/worker下带index.ts的目录然后将每个 worker 打包成独立 JS 文件。它还会额外复制llamaindex/liteparse等运行时依赖。原因是这类依赖包含原生.node文件和动态库不适合直接打进 bundle需要以真实文件形式存在。所以build:workers不是普通的构建步骤而是在为主应用准备文件解析和知识库处理所需的运行时能力。开发依赖服务有哪些FastGPT 开发环境需要一组支撑服务。deploy/dev/docker-compose.yml的注释写得很清楚这个 compose 文件只包含 FastGPT 的最小化运行条件没有 FastGPT 本体。它主要提供服务默认端口作用PostgreSQL pgvector5432默认向量数据库MongoDB27017业务元数据存储Redis6379缓存、锁、队列、流式恢复等MinIO9000、9001对象存储和控制台Code Sandbox3002工作流代码节点执行MCP Server3003MCP 能力Plugin3004插件服务Volume Manager3005Agent Sandbox 卷管理Agent Sandbox Proxy3006沙盒代理OpenSandbox Server8090Agent Sandbox 运行环境AI Proxy3010模型聚合代理最小可启动链路通常至少需要能力必需服务登录和基础页面MongoDB、Redis文件上传和知识库MongoDB、Redis、MinIO、PG 向量库知识库检索MongoDB、PG 向量库、模型配置工作流代码节点Code Sandbox模型调用AI Proxy 或其他模型供应商配置MCP 使用MCP Server如果只是阅读页面和部分基础功能不一定要立刻启用所有高级服务。但如果要完整体验知识库、工作流和 Agent 能力建议直接启动开发 compose。环境变量文件应该放在哪里当前仓库中主应用只有projects/app/.env.template它是模板文件不会自动变成本地开发配置。Next.js 常见做法是复制为projects/app/.env.local示例cpprojects/app/.env.template projects/app/.env.local如果你从根目录执行pnpm--filterfastgpt/app devNext.js 仍会以projects/app作为主应用目录读取环境变量。因此本地 app 环境变量建议放在projects/app/.env.local。如果你使用 shell 注入环境变量也可以不创建.env.local但长期开发中不如文件方式直观。.env.template的配置分组projects/app/.env.template已经按功能分组。对本地开发来说可以先关注下面几组。基础配置变量作用DEFAULT_ROOT_PSW默认 root 用户密码DB_MAX_LINK数据库最大连接数SYNC_INDEX是否自动同步索引LOG_DEPTH日志输出深度本地开发中DEFAULT_ROOT_PSW直接影响 root 用户登录。模板中默认是123456README 中 Docker 快速启动示例默认密码可能是1234。实际以当前环境变量和初始化逻辑为准。密钥配置变量作用FILE_TOKEN_KEY文件阅读相关密钥AES256_SECRET_KEY密钥加密 keyINVOKE_TOKEN_SECRETInvoke 反向调用 JWT 密钥要求至少 32 位ROOT_KEYroot key拥有高权限这些变量在生产环境必须替换成安全随机值。本地开发可以使用模板值快速启动但不要把生产密钥写入文章、提交记录或公共配置。服务地址与集成变量默认值作用PLUGIN_BASE_URLhttp://localhost:3004插件服务地址CODE_SANDBOX_URLhttp://localhost:3002代码沙盒地址CODE_SANDBOX_TOKENcodesandbox代码沙盒 tokenAIPROXY_API_ENDPOINThttp://localhost:3010AI Proxy 地址AIPROXY_API_TOKENtokenAI Proxy tokenSSE_MCP_SERVER_PROXY_ENDPOINThttp://localhost:3003MCP SSE 代理地址MARKETPLACE_URLhttps://v2.marketplace.fastgpt.cn插件市场地址这些地址和deploy/dev/docker-compose.yml暴露的端口基本对应。也就是说依赖服务运行在 Docker 中主应用运行在宿主机 Node 进程中通过localhost访问这些依赖服务。对象存储变量默认值作用STORAGE_VENDORminio存储供应商STORAGE_ACCESS_KEY_IDminioadminMinIO access keySTORAGE_SECRET_ACCESS_KEYminioadminMinIO secret keySTORAGE_PUBLIC_BUCKETfastgpt-public公共桶STORAGE_PRIVATE_BUCKETfastgpt-private私有桶STORAGE_S3_ENDPOINThttp://localhost:9000S3 API endpointSTORAGE_S3_FORCE_PATH_STYLEtrueMinIO 通常需要 path style本地源码开发时主应用在宿主机运行所以 endpoint 使用localhost:9000是合理的。但如果 FastGPT 本体也运行在 Docker 容器中localhost就会指向容器自身而不是 MinIO 容器。此时应该使用 compose 网络内的服务名例如http://fastgpt-minio:9000。这也是开发 compose 注释里特别强调STORAGE_EXTERNAL_ENDPOINT不要写127.0.0.1或localhost的原因容器内访问和浏览器访问不是同一个网络视角。数据库与缓存变量默认值作用REDIS_URLredis://default:mypasswordlocalhost:6379Redis 连接MONGODB_URImongodb://myusername:mypasswordlocalhost:27017/fastgpt?authSourceadmindirectConnectiontrueMongoDB 连接MONGODB_LOG_URI空日志库连接可选PG_URLpostgresql://username:passwordlocalhost:5432/postgresPG 向量库连接MILVUS_ADDRESS空Milvus 连接可选OPENGAUSS_URL空openGauss 连接可选本地开发默认使用 PG pgvector 作为向量库优先级注释中写的是pg oceanbase milvus opengauss如果你只启用了 PG就保持PG_URL即可。切换 Milvus 或其他向量库时要同时确认 compose、环境变量和实际服务都已对齐。日志、指标与链路追踪变量作用LOG_ENABLE_CONSOLE是否输出控制台日志LOG_CONSOLE_LEVEL控制台日志等级LOG_ENABLE_OTEL是否启用 OTEL 日志METRICS_ENABLE_OTEL是否启用指标上报TRACING_ENABLE_OTEL是否启用链路追踪*_OTEL_URLOTEL Collector 地址本地开发中如果没有启动 OpenTelemetry Collector可以先关闭 OTEL 相关配置保留控制台日志即可。域名与前端变量作用FE_DOMAIN页面访问域名用于补全相对路径FILE_DOMAIN文件访问域名NEXT_PUBLIC_BASE_URL二级路由构建时确定NEXT_PUBLIC_BASE_URL会被packages/web/env.ts读取并通过next.config.ts影响basePath。如果你要把 FastGPT 部署在/fastai这样的子路径下需要在构建时设置它。本地开发通常可以保持为空。安全配置变量作用USE_IP_LIMIT是否启用 IP 限流CHECK_INTERNAL_IP是否检查内网 IPTRUSTED_PROXY_ENABLE是否启用可信反向代理客户端 IP 校验TRUSTED_PROXY_IPS可信代理列表ALLOWED_ORIGINS自定义跨域来源MULTIPLE_DATA_TO_BASE64是否强制图片转 base64 传给模型本地开发中安全配置往往会放松例如USE_IP_LIMITfalse。但生产环境应结合实际代理、域名和文件访问策略重新审视这些配置。并发和资源限制变量作用PARSE_FILE_WORKERS文件解析 worker 并发HTML_TO_MARKDOWN_WORKERSHTML 转 Markdown 并发TEXT_TO_CHUNKS_WORKERS文本切块并发WORKFLOW_MAX_RUN_TIMES工作流最大运行次数WORKFLOW_MAX_LOOP_TIMES循环和并行节点最大输入数组长度WORKFLOW_PARALLEL_MAX_CONCURRENCY并行节点并发上限CHAT_MAX_QPM工作流 QPM 上限UPLOAD_FILE_MAX_SIZE最大上传文件大小MAX_HTML_TRANSFORM_CHARSHTML 转 Markdown 最大字符数这些配置决定了本地开发时的资源占用。机器内存较小时不建议盲目提高 worker 并发、上传文件大小和队列处理并发。知识库队列并发变量作用DATASET_PARSE_MAX_PROCESS知识库文件解析队列最大并发VECTOR_MAX_PROCESS向量训练队列最大并发QA_MAX_PROCESS问答拆分队列最大并发VLM_MAX_PROCESS图片理解模型处理队列最大并发如果本地只是调试 API 或页面可以降低这些并发减少资源竞争。如果要压测知识库导入链路再逐步提高。环境变量校验入口FastGPT 并不是完全无约束地读取环境变量。部分环境变量通过t3-oss/env-core和 Zod schema 校验。主应用环境变量入口projects/app/src/env.ts这里校验了DEFAULT_ROOT_PSW、SSE_MCP_SERVER_PROXY_ENDPOINT、SYSTEM_NAME、MARKETPLACE_URL、OPENAPI_KEY_MAX_COUNT等变量。Worker 环境变量入口packages/service/worker/env.ts这里校验了MAX_HTML_TRANSFORM_CHARS。前端 basePath 环境变量入口packages/web/env.ts这里读取并规范化NEXT_PUBLIC_BASE_URL。如果启动时报类似Invalid app environment variables的错误优先检查.env.local中对应变量是否为空、格式是否正确。例如 URL 类型变量不能随便写普通字符串。本地源码开发与 Docker 部署的区别FastGPT 有两类常见启动方式。第一类是源码开发依赖服务跑在 Docker FastGPT 主应用跑在宿主机 Node 进程这种方式适合改代码、调试页面、调试 API、看日志和断点。第二类是完整 Docker 部署依赖服务和 FastGPT 主应用都跑在 Docker这种方式适合快速体验、部署验证和接近生产环境的测试。两者的关键差异在于网络地址。场景主应用访问 MongoDB主应用访问 MinIO说明源码开发app 在宿主机localhost:27017localhost:9000依赖服务端口映射到宿主机Docker 部署app 在容器内fastgpt-mongo:27017fastgpt-minio:9000使用 compose service name所以不要简单复制容器环境变量到本地源码开发也不要把本地localhost配置直接搬到容器环境里。推荐的启动步骤下面给一条适合首次源码开发的路径。第一步安装依赖chmod-Rx ./scripts/pnpmi如果 postinstall 没有正常构建 SDK再执行pnpmbuild:sdks第二步准备环境变量cpprojects/app/.env.template projects/app/.env.local然后至少确认下面几类配置和本机依赖服务一致配置本地默认值MONGODB_URImongodb://myusername:mypasswordlocalhost:27017/fastgpt?authSourceadmindirectConnectiontrueREDIS_URLredis://default:mypasswordlocalhost:6379PG_URLpostgresql://username:passwordlocalhost:5432/postgresSTORAGE_S3_ENDPOINThttp://localhost:9000CODE_SANDBOX_URLhttp://localhost:3002AIPROXY_API_ENDPOINThttp://localhost:3010第三步启动依赖服务国际镜像源dockercompose-fdeploy/dev/docker-compose.yml up-d国内镜像源dockercompose-fdeploy/dev/docker-compose.cn.yml up-d开发 compose 只启动依赖服务不启动 FastGPT 主应用。第四步启动主应用根目录执行pnpm--filterfastgpt/app dev或makedevnameapp启动成功后访问http://localhost:3000默认 root 密码以当前环境变量DEFAULT_ROOT_PSW为准。常见问题与排查路径依赖安装失败先检查 Node 和 pnpm 版本node-vpnpm-v再检查是否使用了正确的 pnpm 版本。当前仓库要求 pnpm10.x。如果是原生依赖构建失败重点关注sharp、canvas、mongodb-memory-server、protobufjs等依赖以及当前机器架构和网络代理。SDK 模块解析失败如果看到fastgpt-sdk/otel/logger或类似 subpath export 找不到先执行pnpmbuild:sdks然后重新启动主应用。Worker 构建失败先单独执行pnpm--filterfastgpt/app build:workers如果错误指向llamaindex/liteparse需要检查依赖是否安装完整以及当前平台对应的 native 包是否存在。MongoDB 连接失败检查docker compose中fastgpt-mongo是否启动。MONGODB_URI用户名、密码、端口是否和 compose 一致。本地源码开发是否使用localhost:27017。远程 MongoDB 是否需要directConnectiontrue。Redis 连接失败检查fastgpt-redis是否启动。REDIS_URL密码是否是mypassword。本机6379端口是否被其他 Redis 占用。向量库连接失败默认开发 compose 使用 PG pgvector。检查fastgpt-pg是否启动。PG_URL是否是postgresql://username:passwordlocalhost:5432/postgres。本机5432是否被其他 PostgreSQL 占用。是否错误配置了 Milvus、OceanBase 或 OpenGauss导致向量库选择与实际服务不一致。文件上传或预览异常重点检查 MinIOfastgpt-minio是否启动。STORAGE_S3_ENDPOINT是否对服务端可访问。STORAGE_EXTERNAL_ENDPOINT是否对浏览器可访问。bucket 名称、access key、secret key 是否一致。本地源码开发中服务端和浏览器通常都能访问localhost:9000。容器部署时要特别区分容器内地址和浏览器地址。模型调用失败FastGPT 能启动不代表模型一定可用。模型调用还依赖AI Proxy 是否启动。AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN是否正确。模型配置是否存在。对应模型供应商的 key、baseURL、模型名是否配置正确。如果页面能打开但聊天报错优先排查模型配置而不是 Next.js 启动链路。Code Sandbox 调用失败检查fastgpt-code-sandbox是否启动。CODE_SANDBOX_URL是否指向http://localhost:3002。CODE_SANDBOX_TOKEN是否和 compose 中的codesandbox一致。如果代码节点访问外部网络是否被沙盒安全策略拦截。本地调试建议先跑通最小链路第一次启动不要同时调试所有能力。建议先确认页面能打开。root 能登录。MongoDB 和 Redis 连接正常。基础应用列表能加载。再逐步验证模型调用。文件上传。知识库导入。知识库检索。工作流节点。代码沙盒和 MCP。这样排查问题更聚焦。区分启动失败和业务失败启动失败通常表现为next dev报错、环境变量校验失败、依赖模块找不到。业务失败通常表现为页面能打开但某个功能报错例如知识库训练失败、模型调用失败、代码节点失败。这两类问题的排查入口不同。前者看终端和构建日志后者看接口响应、服务日志和依赖服务状态。保持环境变量最小可读.env.template很长但本地开发时不一定要理解每一项。可以先把它按功能分组阅读数据库与缓存 对象存储 模型与插件服务 日志与追踪 安全配置 并发与资源限制遇到具体功能问题再回到对应分组细看。不要混用两套网络视角这是本地开发最常见的问题之一。如果主应用在宿主机跑依赖服务用localhost。如果主应用在 Docker 容器里跑依赖服务用 compose service name。同一份环境变量不要在两种模式之间直接复用。本篇小结FastGPT 的本地开发不是单纯执行next dev。更准确地说它需要先准备一个 AI 应用平台的运行底座MongoDB、Redis、向量库、对象存储、模型代理、代码沙盒以及用于文件解析和知识库处理的 workers。这篇文章里我们梳理了根目录脚本和 app 脚本的分工。为什么要先构建 SDK。为什么主应用启动前要构建 workers。开发 compose 提供哪些依赖服务。.env.template中的关键配置分组。本地源码开发和 Docker 部署的网络差异。常见启动问题的排查路径。下一篇我们会进入主应用本身拆解projects/app的 Next.js 架构页面、组件、API 路由、服务层分别如何组织以及 FastGPT 为什么把前端页面和 API 放在同一个主应用中。