FastGPT 环境变量清单生成器

配置模板里有 136 项变量，分成 15 组。一次部署实际要动的远少于这个数：其中 104 项带默认值，不动也能跑；真正必须自己填的是 32 项，另有 24 项默认不启用、要显式打开才生效。下面这个模块按部署形态与要用的能力，把该配的那些筛出来。

为什么不建议照着模板逐项填

配置模板是把所有可能用到的变量都列出来的一份清单，它不是一份「每次都要填满」的表格。逐项填有三个坏处。

第一是把带默认值的项改成了另一个值。136 项里有 104 项自带默认值，这些默认值多数是按单机部署调过的，手工改成看起来更合理的数字反而容易踩到资源上限。

第二是把不需要的能力打开了。对象存储、沙箱、增强解析这些分组的变量，只有在用到对应能力时才需要配；填了一半的配置比不填更麻烦，服务起来之后才报错，而报错信息指向的是下游组件。

第三是漏掉真正必须填的那些。必须填的项散在不同分组里，并不集中在开头，按顺序从上往下填很容易在中途停下，而漏掉的那几项往往是密钥与外部服务地址这类没有默认值的。

交互模块：按部署形态生成变量清单

选择部署形态与要启用的能力，模块会列出这次实际需要设置的变量、每一项的默认值，以及哪些必须自己填。可以只看必填项，也可以把默认不启用的项一起列出来。

取值口径 v4.16.2核验日 2026-09-09变量 136分组 15

本次清单112

必须自己填19

默认关闭0

基础配置4 / 4 项

变量名	默认值	状态	说明
`LOG_DEPTH`	`3`	默认启用	模板未附说明
`DEFAULT_ROOT_PSW`	`123456`	默认启用	默认用户密码（用户名为 root），每次重启会自动更新。
`DB_MAX_LINK`	`5`	默认启用	数据库最大连接数
`SYNC_INDEX`	`true`	默认启用	自动同步索引

密钥4 / 4 项

变量名	默认值	状态	说明
`FILE_TOKEN_KEY`	无默认值	必须自己填	文件阅读时的密钥
`AES256_SECRET_KEY`	`fastgptsecret`	默认启用	密钥加密 key
`INVOKE_TOKEN_SECRET`	`fastgpt_invoke_token_secret_32_chars_min`	默认启用	Invoke 反向调用 JWT 密钥，至少 32 位
`ROOT_KEY`	`fdafasd`	默认启用	root key（最高权限）

服务地址与集成30 / 34 项

