# RAGFlow Administrator & Developer Guide

## 1. Architecture Overview

### 1.1 System Architecture

RAGFlow is an open-source Retrieval-Augmented Generation engine built on deep document understanding. The system employs a dual-language architecture that separates concerns across Python and Go runtimes, backed by a React-based frontend and orchestrated through Docker Compose.

The platform ingests documents, parses them with vision-based OCR and layout recognition (DeepDoc), chunks the content intelligently, generates vector embeddings via configurable LLM providers, stores those vectors in a pluggable document engine, and serves retrieval-augmented answers with source citations.

### 1.2 Dual-Language Design

**Python stack** handles document processing, RAG pipeline execution, and the primary API server:

| Process | Entry Point | Framework | Default Port | Purpose |
|---------|------------|-----------|-------------|---------|
| API Server | `api/ragflow_server.py` | Quart | 9380 | Web API, user auth, job management |
| Task Executor | `rag/svr/task_executor.py` | Standalone | N/A | Document parsing workers |
| Data Source Sync | `rag/svr/sync_data_source.py` | Standalone | N/A | Connector synchronization |
| MCP Server | `mcp/server/server.py` | Click + FastMCP | 9382 | Model Context Protocol server |
| Sandbox Executor | `agent/sandbox/executor_manager/main.py` | FastAPI | 9385 | Code sandbox management |
| Admin Endpoints | `admin/server/` | Quart | 9381 | Python admin API |

**Go stack** provides a newer API server, admin server, CLI client, and high-performance tokenization:

| Binary | Entry Point | Framework | Purpose |
|--------|------------|-----------|---------|
| `server_main` | `cmd/server_main.go` | Gin | API server (port configurable via `-p` flag) |
| `admin_server` | `cmd/admin_server.go` | Gin | Admin server with RBAC |
| `ragflow_cli` | `cmd/ragflow_cli.go` | liner (REPL) | CLI client for admin and user operations |

**C++ binding** (`internal/cpp/`): A tokenizer built on DARTS double-array trie, Snowball stemmer, OpenCC (simplified/traditional Chinese conversion), and RE2 regex. Compiled to a static library `librag_tokenizer_c_api.a` and linked into the Go binary via CGO.

> [!IMPORTANT]
> The Go server is a newer addition that runs alongside the Python server. Both share the same MySQL database, Redis cache, MinIO storage, and document engine. The Python server remains the primary runtime for document processing and the task executor pipeline.

### 1.3 Data Flow

```
User uploads document
    │
    ▼
API Server (Python/Quart, port 9380)
    │
    ├── Stores raw file → MinIO (object storage)
    ├── Creates task record → MySQL (metadata DB)
    │
    ▼
Task Executor picks up task
    │
    ├── DeepDoc parses document
    │   ├── OCR (PaddleOCR/ONNX)
    │   ├── Layout recognition (ONNX models)
    │   └── Table structure recognition
    │
    ├── Chunking (naive, QA, resume, table, etc.)
    ├── Embedding via configured LLM provider
    │
    ▼
Document Engine stores vectors + text
    (Elasticsearch | OpenSearch | Infinity | OceanBase)
    │
    ▼
User queries → Retrieval → Reranking → LLM generates answer with citations
```

### 1.4 Infrastructure Services

All backing services run as Docker containers defined in `docker/docker-compose-base.yml`:

| Service | Image | Default Port(s) | Purpose |
|---------|-------|-----------------|---------|
| `es01` | `elasticsearch:${STACK_VERSION}` | 9200 (`ES_PORT`) | Document engine (default) |
| `opensearch01` | `opensearchproject/opensearch:2.19.1` | 9201 (`OS_PORT`) | Alternative doc engine |
| `infinity` | `infiniflow/infinity:v0.7.0-dev5` | 23817, 23820, 5432 | Alternative doc engine |
| `oceanbase` | `oceanbase/oceanbase-ce:4.4.1.0` | 2881 | Alternative doc engine |
| `seekdb` | `oceanbase/seekdb:latest` | 2881 | Alternative doc engine |
| `mysql` | `mysql:8.0.39` | `EXPOSE_MYSQL_PORT` → 3306 | Metadata database |
| `minio` | `pgsty/minio:RELEASE.2026-03-25` | 9000, 9001 | Object storage |
| `redis` | `valkey/valkey:8` | 6379 (`REDIS_PORT`) | Cache (128MB, allkeys-lru) |
| `sandbox-executor-manager` | `infiniflow/sandbox-executor-manager` | 9385 | Code execution sandbox |
| `tei-cpu` / `tei-gpu` | `TEI_IMAGE_CPU` / `TEI_IMAGE_GPU` | 6380 (`TEI_PORT`) | Text embeddings inference |
| `kibana` | `kibana:${STACK_VERSION}` | 5601 | Elasticsearch monitoring |

**Docker Compose profiles** control which services start:

| Profile | Services Activated |
|---------|-------------------|
| `cpu` | RAGFlow in CPU mode |
| `gpu` | RAGFlow in GPU mode |
| `elasticsearch` | Elasticsearch + Kibana |
| `opensearch` | OpenSearch |
| `infinity` | Infinity vector DB |
| `oceanbase` | OceanBase CE |
| `seekdb` | SeekDB |
| `sandbox` | Sandbox executor manager |
| `tei-cpu` | TEI CPU embeddings |
| `tei-gpu` | TEI GPU embeddings |
| `kibana` | Kibana dashboard |

### 1.5 Frontend Architecture

The web UI lives in `web/` and is built with:

- React 18 with TypeScript
- Vite build system
- Tailwind CSS + Ant Design + Radix UI components
- XYFlow for agent canvas visualization
- i18next with 16 locale files for internationalization
- SPA with client-side routing

---

## 2. System Requirements

### 2.1 Hardware Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| CPU | 4 cores | 8+ cores |
| RAM | 16 GB | 32+ GB |
| Disk | 50 GB SSD | 200+ GB SSD |
| GPU | None (CPU mode) | NVIDIA with CUDA (GPU mode) |

> [!NOTE]
> Document parsing with DeepDoc's OCR and layout recognition is CPU-intensive. The task executor's ONNX models benefit significantly from additional CPU cores. GPU mode accelerates embedding generation and OCR processing.

### 2.2 Software Requirements

| Software | Version | Purpose |
|----------|---------|---------|
| Docker | 20.10+ | Container runtime |
| Docker Compose | v2.0+ | Service orchestration |
| Python | 3.11+ | Python stack runtime |
| Go | 1.24+ (module requires 1.25) | Go stack compilation |
| cmake | 4.0+ | C++ tokenizer build |
| g++ | C++17/C++23 support | C++ tokenizer compilation |
| libpcre2-dev | System package | PCRE2 for tokenizer regex |
| Node.js | 18+ | Frontend build |

### 2.3 Build System

The `build.sh` script orchestrates the full build:

1. **C++ static library**: `cmake` + `make` produces `librag_tokenizer_c_api.a`
2. **Go binaries**: `CGO_ENABLED=1` compiles `server_main` and `admin_server`, linking the C++ tokenizer

```bash
# Full build sequence
./build.sh
```

### 2.4 Network Ports

| Port | Service | Protocol | Exposure |
|------|---------|----------|----------|
| 9380 | Python API server | HTTP | Public (via nginx) |
| 9381 | Python admin server | HTTP | Internal |
| 9382 | MCP server | HTTP | Internal/Configurable |
| 9383 | Go admin server | HTTP | Internal |
| 9385 | Sandbox executor | HTTP | Internal |
| 3306 | MySQL | TCP | Internal |
| 9200 | Elasticsearch | HTTP | Internal |
| 9000/9001 | MinIO (API/Console) | HTTP | Internal |
| 6379 | Redis/Valkey | TCP | Internal |
| 80/443 | nginx | HTTP/HTTPS | Public |

---

## 3. Configuration Reference

### 3.1 Configuration Architecture

RAGFlow uses a layered configuration system:

1. **YAML config**: `conf/service_conf.yaml` (primary), overridden by `conf/local.service_conf.yaml` (gitignored)
2. **Environment variables**: Override YAML values; sourced from `.env` for Docker Compose or shell environment
3. **Docker Compose `.env`**: Sets container-level variables (`docker/.env`)
4. **Runtime settings**: Some values configurable via admin API at runtime

The configuration loader (`common/config_utils.py`) reads YAML first, then applies environment variable overrides. Sensitive values are automatically masked in log output.

> [!TIP]
> Create `conf/local.service_conf.yaml` for local overrides that should not be committed. This file takes precedence over `conf/service_conf.yaml` for any keys it defines.

### 3.2 Core Settings (`common/settings.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `DOC_ENGINE` | `elasticsearch` | Document engine backend: `elasticsearch`, `opensearch`, `infinity`, `oceanbase` |
| `STORAGE_IMPL` | `MINIO` | Storage backend for files |
| `DB_TYPE` | `mysql` | Metadata database type |
| `DEVICE` | `cpu` | Compute device: `cpu` or `gpu` |
| `REGISTER_ENABLED` | `1` | Allow new user self-registration (`0` to disable) |
| `DISABLE_PASSWORD_LOGIN` | (unset) | Disable password-based login when set |
| `SANDBOX_ENABLED` | `0` | Enable code sandbox execution |
| `SANDBOX_HOST` | `sandbox-executor-manager` | Sandbox service hostname |
| `DOC_BULK_SIZE` | `4` | Bulk operation batch size for document engine writes |
| `EMBEDDING_BATCH_SIZE` | `16` | Number of chunks per embedding API call |
| `MAX_FILE_NUM_PER_USER` | `0` | Maximum files per user (0 = unlimited) |
| `THREAD_POOL_MAX_WORKERS` | `128` | Global thread pool size |
| `STRONG_TEST_COUNT` | `8` | Strong retrieval test count |
| `RAGFLOW_CRYPTO_ENABLED` | `false` | Enable field-level encryption |
| `RAGFLOW_CRYPTO_ALGORITHM` | `aes-256-cbc` | Encryption algorithm for field encryption |
| `RAGFLOW_CRYPTO_KEY` | (unset) | Encryption key (required when crypto is enabled) |

### 3.3 API Server Settings (`api/apps/__init__.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `QUART_RESPONSE_TIMEOUT` | `600` | Maximum response time in seconds |
| `QUART_BODY_TIMEOUT` | `600` | Maximum request body receive time in seconds |
| `MAX_CONTENT_LENGTH` | (unset) | Maximum upload size in bytes |
| `RAGFLOW_API_TIMING` | (unset) | Enable API endpoint timing headers when set |
| `RAGFLOW_DEBUGPY_LISTEN` | `0` | Enable debugpy remote debugging (port 5678) |

### 3.4 LLM Settings (`rag/llm/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_TIMEOUT_SECONDS` | `600` | Timeout for LLM API calls |
| `LLM_MAX_RETRIES` | `5` | Maximum retry attempts for failed LLM calls |
| `LLM_BASE_DELAY` | `2.0` | Base delay in seconds for exponential backoff |
| `OLLAMA_KEEP_ALIVE` | (unset) | Ollama model keep-alive duration |
| `COMPOSE_PROFILES` | (unset) | Docker Compose profiles to activate |

### 3.5 Task Executor Settings (`rag/svr/task_executor.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `MAX_CONCURRENT_CHUNK_BUILDERS` | `1` | Concurrent chunk builder threads |
| `MAX_CONCURRENT_MINIO` | `10` | Concurrent MinIO upload/download operations |
| `WORKER_HEARTBEAT_TIMEOUT` | `120` | Seconds before a worker is considered dead |
| `RAPTOR_MAX_ERRORS` | `3` | Maximum RAPTOR processing errors before abort |
| `TRACE_MALLOC_ENABLED` | `0` | Enable Python malloc tracing for memory debugging |

### 3.6 Sandbox Settings

**Executor Manager** (`agent/sandbox/executor_manager/core/`):

| Variable | Default | Description |
|----------|---------|-------------|
| `SANDBOX_TIMEOUT` | `10s` | Maximum code execution time |
| `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` | `1` | Pre-warmed container pool size |
| `SANDBOX_MAX_MEMORY` | (unset, compose: `256m`) | Container memory limit |
| `SANDBOX_BASE_PYTHON_IMAGE` | `sandbox-base-python:latest` | Base image for Python sandboxes |
| `SANDBOX_BASE_NODEJS_IMAGE` | `sandbox-base-nodejs:latest` | Base image for Node.js sandboxes |
| `SANDBOX_ENABLE_SECCOMP` | (compose: `false`) | Enable seccomp security profile |
| `SANDBOX_ARTIFACT_BUCKET` | `sandbox-artifacts` | MinIO bucket for sandbox outputs |
| `SANDBOX_ARTIFACT_EXPIRE_DAYS` | `7` | Days before sandbox artifacts are purged |

> [!WARNING]
> The sandbox executor manager container mounts `docker.sock` from the host. This grants it the ability to create and manage sibling containers. In production, restrict access to the sandbox service and consider network policies to limit container escape risk.

