环境变量说明

本文说明 FastGPT 自部署时常用服务的环境变量。projects/app 与 pro/admin 会大量复用 packages/service/env.ts 中的服务端配置，因此数据库、密钥、对象存储、向量库等变量合并说明；只有 projects/app 或 pro/admin 自己读取的变量单独列出。

说明

projects/app：主应用服务，包含 Next.js 页面、API 路由、工作流、知识库、对象存储、向量库等能力。
pro/admin：商业版 Admin 服务。除自己的后台功能变量外，也会复用 App/Service 的数据库、密钥、对象存储、模型、日志等变量。
projects/code-sandbox：代码沙箱服务，对外暴露 /sandbox 执行接口，供 App 通过 CODE_SANDBOX_URL 调用。
代码中 packages/service/env.ts 导出名为 serviceEnv，projects/app/src/env.ts 导出名为 appEnv。
App/Admin 共享布尔变量使用 true、1、yes 或 y 表示开启；其他值视为关闭。
FILE_TOKEN_KEY 与 AES256_SECRET_KEY 为运行期必填，建议使用随机强密钥，不要使用示例值。

App/Admin 共享变量

这些变量主要由 packages/service/env.ts 校验，适用于 projects/app，也适用于会导入 @fastgpt/service 的 pro/admin。注意：packages/service/env.ts 当前也包含少量 App 侧开关；这类变量在下方 projects/app 额外变量中单独列出。

基础与密钥

变量	默认值	说明
`DB_MAX_LINK`	`5`	MongoDB、PG、OceanBase、openGauss 等数据库连接池最大连接数。
`SYNC_INDEX`	`true`	启动时是否同步 MongoDB 索引。
`TOKEN_KEY`	`fastgpt_token_key`	用户登录态、业务 Token 等签名密钥，长度至少 6 位。
`FILE_TOKEN_KEY`	无，必填	文件读取、文件鉴权相关密钥，长度至少 6 位。
`AES256_SECRET_KEY`	无，必填	AES 加解密密钥，长度至少 6 位。
`ROOT_KEY`	`fastgpt_root_key`	Root API Key/内部最高权限密钥，长度至少 6 位。
`PRO_URL`	空	商业版服务地址，配置后 App 可调用 Pro API，也会作为文件 URL 安全校验允许域名。

服务地址与集成

变量	默认值	说明
`PLUGIN_BASE_URL`	`http://localhost:3004`	FastGPT Plugin 服务地址；部署模板通常会配置为内部 Plugin 服务地址。
`PLUGIN_TOKEN`	`token`	调用 Plugin 服务使用的认证 Token；需与 Plugin 服务配置一致。
`CODE_SANDBOX_URL`	`http://localhost:3002`	Code Sandbox 服务地址；部署模板通常会配置为内部 Code Sandbox 服务地址。
`CODE_SANDBOX_TOKEN`	`codesandbox`	App 调用 Code Sandbox 时使用的认证 Token，需与沙箱服务 `SANDBOX_TOKEN` 一致。
`AIPROXY_API_ENDPOINT`	`http://localhost:3010`	AI Proxy 服务地址；配置后模型请求会优先走 AI Proxy。
`AIPROXY_API_TOKEN`	`token`	调用 AI Proxy 使用的认证 Token。
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	未配置 AI Proxy 时，兼容 OpenAI 协议的默认模型接口地址。
`CHAT_API_KEY`	空	未配置 AI Proxy Token 时，兼容 OpenAI 协议的默认模型 API Key。
`MARKETPLACE_URL`	`https://marketplace.fastgpt.cn`	插件市场接口地址。
`FEISHU_BASE_URL`	`https://open.feishu.cn`	飞书开放平台地址，私有化飞书可改为对应域名。
`DINGTALK_BASE_URL`	`https://api.dingtalk.com`	钉钉新版 API 基础地址。
`DINGTALK_OAPI_BASE_URL`	`https://oapi.dingtalk.com`	钉钉 OAPI 基础地址。
`YUQUE_DATASET_BASE_URL`	`https://www.yuque.com`	语雀知识库地址。