变量名	默认值	状态	说明
`PLUGIN_BASE_URL`	`http://localhost:3004`	默认启用	插件服务
`PLUGIN_TOKEN`	`XHgR8zvKx1FhjHUxCKdJMNpzFUMlavM1`	默认启用	模板未附说明
`CODE_SANDBOX_URL`	`http://localhost:3002`	默认启用	代码沙箱服务
`CODE_SANDBOX_TOKEN`	`codesandbox`	默认启用	模板未附说明
`AIPROXY_API_ENDPOINT`	`http://localhost:3010`	默认启用	AI Proxy API
`AIPROXY_API_TOKEN`	`token`	默认启用	模板未附说明
`SSE_MCP_SERVER_PROXY_ENDPOINT`	`http://localhost:3003`	默认启用	MCP Server 代理地址，用于 MCP 使用方式页拼接 SSE 地址（末尾不要带 /）
`MARKETPLACE_URL`	`https://v2.marketplace.fastgpt.cn`	默认启用	插件市场地址
`AGENT_SANDBOX_PROVIDER`	无默认值	必须自己填	Agent sandbox
`AGENT_SANDBOX_SEALOS_BASEURL`	无默认值	必须自己填	Sealos devbox
`AGENT_SANDBOX_SEALOS_TOKEN`	无默认值	必须自己填	模板未附说明
`AGENT_SANDBOX_SEALOS_IMAGE`	无默认值	必须自己填	模板未附说明
`AGENT_SANDBOX_SEALOS_WORK_DIRECTORY`	`/home/devbox/workspace`	默认启用	模板未附说明
`AGENT_SANDBOX_CPU_COUNT`	`1`	默认启用	Agent Sandbox 单实例 CPU 核数和内存上限（MiB）
`AGENT_SANDBOX_MEMORY_MIB`	`2048`	默认启用	模板未附说明
`AGENT_SANDBOX_STORAGE_SIZE_GI`	`1`	默认启用	Agent Sandbox 存储容量，单位 Gi
`AGENT_SANDBOX_OPENSANDBOX_BASEURL`	`http://localhost:8090`	默认启用	OpenSandbox 配置（PROVIDER=opensandbox 时生效）
`AGENT_SANDBOX_OPENSANDBOX_API_KEY`	`my_secure_sandbox_key_123`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_RUNTIME`	`docker`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_IMAGE`	`registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox:v0.1`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY`	`true`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL`	`http://localhost:3005`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN`	`vmtoken`	默认启用	模板未附说明
`AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX`	`fastgpt-session`	默认启用	模板未附说明
`AGENT_SANDBOX_MAX_EDIT_DEBUG`	`100`	默认启用	活跃编辑/调试沙箱数量上限
`AGENT_SANDBOX_SUSPEND_MINUTES`	`60`	默认启用	运行中 Agent 沙箱持续未活跃多少分钟后自动暂停
`AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS`	`7`	默认启用	已暂停 Agent 沙箱持续未活跃多少天后自动归档
`AGENT_SANDBOX_NPM_REGISTRY`	无默认值	必须自己填	Agent 沙箱内 npm/yarn/pnpm/bun 使用的 npm registry（可选）
`AGENT_SANDBOX_PYPI_INDEX_URL`	无默认值	必须自己填	Agent 沙箱内 pip/python -m pip/uv 使用的 PyPI index URL（可选）
`AGENT_SANDBOX_APT_MIRROR`	无默认值	必须自己填	Ubuntu 或 Debian Agent 沙箱内使用的 apt 镜像地址（可选），仅 root 有效；Debian 的 /debian-security 会自动推导

沙盒代理 (agent-sandbox-proxy) 与网络配置3 / 3 项

变量名	默认值	状态	说明
`AGENT_SANDBOX_PROXY_SECRET`	`default_fastgpt_agent_sandbox_proxy_secret`	默认启用	JWT 验签与内网安全物理阻断密钥 (必须与 Rust Proxy 的 AGENT_SANDBOX_PROXY_SECRET 环境变量保持完全一致) 生产环境必须配置为至少 32 字节的高强度随机值，不能使用示例占位。
`AGENT_SANDBOX_PROXY_URL`	`ws://localhost:3006`	默认启用	浏览器客户端连接沙盒代理的对外 WebSocket 地址。启用 Agent Sandbox（show_agent_sandbox）时必填；未启用时可留空。开发环境建议配置为 ws://localhost:3006 (指向 Docker Compose 中的 Rust 代理)。生产环境请配置浏览器可访问的 ws:// 或 wss:// 代理地址。
`AGENT_SANDBOX_PREVIEW_PROXY_URL`	`http://localhost:3006`	默认启用	浏览器访问沙盒文件预览的 HTTP(S) 地址。启用 Agent Sandbox 时必填；默认单端口部署时与 WebSocket 使用相同端口。

对象存储14 / 14 项