### 3.7 MCP Server Settings (`mcp/server/server.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `RAGFLOW_MCP_BASE_URL` | (unset) | Override the RAGFlow backend URL |
| `RAGFLOW_MCP_HOST` | (unset) | Override the bind host |
| `RAGFLOW_MCP_PORT` | (unset) | Override the bind port (default 9382) |
| `RAGFLOW_MCP_LAUNCH_MODE` | (unset) | `self-host` (single tenant) or `host` (multi-tenant) |
| `RAGFLOW_MCP_HOST_API_KEY` | (unset) | API key for self-host mode |

### 3.8 OCR & Vision Settings (`deepdoc/vision/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `LAYOUT_RECOGNIZER_TYPE` | `onnx` | Layout recognition model type |
| `TABLE_STRUCTURE_RECOGNIZER_TYPE` | `onnx` | Table structure model type |
| `TABLE_AUTO_ROTATE` | `true` | Auto-rotate detected tables |
| `OCR_INTRA_OP_NUM_THREADS` | `2` | ONNX intra-operation parallelism |
| `OCR_INTER_OP_NUM_THREADS` | `2` | ONNX inter-operation parallelism |
| `OCR_GPU_MEM_LIMIT_MB` | `2048` | GPU memory limit for OCR in MB |
| `OCR_ARENA_EXTEND_STRATEGY` | `kNextPowerOfTwo` | ONNX memory arena strategy |
| `OCR_GPUMEM_ARENA_SHRINKAGE` | (unset) | GPU memory arena shrinkage policy |
| `TENSORRT_DLA_SVR` | (unset) | TensorRT DLA server address |
| `ASCEND_LAYOUT_RECOGNIZER_DEVICE_ID` | `0` | Huawei Ascend device ID |

### 3.9 GraphRAG Settings (`rag/graphrag/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `MAX_CONCURRENT_PROCESS_AND_EXTRACT_CHUNK` | `10` | Concurrent graph extraction workers |
| `GRAPHRAG_MAX_ERRORS` | `3` | Maximum errors before aborting graph extraction |
| `ENABLE_TIMEOUT_ASSERTION` | (unset) | Enable timeout assertions in community reports |

### 3.10 Agent Settings (`agent/component/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `COMPONENT_EXEC_TIMEOUT` | (unset) | Per-component execution timeout |
| `MAX_CONCURRENT_CHATS` | `10` | Maximum concurrent agent chat sessions |

### 3.11 HTTP Client Settings (`common/http_client.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `HTTP_CLIENT_TIMEOUT` | `15` | Default HTTP client timeout in seconds |
| `HTTP_CLIENT_MAX_RETRIES` | `2` | Maximum retry attempts |
| `HTTP_CLIENT_BACKOFF_FACTOR` | `0.5` | Exponential backoff multiplier |
| `HTTP_CLIENT_MAX_REDIRECTS` | `30` | Maximum redirect follows |
| `HTTP_CLIENT_FOLLOW_REDIRECTS` | `1` | Enable redirect following |
| `HTTP_CLIENT_PROXY` | (unset) | HTTP proxy URL |
| `HTTP_CLIENT_USER_AGENT` | `ragflow-http-client` | User-Agent header value |

### 3.12 Document Parsing Settings

| Variable | Default | Source | Description |
|----------|---------|--------|-------------|
| `DOCLING_SERVER_URL` | (unset) | `deepdoc/parser/docling_parser.py` | External Docling parsing server URL |
| `DOCLING_OUTPUT_DIR` | (unset) | `rag/app/naive.py` | Docling output directory |
| `DOCLING_DELETE_OUTPUT` | `1` | `rag/app/naive.py` | Delete Docling output after processing |
| `PADDLEOCR_API_URL` | (unset) | `deepdoc/parser/paddleocr_parser.py` | PaddleOCR API endpoint |
| `PADDLEOCR_ACCESS_TOKEN` | (unset) | `deepdoc/parser/paddleocr_parser.py` | PaddleOCR authentication token |
| `PADDLEOCR_ALGORITHM` | `PaddleOCR-VL` | `deepdoc/parser/paddleocr_parser.py` | OCR algorithm selection |

### 3.13 Chunk Feedback Settings (`api/db/services/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `CHUNK_FEEDBACK_ENABLED` | `false` | Enable user feedback on retrieved chunks |
| `CHUNK_FEEDBACK_WEIGHTING` | `relevance` | Feedback weighting strategy |
| `PIPELINE_OPERATION_LOG_LIMIT` | `1000` | Maximum pipeline log entries retained |

### 3.14 OceanBase Settings (`common/doc_store/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `OB_DDL_TIMEOUT` | `60` | DDL operation timeout in seconds |
| `OB_QUERY_TIMEOUT` | `100_000_000` | Query timeout in microseconds |
| `OB_POOL_TIMEOUT` | `30` | Connection pool timeout in seconds |
| `OB_MAX_OVERFLOW` | (unset) | Maximum pool overflow connections |
| `ENABLE_HYBRID_SEARCH` | `false` | Enable hybrid (vector + keyword) search |

### 3.15 Infinity Settings (`common/doc_store/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `INFINITY_POOL_MAX_SIZE` | `4` | Connection pool maximum size |

### 3.16 Superuser Settings (`api/db/init_data.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `DEFAULT_SUPERUSER_NICKNAME` | `admin` | Initial admin display name |
| `DEFAULT_SUPERUSER_PASSWORD` | `admin` | Initial admin password |
| `DEFAULT_SUPERUSER_EMAIL` | `[email removed]` | Initial admin email |

> [!CAUTION]
> The default superuser credentials are `[email removed]` / `admin`. Change these immediately after first deployment. Use the `--init-superuser` entrypoint flag or the `reset-password` CLI command to update credentials.

### 3.17 Logging Settings (`common/log_utils.py`)

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVELS` | (unset) | Override log levels per module (format: `module1=DEBUG,module2=WARNING`) |

Log levels can also be adjusted at runtime via the admin API (`PUT /log_levels`).

### 3.18 Data Source Connector Settings (`common/data_source/config.py`)

**Global connector settings:**

| Variable | Default | Description |
|----------|---------|-------------|
| `REQUEST_TIMEOUT_SECONDS` | (unset) | Global connector request timeout |
| `CONTINUE_ON_CONNECTOR_FAILURE` | (unset) | Continue sync when individual items fail |
| `MAX_CONCURRENT_TASKS` | `5` | Concurrent data source sync tasks |
| `HTML_BASED_CONNECTOR_TRANSFORM_LINKS_STRATEGY` | (unset) | Link transformation strategy for HTML connectors |
| `PARSE_WITH_TRAFILATURA` | (unset) | Use Trafilatura for HTML parsing |

**Confluence:**

| Variable | Default | Description |
|----------|---------|-------------|
| `OAUTH_CONFLUENCE_CLOUD_CLIENT_ID` | (unset) | Confluence Cloud OAuth client ID |
| `OAUTH_CONFLUENCE_CLOUD_CLIENT_SECRET` | (unset) | Confluence Cloud OAuth client secret |
| `CONFLUENCE_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD` | (unset) | Maximum attachment size to process |
| `CONFLUENCE_CONNECTOR_ATTACHMENT_CHAR_COUNT_THRESHOLD` | `200000` | Maximum attachment character count |
| `CONFLUENCE_TIMEZONE_OFFSET` | (unset) | Timezone offset for sync timestamps |
| `CONFLUENCE_SYNC_TIME_BUFFER_SECONDS` | (unset) | Buffer time for incremental sync |
| `CONFLUENCE_CONNECTOR_LABELS_TO_SKIP` | (unset) | Comma-separated labels to exclude |
| `CONFLUENCE_CONNECTOR_INDEX_ARCHIVED_PAGES` | (unset) | Include archived pages |
| `CONFLUENCE_CONNECTOR_USER_PROFILES_OVERRIDE` | (unset) | Override user profile behavior |

**Google Drive / Gmail:**

| Variable | Default | Description |
|----------|---------|-------------|
| `OAUTH_GOOGLE_DRIVE_CLIENT_ID` | (unset) | Google Drive OAuth client ID |
| `OAUTH_GOOGLE_DRIVE_CLIENT_SECRET` | (unset) | Google Drive OAuth client secret |
| `GOOGLE_DRIVE_WEB_OAUTH_REDIRECT_URI` | `http://localhost:9380/v1/connector/google-drive/oauth/web/callback` | OAuth redirect URI |
| `GMAIL_WEB_OAUTH_REDIRECT_URI` | `http://localhost:9380/v1/connector/gmail/oauth/web/callback` | Gmail OAuth redirect URI |
| `GOOGLE_DRIVE_SYNC_TIME_BUFFER_SECONDS` | (unset) | Sync time buffer |
| `GOOGLE_DRIVE_CONNECTOR_SIZE_THRESHOLD` | (unset) | Maximum file size to process |
| `GMAIL_TEST_EMAIL` | `[email removed]` | Test email for Gmail connector |

**Jira:**

| Variable | Default | Description |
|----------|---------|-------------|
| `OAUTH_JIRA_CLOUD_CLIENT_ID` | (unset) | Jira Cloud OAuth client ID |
| `OAUTH_JIRA_CLOUD_CLIENT_SECRET` | (unset) | Jira Cloud OAuth client secret |
| `JIRA_CONNECTOR_MAX_TICKET_SIZE` | (unset) | Maximum ticket size to process |
| `JIRA_SYNC_TIME_BUFFER_SECONDS` | (unset) | Sync time buffer |
| `JIRA_TIMEZONE_OFFSET` | (unset) | Timezone offset |
| `JIRA_CONNECTOR_LABELS_TO_SKIP` | (unset) | Labels to exclude |

**Slack:**

| Variable | Default | Description |
|----------|---------|-------------|
| `OAUTH_SLACK_CLIENT_ID` | (unset) | Slack OAuth client ID |
| `OAUTH_SLACK_CLIENT_SECRET` | (unset) | Slack OAuth client secret |
| `SLACK_BOT_TOKEN` | `test-token` | Slack bot token |
| `SLACK_CHANNEL` | (unset) | Default Slack channel |

**Discord:**

| Variable | Default | Description |
|----------|---------|-------------|
| `discord_bot_token` | (unset) | Discord bot token |
| `server_ids` | `None` | Comma-separated Discord server IDs |
| `channel_names` | `None` | Comma-separated channel names to sync |
| `start_date` | `None` | Sync start date |
| `https_proxy` / `http_proxy` | (unset) | Proxy for Discord API |

**Notion:**

| Variable | Default | Description |
|----------|---------|-------------|
| `NOTION_INTEGRATION_TOKEN` | (unset) | Notion integration token |
| `NOTION_ROOT_PAGE_ID` | (unset) | Root page ID for sync scope |
| `NOTION_CONNECTOR_DISABLE_RECURSIVE_PAGE_LOOKUP` | (unset) | Disable recursive page discovery |

**Dropbox:**

| Variable | Default | Description |
|----------|---------|-------------|
| `DROPBOX_ACCESS_TOKEN` | (unset) | Dropbox API access token |

**Box:**

| Variable | Default | Description |
|----------|---------|-------------|
| `BOX_WEB_OAUTH_REDIRECT_URI` | `http://localhost:9380/v1/connector/box/oauth/web/callback` | Box OAuth redirect URI |

**GitHub / Bitbucket:**

| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_CONNECTOR_BASE_URL` | (unset) | GitHub Enterprise base URL |

**Airtable:**

| Variable | Default | Description |
|----------|---------|-------------|
| `AIRTABLE_ACCESS_TOKEN` | (unset) | Airtable personal access token |
| `AIRTABLE_CONNECTOR_SIZE_THRESHOLD` | (unset) | Maximum record size |

**Asana:**

| Variable | Default | Description |
|----------|---------|-------------|
| `ASANA_CONNECTOR_SIZE_THRESHOLD` | (unset) | Maximum task size |

**IMAP (Email):**

| Variable | Default | Description |
|----------|---------|-------------|
| `IMAP_HOST` | (unset) | IMAP server hostname |
| `IMAP_PORT` | `993` | IMAP server port |
| `IMAP_USERNAME` | (unset) | IMAP login username |
| `IMAP_PASSWORD` | (unset) | IMAP login password |
| `IMAP_MAILBOXES` | `INBOX` | Comma-separated mailbox names |
| `IMAP_CONNECTOR_SIZE_THRESHOLD` | (unset) | Maximum email size |

**WebDAV:**

| Variable | Default | Description |
|----------|---------|-------------|
| `WEBDAV_USERNAME` | (unset) | WebDAV username |
| `WEBDAV_PASSWORD` | (unset) | WebDAV password |

**RDBMS:**

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_USERNAME` | `root` | Database username |
| `DB_PASSWORD` | (unset) | Database password |
| `DB_HOST` | `localhost` | Database host |
| `DB_PORT` | `3306` | Database port |
| `DB_NAME` | `test` | Database name |

**DingTalk:**

| Variable | Default | Description |
|----------|---------|-------------|
| `DINGTALK_ACCESS_TOKEN` | (unset) | DingTalk access token |
| `DINGTALK_OPERATOR_ID` | (unset) | DingTalk operator ID |
| `DINGTALK_AI_TABLE_BASE_ID` | (unset) | AI table base ID |

**Zendesk:**

| Variable | Default | Description |
|----------|---------|-------------|
| `ZENDESK_CONNECTOR_SKIP_ARTICLE_LABELS` | (unset) | Labels to skip during sync |

**Web Connector:**

