V4.15.0-beta7 (Environment Changes, Upgrade Script)

📦 Upgrade Guide

1. Open-source config.json Configuration Removed

The config.json configuration file has been removed. All configuration is now provided through environment variables:

# MCP Server proxy endpoint, used on the MCP usage page to build the SSE URL (do not include a trailing /)
SSE_MCP_SERVER_PROXY_ENDPOINT=http://localhost:3003
# ==================== Enhanced PDF Parsing (Optional) ====================
# Custom PDF parsing service endpoint
# 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 retrieval. Only applies to PG / OB / OpenGauss.
HNSW_EF_SEARCH=100
# Maximum scanned rows for vector retrieval. Only applies to PG.
HNSW_MAX_SCAN_TUPLES=100000

#  ==================== Knowledge Base Processing Concurrency Control  ====================
# Maximum concurrency for the Knowledge Base file parsing queue
DATASET_PARSE_MAX_PROCESS=10
# Maximum concurrency for the vector training queue
VECTOR_MAX_PROCESS=10
# Maximum concurrency for the Q&A splitting queue
QA_MAX_PROCESS=10
# Maximum concurrency for the image understanding model processing queue
VLM_MAX_PROCESS=10

2. Commercial Edition: Add the SSE MCP Endpoint

This setting has been removed from admin and must now be added as an environment variable to the fastgpt service:

SSE_MCP_SERVER_PROXY_ENDPOINT=http://localhost:3003

3. OpenSandbox Variable Updates

The OpenSandbox Volume Manager configuration is now required, and the environment variables have been renamed to:

AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL=http://localhost:3005
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN=vmtoken

4. Update Images

See the 4.15.0 stable image tags and update all images to the stable release.

5. Run the Workflow V1 to V2 Migration (Optional)

Only users who have deployed a FastGPT version earlier than <4.8 need to run this step.

Starting from V4.15.0-beta7, workflow save payloads use the V2 structure consistently. Historical apps.modules and app_versions.nodes records may still use the V1 structure. After upgrading, run the V1 -> V2 migration first, then run the V2 dirty-data cleanup in the next step.

Migration script path: projects/app/src/pages/api/admin/dataClean/v1WorkflowToV2.ts. This endpoint is only for this upgrade migration and is not a public OpenAPI endpoint.

The endpoint uses dry-run mode by default. It scans, converts in memory, and validates with PublishAppBodySchema without writing to MongoDB:

curl -X POST 'https://your-domain/api/admin/dataClean/v1WorkflowToV2' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":true}'

After confirming the returned statistics, set dryRun to false to write the converted data:

curl -X POST 'https://your-domain/api/admin/dataClean/v1WorkflowToV2' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":false}'

Request parameters:

Migration behavior:

1. Scans apps where apps.version != 'v2' and type is not folder, httpPlugin, or toolFolder.
2. For each batch of apps, converts and writes related app_versions first, then converts and writes apps, so historical versions will not be missed if the migration is interrupted.
3. Converts V1 node fields to V2 node fields, such as moduleId -> nodeId and flowType -> flowNodeType.
4. Unknown node types fall back to emptyNode, and invalid valueType values are converted to any.
5. Missing node.name falls back to flowType, and missing input.label falls back to input.key.
6. Before writing, the script validates nodes, edges, and chatConfig with PublishAppBodySchema. Documents that fail validation are not written and are included in the endpoint response.

6. Run the Workflow V2 Enum and Structure Cleanup

Some historical workflow nodes may have stored TypeScript enum expression strings directly in MongoDB, for example:

{
  "renderTypeList": ["FlowNodeInputTypeEnum.hidden"],
  "valueType": "WorkflowIOValueTypeEnum.any"
}

The correct stored values are:

{
  "renderTypeList": ["hidden"],
  "valueType": "any"
}

This dirty data can affect workflow node input rendering and IO type checks. After running the V1 -> V2 migration, continue with the V2 cleanup script to scan and fix apps.modules and app_versions.nodes.

The endpoint uses dry-run mode by default. It formats data in memory and validates with PublishAppBodySchema without writing to MongoDB:

curl -X POST 'https://your-domain/api/admin/dataClean/initWorkflowData' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":true,"batchSize":1000,"writeBatchSize":10}'

After confirming the returned statistics, set dryRun to false to write the cleanup:

curl -X POST 'https://your-domain/api/admin/dataClean/initWorkflowData' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":false,"batchSize":1000,"writeBatchSize":10}'

Request parameters:

Cleanup behavior:

1. Scans workflow data in apps and app_versions in batches to reduce read and write pressure.
2. Formats each workflow document once, covering historical dirty fields, null values, enum expressions, and legacy structure compatibility.
3. After formatting, validates the save payload fields nodes, edges, and chatConfig with PublishAppBodySchema.
4. Documents that fail Zod validation are only recorded in the response and are not written to MongoDB.
5. In non-dry-run mode, only documents that changed during formatting and passed Zod validation are written. Unchanged documents are not written again.

The response includes separate statistics for apps, appVersions, and total, including scanned documents, fixable documents, Zod error count, successful writes, failed writes, enum expression statistics, change samples, and error samples.

7. Clean Up Duplicate Chat Headers

Some historical data may contain duplicate chats records with the same appId + chatId, which can prevent the new unique index from being created. After upgrading, run the duplicate chat header cleanup script to keep the record with the latest updateTime. If multiple records have the same updateTime, the record with the largest _id is kept.

Migration script path: projects/app/src/pages/api/admin/dataClean/cleanupDuplicateChats.ts. This endpoint is only for this upgrade migration and is not a public OpenAPI endpoint.

The endpoint uses dry-run mode by default. It scans duplicate groups and returns samples without deleting data:

curl -X POST 'https://your-domain/api/admin/dataClean/cleanupDuplicateChats' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":true,"sampleLimit":20}'

After confirming the returned statistics, set dryRun to false to delete duplicates:

curl -X POST 'https://your-domain/api/admin/dataClean/cleanupDuplicateChats' \
  -H 'Content-Type: application/json' \
  -H 'rootkey: YOUR_ROOT_KEY' \
  -d '{"dryRun":false,"sampleLimit":20}'

Request parameters:

Cleanup behavior:

1. Scans duplicate chat headers in the chats collection by appId + chatId.
2. Keeps the record with the latest updateTime; if timestamps are equal, _id descending order is used as a stable fallback.
3. In non-dry-run mode, deletes only duplicate chats headers. Messages in chatitems and chat_item_responses are not deleted.
4. The response includes duplicate group count, estimated delete count, actual delete count, and duplicate group samples.

🐛 Fixes

1. Fixed historical V1 workflow data that could fail validation under the new save payload structure.
2. Fixed dirty FlowNodeInputTypeEnum.*, FlowNodeOutputTypeEnum.*, and WorkflowIOValueTypeEnum.* expression strings in workflow node configuration that could break input rendering and IO type checks.
3. Fixed AgentV2 MCP not being able to retrieve schemas.
4. Fixed workflow text boxes where pressing Ctrl+C while selecting text could be intercepted by node copy handling, preventing text from being copied.