变量名	默认值	状态	说明
`STORAGE_VENDOR`	`minio`	默认启用	存储供应商；如果是 Sealos 的对象存储请填 aws-s3
`STORAGE_REGION`	`us-east-1`	默认启用	模板未附说明
`STORAGE_ACCESS_KEY_ID`	`minioadmin`	默认启用	模板未附说明
`STORAGE_SECRET_ACCESS_KEY`	`minioadmin`	默认启用	模板未附说明
`STORAGE_PUBLIC_BUCKET`	`fastgpt-public`	默认启用	模板未附说明
`STORAGE_PRIVATE_BUCKET`	`fastgpt-private`	默认启用	模板未附说明
`STORAGE_EXTERNAL_ENDPOINT`	无默认值	必须自己填	模板未附说明
`STORAGE_S3_CDN_ENDPOINT`	无默认值	必须自己填	模板未附说明
`STORAGE_DOWNLOAD_URL_MODE`	`short-proxy`	默认启用	下载链接模式：short-proxy \| short-redirect \| presigned
`STORAGE_DOWNLOAD_REDIRECT_TTL_SECONDS`	`300`	默认启用	short-redirect 模式下临时 S3 预签名下载链接 TTL（秒），不太需要改。
`STORAGE_S3_ENDPOINT`	`http://localhost:9000`	默认启用	模板未附说明
`STORAGE_S3_FORCE_PATH_STYLE`	`true`	默认启用	模板未附说明
`STORAGE_S3_MAX_RETRIES`	`3`	默认启用	模板未附说明
`STORAGE_PUBLIC_ACCESS_EXTRA_SUB_PATH`	无默认值	必须自己填	模板未附说明

数据库与缓存5 / 15 项

变量名	默认值	状态	说明
`REDIS_URL`	`redis://default:mypassword@localhost:6379`	默认启用	Redis URL
`MONGODB_URI`	`mongodb://myusername:mypassword@localhost:27017/fastgpt?authSource=admin&directConnection=true`	默认启用	MongoDB 连接参数；本地开发连接远程数据库时，可能需要添加 directConnection=true 才能连接
`MONGODB_LOG_URI`	无默认值	必须自己填	日志库
`VECTOR_VQ_LEVEL`	`32`	默认启用	向量库优先级: pg > oceanbase > milvus > opengauss 向量量化等级: PG 支持 32/16，OceanBase 支持 32/8/1
`PG_URL`	`postgresql://username:password@localhost:5432/postgres`	默认启用	PG 向量库连接参数

日志配置12 / 12 项

变量名	默认值	状态	说明
`LOG_ENABLE_CONSOLE`	`true`	默认启用	日志等级: trace \| debug \| info \| warning \| error \| fatal
`LOG_CONSOLE_LEVEL`	`debug`	默认启用	模板未附说明
`LOG_ENABLE_OTEL`	`true`	默认启用	模板未附说明
`LOG_OTEL_LEVEL`	`info`	默认启用	模板未附说明
`LOG_OTEL_SERVICE_NAME`	`fastgpt-client`	默认启用	模板未附说明
`LOG_OTEL_URL`	`http://localhost:4318/v1/logs`	默认启用	模板未附说明
`METRICS_ENABLE_OTEL`	`true`	默认启用	指标
`METRICS_OTEL_URL`	`http://localhost:4318/v1/metrics`	默认启用	模板未附说明
`METRICS_OTEL_SERVICE_NAME`	`fastgpt-client`	默认启用	模板未附说明
`TRACING_ENABLE_OTEL`	`true`	默认启用	追踪
`TRACING_OTEL_URL`	`http://localhost:4318/v1/traces`	默认启用	模板未附说明
`TRACING_OTEL_SERVICE_NAME`	`fastgpt-client`	默认启用	模板未附说明

域名与前端2 / 3 项

变量名	默认值	状态	说明
`FE_DOMAIN`	`http://localhost:3000`	默认启用	必填。客户端访问 FastGPT 时使用的地址，由协议、主机和可选端口组成，用于补全相对路径资源（注意结尾不要带 /）
`FILE_DOMAIN`	`http://localhost:3000`	默认启用	文件域名（也指向 FastGPT 服务）；如需更高安全性可独立分配域名，避免高危文件读取到主域名内容

安全配置10 / 10 项