Agent Sandbox

变量	默认值	说明
`AGENT_SANDBOX_PROVIDER`	空	Agent 沙箱提供方，可选 `sealosdevbox`、`opensandbox`、`e2b`；为空时不启用 Agent 沙箱。
`AGENT_SANDBOX_E2B_API_KEY`	空	E2B 沙箱 API Key。
`AGENT_SANDBOX_SEALOS_BASEURL`	空	Sealos Devbox 服务地址。
`AGENT_SANDBOX_SEALOS_TOKEN`	空	Sealos Devbox 访问 Token。
`AGENT_SANDBOX_OPENSANDBOX_BASEURL`	空	OpenSandbox 服务地址。
`AGENT_SANDBOX_OPENSANDBOX_API_KEY`	空	OpenSandbox API Key。
`AGENT_SANDBOX_OPENSANDBOX_RUNTIME`	`docker`	OpenSandbox 运行时，可选 `docker` 或 `kubernetes`。
`AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO`	空	OpenSandbox 使用的镜像仓库。
`AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG`	`latest`	OpenSandbox 使用的镜像标签。
`AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY`	`true`	OpenSandbox 是否通过服务端代理访问。
`AGENT_SANDBOX_ENABLE_VOLUME`	`false`	Agent 沙箱是否启用持久化 Volume。
`AGENT_SANDBOX_VOLUME_MANAGER_URL`	空	Volume Manager 服务地址。
`AGENT_SANDBOX_VOLUME_MANAGER_TOKEN`	空	Volume Manager 认证 Token。
`AGENT_SANDBOX_VOLUME_MANAGER_MOUNT_PATH`	`/workspace`	Volume 挂载到沙箱内的路径。
`AGENT_SANDBOX_FREE_TIP`	`false`	前端是否展示 Agent Sandbox 免费提示。
`AGENT_SANDBOX_MAX_EDIT_DEBUG`	空	Agent 编辑/调试沙箱数量限制；为空表示不限制。
`AGENT_SANDBOX_MAX_SESSION_RUNTIME`	空	Agent 沙箱会话运行时长限制；为空表示不限制。

Skill 限制

变量	默认值	说明
`AGENT_SKILL_MAX_UPLOAD_SIZE`	空	Skill 上传包大小上限。
`AGENT_SKILL_MAX_UNCOMPRESSED_SIZE`	空	Skill 解压后大小上限。
`AGENT_SKILL_MAX_DOWNLOAD_SIZE`	空	Skill 下载资源大小上限。
`AGENT_SKILL_MAX_SANDBOX_SIZE`	空	Skill 沙箱目录大小上限。

数据库、缓存与向量库

变量	默认值	说明
`REDIS_URL`	`redis://default:mypassword@localhost:6379`	Redis 连接地址。
`STREAM_RESUME_TTL_SECONDS`	`300`	流式恢复镜像在生成中的 TTL，单位秒。
`STREAM_RESUME_POST_COMPLETE_TTL_SECONDS`	`30`	流结束后恢复镜像的缩短 TTL，单位秒。
`STREAM_RESUME_REDIS_MAXMEMORY_RATIO`	`0.5`	Redis 已用内存与 `maxmemory` 比例达到该值后，不再创建新的流恢复镜像。
`STREAM_RESUME_REDIS_MEMORY_CHECK_INTERVAL_MS`	`5000`	Redis 内存水位检测缓存时间，单位毫秒。
`MONGODB_URI`	本地 MongoDB 示例地址	主业务 MongoDB 连接地址。
`MONGODB_LOG_URI`	同 `MONGODB_URI` 示例地址	日志 MongoDB 连接地址；不配置时可复用主库。
`VECTOR_VQ_LEVEL`	`32`	向量量化等级；不同向量库支持范围不同。
`PG_URL`	空	PostgreSQL/pgvector 向量库连接地址。
`OCEANBASE_URL`	空	OceanBase 向量库连接地址。
`SEEKDB_URL`	空	SeekDB 向量库连接地址。
`MILVUS_ADDRESS`	空	Milvus/Zilliz 连接地址。
`MILVUS_TOKEN`	空	Milvus/Zilliz 访问 Token。
`OPENGAUSS_URL`	空	openGauss 向量库连接地址。