| Variable | Default | Description |
|----------|---------|-------------|
| `WEB_CONNECTOR_IGNORED_CLASSES` | `sidebar,footer` | CSS classes to ignore during crawling |
| `WEB_CONNECTOR_IGNORED_ELEMENTS` | `nav,footer,meta,script,style,symbol,aside` | HTML elements to strip |

**Firecrawl:**

| Variable | Default | Description |
|----------|---------|-------------|
| `FIRECRAWL_API_KEY` | (unset) | Firecrawl API key |
| `FIRECRAWL_API_URL` | `https://api.firecrawl.dev` | Firecrawl API endpoint |
| `FIRECRAWL_MAX_RETRIES` | `3` | Maximum retry attempts |
| `FIRECRAWL_TIMEOUT` | `30` | Request timeout in seconds |
| `FIRECRAWL_RATE_LIMIT_DELAY` | `1.0` | Delay between requests |
| `FIRECRAWL_MAX_CONCURRENT` | `5` | Maximum concurrent requests |

### 3.19 Azure Storage Settings (`rag/utils/`)

| Variable | Default | Description |
|----------|---------|-------------|
| `CONTAINER_URL` | (unset) | Azure Blob SAS container URL |
| `SAS_TOKEN` | (unset) | Azure SAS token |
| `ACCOUNT_URL` | (unset) | Azure SPN account URL |
| `CLIENT_ID` | (unset) | Azure SPN client ID |
| `SECRET` | (unset) | Azure SPN client secret |
| `TENANT_ID` | (unset) | Azure tenant ID |
| `CONTAINER_NAME` | (unset) | Azure container name |
| `AZURE_CLOUD` | (unset) | Azure cloud environment |

### 3.20 Miscellaneous Settings

| Variable | Default | Source | Description |
|----------|---------|--------|-------------|
| `RAG_PROJECT_BASE` | (unset) | `common/file_utils.py` | Project base directory override |
| `RAG_DEPLOY_BASE` | (unset) | `common/file_utils.py` | Deployment base directory override |
| `RAGFLOW_CONF_DIR` | (unset) | `internal/utility/path.go` | Configuration directory (Go stack) |
| `DISABLE_SDK` | (unset) | `api/utils/api_utils.py` | Disable SDK API endpoints |
| `TEI_MODEL` | (unset) | `api/apps/llm_app.py` | TEI model name |
| `MACOS` | (unset) | `api/db/services/task_service.py` | macOS compatibility mode |
| `STEPFUN_TTS_VOICE` | (unset) | `rag/llm/tts_model.py` | StepFun TTS voice selection |
| `TRINO_USE_TLS` | `0` | `api/apps/canvas_app.py` | Enable TLS for Trino connections |
| `TCADP_OUTPUT_DIR` | (unset) | `rag/app/naive.py` | TCADP output directory |
| `BUCKET_TYPE` | (unset) | `common/data_source/blob_connector.py` | Cloud storage bucket type |
| `BUCKET_NAME` | (unset) | `common/data_source/blob_connector.py` | Cloud storage bucket name |
| `AWS_ACCESS_KEY_ID` | (unset) | `common/data_source/blob_connector.py` | AWS access key |
| `AWS_SECRET_ACCESS_KEY` | (unset) | `common/data_source/blob_connector.py` | AWS secret key |
| `MINIO_IP` | (unset) | `internal/server/config.go` | MinIO host (Go stack override) |
| `MINIO_PORT` | (unset) | `internal/server/config.go` | MinIO port (Go stack override) |
| `MINIO_REGION` | (unset) | `internal/server/config.go` | MinIO region (Go stack override) |
| `LANGUAGE` | (unset) | `internal/server/config.go` | System language (Go stack) |

### 3.21 YAML Configuration (`conf/service_conf.yaml`)

The primary YAML configuration file contains structured settings for all backing services. Key sections:

```yaml
# Database
mysql:
  host: mysql
  port: 3306
  user: root
  password: ...
  database: ragflow

# Redis
redis:
  host: redis
  port: 6379
  password: ...

# MinIO
minio:
  host: minio:9000
  access_key: ...
  secret_key: ...

# Elasticsearch
es:
  host: es01:9200
  scheme: http

# Storage
storage:
  type: MINIO
```

Local overrides go in `conf/local.service_conf.yaml`. The Go stack reads the same YAML via `internal/server/config.go`.

---

## 4. Deployment & Scaling

### 4.1 Docker Compose Deployment

The standard deployment uses Docker Compose with profile selection:

```bash
# Default deployment with Elasticsearch (CPU mode)
docker compose --profile cpu --profile elasticsearch up -d

# GPU mode with OpenSearch
docker compose --profile gpu --profile opensearch up -d

# With Infinity vector database
docker compose --profile cpu --profile infinity up -d

# With OceanBase
docker compose --profile cpu --profile oceanbase up -d

# Enable sandbox for agent code execution
docker compose --profile cpu --profile elasticsearch --profile sandbox up -d

# Enable TEI for local embeddings
docker compose --profile cpu --profile elasticsearch --profile tei-cpu up -d
```

### 4.2 Entrypoint Configuration

The Docker entrypoint (`docker/entrypoint.sh`) starts nginx + ragflow_server (Python) + task executors + data source sync. Control startup behavior with flags:

| Flag | Description |
|------|-------------|
| `--disable-webserver` | Skip starting the Python API server |
| `--disable-taskexecutor` | Skip starting task executor workers |
| `--disable-datasync` | Skip starting data source synchronization |
| `--enable-mcpserver` | Start the MCP server (port 9382) |
| `--enable-adminserver` | Start the Go admin server |
| `--init-superuser` | Initialize the superuser account on startup |
| `--workers=<num>` | Number of task executor workers (default: 1) |
| `--consumer-no-beg=<n>` | Range-based worker ID start |
| `--consumer-no-end=<n>` | Range-based worker ID end |
| `--host-id=<string>` | Worker host identifier (defaults to hostname, truncated to 32 chars or MD5-hashed if longer) |

```bash
# Example: Run with 4 task executors, MCP server enabled, admin server enabled
docker run ... ragflow --workers=4 --enable-mcpserver --enable-adminserver
```

### 4.3 Scaling Task Executors

Task executors are the document processing workers. Scale them based on document processing load:

```bash
# Run 4 workers in a single container
docker compose up -d  # with --workers=4 in the entrypoint command

# Or run separate worker containers with range-based IDs
# Container 1: workers 0-3
docker run ... ragflow --disable-webserver --consumer-no-beg=0 --consumer-no-end=3

# Container 2: workers 4-7
docker run ... ragflow --disable-webserver --consumer-no-beg=4 --consumer-no-end=7
```

> [!TIP]
> Separate the API server from task executors in production. Run one container with `--disable-taskexecutor` for the API and dedicated containers with `--disable-webserver` for workers. This isolates document processing load from API responsiveness.

### 4.4 Kubernetes Deployment (Helm)

RAGFlow provides a Helm chart in `helm/` with 13 templates:

```bash
# Install with default values
helm install ragflow ./helm

# Install with custom values
helm install ragflow ./helm -f custom-values.yaml

# Upgrade
helm upgrade ragflow ./helm -f custom-values.yaml
```

The Helm chart includes templates for:

| Template | Purpose |
|----------|---------|
| `deployment.yaml` | RAGFlow application deployment |
| `service.yaml` | Kubernetes service exposure |
| `configmap.yaml` | Configuration injection |
| `secret.yaml` | Sensitive value management |
| `ingress.yaml` | HTTP routing rules |
| `hpa.yaml` | Horizontal Pod Autoscaler |
| `pvc.yaml` | Persistent volume claims |
| `serviceaccount.yaml` | RBAC service account |
| `networkpolicy.yaml` | Network access control |
| `_helpers.tpl` | Template helper functions |
| `NOTES.txt` | Post-install instructions |
| `tests/` | Helm test pod |
| `values.yaml` | Default configuration values |

Key `values.yaml` sections cover replica counts, resource limits, image tags, persistence, ingress rules, and all backing service connection strings.

### 4.5 Document Engine Selection

Choose the document engine based on your scale and requirements:

| Engine | Best For | Hybrid Search | Scaling |
|--------|----------|---------------|---------|
| **Elasticsearch** | General use, mature ecosystem | Built-in | Cluster-native |
| **OpenSearch** | AWS environments, open governance | Built-in | Cluster-native |
| **Infinity** | High-performance vector search | Supported | Developing |
| **OceanBase** | Existing OceanBase deployments | Via `ENABLE_HYBRID_SEARCH` | Distributed |

Switch engines by setting `DOC_ENGINE` in `.env` and activating the corresponding Docker Compose profile.

### 4.6 nginx Configuration

The bundled nginx (`docker/nginx/`) serves as a reverse proxy:

- Routes `/v1/` API requests to the Python API server (port 9380)
- Serves the React frontend static files
- Handles WebSocket upgrades for SSE streaming
- Applies upload size limits and proxy timeouts

---

## 5. Operations

### 5.1 Superuser Management

**Initialize superuser on first boot:**

```bash
docker exec -it ragflow python api/ragflow_server.py --init-superuser
```

**Reset password via CLI:**

```bash
# Using the built-in management command
python -m api.utils.commands reset-password \
  --email [email removed] \
  --new-password NEW_PASSWORD \
  --password-confirm NEW_PASSWORD
```

**Reset email:**

```bash
python -m api.utils.commands reset-email \
  --email [email removed] \
  --new-email [email removed] \
  --email-confirm [email removed]
```

### 5.2 RAGFlow CLI

The Go-based CLI (`ragflow_cli`) provides an interactive REPL and single-command execution:

```bash
# Interactive admin mode
./ragflow_cli -h 127.0.0.1 -p 9381 --admin

# Interactive user mode with config file
./ragflow_cli -f rf.yml

# Single command execution
./ragflow_cli -h 127.0.0.1 -p 9381 --admin -w admin "list users"
```

**CLI arguments:**

| Flag | Default | Description |
|------|---------|-------------|
| `-h`, `--host` | `127.0.0.1` | Admin or RAGFlow service host |
| `-p`, `--port` | `9381` | Service port |
| `-w`, `--password` | `admin` | Superuser password |
| `-t`, `--type` | `admin` | CLI mode: `admin` or `user` |
| `-u`, `--username` | (auto) | Username (email). Defaults to `[email removed]` in admin mode |
| `-f`, `--config` | (unset) | Config file path (reads `rf.yml` from CWD by default) |
| `-o`, `--output` | `table` | Output format: `table`, `plain`, `json` |
| `--admin` | false | Admin mode flag |

**CLI config file** (`rf.yml`):

```yaml
host: "127.0.0.1:9380"
api_token: "ragflow-xxxxxxxxxxxx"
user_name: "[email removed]"
password: "password"
```

### 5.3 Health Checks

| Endpoint | Server | Purpose |
|----------|--------|---------|
| `GET /health` | Go API | Basic health check |
| `GET /v1/system/ping` | Go API | Ping check |
| `GET /v1/system/config` | Go API | Configuration status |
| `GET /api/v1/system/status` | Python API | Full system status including backing services |
| `GET /api/v1/system/oceanbase/status` | Python API | OceanBase-specific health |
| `GET /health` | Go Admin | Admin server health |
| `GET /ping` | Go Admin / Python Admin | Admin ping |

### 5.4 Backup and Recovery

**MySQL metadata:**

```bash
# Backup
docker exec mysql mysqldump -u root -p ragflow > ragflow_backup.sql

# Restore
docker exec -i mysql mysql -u root -p ragflow < ragflow_backup.sql
```

**MinIO object storage:**

```bash
# Use mc (MinIO client) for backup
mc mirror minio/ragflow /backup/minio-ragflow/
```

**Elasticsearch indices:**

```bash
# Create snapshot repository
curl -X PUT "localhost:9200/_snapshot/backup" -H 'Content-Type: application/json' -d '{
  "type": "fs",
  "settings": { "location": "/usr/share/elasticsearch/backup" }
}'

# Create snapshot
curl -X PUT "localhost:9200/_snapshot/backup/snapshot_1"
```

### 5.5 Log Management

RAGFlow logs are written to stdout/stderr by default (Docker-captured). Key log sources:

| Component | Log Source | Configuration |
|-----------|-----------|---------------|
| Python API | `api/ragflow_server.py` | `LOG_LEVELS` env var |
| Task Executor | `rag/svr/task_executor.py` | `LOG_LEVELS` env var |
| Go Server | `internal/logger/` | `PUT /log_level` admin API |
| nginx | `/var/log/nginx/` | Docker log driver |

**Runtime log level adjustment:**

```bash
# Get current log levels (admin API)
curl -X GET http://localhost:9381/log_levels

# Set log level
curl -X PUT http://localhost:9381/log_levels \
  -H 'Content-Type: application/json' \
  -d '{"logger": "root", "level": "DEBUG"}'
```

### 5.6 Monitoring with Kibana

Enable the Kibana profile for Elasticsearch monitoring:

```bash
docker compose --profile elasticsearch --profile kibana up -d
```

Access Kibana at `http://localhost:5601`. Use it to monitor index health, shard allocation, query performance, and document counts.

---

## 6. Performance

### 6.1 Task Executor Tuning