变量名	默认值	状态	说明
`USE_IP_LIMIT`	`false`	默认启用	启动 IP 限流（true）；部分接口启用 IP 限流策略以防止异常请求
`CHECK_INTERNAL_IP`	`false`	默认启用	启用内网 IP 检查
`AUTH_COOKIE_SECURE`	`false`	默认启用	是否为登录 Cookie 添加 Secure 属性，仅在全站 HTTPS 时启用
`TRUSTED_PROXY_ENABLE`	`false`	默认启用	是否启用可信反向代理客户端 IP 校验
`TRUSTED_PROXY_IPS`	无默认值	必须自己填	可信反向代理 IP/CIDR 列表，逗号或空白分隔。仅 TRUSTED_PROXY_ENABLE=true 时生效；仅显式可信代理传入的 X-Forwarded-For/X-Real-IP 会用于客户端 IP 解析
`PASSWORD_LOGIN_MINUTE_LIMIT_COUNT`	无默认值	必须自己填	密码登录每分钟次数限制（默认 10）
`PASSWORD_EXPIRED_MONTH`	无默认值	必须自己填	密码过期月份（不设置则不过期）
`MAX_LOGIN_SESSION`	无默认值	必须自己填	最大登录客户端数量（默认 10）
`ALLOWED_ORIGINS`	无默认值	必须自己填	自定义跨域；不配置时默认允许所有跨域（逗号分割）
`MULTIPLE_DATA_TO_BASE64`	`true`	默认启用	强制将图片转成 base64 传递给模型

功能开关与特殊配置8 / 8 项

变量名	默认值	状态	说明
`SHOW_COUPON`	`false`	默认启用	是否展示兑换码功能
`SHOW_DISCOUNT_COUPON`	`false`	默认启用	是否展示优惠券功能
`APP_REGISTRATION_URL`	无默认值	必须自己填	申请应用备案地址
`HIDE_CHAT_COPYRIGHT_SETTING`	无默认值	必须自己填	是否隐藏版权信息配置，只有值为 true 时隐藏
`WECOM_LOGIN_AUTO_REDIRECT`	`false`	默认启用	是否允许企微终端自动跳转登录，默认 false
`OPENAPI_KEY_MAX_COUNT`	`100`	默认启用	单个团队成员最多可创建的系统 API Key 数量，最小值为 1
`AGENT_ENGINE`	`fastAgent`	默认启用	Agent 引擎选择：fastAgent（FastGPT agent loop）\| piAgent（pi-agent-core 引擎）
`SKIP_FILE_TYPE_CHECK`	`false`	默认启用	模板未附说明

并发控制与限制6 / 6 项

变量名	默认值	状态	说明
`WECHAT_CHANNEL_CONCURRENCY`	`1000`	默认启用	微信渠道 poll worker 并发数（默认 1000），需 ≥ online channel 数；channel 数超过该值时消息延迟会线性恶化
`PARSE_FILE_TIMEOUT_SECONDS`	`600`	默认启用	文件解析超时时间（秒）
`WORKFLOW_MAX_RUN_TIMES`	`500`	默认启用	工作流最大运行次数，避免极端死循环
`WORKFLOW_MAX_LOOP_TIMES`	`100`	默认启用	循环/并行节点最大输入数组长度（默认 100）
`WORKFLOW_PARALLEL_MAX_CONCURRENCY`	`10`	默认启用	并行节点并发上限（最终会 clamp 到 [5, 100]，默认 10）
`CHAT_MAX_QPM`	`5000`	默认启用	工作流 QPM（若用户套餐有限制，这里不生效）

资源限制8 / 8 项