对象存储

变量	默认值	说明
`STORAGE_VENDOR`	`minio`	对象存储类型，可选 `minio`、`aws-s3`、`cos`、`oss`。
`STORAGE_PUBLIC_BUCKET`	`fastgpt-public`	公开文件 Bucket。
`STORAGE_PRIVATE_BUCKET`	`fastgpt-private`	私有文件 Bucket。
`STORAGE_REGION`	`us-east-1`	对象存储 Region。
`STORAGE_EXTERNAL_ENDPOINT`	空	外部可访问的对象存储地址，用于浏览器或外部服务访问。
`STORAGE_S3_ENDPOINT`	`http://localhost:9000`	S3/MinIO 兼容 API 地址。
`STORAGE_PUBLIC_ACCESS_EXTRA_SUB_PATH`	空	公开文件访问路径的额外子路径。
`STORAGE_ACCESS_KEY_ID`	`minioadmin`	对象存储 Access Key。
`STORAGE_SECRET_ACCESS_KEY`	`minioadmin`	对象存储 Secret Key。
`STORAGE_S3_FORCE_PATH_STYLE`	`false`	S3 是否强制 path-style 访问，MinIO 通常需要开启。
`STORAGE_S3_MAX_RETRIES`	`3`	S3 客户端最大重试次数。
`STORAGE_COS_PROTOCOL`	`https:`	腾讯云 COS 访问协议，可选 `https:` 或 `http:`。
`STORAGE_COS_USE_ACCELERATE`	`false`	腾讯云 COS 是否使用全球加速域名。
`STORAGE_COS_CNAME_DOMAIN`	空	腾讯云 COS 自定义 CNAME 域名。
`STORAGE_COS_PROXY`	空	腾讯云 COS 代理地址。
`STORAGE_OSS_ENDPOINT`	空	阿里云 OSS Endpoint。
`STORAGE_OSS_CNAME`	`false`	阿里云 OSS 是否使用 CNAME。
`STORAGE_OSS_INTERNAL`	`false`	阿里云 OSS 是否使用内网 Endpoint。
`STORAGE_OSS_SECURE`	`false`	阿里云 OSS 是否使用 HTTPS。
`STORAGE_OSS_ENABLE_PROXY`	`true`	阿里云 OSS 是否启用代理访问。

日志、指标与追踪

变量	默认值	说明
`LOG_ENABLE_CONSOLE`	`true`	是否输出控制台日志。
`LOG_CONSOLE_LEVEL`	`debug`	控制台日志等级，可选 `trace`、`debug`、`info`、`warning`、`error`、`fatal`。
`LOG_DEPTH`	`3`	历史模板变量，用于日志对象展开深度；当前新版结构化日志主要使用日志等级配置。
`LOG_ENABLE_OTEL`	`false`	是否启用 OpenTelemetry 日志上报。
`LOG_OTEL_LEVEL`	`info`	OTEL 日志等级。
`LOG_OTEL_SERVICE_NAME`	`fastgpt-client`	OTEL 日志服务名。
`LOG_OTEL_URL`	空	OTEL 日志上报地址。
`METRICS_ENABLE_OTEL`	`false`	是否启用 OpenTelemetry 指标上报。
`METRICS_EXPORT_INTERVAL`	`30000`	指标导出间隔，单位毫秒。
`METRICS_OTEL_SERVICE_NAME`	`fastgpt-client`	OTEL 指标服务名。
`METRICS_OTEL_URL`	空	OTEL 指标上报地址。
`TRACING_ENABLE_OTEL`	`false`	是否启用 OpenTelemetry 链路追踪。
`TRACING_OTEL_SERVICE_NAME`	`fastgpt-client`	OTEL 追踪服务名。
`TRACING_OTEL_URL`	空	OTEL 追踪上报地址。
`TRACING_OTEL_SAMPLE_RATIO`	空	追踪采样比例，范围 `0` 到 `1`。
`CHAT_LOG_URL`	空	对话日志推送服务地址；为空时不推送。
`CHAT_LOG_INTERVAL`	空	对话日志批量推送间隔，单位毫秒。
`CHAT_LOG_SOURCE_ID_PREFIX`	`fastgpt-`	对话日志来源 ID 前缀。
`TRACK_BATCH_UPDATE_TIME`	`10000`	事件计数批量写入间隔，单位毫秒。