| Parameter | Impact | Recommendation |
|-----------|--------|----------------|
| `--workers` | Parallel document processing | Set to CPU cores / 2 for CPU-bound OCR workloads |
| `MAX_CONCURRENT_CHUNK_BUILDERS` | Concurrent chunking threads | Increase to 2-4 for large documents |
| `MAX_CONCURRENT_MINIO` | Storage I/O parallelism | Default 10 is sufficient; increase for high-throughput storage |
| `EMBEDDING_BATCH_SIZE` | Chunks per embedding API call | Increase for faster LLM APIs; decrease to avoid timeouts |
| `DOC_BULK_SIZE` | Document engine write batch size | Match to ES `bulk` thread pool for optimal throughput |

### 6.2 OCR Optimization

| Parameter | Impact | Recommendation |
|-----------|--------|----------------|
| `OCR_INTRA_OP_NUM_THREADS` | Per-operation parallelism | Set to physical core count |
| `OCR_INTER_OP_NUM_THREADS` | Cross-operation parallelism | Set to 1-2 for most workloads |
| `OCR_GPU_MEM_LIMIT_MB` | GPU memory allocation | Increase for batch OCR on GPU |
| `LAYOUT_RECOGNIZER_TYPE` | Model runtime | `onnx` for CPU, consider TensorRT for GPU |

### 6.3 Elasticsearch Tuning

For production Elasticsearch deployments:

```yaml
# docker-compose override
es01:
  environment:
    - "ES_JAVA_OPTS=-Xms4g -Xmx4g"
    - "discovery.type=single-node"
    - "xpack.security.enabled=false"
  ulimits:
    memlock:
      soft: -1
      hard: -1
```

Key index settings to consider:
- Increase `number_of_replicas` for read scaling
- Adjust `refresh_interval` for write-heavy workloads (e.g., during bulk ingestion, set to `30s`)
- Configure `merge.scheduler.max_thread_count` based on available I/O

### 6.4 Redis Cache Strategy

Redis is configured with `maxmemory 128mb` and `allkeys-lru` eviction. For larger deployments:

- Increase `maxmemory` proportionally with active user count
- Monitor eviction rates via `INFO stats`
- Consider Redis Cluster for horizontal scaling

### 6.5 Thread Pool Configuration

The global thread pool (`THREAD_POOL_MAX_WORKERS=128`) handles async operations across the Python stack. Adjust based on:

- Number of concurrent API requests
- Task executor parallelism
- Data source sync concurrency

### 6.6 LLM Call Optimization

| Parameter | Tuning Guidance |
|-----------|----------------|
| `LLM_TIMEOUT_SECONDS=600` | Reduce for fast models; increase for large context windows |
| `LLM_MAX_RETRIES=5` | Reduce for interactive use cases; keep high for batch processing |
| `LLM_BASE_DELAY=2.0` | Exponential backoff base; increase if hitting provider rate limits |

---

## 7. Security

### 7.1 Authentication Architecture

RAGFlow supports multiple authentication methods:

| Method | Configuration | Use Case |
|--------|--------------|----------|
| Email/Password | Built-in (default) | Standard user accounts |
| GitHub OAuth | `github_config` in auth settings | Developer-focused deployments |
| Feishu OAuth | `feishu_config` in auth settings | Chinese enterprise environments |
| OIDC | `oidc_config` with issuer discovery | Enterprise SSO (Okta, Azure AD, etc.) |
| OAuth2 | `oauth2_config` with manual URLs | Custom identity providers |
| API Tokens | Per-user generated tokens | Programmatic access |

**OAuth2/OIDC configuration structure:**

```python
# OIDC (auto-discovery)
{
    "type": "oidc",
    "issuer": "https://your-idp.com/oidc",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://your-ragflow.com/v1/user/oauth/callback/<channel>"
}

# OAuth2 (manual endpoints)
{
    "type": "oauth2",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "authorization_url": "https://your-idp.com/oauth/authorize",
    "token_url": "https://your-idp.com/oauth/token",
    "userinfo_url": "https://your-idp.com/oauth/userinfo",
    "redirect_uri": "https://your-ragflow.com/v1/user/oauth/callback/<channel>"
}
```