变量名	默认值	状态	说明
`SERVICE_REQUEST_MAX_CONTENT_LENGTH`	`10`	默认启用	服务器接收请求的最大大小（MB）
`MAX_FOLDER_DEPTH`	`4`	默认启用	允许的最深文件夹层级，默认 4，范围 2~20（根目录下最多 4 层文件夹）
`APP_FOLDER_MAX_AMOUNT`	`1000`	默认启用	应用文件夹最大数量
`DATASET_FOLDER_MAX_AMOUNT`	`1000`	默认启用	数据集文件夹最大数量
`UPLOAD_FILE_MAX_SIZE`	`1000`	默认启用	最大上传文件大小（MB）
`UPLOAD_FILE_MAX_AMOUNT`	`1000`	默认启用	最大上传文件数量
`LLM_REQUEST_TRACKING_RETENTION_HOURS`	`6`	默认启用	LLM 请求追踪保留时长（小时）
`MAX_HTML_TRANSFORM_CHARS`	`1000000`	默认启用	HTML 转 Markdown 最大字符数（超过后不执行转换）

PDF 增强解析（可选）2 / 8 项

变量名	默认值	状态	说明
`HNSW_EF_SEARCH`	`100`	默认启用	向量检索 hnsw ef_search 参数，仅对 PG / OB / OpenGauss 生效
`HNSW_MAX_SCAN_TUPLES`	`100000`	默认启用	向量检索最大扫描数据量，仅对 PG 生效

知识库处理并发控制4 / 4 项

变量名	默认值	状态	说明
`DATASET_PARSE_MAX_PROCESS`	`10`	默认启用	知识库文件解析队列最大并发数
`VECTOR_MAX_PROCESS`	`10`	默认启用	向量训练队列最大并发数
`QA_MAX_PROCESS`	`10`	默认启用	问答拆分队列最大并发数
`VLM_MAX_PROCESS`	`10`	默认启用	图片理解模型处理队列最大并发数

15 个分组的分布

这张表是全部分组的分布，可以直接对照使用。「有默认值」小于「项数」的分组，差额就是那一组里必须自己填的项。

分组	项数	有默认值	默认启用	模板附了说明
基础配置	4	4	4	3
密钥	4	3	4	4
服务地址与集成	34	24	30	18
沙盒代理 (agent-sandbox-proxy) 与网络配置	3	3	3	3
对象存储	14	11	14	3
数据库与缓存	15	10	5	12
日志配置	12	12	12	3
域名与前端	3	3	2	3
安全配置	10	5	10	10
功能开关与特殊配置	8	6	8	7
对话日志推送（可选）	3	3	0	3
并发控制与限制	6	6	6	6
资源限制	8	8	8	8
PDF 增强解析（可选）	8	2	2	8
知识库处理并发控制	4	4	4	4

必须自己填的 32 项集中在哪里

没有默认值的项分布并不均匀。服务地址与集成那一组最多，因为它装的是外部服务的地址与凭证，这类值不可能有默认值；对象存储与数据库缓存两组也各有几项，取决于用的是内置组件还是外部实例。

有一类值要特别注意：带默认值但必须改的项。带默认值不等于可以不改 —— 这些默认值就写在公开的配置模板里，任何人拿到同一份模板都知道它是什么。下面这几项属于这一档：

变量名	分组	模板里的默认值	它管什么
DEFAULTROOTPSW	基础配置	`123456`	root 账号的初始密码
ROOT_KEY	密钥	`fdafasd`	根级接口调用凭证
AES256SECRETKEY	密钥	`fastgptsecret`	敏感字段落库前的加密密钥
INVOKETOKENSECRET	密钥	`fastgpt_invoke_token_secret_32_chars_min`	内部调用令牌的签名密钥
AGENTSANDBOXPROXY_SECRET	沙盒代理 (agent-sandbox-proxy) 与网络配置	`default_fastgpt_agent_sandbox_proxy_secret`	沙箱代理的验签密钥
AGENTSANDBOXOPENSANDBOXAPIKEY	服务地址与集成	`my_secure_sandbox_key_123`	沙箱服务的接口凭证
STORAGEACCESSKEY_ID	对象存储	`minioadmin`	内置对象存储的账号
STORAGESECRETACCESS_KEY	对象存储	`minioadmin`	内置对象存储的密码

对照这张表检查自己的配置文件，比逐项回想改过没有更快。其中对象存储那两项只在使用内置存储时需要改，接了外部对象存储时它们会被外部服务的凭证替代。