域名、前端与运行时

变量	默认值	说明
`FE_DOMAIN`	空	FastGPT 前端外部访问地址，用于补全文件、图片等资源路径；不要配置为 `localhost`。
`FILE_DOMAIN`	空	文件访问域名，通常也指向 FastGPT 服务；可独立域名隔离文件风险。
`NEXT_PUBLIC_BASE_URL`	空	Next.js 子路径部署前缀，例如 `/fastgpt`；需要在构建镜像时确定。
`HOSTNAME`	`localhost`	服务本机 Host，用于内部 URL 与 SSRF 本地地址识别；容器中常设为 `0.0.0.0`。
`PORT`	`3000`	Next.js 服务监听端口，也用于本地地址识别。
`NODE_ENV`	空	标准 Node/Next.js 运行环境变量，生产镜像中为 `production`。
`NEXT_TELEMETRY_DISABLED`	`1`	生产镜像中关闭 Next.js Telemetry。
`NODE_OPTIONS`	`--max-old-space-size=4096`	生产镜像构建阶段使用的 Node 启动参数，用于提高构建内存上限。

安全配置

变量	默认值	说明
`USE_IP_LIMIT`	`false`	是否启用部分接口的 IP 限流。
`CHECK_INTERNAL_IP`	`false`	是否启用内网 IP 检查，用于降低 SSRF 风险。
`PASSWORD_LOGIN_LOCK_SECONDS`	`120`	密码登录错误后的锁定时长，单位秒。
`MAX_LOGIN_SESSION`	空	单账号最大登录客户端数量；为空时使用默认逻辑。
`ALLOWED_ORIGINS`	空	允许跨域来源，多个来源使用英文逗号分隔；为空默认允许所有跨域。
`MULTIPLE_DATA_TO_BASE64`	`true`	是否强制将图片转成 base64 传递给模型。
`DISABLE_CACHE`	`false`	是否关闭系统缓存命中，主要用于调试。
`PLUGIN_ACCESS_TOKEN_SECRET`	`plugin_access_token_secret`	插件访问 Token 签名密钥。
`PLUGIN_ACCESS_TOKEN_EXPIRES_IN`	`86400`	插件访问 Token 有效期，单位秒。
`HTTP_PROXY`	空	Node/worker 出站 HTTP 代理。
`HTTPS_PROXY`	空	Node/worker 出站 HTTPS 代理。
`NO_PROXY`	空	不走代理的地址列表。
`ALL_PROXY`	空	通用出站代理。

功能开关与限制