> [!WARNING]
> The OIDC implementation has a known community-reported issue (#14066). Test OIDC flows thoroughly after configuration changes, particularly around token validation and callback handling.

### 7.2 Admin Authentication

The admin server uses JWT-based session management:

1. Login via `POST /login` with admin credentials
2. Receive JWT token
3. Include token in subsequent requests

Default credentials: `[email removed]` / `admin`. The admin API provides RBAC with:
- Role creation and management (`/roles`)
- Permission assignment (`/roles/:role_name/permission`)
- User-role binding (`/users/:username/role`)

### 7.3 Field Encryption

Enable field-level encryption for sensitive data at rest:

```bash
RAGFLOW_CRYPTO_ENABLED=true
RAGFLOW_CRYPTO_ALGORITHM=aes-256-cbc
RAGFLOW_CRYPTO_KEY=your-32-byte-base64-key
```

When enabled, designated database fields are encrypted before storage and decrypted on read.

### 7.4 Network Security

**CORS**: The Python API server sets `Access-Control-Allow-Origin: *` by default (`common/connection_utils.py`). For production, restrict this to your frontend domain.

**MySQL TLS**: MySQL is configured to require TLS 1.2/1.3 with custom authentication plugin.

**Redis**: Password-protected via `service_conf.yaml`. Uses `maxmemory` with `allkeys-lru` to prevent OOM.

> [!CAUTION]
> The default CORS configuration (`Access-Control-Allow-Origin: *`) allows any origin to make authenticated API requests. In production deployments, restrict CORS to your specific frontend domain(s).

### 7.5 Sandbox Security

The sandbox executor provides isolated code execution for agent components:

| Control | Implementation |
|---------|---------------|
| Container isolation | Each execution runs in a fresh Docker container |
| Memory limits | `SANDBOX_MAX_MEMORY` (default 256MB in compose) |
| Execution timeout | `SANDBOX_TIMEOUT` (default 10s) |
| Seccomp profile | Optional via `SANDBOX_ENABLE_SECCOMP` |
| Rate limiting | slowapi on the executor manager API |
| Artifact lifecycle | Auto-purge after `SANDBOX_ARTIFACT_EXPIRE_DAYS` |

**Sandbox providers:**
- **Self-managed**: Docker-based, runs on the same host. Requires `docker.sock` mount.
- **Aliyun OpenSandbox**: Cloud-based alternative. Requires `ALIYUN_ACCESS_KEY_ID` and `ALIYUN_ACCESS_KEY_SECRET`.

### 7.6 API Token Management

API tokens are managed per-user via the admin API:

```bash
# Generate API key for a user
POST /admin/users/:username/keys

# List user's API keys
GET /admin/users/:username/keys

# Revoke a specific key
DELETE /admin/users/:username/keys/:token
```

### 7.7 Password Security

Passwords are encrypted client-side using RSA before transmission. The server validates password complexity via `STRONG_TEST_COUNT` (default 8).

### 7.8 Registration Control

| Variable | Value | Effect |
|----------|-------|--------|
| `REGISTER_ENABLED` | `1` (default) | Allow self-registration |
| `REGISTER_ENABLED` | `0` | Disable self-registration (admin creates accounts) |
| `DISABLE_PASSWORD_LOGIN` | (set) | Disable password login (OAuth only) |

---

## 8. Developer Internals

### 8.1 Module Reference

#### 8.1.1 Root Level (8 files, 23K chars)

Top-level scripts including `build.sh`, `run_tests.py`, `download_deps.py`, and `pyproject.toml`. The build script orchestrates C++ compilation and Go binary builds.

#### 8.1.2 `api/` — Python API Server (5 files, 9K chars)

| File | Purpose |
|------|---------|
| `ragflow_server.py` | Quart application entry point, server startup, debugpy support |
| `__init__.py` | Package initialization |

#### 8.1.3 `api/apps/` — API Route Handlers (17 files, 292K chars)

| Module | Endpoints | Purpose |
|--------|-----------|---------|
| `canvas_app.py` | 26 endpoints | Agent canvas CRUD, completion, sessions, versioning, debug |
| `chunk_app.py` | 7 endpoints | Chunk CRUD, retrieval testing, knowledge graph |
| `connector_app.py` | 13 endpoints | Connector CRUD, OAuth flows (Google, Gmail, Box) |
| `document_app.py` | 19 endpoints | Document upload, parsing, web crawl, metadata, thumbnails |
| `evaluation_app.py` | 13 endpoints | Evaluation datasets, test cases, runs, comparison |
| `file2document_app.py` | 2 endpoints | File-to-document conversion |
| `kb_app.py` | 16 endpoints | Knowledge base CRUD, tags, pipeline logs, mindmaps |
| `langfuse_app.py` | 3 endpoints | Langfuse API key management |
| `llm_app.py` | 7 endpoints | LLM factory listing, API key management, model CRUD |
| `mcp_server_app.py` | 8 endpoints | MCP server CRUD, tool listing/testing, import/export |
| `plugin_app.py` | 1 endpoint | LLM tools listing |
| `system_app.py` | 3 endpoints | System status, OceanBase status, config |
| `tenant_app.py` | 5 endpoints | Tenant user management, agreement |
| `user_app.py` | 18 endpoints | Auth (login, register, OAuth), profile, password reset |

#### 8.1.4 `api/apps/services/` — Business Logic Services (5 files, 70K chars)

Service layer between route handlers and database operations.

#### 8.1.5 `api/db/` — Database Layer (7 files, 104K chars)

| File | Purpose |
|------|---------|
| `db_models.py` | SQLAlchemy/Peewee ORM model definitions |
| `init_data.py` | Database initialization, superuser creation, LLM factory seeding |
| `db_utils.py` | Database connection management, migration |

#### 8.1.6 `api/db/services/` — Database Services (25 files, 420K chars)

The largest module group by character count. Contains the core business logic for:

| Service | Purpose |
|---------|---------|
| `canvas_service.py` | Agent canvas persistence, version management |
| `chunk_feedback_service.py` | Chunk relevance feedback tracking |
| `connector_service.py` | Data source connector management |
| `document_service.py` | Document lifecycle management |
| `evaluation_service.py` | Evaluation run orchestration |
| `kb_service.py` | Knowledge base management |
| `langfuse_service.py` | Langfuse integration |
| `llm_service.py` | LLM provider management |
| `mcp_server_service.py` | MCP server configuration |
| `pipeline_operation_log_service.py` | Pipeline execution logging |
| `task_service.py` | Task queue management |
| `tenant_service.py` | Multi-tenant operations |
| `user_service.py` | User account operations |

#### 8.1.7 `api/utils/` — API Utilities (17 files, 117K chars)

| File | Purpose |
|------|---------|
| `api_utils.py` | Response helpers, authentication decorators, SDK gate |
| `commands.py` | CLI commands (reset-password, reset-email) |
| `web_utils.py` | Headless Chrome integration for web crawling |

#### 8.1.8 `api/common/` — API Common (3 files, 4K chars)

Shared constants, error codes, and utility functions for the API layer.

#### 8.1.9 `rag/` — RAG Pipeline Core (4 files, 25K chars)

| File | Purpose |
|------|---------|
| `__init__.py` | RAG package initialization |
| `benchmark.py` | Retrieval benchmarking (MS MARCO, TriviaQA, MIRACL) |

#### 8.1.10 `rag/app/` — Document Parsers (15 files, 275K chars)

| Parser | Purpose |
|--------|---------|
| `naive.py` | Default chunking strategy with configurable chunk size |
| `resume.py` | Resume/CV parsing with structured extraction |
| `table.py` | Table-aware document parsing |
| `qa.py` | Question-answer pair extraction |
| `paper.py` | Academic paper parsing |
| `book.py` | Book/chapter parsing |
| `laws.py` | Legal document parsing |
| `presentation.py` | PowerPoint/slide parsing |
| `picture.py` | Image description via vision models |
| `audio.py` | Audio transcription |
| `email_app.py` | Email message parsing |
| `knowledge_graph.py` | Knowledge graph extraction |
| `manual.py` | Technical manual parsing |
| `one.py` | Single-chunk mode |
| `tag.py` | Tag-based parsing |

#### 8.1.11 `rag/llm/` — LLM Integration (8 files, 235K chars)

| Module | Purpose |
|--------|---------|
| `chat_model.py` | Chat/completion models (OpenAI, Anthropic, Google, etc.) |
| `embedding_model.py` | Text embedding models |
| `cv_model.py` | Computer vision models (image understanding) |
| `rerank_model.py` | Reranking models |
| `tts_model.py` | Text-to-speech models |
| `sequence2txt_model.py` | Audio-to-text models |
| `ocr_model.py` | OCR model integration |

#### 8.1.12 `rag/svr/` — Server Processes (4 files, 125K chars)

| File | Purpose |
|------|---------|
| `task_executor.py` | Document processing worker with heartbeat, task claiming, and execution |
| `sync_data_source.py` | Data source synchronization with concurrent task support |

#### 8.1.13 `rag/nlp/` — NLP Utilities (7 files, 112K chars)

Tokenization, query parsing, language detection, and text normalization.

#### 8.1.14 `rag/graphrag/` — Graph RAG (5 + 11 files, 66K + 95K chars)

| Submodule | Files | Purpose |
|-----------|-------|---------|
| `rag/graphrag/` | 5 files | Base GraphRAG classes, entity/relationship models |
| `rag/graphrag/general/` | 11 files | Full GraphRAG implementation: extraction, community detection, reports |

#### 8.1.15 `rag/utils/` — RAG Utilities (20 files, 251K chars)

| File | Purpose |
|------|---------|
| `es_conn.py` | Elasticsearch connection and operations |
| `ob_conn.py` | OceanBase connection |
| `infinity_conn.py` | Infinity connection |
| `opensearch_conn.py` | OpenSearch connection |
| `redis_conn.py` | Redis cache operations |
| `minio_conn.py` | MinIO storage operations |
| `azure_sas_conn.py` | Azure Blob (SAS) storage |
| `azure_spn_conn.py` | Azure Blob (SPN) storage |

#### 8.1.16 `rag/prompts/` — Prompt Templates (3 files, 38K chars)

System prompts for RAG, GraphRAG, and agent components.

#### 8.1.17 `rag/advanced_rag/` — Advanced RAG (2 files, 6.5K chars)

Advanced retrieval strategies and RAPTOR hierarchical summarization.

#### 8.1.18 `rag/flow/` — Flow Engine (4 files, 13K chars)

Data flow pipeline definitions, chunker abstractions, and parser orchestration.

#### 8.1.19 `deepdoc/` — Document Understanding Engine (1 file, 695 chars)

Package root for the DeepDoc document analysis engine.

#### 8.1.20 `deepdoc/vision/` — Vision Models (10 files, 138K chars)

| Module | Purpose |
|--------|---------|
| `ocr.py` | PaddleOCR/ONNX OCR engine with GPU support |
| `layout_recognizer.py` | Document layout analysis (ONNX, TensorRT, Ascend) |
| `table_structure_recognizer.py` | Table structure detection |
| `recognizer.py` | Base recognizer class |
| `t_ocr.py` | OCR testing utility |
| `t_recognizer.py` | Layout/table recognition testing utility |

#### 8.1.21 `deepdoc/parser/` — Document Parsers (16 files, 251K chars)

| Parser | Format |
|--------|--------|
| `pdf_parser.py` | PDF (with OCR, layout, table extraction) |
| `docx_parser.py` | Microsoft Word (.docx) |
| `excel_parser.py` | Excel (.xlsx, .xls) |
| `ppt_parser.py` | PowerPoint (.pptx) |
| `html_parser.py` | HTML documents |
| `markdown_parser.py` | Markdown files |
| `txt_parser.py` | Plain text |
| `json_parser.py` | JSON files |
| `csv_parser.py` | CSV files |
| `docling_parser.py` | Docling server integration |
| `paddleocr_parser.py` | PaddleOCR API integration |
| `resume/` | Resume-specific entity extraction |

#### 8.1.22 `agent/` — Agent Framework (4 files, 42K chars)

Agent pipeline execution, canvas DSL interpretation, and component orchestration.

#### 8.1.23 `agent/component/` — Agent Components (22 files, 184K chars)

| Component | Purpose |
|-----------|---------|
| `base.py` | Base component class with timeout and concurrency control |
| `agent_with_tools.py` | Agent that can invoke external tools |
| `retrieval.py` | Knowledge base retrieval |
| `generate.py` | LLM text generation |
| `categorize.py` | Input classification/routing |
| `switch.py` | Conditional branching |
| `relevant.py` | Relevance scoring |
| `rewrite_question.py` | Query rewriting |
| `message.py` | Message composition |
| `code.py` | Code execution (via sandbox) |
| `exesql.py` | SQL execution |
| `crawler.py` | Web crawling |
| `email_component.py` | Email sending |
| `invoke.py` | Sub-agent invocation |
| `iteration.py` | Loop/iteration control |
| `variable.py` | Variable manipulation |
| `template.py` | Template rendering |
| `parser.py` | Document parsing component |
| `extractor.py` | Data extraction |
| `doc_generator.py` | Document generation |

#### 8.1.24 `agent/templates/` — Agent Templates (25 files, 1MB+)

Pre-built agent DSL templates for common use cases (HR, customer service, research, etc.).

#### 8.1.25 `agent/sandbox/` — Sandbox System

| Submodule | Files | Chars | Purpose |
|-----------|-------|-------|---------|
| `agent/sandbox/` | 1 | 7K | Sandbox package, provider loading |
| `agent/sandbox/providers/` | 6 | 14K | Provider implementations (self-managed Docker, Aliyun OpenSandbox) |
| `agent/sandbox/executor_manager/core/` | 4 | 10K | Container lifecycle, config, pool management |
| `agent/sandbox/executor_manager/services/` | 4 | 26K | Execution service, container provisioning |
| `agent/sandbox/executor_manager/api/` | 3 | 4K | FastAPI routes for sandbox execution |
| `agent/sandbox/executor_manager/models/` | 3 | 4K | Request/response models |
| `agent/sandbox/executor_manager/utils/` | 2 | 2K | Utility functions |

#### 8.1.26 `agent/plugin/` — Plugin System (4 files, 3K chars)

Embedded plugin framework with LLM tool definitions.

#### 8.1.27 `common/` — Shared Utilities (24 files, 115K chars)

| File | Purpose |
|------|---------|
| `settings.py` | Central settings with environment variable loading |
| `config_utils.py` | YAML configuration loader with local override support |
| `log_utils.py` | Logging configuration with runtime level adjustment |
| `misc_utils.py` | Device detection, thread pool, async utilities |
| `http_client.py` | HTTP client with retry, proxy, and timeout support |
| `connection_utils.py` | CORS, connection management |
| `file_utils.py` | Path resolution, file operations |
| `constants.py` | Global constants |

#### 8.1.28 `common/doc_store/` — Document Store Connectors (7 files, 96K chars)

| File | Purpose |
|------|---------|
| `es_conn.py` | Elasticsearch connector with index management |
| `opensearch_conn.py` | OpenSearch connector |
| `infinity_conn.py` | Infinity connector |
| `infinity_conn_pool.py` | Infinity connection pooling |
| `ob_conn_base.py` | OceanBase base connector |
| `ob_conn_pool.py` | OceanBase connection pooling with hybrid search |

#### 8.1.29 `common/data_source/` — Data Source Connectors (30 files, 475K chars)

| Connector | Data Source |
|-----------|-------------|
| `confluence_connector.py` | Confluence Cloud/Server |
| `google_drive/` | Google Drive |
| `gmail_connector.py` | Gmail |
| `jira/` | Jira Cloud/Server |
| `slack_connector.py` | Slack |
| `discord_connector.py` | Discord |
| `notion_connector.py` | Notion |
| `dropbox_connector.py` | Dropbox |
| `github/` | GitHub repositories |
| `bitbucket/` | Bitbucket repositories |
| `box_connector.py` | Box |
| `airtable_connector.py` | Airtable |
| `asana_connector.py` | Asana |
| `imap_connector.py` | IMAP email |
| `webdav_connector.py` | WebDAV |
| `rdbms_connector.py` | SQL databases (MySQL, PostgreSQL, etc.) |
| `zendesk_connector.py` | Zendesk |
| `dingtalk_ai_table_connector.py` | DingTalk AI Tables |
| `blob_connector.py` | AWS S3 / Cloud blob storage |
| `config.py` | Connector configuration hub |
| `cross_connector_utils/` | Cross-connector utilities |
| `google_util/` | Google API utilities |

#### 8.1.30 `internal/` — Go Server Internals (2 files, 5K chars)

Go package root and shared types.

#### 8.1.31 `internal/router/` — Go HTTP Router (1 file, 13K chars)

Gin router setup with all API route definitions, middleware, and authentication.

#### 8.1.32 `internal/handler/` — Go HTTP Handlers (19 files, 173K chars)

Request handlers for knowledge bases, documents, chunks, chats, search, files, memory, LLM management, and sessions.

#### 8.1.33 `internal/service/` — Go Business Logic (19 files, 307K chars)

Service layer with business logic for all Go API operations.

#### 8.1.34 `internal/dao/` — Go Data Access (28 files, 143K chars)

Data access objects for MySQL operations via GORM.

#### 8.1.35 `internal/entity/` — Go Entity Models (29 files, 86K chars)

Request/response structures and database entity definitions.

#### 8.1.36 `internal/admin/` — Go Admin Server (5 files, 96K chars)

Admin router, handlers, middleware, and RBAC enforcement for the Go admin API.

#### 8.1.37 `internal/cli/` — Go CLI (17 files, 315K chars)

CLI implementation with the context engine for intelligent command parsing and execution.

#### 8.1.38 `internal/cpp/` — C++ Tokenizer (19 files, 238K chars)

High-performance tokenizer with DARTS trie, Snowball stemmer, OpenCC Chinese conversion, and RE2 regex. Compiled to `librag_tokenizer_c_api.a`.

#### 8.1.39 `internal/cache/` — Go Cache Layer (1 file, 25K chars)

Redis-based caching with key management and TTL policies.

#### 8.1.40 `internal/engine/` — Go Document Engine (2 + 4 files)

| Submodule | Purpose |
|-----------|---------|
| `internal/engine/` | Engine interface and factory |
| `internal/engine/elasticsearch/` | Elasticsearch implementation with index management |

#### 8.1.41 `internal/storage/` — Go Storage (6 files, 55K chars)

MinIO and S3-compatible storage operations from the Go stack.

#### 8.1.42 `internal/tokenizer/` — Go Tokenizer Binding (2 files, 27K chars)

CGO binding to the C++ tokenizer library.

#### 8.1.43 `internal/binding/` — Go C Binding (1 file, 8K chars)

Low-level CGO interface to `librag_tokenizer_c_api.a`.

#### 8.1.44 `internal/common/` — Go Common (5 files, 13K chars)

Shared Go utilities, error handling, and constants.

#### 8.1.45 `internal/utility/` — Go Utilities (10 files, 40K chars)

Path resolution, string manipulation, and helper functions.

#### 8.1.46 `internal/logger/` — Go Logging (1 file, 4K chars)

Structured logging via Zap with runtime level control.

#### 8.1.47 `internal/server/` — Go Server Config (3 files, 37K chars)

Server initialization, configuration loading from YAML and environment, and MinIO/Redis/MySQL connection setup.

#### 8.1.48 `memory/` — Memory System

| Submodule | Files | Chars | Purpose |
|-----------|-------|-------|---------|
| `memory/services/` | 2 | 19K | Memory CRUD, session management |
| `memory/utils/` | 7 | 89K | Memory utilities, content extraction, search |

#### 8.1.49 `mcp/` — MCP Integration

| Submodule | Files | Chars | Purpose |
|-----------|-------|-------|---------|
| `mcp/server/` | 1 | 33K | FastMCP server with SSE and streamable-http transport |
| `mcp/client/` | 2 | 4K | MCP client for connecting to external MCP servers |

#### 8.1.50 `sdk/python/` — Python SDK (1 file, 674 chars)

SDK package initialization. Full SDK modules in `sdk/python/ragflow_sdk/modules/`.

#### 8.1.51 `conf/` — Configuration (9 files, 252K chars)

| File | Purpose |
|------|---------|
| `service_conf.yaml` | Primary YAML configuration |
| `llm_factories.json` | LLM provider definitions and model catalog |
| `models/` (3 files, 9K) | Elasticsearch and Infinity index mapping definitions |

#### 8.1.52 `helm/` — Kubernetes Charts (2 + 13 files)

Helm chart root (`Chart.yaml`, `values.yaml`) plus 13 templates for K8s deployment.

#### 8.1.53 `docker/` — Docker Configuration (8 files, 40K chars)

| File | Purpose |
|------|---------|
| `docker-compose-base.yml` | Base service definitions |
| `docker-compose.yml` | Override/extension compose file |
| `entrypoint.sh` | Container entrypoint with process management |
| `Dockerfile` | Multi-stage build for RAGFlow image |
| `nginx/` | nginx configuration for reverse proxy |
| `oceanbase/init.d/` | OceanBase initialization scripts |

#### 8.1.54 `web/` — Frontend (7 files at root level)

| File | Purpose |
|------|---------|
| `vite.config.ts` | Vite build configuration |
| `tailwind.config.ts` | Tailwind CSS configuration |
| `tsconfig.json` | TypeScript configuration |
| `package.json` | Dependencies and scripts |

#### 8.1.55 `cmd/` — Go Entry Points (3 files, 16K chars)

| File | Purpose |
|------|---------|
| `server_main.go` | Go API server entry point |
| `admin_server.go` | Go admin server entry point |
| `ragflow_cli.go` | CLI client entry point |

#### 8.1.56 `admin/` — Admin System

| Submodule | Files | Chars | Purpose |
|-----------|-------|-------|---------|
| `admin/` | 1 | 1K | Admin package root |
| `admin/client/` | 5 | 153K | Python-based admin CLI client |
| `admin/server/` | 9 | 78K | Python admin server with Quart, routes, auth |

#### 8.1.57 `tools/` — Utility Tools

| Tool | Files | Chars | Purpose |
|------|-------|-------|---------|
| `tools/firecrawl/` | 8 | 52K | Firecrawl web crawling integration |
| `tools/es-to-oceanbase-migration/` | -- | -- | Elasticsearch to OceanBase data migration |
| `tools/chatgpt-on-wechat/` | 3 | 7K | WeChat integration plugin |

### 8.2 Build from Source

```bash
# 1. Clone repository
git clone https://github.com/infiniflow/ragflow.git
cd ragflow

# 2. Build C++ tokenizer + Go binaries
./build.sh

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Build frontend
cd web && npm install && npm run build && cd ..

# 5. Run development server
python api/ragflow_server.py --debug
```

**Build dependencies:**

```bash
# Ubuntu/Debian
apt-get install cmake g++ libpcre2-dev golang-go

# The build requires:
# - cmake >= 4.0
# - Go >= 1.24 (module requires 1.25)
# - g++ with C++17/C++23 support
# - libpcre2-dev for PCRE2 regex in tokenizer
```

### 8.3 Testing Infrastructure

| Test Suite | Command | Framework |
|------------|---------|-----------|
| Python unit tests | `python run_tests.py` | pytest (`test/unit_test/`) |
| Go tests | `./run_go_tests.sh` | go test (`internal/` packages) |
| SDK API tests | `pytest test/testcases/test_sdk_api` | pytest |
| HTTP API tests | `pytest test/testcases/test_http_api` | pytest |
| Web API tests | `pytest test/testcases/test_web_api` | pytest |
| Admin API tests | `pytest test/testcases/test_admin_api` | pytest |
| Playwright E2E | `npx playwright test` (`test/playwright/`) | Playwright |
| Sandbox tests | `pytest agent/sandbox/tests/` | pytest |
| Benchmarks | `PYTHONPATH=./test uv run -m benchmark [chat\|retrieval]` | Custom |

**Test runner flags:**

| Flag | Description |
|------|-------------|
| `-c`, `--coverage` | Run with coverage report |
| `-p`, `--parallel` | Parallel execution (requires pytest-xdist) |
| `-v`, `--verbose` | Verbose output |
| `-t`, `--test` | Run specific test file or directory |
| `-m`, `--markers` | Run tests with specific markers (`unit`, `integration`) |
| `-i`, `--ignore` | Suppress SyntaxWarning |

**Pre-commit hooks**: ruff (lint + format), YAML/JSON validation, merge conflict detection.

**Playwright E2E configuration:**

| Variable | Default | Description |
|----------|---------|-------------|
| `RAGFLOW_BASE_URL` / `BASE_URL` | (unset) | RAGFlow URL to test against |
| `E2E_ADMIN_EMAIL` | (unset) | Admin email for E2E tests |
| `E2E_ADMIN_PASSWORD` | (unset) | Admin password for E2E tests |
| `PW_BROWSER` | `chromium` | Browser engine |
| `RAGFLOW_SEEDING_MODE` | `auto` | Test data seeding mode |

---

## 9. Integration Points

### 9.1 MCP Server (Model Context Protocol)

RAGFlow exposes its capabilities via MCP for integration with AI assistants:

```bash
# Start MCP server (self-host mode)
python -m mcp.server.server \
  --base-url http://127.0.0.1:9380 \
  --host 127.0.0.1 \
  --port 9382 \
  --mode self-host \
  --api-key ragflow-xxxxxxxxxxxx

# Multi-tenant mode
python -m mcp.server.server \
  --mode host \
  --port 9382
```

**MCP server options:**

| Flag | Default | Description |
|------|---------|-------------|
| `--base-url` | `http://127.0.0.1:9380` | RAGFlow backend URL |
| `--host` | `127.0.0.1` | Bind host |
| `--port` | `9382` | Bind port |
| `--mode` | `self-host` | `self-host` (single tenant) or `host` (multi-tenant) |
| `--api-key` | (required for self-host) | API key for authentication |
| `--transport-sse-enabled` / `--no-transport-sse-enabled` | `True` | Enable SSE transport |
| `--transport-streamable-http-enabled` / `--no-transport-streamable-http-enabled` | `True` | Enable streamable-http transport |
| `--json-response` / `--no-json-response` | `True` | JSON response mode for streamable-http |

### 9.2 Python SDK

```python
from ragflow_sdk import RAGFlow

# Connect to RAGFlow
rag = RAGFlow(api_key="ragflow-xxxxxxxxxxxx", base_url="http://localhost:9380")

# Create knowledge base
kb = rag.create_dataset("my_kb")

# Upload and parse document
doc = kb.upload_document("document.pdf")
doc.parse()

# Query
results = kb.retrieval("What is the architecture?")
```

### 9.3 Langfuse Observability

RAGFlow integrates with Langfuse for LLM observability:

```bash
# Set Langfuse API key via API
POST /api/v1/langfuse/api_key
{
  "public_key": "pk-...",
  "secret_key": "sk-...",
  "host": "https://cloud.langfuse.com"
}
```

> [!NOTE]
> The Langfuse integration has a known issue (#14204) where `start_generation` raises an `AttributeError` in recent Docker images. Monitor the issue tracker for a fix before relying on this feature in production.

### 9.4 LLM Provider Configuration

RAGFlow supports dozens of LLM providers defined in `conf/llm_factories.json`. Add providers via the API:

```bash
# Set API key for a provider
POST /api/v1/llm/set_api_key
{
  "llm_factory": "OpenAI",
  "api_key": "sk-..."
}

# Add a custom model
POST /api/v1/llm/add_llm
{
  "llm_factory": "OpenAI",
  "model_name": "gpt-4",
  "model_type": "chat"
}
```

### 9.5 Webhook Integration

Agent canvases support webhook-based triggers via the Begin node's webhook configuration. Configure via the canvas settings API.

### 9.6 Evaluation Framework

RAGFlow includes a built-in evaluation framework for measuring retrieval quality:

```bash
# Create evaluation dataset
POST /api/v1/evaluation/dataset/create

# Import test cases
POST /api/v1/evaluation/dataset/{id}/case/import

# Run evaluation
POST /api/v1/evaluation/run/start

# Compare runs
POST /api/v1/evaluation/compare
```

**Benchmark tool** for standard datasets:

```bash
# MS MARCO benchmark
PYTHONPATH=./test uv run -m benchmark retrieval \
  --dataset ms_marco_v1.1 \
  --kb_id <dataset_id>

# TriviaQA benchmark
PYTHONPATH=./test uv run -m benchmark retrieval \
  --dataset trivia_qa \
  --kb_id <dataset_id>
```

### 9.7 ES-to-OceanBase Migration

A dedicated migration tool exists in `tools/es-to-oceanbase-migration/`:

```bash
cd tools/es-to-oceanbase-migration
pip install -e .
es-ob-migrate --help
```

---

## 10. API Reference

### 10.1 Python API Server Endpoints (port 9380)

#### Canvas / Agent Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /templates | `templates` | List agent templates |
| POST | /rm | `rm` | Delete canvas |
| POST | /set | `save` | Create/update canvas |
| GET | /get/\<canvas_id\> | `get` | Get canvas details |
| GET | /getsse/\<canvas_id\> | `getsse` | Get canvas via SSE |
| POST | /completion | `run` | Run agent completion |
| POST | /\<canvas_id\>/completion | `exp_agent_completion` | Experimental agent completion |
| POST | /rerun | `rerun` | Rerun agent task |
| PUT | /cancel/\<task_id\> | `cancel` | Cancel running task |
| POST | /reset | `reset` | Reset canvas state |
| POST | /upload/\<canvas_id\> | `upload` | Upload file to canvas |
| GET | /input_form | `input_form` | Get canvas input form |
| POST | /debug | `debug` | Debug canvas execution |
| POST | /test_db_connect | `test_db_connect` | Test database connection |
| GET | /getlistversion/\<canvas_id\> | `getlistversion` | List canvas versions |
| GET | /getversion/\<version_id\> | `getversion` | Get specific version |
| GET | /list | `list_canvas` | List all canvases |
| POST | /setting | `setting` | Update canvas settings |
| GET | /trace | `trace` | Get execution trace |
| GET | /\<canvas_id\>/sessions | `sessions` | List canvas sessions |
| PUT | /\<canvas_id\>/sessions | `set_session` | Create/update session |
| GET | /\<canvas_id\>/sessions/\<session_id\> | `get_session` | Get specific session |
| DELETE | /\<canvas_id\>/sessions/\<session_id\> | `del_session` | Delete session |
| GET | /prompts | `prompts` | Get available prompts |
| GET | /download | `download` | Download canvas artifact |

#### Chunk Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /list | `list_chunk` | List chunks with filtering |
| GET | /get | `get` | Get chunk by ID |
| POST | /set | `set` | Update chunk content |
| POST | /switch | `switch` | Toggle chunk availability |
| POST | /rm | `rm` | Delete chunks |
| POST | /create | `create` | Create manual chunk |
| POST | /retrieval_test | `retrieval_test` | Test retrieval against chunks |
| GET | /knowledge_graph | `knowledge_graph` | Get knowledge graph data |

#### Connector Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /set | `set_connector` | Create/update connector |
| GET | /list | `list_connector` | List connectors |
| GET | /\<connector_id\> | `get_connector` | Get connector details |
| GET | /\<connector_id\>/logs | `list_logs` | Get connector sync logs |
| PUT | /\<connector_id\>/resume | `resume` | Resume paused connector |
| PUT | /\<connector_id\>/rebuild | `rebuild` | Rebuild connector index |
| POST | /\<connector_id\>/rm | `rm_connector` | Delete connector |
| POST | /google/oauth/web/start | `start_google_web_oauth` | Start Google OAuth flow |
| GET | /gmail/oauth/web/callback | `google_gmail_web_oauth_callback` | Gmail OAuth callback |
| GET | /google-drive/oauth/web/callback | `google_drive_web_oauth_callback` | Google Drive OAuth callback |
| POST | /google/oauth/web/result | `poll_google_web_result` | Poll Google OAuth result |
| POST | /box/oauth/web/start | `start_box_web_oauth` | Start Box OAuth flow |
| GET | /box/oauth/web/callback | `box_web_oauth_callback` | Box OAuth callback |
| POST | /box/oauth/web/result | `poll_box_web_result` | Poll Box OAuth result |

#### Document Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /web_crawl | `web_crawl` | Crawl and ingest web page |
| POST | /create | `create` | Create document record |
| POST | /list | `list_docs` | List documents with filtering |
| POST | /filter | `get_filter` | Get filter options |
| POST | /infos | `doc_infos` | Get document metadata |
| POST | /metadata/update | `metadata_update` | Update document metadata |
| POST | /update_metadata_setting | `update_metadata_setting` | Update metadata configuration |
| GET | /thumbnails | `thumbnails` | Get document thumbnails |
| POST | /change_status | `change_status` | Change document status |
| POST | /rm | `rm` | Delete documents |
| POST | /run | `run` | Trigger document parsing |
| GET | /get/\<doc_id\> | `get` | Get document by ID |
| GET | /download/\<attachment_id\> | `download_attachment` | Download attachment |
| POST | /change_parser | `change_parser` | Change document parser |
| GET | /image/\<image_id\> | `get_image` | Get parsed image |
| GET | /artifact/\<filename\> | `get_artifact` | Get sandbox artifact |
| POST | /upload_and_parse | `upload_and_parse` | Upload and immediately parse |
| POST | /parse | `parse` | Parse uploaded document |
| POST | /upload_info | `upload_info` | Get upload progress |

#### Evaluation Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /dataset/create | `create_dataset` | Create evaluation dataset |
| GET | /dataset/list | `list_datasets` | List evaluation datasets |
| GET | /dataset/\<dataset_id\> | `get_dataset` | Get dataset details |
| PUT | /dataset/\<dataset_id\> | `update_dataset` | Update dataset |
| DELETE | /dataset/\<dataset_id\> | `delete_dataset` | Delete dataset |
| POST | /dataset/\<dataset_id\>/case/add | `add_test_case` | Add test case |
| POST | /dataset/\<dataset_id\>/case/import | `import_test_cases` | Bulk import test cases |
| GET | /dataset/\<dataset_id\>/cases | `get_test_cases` | List test cases |
| DELETE | /case/\<case_id\> | `delete_test_case` | Delete test case |
| POST | /run/start | `start_evaluation` | Start evaluation run |
| GET | /run/\<run_id\> | `get_evaluation_run` | Get run details |
| GET | /run/\<run_id\>/results | `get_run_results` | Get run results |
| GET | /run/list | `list_evaluation_runs` | List all runs |
| DELETE | /run/\<run_id\> | `delete_evaluation_run` | Delete run |
| GET | /run/\<run_id\>/recommendations | `get_recommendations` | Get improvement recommendations |
| POST | /compare | `compare_runs` | Compare two evaluation runs |
| GET | /run/\<run_id\>/export | `export_results` | Export results |
| POST | /evaluate_single | `evaluate_single` | Evaluate a single query |

#### Knowledge Base Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /update_metadata_setting | `update_metadata_setting` | Update KB metadata settings |
| GET | /detail | `detail` | Get KB details |
| GET | /\<kb_id\>/tags | `list_tags` | List tags for a KB |
| GET | /tags | `list_tags_from_kbs` | List tags across KBs |
| POST | /\<kb_id\>/rm_tags | `rm_tags` | Remove tags |
| POST | /\<kb_id\>/rename_tag | `rename_tags` | Rename tags |
| GET | /get_meta | `get_meta` | Get metadata schema |
| GET | /basic_info | `get_basic_info` | Get basic KB info |
| POST | /list_pipeline_logs | `list_pipeline_logs` | List pipeline logs |
| POST | /list_pipeline_dataset_logs | `list_pipeline_dataset_logs` | List dataset pipeline logs |
| POST | /delete_pipeline_logs | `delete_pipeline_logs` | Delete pipeline logs |
| GET | /pipeline_log_detail | `pipeline_log_detail` | Get log details |
| POST | /run_mindmap | `run_mindmap` | Generate knowledge mindmap |
| GET | /trace_mindmap | `trace_mindmap` | Trace mindmap generation |
| DELETE | /unbind_task | `delete_kb_task` | Unbind task from KB |
| POST | /check_embedding | `check_embedding` | Validate embedding configuration |

#### LLM Management Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /factories | `factories` | List LLM provider factories |
| POST | /set_api_key | `set_api_key` | Set provider API key |
| POST | /add_llm | `add_llm` | Add custom LLM model |
| POST | /delete_llm | `delete_llm` | Delete LLM model |
| POST | /enable_llm | `enable_llm` | Enable/disable LLM |
| POST | /delete_factory | `delete_factory` | Delete LLM factory |
| GET | /my_llms | `my_llms` | List user's configured LLMs |
| GET | /list | `list_app` | List all available LLMs |

#### Langfuse Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /api_key | `set_api_key` | Set Langfuse API key |
| PUT | /api_key | `set_api_key` | Update Langfuse API key |
| GET | /api_key | `get_api_key` | Get Langfuse API key |
| DELETE | /api_key | `delete_api_key` | Delete Langfuse API key |

#### MCP Server Management Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /list | `list_mcp` | List MCP servers |
| GET | /detail | `detail` | Get MCP server details |
| POST | /create | `create` | Create MCP server config |
| POST | /update | `update` | Update MCP server config |
| POST | /rm | `rm` | Delete MCP server |
| POST | /import | `import_multiple` | Bulk import MCP configs |
| POST | /export | `export_multiple` | Bulk export MCP configs |
| POST | /list_tools | `list_tools` | List tools from MCP server |
| POST | /test_tool | `test_tool` | Test MCP tool execution |
| POST | /cache_tools | `cache_tool` | Cache tool definitions |
| POST | /test_mcp | `test_mcp` | Test MCP server connection |

#### User & Auth Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /login | `login` | User login |
| GET | /login | `login` | Login page redirect |
| GET | /login/channels | `get_login_channels` | List available login methods |
| GET | /login/\<channel\> | `oauth_login` | Initiate OAuth login |
| GET | /oauth/callback/\<channel\> | `oauth_callback` | OAuth callback handler |
| GET | /github_callback | `github_callback` | GitHub OAuth callback |
| GET | /feishu_callback | `feishu_callback` | Feishu OAuth callback |
| GET | /logout | `log_out` | User logout |
| POST | /setting | `setting_user` | Update user settings |
| GET | /info | `user_profile` | Get user profile |
| POST | /register | `user_add` | Register new user |
| GET | /tenant_info | `tenant_info` | Get tenant information |
| POST | /set_tenant_info | `set_tenant_info` | Update tenant settings |
| GET | /forget/captcha | `forget_get_captcha` | Get password reset captcha |
| POST | /forget/otp | `forget_send_otp` | Send OTP for password reset |
| POST | /forget/verify-otp | `forget_verify_otp` | Verify OTP |
| POST | /forget/reset-password | `forget_reset_password` | Reset password with OTP |

#### Tenant Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /\<tenant_id\>/user/list | `user_list` | List tenant users |
| POST | /\<tenant_id\>/user | `create` | Create tenant user |
| DELETE | /\<tenant_id\>/user/\<user_id\> | `rm` | Remove tenant user |
| GET | /list | `tenant_list` | List all tenants |
| PUT | /agree/\<tenant_id\> | `agree` | Accept tenant invitation |

#### System Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /stats | `stats` | API statistics |
| GET | /status | `status` | System status |
| GET | /oceanbase/status | `oceanbase_status` | OceanBase health |
| GET | /config | `get_config` | System configuration |

#### File Conversion Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| POST | /convert | `convert` | Convert file to document |
| POST | /rm | `rm` | Remove file |

#### Plugin Endpoints

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /llm_tools | `llm_tools` | List available LLM tools |

### 10.2 Go API Server Endpoints (configurable port)

#### System

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health check |
| GET | /v1/system/ping | Ping |
| GET | /v1/system/config | Configuration |
| GET | /v1/system/configs | All configurations |
| GET | /v1/system/version | Version info |

#### User & Auth

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/user/register | Register |
| GET | /v1/user/login/channels | Login channels |
| POST | /v1/user/login | Login |
| GET | /v1/user/logout | Logout |
| GET | /v1/user/info | User profile |
| GET | /v1/user/tenant_info | Tenant info |
| GET | /v1/tenant/list | List tenants |
| POST | /v1/user/setting | Update settings |
| POST | /v1/user/setting/password | Change password |
| POST | /v1/user/set_tenant_info | Update tenant info |

#### Knowledge Base (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| POST | /register | Create KB |
| POST | /login | KB login (legacy) |
| GET | /:id | Get KB |
| PUT | /:id | Update KB |
| DELETE | /:id | Delete KB |
| POST | /update | Update KB |
| POST | /update_metadata_setting | Update metadata settings |
| GET | /detail | KB detail |
| GET | /tags | List KB tags |
| GET | /get_meta | Get metadata |
| GET | /basic_info | Basic info |
| POST | /doc_engine_table | Create doc engine table |
| DELETE | /doc_engine_table | Delete doc engine table |
| POST | /insert_from_file | Insert from file |
| GET | /tags (scoped) | List tags within scope |
| POST | /rm_tags | Remove tags |
| POST | /rename_tag | Rename tag |
| GET | /knowledge_graph | Get knowledge graph |
| DELETE | /knowledge_graph | Delete knowledge graph |
| POST | /doc_engine_metadata_table | Create metadata table |
| DELETE | /doc_engine_metadata_table | Delete metadata table |
| POST | /insert_metadata_from_file | Insert metadata from file |

#### Documents (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| POST | /list | List documents |
| POST | /metadata/summary | Metadata summary |
| POST | /set_meta | Set document metadata |
| GET | /:author_id/documents | List by author |

#### Chunks (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| POST | /retrieval_test | Retrieval test |
| GET | /get | Get chunk |
| POST | /list | List chunks |
| POST | /update | Update chunk |
| POST | /rm | Delete chunks |

#### LLM (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| GET | /my_llms | User's LLMs |
| GET | /factories | LLM factories |
| GET | /list | All LLMs |
| POST | /set_api_key | Set API key |

#### Chat & Conversation (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| POST | /next | Next message |
| POST | /set | Create/update chat |
| POST | /rm | Delete chat |
| POST | /completion | Chat completion |
| GET | /list | List chats |

#### Search (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| POST | /set | Create search |
| POST | /rm | Delete search |
| GET | /list | List searches |

#### Files (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| GET | /root_folder | Get root folder |
| GET | /parent_folder | Get parent folder |
| GET | /all_parent_folder | Get all parent folders |
| POST | /move | Move file |
| GET | /:id/ancestors | Get file ancestors |
| GET | /:id | Get file |

#### Memory (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| PUT | /:memory_id | Update memory |
| DELETE | /:memory_id | Delete memory |
| GET | /:memory_id/config | Get memory config |
| GET | /:memory_id | Get memory |
| DELETE | /:memory_id/:message_id | Delete message |
| PUT | /:memory_id/:message_id | Update message |
| GET | /search | Search memories |
| GET | /:memory_id/:message_id/content | Get message content |

#### LLM Providers (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| GET | / | List providers |
| PUT | / | Update provider |
| GET | /:provider_name | Get provider |
| DELETE | /:provider_name | Delete provider |
| GET | /:provider_name/models | List models |
| GET | /:provider_name/models/:model_name | Get model |
| POST | /:provider_name/instances | Create instance |
| GET | /:provider_name/instances | List instances |
| GET | /:provider_name/instances/:instance_name | Get instance |
| PUT | /:provider_name/instances/:instance_name | Update instance |
| DELETE | /:provider_name/instances | Delete instances |
| GET | /:provider_name/instances/:instance_name/models | List instance models |
| PATCH | /:provider_name/instances/:instance_name/models/:model_name | Update instance model |
| POST | /:provider_name/instances/:instance_name/models/:model_name | Create instance model |

#### Session (Go routes)

| Method | Path | Description |
|--------|------|-------------|
| GET | /:chat_id | Get session by chat ID |
| GET | /:search_id | Get search session |
| PUT | /:search_id | Update search session |
| DELETE | /:search_id | Delete search session |

### 10.3 Go Admin Server Endpoints (port 9383)

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health check |
| GET | /ping | Ping |
| POST | /login | Admin login |
| POST | /reports | Submit report |
| GET | /logout | Admin logout |
| GET | /auth | Auth check |

#### User Management

| Method | Path | Description |
|--------|------|-------------|
| GET | /users | List users |
| POST | /users | Create user |
| GET | /users/:username | Get user details |
| DELETE | /users/:username | Delete user |
| PUT | /users/:username/password | Change password |
| PUT | /users/:username/activate | Activate/deactivate user |
| PUT | /users/:username/admin | Grant admin |
| DELETE | /users/:username/admin | Revoke admin |
| GET | /users/:username/datasets | User's datasets |
| GET | /users/:username/agents | User's agents |
| GET | /users/:username/keys | User's API keys |
| GET | /users/:username/tokens | User's tokens |
| POST | /users/:username/keys | Generate API key |
| POST | /users/:username/tokens | Generate token |
| DELETE | /users/:username/keys/:token | Delete API key |
| DELETE | /users/:username/tokens/:token | Delete token |
| PUT | /users/:username/role | Set user role |
| GET | /users/:username/permission | Get user permissions |

#### Role Management

| Method | Path | Description |
|--------|------|-------------|
| GET | /roles | List roles |
| POST | /roles | Create role |
| GET | /roles/:role_name | Get role |
| PUT | /roles/:role_name | Update role |
| DELETE | /roles/:role_name | Delete role |
| GET | /roles/:role_name/permission | Get role permissions |
| POST | /roles/:role_name/permission | Grant permission |
| DELETE | /roles/:role_name/permission | Revoke permission |

#### Service Management

| Method | Path | Description |
|--------|------|-------------|
| GET | /services | List services |
| GET | /service_types/:service_type | Services by type |
| GET | /services/:service_id | Get service |
| DELETE | /services/:service_id | Shutdown service |
| PUT | /services/:service_id | Restart service |

#### Configuration & Variables

| Method | Path | Description |
|--------|------|-------------|
| GET | /variables | Get variables |
| PUT | /variables | Set variable |
| GET | /configs | Get configurations |
| GET | /environments | Get environment info |
| GET | /version | Get version |

#### Sandbox Management

| Method | Path | Description |
|--------|------|-------------|
| GET | /sandbox/providers | List sandbox providers |
| GET | /sandbox/providers/:provider_id/schema | Get provider schema |
| GET | /sandbox/config | Get sandbox config |
| POST | /sandbox/config | Set sandbox config |
| POST | /sandbox/test | Test sandbox connection |

#### License Management

| Method | Path | Description |
|--------|------|-------------|
| GET | /fingerprint | Get machine fingerprint |
| POST | /license | Upload license |
| POST | /license/config | Update license config |
| GET | /license | Get license info |

#### Logging

| Method | Path | Description |
|--------|------|-------------|
| GET | /log_level | Get log levels |
| PUT | /log_level | Set log level |

#### LLM Providers (Admin)

| Method | Path | Description |
|--------|------|-------------|
| GET | / | List providers |
| GET | /:provider_name | Get provider |
| GET | /:provider_name/models | List models |
| GET | /:provider_name/models/:model_name | Get model details |

### 10.4 Python Admin Server Endpoints (port 9381)

| Method | Path | Handler | Description |
|--------|------|---------|-------------|
| GET | /ping | `ping` | Health check |
| POST | /login | `login` | Admin login |
| GET | /logout | `logout` | Admin logout |
| GET | /auth | `auth_admin` | Auth verification |
| GET | /users | `list_users` | List all users |
| POST | /users | `create_user` | Create user |
| DELETE | /users/\<username\> | `delete_user` | Delete user |
| PUT | /users/\<username\>/password | `change_password` | Change password |
| PUT | /users/\<username\>/activate | `alter_user_activate_status` | Toggle active status |
| PUT | /users/\<username\>/admin | `grant_admin` | Grant admin privileges |
| DELETE | /users/\<username\>/admin | `revoke_admin` | Revoke admin privileges |
| GET | /users/\<username\> | `get_user_details` | User details |
| GET | /users/\<username\>/datasets | `get_user_datasets` | User's datasets |
| GET | /users/\<username\>/agents | `get_user_agents` | User's agents |
| GET | /services | `get_services` | List running services |
| GET | /service_types/\<service_type\> | `get_services_by_type` | Services by type |
| GET | /services/\<service_id\> | `get_service` | Get service details |
| DELETE | /services/\<service_id\> | `shutdown_service` | Shutdown service |
| PUT | /services/\<service_id\> | `restart_service` | Restart service |
| POST | /roles | `create_role` | Create role |
| PUT | /roles/\<role_name\> | `update_role` | Update role |
| DELETE | /roles/\<role_name\> | `delete_role` | Delete role |
| GET | /roles | `list_roles` | List roles |
| GET | /roles/\<role_name\>/permission | `get_role_permission` | Get permissions |
| POST | /roles/\<role_name\>/permission | `grant_role_permission` | Grant permission |
| DELETE | /roles/\<role_name\>/permission | `revoke_role_permission` | Revoke permission |
| PUT | /users/\<user_name\>/role | `update_user_role` | Set user role |
| GET | /users/\<user_name\>/permission | `get_user_permission` | Get user permissions |
| PUT | /variables | `set_variable` | Set runtime variable |
| GET | /variables | `get_variable` | Get runtime variables |
| GET | /configs | `get_config` | Get configuration |
| GET | /environments | `get_environments` | Get environment info |
| POST | /users/\<username\>/keys | `generate_user_api_key` | Generate API key |
| GET | /users/\<username\>/keys | `get_user_api_keys` | List API keys |
| DELETE | /users/\<username\>/keys/\<key\> | `delete_user_api_key` | Delete API key |
| GET | /version | `show_version` | Get version |
| GET | /sandbox/providers | `list_sandbox_providers` | List sandbox providers |
| GET | /sandbox/providers/\<provider_id\>/schema | `get_sandbox_provider_schema` | Provider schema |
| GET | /sandbox/config | `get_sandbox_config` | Get sandbox config |
| POST | /sandbox/config | `set_sandbox_config` | Set sandbox config |
| POST | /sandbox/test | `test_sandbox_connection` | Test sandbox |
| GET | /log_levels | `get_logger_levels` | Get log levels |
| PUT | /log_levels | `set_logger_level` | Set log level |

---

## 11. Troubleshooting

### 11.1 Deployment Failures

**Error**: Container fails to start, version upgrade data not inherited

**Cause**: Known issue (#13713) with v0.24.0 where deployment fails and previous data is lost during upgrade.

**Solution**: Back up MySQL data and MinIO storage before upgrading. Use `docker compose down` (without `-v`) to preserve volumes. Verify volume mounts match between compose versions.

**Prevention**: Always snapshot volumes before version upgrades.

---

**Error**: `docker/entrypoint.sh file can't find service_conf.yaml.template`

**Cause**: Issue #6927 -- the entrypoint expects configuration templates that may be missing in certain build configurations.

**Solution**: Ensure the Docker image was built completely. Verify `conf/service_conf.yaml` exists in the container. Rebuild the image if necessary.

**Prevention**: Use official Docker images from the InfiniFlow registry.

---

**Error**: Nightly deployment failures

**Cause**: Issue #14171 -- automated nightly builds fail due to dependency or infrastructure changes.

**Solution**: Pin dependency versions in production deployments. Use tagged releases rather than nightly builds.

**Prevention**: Always use stable tagged releases for production.

---

**Error**: Latest Docker image not available, minor bugs remain unfixed

**Cause**: Issue #14193 -- gap between source fixes and Docker image publication.

**Solution**: Build from source if you need the latest fixes. Monitor the release schedule for updated images.

**Prevention**: Subscribe to release notifications on the GitHub repository.

### 11.2 Document Processing Errors

**Error**: `internal server error while chunking: expected string or bytes-like object`

**Cause**: Issue #6990 -- type mismatch during chunking when document content contains unexpected data types.

**Solution**: Check the source document for corruption. Try a different parser method. Verify the document encoding is UTF-8.

**Prevention**: Validate documents before upload. Use the `naive` parser as a fallback.

---

**Error**: Error chunking CV with Resume method

**Cause**: Issue #6933 -- the Resume parser fails on certain CV formats or structures.

**Solution**: Try the `naive` parser instead. Check that the CV is in a supported format (PDF preferred). Verify the document is not password-protected.

**Prevention**: Pre-process CVs to standard PDF format before uploading.

---

**Error**: DeepDoc fails on 1000+ page PDFs with poor image quality

**Cause**: Issue #14196 -- memory and processing limits for very large documents.

**Solution**: Split large PDFs into smaller chunks before uploading. Increase `OCR_GPU_MEM_LIMIT_MB` for GPU deployments. Increase worker memory limits.

**Prevention**: Set document size limits. Process large documents in segments.

---

**Error**: MinerU parsed images are obscured/garbled

**Cause**: Issue #14197 -- MinerU parser produces degraded image output.

**Solution**: Switch to DeepDoc's native parser. Verify MinerU server configuration. Check image encoding settings.

**Prevention**: Test parser output quality before bulk processing.

---

**Error**: Document parsing stuck or no progress

**Cause**: Task executor worker may have died without updating status. Worker heartbeat timeout exceeded.

**Solution**: Check task executor logs. Restart the worker container. Verify `WORKER_HEARTBEAT_TIMEOUT` (default 120s) is appropriate for your workloads.

**Prevention**: Monitor worker heartbeats. Set up health checks on executor processes.

### 11.3 API and Retrieval Issues

**Error**: Retrieval API returns 110 timeout

**Cause**: Issue #6998 -- the retrieval operation completes server-side (200 response logged) but the client times out waiting.

**Solution**: Increase `QUART_RESPONSE_TIMEOUT`. Optimize Elasticsearch query performance. Check network latency between client and server.

**Prevention**: Tune Elasticsearch indices. Set appropriate client-side timeouts.

---

**Error**: Shared chat links cannot search knowledge base content but editing page works

**Cause**: Issue #14115 -- shared links may use different authentication contexts that restrict knowledge base access.

**Solution**: Verify share link permissions. Check that the shared canvas has proper KB bindings.

**Prevention**: Test shared links after creation. Verify KB access permissions.

---

**Error**: Iteration component only processes first element from Code node

**Cause**: Issue #14142 -- array output from Code nodes not properly iterated in v0.24.0.

**Solution**: Ensure the Code node output is properly formatted as a JSON array. Check iteration component configuration.

**Prevention**: Test iteration flows with multi-element arrays before production deployment.

---

**Error**: Incorrect time display in API responses

**Cause**: Issue #6970 -- RFC 1123 format missing timezone information.

**Solution**: The issue has been addressed in newer versions. Ensure client-side timezone handling accounts for UTC responses.

**Prevention**: Always parse API timestamps as UTC.

### 11.4 Authentication Issues

**Error**: OIDC authorization broken

**Cause**: Issue #14066 -- OIDC flow fails during token validation or callback processing.

**Solution**: Verify OIDC configuration matches the identity provider's settings. Check `redirect_uri` matches exactly. Verify the issuer URL is accessible and `.well-known/openid-configuration` returns valid data. Check server logs for JWT validation errors.

**Prevention**: Test OIDC flow in a non-production environment first. Monitor auth logs.

> [!IMPORTANT]
> If OIDC is your sole login method, ensure `DISABLE_PASSWORD_LOGIN` is NOT set until OIDC is fully verified. Keep password login as a fallback during testing.

---

**Error**: Login fails after upgrading

**Cause**: Database schema changes or session token format changes between versions.

**Solution**: Clear browser cookies. Verify MySQL migrations completed successfully. Use `reset-password` CLI command if needed.

**Prevention**: Run database migrations explicitly during upgrades.

### 11.5 Integration Issues

**Error**: Langfuse integration broken -- `start_generation` AttributeError

**Cause**: Issue #14204 -- incompatible Langfuse SDK version in the Docker image.

**Solution**: Check the Langfuse SDK version. Pin to a compatible version. Monitor the issue for an official fix.

**Prevention**: Test Langfuse integration after image updates.

---

**Error**: QA mode recalls in knowledge base but not in agent nodes

**Cause**: Issue #6982 -- agent nodes may use different retrieval parameters than the knowledge base test interface.

**Solution**: Verify retrieval parameters (similarity threshold, top-k) match between KB settings and agent node configuration. Check that the correct KB is bound to the agent node.

**Prevention**: Align retrieval parameters across all access paths.

---

**Error**: Session crashes during chat

**Cause**: Issue #6966 -- session state corruption or memory exhaustion during complex conversations.

**Solution**: Restart the API server. Check memory usage. Clear the session cache in Redis.

**Prevention**: Monitor Redis memory usage. Set conversation length limits.

---

**Error**: Robot returns garbled/weird responses to basic questions

**Cause**: Issue #6964 -- LLM configuration issue, wrong model selected, or prompt template corruption.

**Solution**: Verify the chat model is correctly configured. Check the system prompt. Test the model directly via the LLM provider's API.

**Prevention**: Validate LLM configuration after setup. Use model testing endpoints.

### 11.6 Elasticsearch Issues

**Error**: Elasticsearch cluster yellow/red status

**Cause**: Unassigned replica shards (yellow) or missing primary shards (red).

**Solution**: For yellow: expected on single-node. Set `number_of_replicas: 0` for single-node deployments. For red: check disk space, node health, and recovery status.

**Prevention**: Monitor disk space. Use Kibana for proactive alerting.

---

**Error**: Elasticsearch out of memory

**Cause**: Heap size too small for index volume.

**Solution**: Increase `ES_JAVA_OPTS` heap allocation. Minimum: set to 50% of container memory, not exceeding 31GB.

**Prevention**: Size Elasticsearch heap according to index volume. Monitor JVM metrics via Kibana.

### 11.7 MinIO Issues

**Error**: File upload fails with connection refused

**Cause**: MinIO container not running or port mismatch.

**Solution**: Verify MinIO is running: `docker ps | grep minio`. Check port mapping matches `service_conf.yaml`. Verify MinIO access keys.

**Prevention**: Include MinIO in health check monitoring.

---

**Error**: Storage full, uploads rejected

**Cause**: MinIO disk volume exhausted.

**Solution**: Expand the storage volume. Remove old/unused files. Check for orphaned objects.

**Prevention**: Monitor disk usage. Set up alerting at 80% capacity.

### 11.8 Redis Issues

**Error**: Cache evictions causing performance degradation

**Cause**: Redis `maxmemory` (128MB default) too small for the working set.

**Solution**: Increase `maxmemory` in the Redis configuration. Monitor `evicted_keys` metric.

**Prevention**: Size Redis memory to match your active user count and session volume.

### 11.9 Sandbox Issues

**Error**: Sandbox code execution times out

**Cause**: `SANDBOX_TIMEOUT` (default 10s) too short for the operation.

**Solution**: Increase `SANDBOX_TIMEOUT`. Check that sandbox base images are pre-pulled. Verify Docker daemon responsiveness.

**Prevention**: Pre-pull sandbox base images. Size timeout to expected workload.

---

**Error**: Sandbox container creation fails

**Cause**: Docker socket not accessible or Docker daemon out of resources.

**Solution**: Verify `docker.sock` is mounted. Check Docker daemon logs. Verify container limits haven't been exceeded.

**Prevention**: Monitor Docker daemon health. Set container cleanup policies.

### 11.10 OceanBase Issues

**Error**: DDL timeout during index creation

**Cause**: `OB_DDL_TIMEOUT` (default 60s) exceeded for large table operations.

**Solution**: Increase `OB_DDL_TIMEOUT`. Check OceanBase server load.

**Prevention**: Schedule DDL operations during low-traffic periods.

---

**Error**: Metadata creation fails

**Cause**: Issue #14188 -- error during metadata table operations.

**Solution**: Check OceanBase connection. Verify table schema. Check server logs for the specific SQL error.

**Prevention**: Test metadata operations in a staging environment.

### 11.11 MySQL Issues

**Error**: Connection refused or authentication failure after upgrade

**Cause**: MySQL 8.0 authentication plugin changes or configuration drift.

**Solution**: Verify MySQL credentials in `service_conf.yaml`. Check that the `mysql` container is healthy. Verify TLS settings match between server and client.

**Prevention**: Pin MySQL version in docker-compose. Test connectivity after upgrades.

---

**Error**: Database migration fails on startup

**Cause**: Schema version mismatch between application code and database state.

**Solution**: Check migration logs. Run migrations manually if needed. Verify MySQL user has DDL privileges.

**Prevention**: Back up the database before upgrades. Review migration scripts in release notes.

### 11.12 Build Issues

**Error**: `build.sh` fails during C++ compilation

**Cause**: Missing build dependencies (cmake, g++, libpcre2-dev).

**Solution**: Install required build tools. On Ubuntu: `apt-get install cmake g++ libpcre2-dev`. Verify cmake version is 4.0+.

**Prevention**: Use the provided Dockerfile for consistent build environments.

---

**Error**: Go binary build fails with CGO errors

**Cause**: C++ static library not built or not found.

**Solution**: Run the C++ build step first. Verify `librag_tokenizer_c_api.a` exists. Ensure `CGO_ENABLED=1` is set.

**Prevention**: Always run the full `build.sh` sequence.

### 11.13 GraphRAG Issues

**Error**: Graph extraction aborts after repeated errors

**Cause**: `GRAPHRAG_MAX_ERRORS` (default 3) threshold reached during entity extraction.

**Solution**: Increase `GRAPHRAG_MAX_ERRORS`. Check LLM provider connectivity. Verify the document content is suitable for graph extraction.

**Prevention**: Monitor extraction logs. Ensure LLM provider has sufficient quota.

---

_Generated May 2026 from infiniflow/ragflow at 6712b50. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._