document/content/self-host/upgrading/4-15/41500.en.mdx
import { Alert } from '@/components/docs/Alert';
v4.15.0 introduces stricter environment variable validation. After upgrading, make sure the following variables are configured correctly.
# Encryption key. Must be the same in both services.
AES256_SECRET_KEY=
# File token key. Must be the same in both services.
FILE_TOKEN_KEY=
# JWT secret for invoke callbacks. Must be at least 32 characters and the same in both services.
INVOKE_TOKEN_SECRET=
Required
# SSE MCP Server address. Leave empty if you do not use SSE.
SSE_MCP_SERVER_PROXY_ENDPOINT=
Optional
The following variables have defaults or can be left unset without affecting normal usage.
# File parsing worker concurrency (optional)
PARSE_FILE_WORKERS=10
# File parsing timeout in seconds (optional)
PARSE_FILE_TIMEOUT_SECONDS=600
# HTML-to-Markdown worker concurrency (optional)
HTML_TO_MARKDOWN_WORKERS=10
# Text chunking worker concurrency (optional)
TEXT_TO_CHUNKS_WORKERS=10
# Automatically sync MongoDB indexes. Use boolean strings instead of 0 or 1. (optional)
SYNC_INDEX=true
# Whether to enable trusted reverse proxy client IP verification (optional)
TRUSTED_PROXY_ENABLE=false
# Trusted reverse proxy IP/CIDR list, separated by commas or whitespace. Only takes effect when TRUSTED_PROXY_ENABLE=true.
# Only X-Forwarded-For/X-Real-IP from explicitly trusted proxies will be used for client IP resolution. (optional)
TRUSTED_PROXY_IPS=
# Maximum string length for synchronous system variable replacement, in M. Range: 1-100.
SYSTEM_MAX_STRING_LENGTH_M=100
# Maximum folder depth. Default: 4. Range: 2-20.
MAX_FOLDER_DEPTH=4
# Maximum input array length for Loop/Parallel nodes
WORKFLOW_MAX_LOOP_TIMES=100
# Parallel node concurrency limit. The final value is clamped to [5, 100].
WORKFLOW_PARALLEL_MAX_CONCURRENCY=10
The open-source edition no longer uses the config.json configuration file. These settings have moved to environment variables. After removing the volume mount, add the following variables as needed:
# Custom PDF parsing service URL
CUSTOM_PDF_PARSE_URL=
# Custom PDF parsing service key
CUSTOM_PDF_PARSE_KEY=
# Doc2x PDF parsing service key
DOC2X_KEY=
# TextIn service App ID
TEXTIN_APP_ID=
# TextIn service Secret Code
TEXTIN_SECRET_CODE=
# hnsw ef_search parameter for vector search. Only applies to PG / OB / OpenGauss.
HNSW_EF_SEARCH=100
# Maximum vector scan tuple count. Only applies to PG.
HNSW_MAX_SCAN_TUPLES=100000
# Maximum Knowledge Base file parsing queue concurrency
DATASET_PARSE_MAX_PROCESS=10
# Maximum vector training queue concurrency
VECTOR_MAX_PROCESS=10
# Maximum Q&A split queue concurrency
QA_MAX_PROCESS=10
# Maximum vision-language model processing queue concurrency
VLM_MAX_PROCESS=10
Code Sandbox adds security-related environment variables such as SANDBOX_API_MAX_BODY_MB and SANDBOX_MAX_OUTPUT_MB, and supports grouped run queueing through queueId. Full defaults:
| Variable | Default | Description |
|---|---|---|
SANDBOX_API_MAX_BODY_MB | 8 | Maximum /sandbox API JSON body size, including variables, in MB. |
SANDBOX_MAX_OUTPUT_MB | 10 | Maximum output JSON size for one code execution, including return values and logs, in MB. |
CHECK_INTERNAL_IP | true | Enables internal IP checks for sandbox network requests by default to reduce SSRF risk. |
SANDBOX_MAX_TIMEOUT | 60000 | Timeout for one code execution, in milliseconds. |
SANDBOX_MAX_MEMORY_MB | 256 | Memory limit for one sandbox, in MB. The runtime reserves an extra 50 MB for overhead. |
SANDBOX_POOL_SIZE | 20 | Number of pre-warmed JS/Python workers. |
SANDBOX_REQUEST_MAX_COUNT | 30 | Maximum number of network requests allowed during one code execution. |
SANDBOX_REQUEST_TIMEOUT | 60000 | Timeout for one network request from inside the sandbox, in milliseconds. |
SANDBOX_REQUEST_MAX_RESPONSE_MB | 10 | Maximum response body size for one sandbox network request, in MB. |
SANDBOX_REQUEST_MAX_BODY_MB | 5 | Maximum request body size for one sandbox network request, in MB. |
SANDBOX_QUEUE_ID_CONCURRENCY | Empty | Number of requests with the same queueId that may enter execution at once. Empty disables queueing. |
The plugin service has been reworked. You must add AUTH_TOKEN and FASTGPT_BASE_URL, and update the MONGODB_URI variable:
AUTH_TOKEN for fastgpt-plugin. It must be at least 32 characters long.PLUGIN_TOKEN in both fastgpt and fastgpt-pro to the same value as fastgpt-plugin's AUTH_TOKEN.fastgpt-plugin's MONGODB_URI so it does not conflict with FastGPT's MongoDB database name. Example: mongodb://myusername:mypassword@fastgpt-mongo:27017/fastgpt-plugin?authSource=admin.Additional variables you may adjust
# ================ System =====================
# Auth token
AUTH_TOKEN=
# Maximum API request body size (MB)
MAX_API_SIZE=10
# FastGPT service URL. It can be an internal address and is used for callbacks to FastGPT APIs.
FASTGPT_BASE_URL=http://fastgpt-app:3000
# ================ Plugin runtime =====================
# Supported value: localPool
PLUGIN_RUNTIME_MODE=localPool
# Temporary file storage directory. Can be empty.
LOCAL_FILE_BASE_PATH=
# ================ Process pool =====================
# Health check interval (ms)
POOL_HEALTH_CHECK_INTERVAL=30000
# Maximum total process count
POOL_MAX_TOTAL_PODS=100
# Minimum process count for one Service
POOL_SERVICE_MIN_PODS=0
# Maximum process count for one Service
POOL_SERVICE_MAX_PODS=5
# Global idle timeout (ms)
POOL_SERVICE_IDLE_TIMEOUT=60000
# Process runtime timeout (ms)
POOL_SERVICE_POD_TIMEOUT=120000
# Maximum concurrent requests per process
POOL_SERVICE_MAX_CONCURRENT_REQUESTS_PER_POD=10
# Global maximum requests per process before automatic rotation
POOL_SERVICE_MAX_REQUESTS_PER_POD=100
# Global maximum process queue length
POOL_SERVICE_MAX_QUEUE_SIZE=500
# Global process queue timeout (ms)
POOL_SERVICE_QUEUE_TIMEOUT=60000
# Startup retry backoff base delay (ms)
POOL_SERVICE_STARTUP_RETRY_BASE_DELAY=1000
# Startup retry backoff maximum delay (ms)
POOL_SERVICE_STARTUP_RETRY_MAX_DELAY=10000
# ================ Database =====================
MONGODB_URI=mongodb://username:password@localhost:27017/fastgpt?authSource=admin&directConnection=true
MONGO_MAX_LINK=20
SYNC_INDEX=true
REDIS_URL=redis://default:password@localhost:6379/0
# ================ Object storage =====================
# S3 file prefix. Do not change it casually after use.
S3_FILE_BASE_PATH=system/plugin
STORAGE_VENDOR=minio
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=http://localhost:9000
STORAGE_S3_ENDPOINT=http://localhost:9000
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_MAX_RETRIES=3
STORAGE_PUBLIC_ACCESS_EXTRA_SUB_PATH=
# ================ Logs =====================
LOG_ENABLE_CONSOLE=true
# Console log level: "trace" | "debug" | "info" | "warning" | "error" | "fatal"
LOG_CONSOLE_LEVEL=info
LOG_ENABLE_OTEL=false
# Minimum log level stored in OTEL
LOG_OTEL_LEVEL=info
LOG_OTEL_SERVICE_NAME=fastgpt-plugin
LOG_OTEL_URL=http://localhost:4318/v1/logs
# ================ Metrics =====================
METRICS_ENABLE_OTEL=false
METRICS_OTEL_SERVICE_NAME=fastgpt-plugin
METRICS_OTEL_URL=http://localhost:4318/v1/metrics
METRICS_EXPORT_INTERVAL_MS=30000
METRICS_EXPORT_TIMEOUT_MS=10000
METRICS_INCLUDE_PLUGIN_VERSION=true
METRICS_INCLUDE_PLUGIN_ETAG=false
METRICS_INCLUDE_HOSTNAME=true
# For multi-node deployments, use Pod UID / container id / instance id. Empty generates an opaque id.
SERVICE_INSTANCE_ID=
DEPLOYMENT_ENVIRONMENT=
OpenSandbox and other sandbox provider settings have moved to Sandbox Configuration and are no longer built into the deployment yml.
For this upgrade, focus on:
agent-sandbox-proxy service.fastgpt-app and fastgpt-pro.If opensandbox is enabled, also update:
Run docker compose up -d to restart services.
After upgrading the plugin service, reinstall all legacy system tools:
fastgpt web app, click Admin in the navbar, click Add Plugin, click Import/Update Plugin, upload the zip package, and confirm.You can also install them one by one from the plugin marketplace: https://v2.marketplace.fastgpt.cn. The environment variable default now points to this address, so no marketplace-related variables are required.
Before running scripts:
fastgpt-app / fastgpt-pro to image versions that include these root-admin APIs.{{host}} and {{rootkey}}. All APIs below require rootkey.The stable release syncs two unique indexes: { appId, chatId } and { sourceType, appId, chatId }. Before the indexes sync successfully, check and clean duplicate appId + chatId records in the chats collection. Otherwise, when SYNC_INDEX=true, index sync may fail with E11000 duplicate key error, and the unique constraint will not take effect.
This API depends on the upgraded fastgpt-app image. If the first stable-release startup already reports a unique index conflict but the service is still reachable, run the dry-run and cleanup commands below, then restart the service so it can sync indexes again.
Run the dry-run first. This does not delete data, and every deployment should run it at least once:
curl -X POST 'https://{{host}}/api/admin/dataClean/cleanupDuplicateChats' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":true,"sampleLimit":20}'
Check these response fields:
duplicateDocumentCount: expected number of duplicate chats headers to delete.samples: duplicate samples, including the retained keepId and candidate deleteIds.deletedDocumentCount: number actually deleted during apply. It is always 0 in dry-run mode.If duplicateDocumentCount=0, no apply step is needed. If it is greater than 0, confirm the samples and then apply the cleanup:
curl -X POST 'https://{{host}}/api/admin/dataClean/cleanupDuplicateChats' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":false,"sampleLimit":20}'
Cleanup policy: for each duplicate appId + chatId group, the API keeps the record with the latest updateTime. If timestamps are equal, it uses _id descending as a stable tie-breaker. The API only deletes duplicate chats headers. It does not delete message content in chatitems or chat_item_responses.
After cleanup, keep SYNC_INDEX=true and restart fastgpt-app / fastgpt-pro so the service can sync indexes again. You can enter MongoDB and confirm both indexes are unique: true:
db.chats
.getIndexes()
.filter((idx) => ['appId_1_chatId_1', 'sourceType_1_appId_1_chatId_1'].includes(idx.name));
Run this only when upgrading directly from a version earlier than <4.8, or when your deployment still contains historical V1 Workflow data. The API defaults to dry-run mode. It scans, converts, and validates the saved structure without writing to the database.
curl -X POST 'https://{{host}}/api/admin/dataClean/v1WorkflowToV2' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":true}'
After confirming the returned statistics, apply the migration:
curl -X POST 'https://{{host}}/api/admin/dataClean/v1WorkflowToV2' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":false}'
Skip this step if you already completed the V1 -> V2 migration in an earlier version, or if you are upgrading from v4.8 or later.
This script scans and fixes historical enum-expression strings, nullish values, and legacy-structure compatibility issues in apps.modules and app_versions.nodes. All self-hosted deployments should run the dry-run first. If the returned statistics show fixable data, apply the write step.
If 6.2 applies to your deployment, run this script after 6.2 completes.
curl -X POST 'https://{{host}}/api/admin/dataClean/initWorkflowData' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":true,"batchSize":1000,"writeBatchSize":10}'
After confirming the dry-run result, apply the cleanup:
curl -X POST 'https://{{host}}/api/admin/dataClean/initWorkflowData' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"dryRun":false,"batchSize":1000,"writeBatchSize":10}'
Lower writeBatchSize if production write pressure is high. Documents that fail Zod validation are reported in the response and are not written back to the database.
If you used legacy sandbox workspaces, this API can fix historical sandbox status fields and optionally archive inactive workspaces to S3. This step does not affect newly generated sandboxes. Skipping it does not block the v4.15 stable upgrade; old workspaces simply will not be archived automatically. You can also delete old sandboxes manually.
Check only, without triggering archive:
curl -X POST 'https://{{host}}/api/admin/dataClean/initSandboxArchive' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"runArchive":false,"inactiveDays":0}'
If you want to immediately archive inactive workspaces that match the condition:
curl -X POST 'https://{{host}}/api/admin/dataClean/initSandboxArchive' \
-H 'Content-Type: application/json' \
-H 'rootkey: {{rootkey}}' \
-d '{"runArchive":true,"inactiveDays":0}'
apikey-appId. Existing API keys remain compatible and continue to work. For details, see the FastGPT API documentation.zod parse error, please submit an issue. It may be caused by legacy data or custom data structures that do not match the declared schema.llm_request_records stores teamId, GET /api/core/ai/record/getRecord queries by { requestId, teamId }, and the unique index changes to { teamId, requestId }. Trace records written before this upgrade do not contain teamId and can no longer be queried; the UI will treat them as expired. Export relevant logs or keep original request details before upgrading if you need to investigate historical calls. If your self-hosted deployment has SYNC_INDEX disabled, run an index sync after upgrading so the old requestId_1 unique index is removed.MAX_FOLDER_DEPTH.defaultConfig.dataId values to prevent invalid data from entering Workflow execution and stream-resume merge logic.MULTIPLE_DATA_TO_BASE64=true.liteparse instead of PDFJs, improving speed by 3x.chat2messages adaptation to avoid standalone reason output.none to avoid errors in some models.defaultConfig override behavior in model configuration.quoteList in nodeResponse did not return q and a.q/a/index when returning nodeResponse; this version restores those fields.runtime structure to a pnpm workspace monorepo, split into HTTP service entry, domain model, use cases, API adapter, infrastructure, SDK, and CLI.@t3-oss/env-core with stronger type checks. Other services also use centralized environment exports.nodeResponse is now stored in a flattened structure to avoid save failures in large nested Workflows.temperature and max_tokens from all built-in LLM requests to avoid incompatibility with some models.FlowNodeInputTypeEnum.*, FlowNodeOutputTypeEnum.*, and WorkflowIOValueTypeEnum.* in Workflow node configuration that caused input rendering and IO type checks to behave incorrectly.Ctrl+C for copying text could be intercepted by node copy behavior, preventing text copy.