变量	默认值	说明
`SHOW_SKILL`	`false`	是否展示 Skill 功能入口；镜像构建也会读取该变量决定服务入口。
`AGENT_ENGINE`	`default`	Agent 引擎，可选 `default` 或 `pi`。
`HELPER_BOT_MODEL`	空	辅助生成模型，需保证系统中已启用对应模型。
`SKIP_FILE_TYPE_CHECK`	`false`	是否跳过上传文件类型检查。
`WECHAT_CHANNEL_CONCURRENCY`	`1000`	微信渠道 poll worker 并发数，最小 `10`。
`PARSE_FILE_WORKERS`	`10`	文件解析 worker 常驻线程数。
`HTML_TO_MARKDOWN_WORKERS`	`10`	HTML 转 Markdown worker 常驻线程数。
`TEXT_TO_CHUNKS_WORKERS`	`10`	文本切块 worker 常驻线程数。
`PARSE_FILE_TIMEOUT_SECONDS`	`600`	文件解析单任务超时时间，单位秒。
`WORKFLOW_MAX_RUN_TIMES`	`500`	工作流最大运行次数，避免极端死循环。
`WORKFLOW_MAX_LOOP_TIMES`	`100`	循环/并行节点最大输入数组长度。
`WORKFLOW_PARALLEL_MAX_CONCURRENCY`	`10`	并行节点并发上限，且不能超过 `WORKFLOW_MAX_LOOP_TIMES`。
`CHAT_MAX_QPM`	`5000`	聊天 QPM 限制；若用户套餐另有限制，以套餐限制为准。
`SERVICE_REQUEST_MAX_CONTENT_LENGTH`	`10`	服务端接收请求体最大大小，单位 MB。
`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 的最大字符数，超过后不转换。

App 额外变量

以下变量主要由 projects/app 读取。其中部分变量当前定义在 packages/service/env.ts 中做统一校验，但实际消费点仍在 App 层。

变量	默认值	说明
`DEFAULT_ROOT_PSW`	`123456`	初始化 root 用户默认密码。
`SYSTEM_NAME`	`AI`	页面标题默认系统名。
`SYSTEM_DESCRIPTION`	空	页面 Meta 描述，不配置时使用默认国际化文案。
`SYSTEM_FAVICON`	空	页面 favicon 地址，不配置时使用系统配置中的 favicon。
`CONFIG_JSON_PATH`	空	生产环境读取 `config.json` 的目录，默认 `/app/data`。
`CHINESE_IP_REDIRECT_URL`	空	前端配置中的中国 IP 跳转地址。
`PAY_FORM_URL`	空	前端配置中的付费表单地址。
`SHOW_COUPON`	`false`	是否展示兑换码功能。
`SHOW_DISCOUNT_COUPON`	`false`	是否展示优惠券功能。
`HIDE_CHAT_COPYRIGHT_SETTING`	`false`	是否隐藏版权信息配置项。
`APP_REGISTRATION_URL`	空	应用备案申请地址；当前主要作为兼容配置保留。
`PASSWORD_EXPIRED_MONTH`	空	密码过期月份数；为空表示不过期。

Admin 额外变量

以下变量主要由 pro/admin 读取。Admin 同时也会使用上面的 App/Admin 共享变量。

变量	默认值	说明
`EVAL_CONCURRENCY`	`3`	批量评估任务并发数。
`EVAL_LINE_LIMIT`	`1000`	单次创建评估任务允许的最大数据行数，也会下发给前端配置。
`UPDATE_BALANCE_DELAY`	空	历史余额更新频率变量，当前类型中保留。
`BATCH_UPDATE_TIME`	`3000`	钱包余额批量更新间隔，单位毫秒。
`INVOICE_FEISHU_WEBHOOK_URL`	空	发票申请通知飞书 Webhook 地址。
`INVOICE_FEISHU_WEBHOOK_CALLBACK_URL`	空	发票通知中按钮回调地址。
`SMS_PROXY`	空	短信发送代理服务地址。
`MAX_CRAWL_PAGE`	`2000`	网站同步最大抓取页面数。
`CRAWL_DYNAMIC_WEBSITE`	`false`	是否启用动态页面爬虫。
`PLUGIN_URL`	空	动态页面爬虫插件服务地址。
`CRAWL_MAX_HTML_SIZE`	`10`	静态网页爬虫单页 HTML 估算大小上限，单位 MB。
`CRAWL_EXCLUDE_LIST`	空	爬虫排除域名或路径规则，多个值使用英文逗号分隔。
`SHOW_GIT`	空	是否在后台展示 Git 信息；不填写则不展示。
`WARN_FREE_ACCOUNT`	空	免费账号清理前的提醒配置。
`CLEAR_FREE_ACCOUNT`	空	免费账号清理配置。
`SYNC_MEMBER_CRON`	空	成员自动同步 Cron 表达式；为空则不启动同步任务。
`WORKORDER_BASE_URL`	空	工单系统地址；配置后前端展示工单入口。
`WORKORDER_JWT_SECRET`	空	创建工单时签发 JWT 使用的密钥。
`EXTERNAL_USER_SYSTEM_BASE_URL`	空	外部用户系统地址。
`EXTERNAL_USER_SYSTEM_AUTH_TOKEN`	空	外部用户系统认证 Token。
`BAIDU_CONVERSION_TOKEN`	空	百度转化跟踪 Token。
`BAIDU_CONVERSION_BASE_URL`	空	百度转化跟踪接口地址。
`BING_ADS_DEVELOPER_TOKEN`	空	Bing Ads Developer Token。
`BING_ADS_CUSTOMER_ID`	空	Bing Ads Customer ID。
`BING_ADS_CUSTOMER_ACCOUNT_ID`	空	Bing Ads Customer Account ID。
`BING_ADS_CONVERSION_NAME`	`fastgptcn`	Bing Ads 转化目标名称。
`BING_OAUTH_CLIENT_ID`	空	Bing OAuth Client ID。
`BING_OAUTH_CLIENT_SECRET`	空	Bing OAuth Client Secret。
`BING_OAUTH_REFRESH_TOKEN`	空	Bing OAuth Refresh Token。
`SHOW_WECOM_CONFIG`	`false`	是否展示企业微信相关配置。
`WECOM_DEV`	`false`	企业微信支付相关开发模式开关。

Code Sandbox 变量

这些变量由 projects/code-sandbox/src/env.ts 加载和校验。App 调用沙箱时，CODE_SANDBOX_TOKEN 需要与这里的 SANDBOX_TOKEN 保持一致。

变量	默认值	说明
`SANDBOX_PORT`	`3000`	Code Sandbox 服务监听端口。
`SANDBOX_TOKEN`	空	`/sandbox` 接口 Bearer Token；为空时不启用接口认证。仅允许 ASCII 可打印字符且不能包含空格。
`SANDBOX_POOL_SIZE`	`20`	JS/Python 预热 worker 数量，范围 `1` 到 `100`。
`SANDBOX_MAX_TIMEOUT`	`60000`	单次代码执行超时时间，单位毫秒，范围 `1000` 到 `600000`。
`SANDBOX_MAX_MEMORY_MB`	`256`	单个沙箱最大内存，单位 MB，范围 `32` 到 `4096`。
`CHECK_INTERNAL_IP`	`false`	是否在沙箱网络请求中启用内网 IP 检查。
`SANDBOX_REQUEST_MAX_COUNT`	`30`	单次代码执行允许发起的最大网络请求数，范围 `1` 到 `1000`。
`SANDBOX_REQUEST_TIMEOUT`	`60000`	沙箱内单次网络请求超时时间，单位毫秒，范围 `1000` 到 `300000`。
`SANDBOX_REQUEST_MAX_RESPONSE_MB`	`10`	沙箱内单次网络响应体最大大小，单位 MB，范围 `1` 到 `100`。
`SANDBOX_REQUEST_MAX_BODY_MB`	`5`	沙箱内单次网络请求体最大大小，单位 MB，范围 `1` 到 `100`。
`SANDBOX_JS_ALLOWED_MODULES`	`lodash,dayjs,moment,uuid,crypto-js,qs,url,querystring`	JS 代码允许导入的模块白名单，使用英文逗号分隔。
`SANDBOX_PYTHON_ALLOWED_MODULES`	内置常用标准库与 `numpy,pandas,matplotlib`	Python 代码允许导入的模块白名单，使用英文逗号分隔。
`NODE_ENV`	空	标准 Node 环境变量；`development` 下内网地址检查会放宽。
`HOSTNAME`	`localhost`	沙箱服务本机 Host，用于本地地址识别。
`PORT`	`3000`	沙箱本地服务端口识别；实际监听优先使用 `SANDBOX_PORT`。

环境变量说明

本页导航