另一类是对接商业版或外部平台的地址与令牌。只用开源版时这些项留空即可，服务不会因为它们为空而起不来；但如果填了地址而没填令牌，会在调用时才失败，这种半填状态比完全不填更难排查。

按分组数一遍：无默认值的项最集中的三组是服务地址与集成 10 项、PDF 增强解析（可选） 6 项、数据库与缓存 5 项。这个分布本身可以当部署前的检查顺序 —— 先把这三组过一遍，剩下各组零散的几项再逐个看，比从模板第一行往下读效率高得多。对照上面那张表还能快速判断某一组要不要动：「项数」与「有默认值」相等的组，这次部署基本不用碰。

改完之后怎么确认它真的生效了

改了配置文件不等于服务读到了新值。这一步经常被跳过，而它导致的现象是「配置看着对，行为还是旧的」，比报错更难查。

第一件事是确认容器是重建过的，不是只重启过。环境变量在容器创建时读入，重启不会重新读配置文件；改完之后要让容器按新的配置重新创建，否则文件是新的、进程里还是旧值。

第二件事是从服务自己的输出去确认，配置文件说明不了这件事。配置文件只能说明「我打算设成什么」，服务启动日志与运行时的行为才说明「它实际用的是什么」。有默认值的项尤其要这样确认：写错了变量名的时候，服务会安静地退回默认值，配置文件里那一行看起来完全正常。

第三件事是逐项确认，不要整批确认。一次改了七八项时，只验证服务能起来说明不了每一项都生效了；把这次改动的项列出来逐个对，比事后从现象反推省时间。上面那个模块生成的清单可以直接当这份核对表用。

默认不启用的 24 项是什么

模板里有一部分变量是注释掉的，24 项属于这种情况。这些都是仍然有效的可选项，用到对应能力时才需要打开，注释掉只表示默认不启用。

这类项集中在几个可选能力上：对话日志推送整组默认关闭，增强解析那一组也基本默认关闭，数据库与缓存里有一部分是给外部实例准备的、用内置组件时不需要。

判断要不要打开的方法是从能力反推。先确定这次部署要不要用某个能力，再去看它那一组需要哪些变量，逐个看变量名去猜它管什么，顺序正好是反的。上面的模块就是按这个顺序组织的。

有 41 项模板里没有附说明

136 项变量里，95 项在模板里带说明，剩下 41 项只有变量名与默认值，没有文字解释。这个缺口在本页如实标出来，上面那张表最后一列就是每组附了说明的项数。

遇到没有说明的项，判断方法有两个。一是看它所在的分组，分组本身说明了它管哪一块；二是拿变量名去开源仓库里搜，被读取的位置通常只有一两处，看那一处怎么用它，比按名字猜更准。

不建议按变量名的字面意思猜。同一个词在不同分组里含义可能不同，比如带「上限」字样的变量，有的是并发上限，有的是单次请求的体积上限，两者调错方向的后果完全不同。

版本差异与失效说明

本页的 136 项来自 v4.16.2 的配置模板。模板在版本之间会增删变量，也会改默认值，所以升级之前建议把两个版本的模板做一次比对，重点看新增项里有没有没有默认值的 —— 那类项不填会导致服务起不来。已经改过的变量在升级时不会被覆盖，但新增项不会自动出现在旧的配置文件里。比对的方法是把两个版本的模板都取下来按变量名做差集，看新增、删除与默认值变化三类；只看变量名不看默认值会漏掉第三类，而默认值变了往往正是升级后行为变化的来源。

继续阅读

本页参数与判定规则取自 FastGPT 开源仓库 v4.16.2，核验日 2026-09-09。

参考资料

同主题内容

技术速查FastGPT 错误码定位器：14 个模块 122 条错误码，含 8 个需要看 statusText 才能区分的码值技术速查FastGPT 环境变量速查全表（136 项 · 按用途分组）技术速查FastGPT 错误码全表（122 条 · 按模块分组）