Environment Variable Configuration Guide

This document provides all environment variables supported by cnAPI and their configuration instructions. You can customize system behavior by setting these environment variables.

[!TIP] Tip cnAPI supports reading environment variables from the .env file. Please refer to the .env.example file and rename it to .env for use.

Basic Configuration

Environment Variable	Description	Default Value	Example
`PORT`	Service listening port	`3000`	`PORT=8080`
`TZ`	Time zone setting	-	`TZ=America/New_York`
`VERSION`	Override running version number	-	`VERSION=1.2.3`

Database Configuration

Environment Variable	Description	Default Value	Example
`SQL_DSN`	Database connection string	SQLite (data/one-api.db)	MySQL: `SQL_DSN=root:123456@tcp(localhost:3306)/new-api` \| PostgreSQL: `SQL_DSN=postgresql://root:123456@postgres:5432/new-api`
`SQL_MAX_IDLE_CONNS`	Maximum number of idle connections in the connection pool	`100`	`SQL_MAX_IDLE_CONNS=50`
`SQL_MAX_OPEN_CONNS`	Maximum number of open connections in the connection pool	`1000`	`SQL_MAX_OPEN_CONNS=500`
`SQL_MAX_LIFETIME`	Maximum connection lifetime (minutes)	`60`	`SQL_MAX_LIFETIME=120`
`LOG_SQL_DSN`	Separate database connection string for log tables	-	`LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi_logs`
`SQLITE_PATH`	SQLite database path	`/path/to/sqlite.db`	`SQLITE_PATH=/var/lib/new-api/new-api.db`

Cache Configuration

Environment Variable	Description	Default Value	Example
`REDIS_CONN_STRING`	Redis connection string	-	`REDIS_CONN_STRING=redis://default:redispw@localhost:6379`
`REDIS_POOL_SIZE`	Redis connection pool size	`10`	`REDIS_POOL_SIZE=20`
`MEMORY_CACHE_ENABLED`	Whether to enable memory cache	`false`	`MEMORY_CACHE_ENABLED=true`
`BATCH_UPDATE_ENABLED`	Enable database batch update aggregation	`false`	`BATCH_UPDATE_ENABLED=true`
`BATCH_UPDATE_INTERVAL`	Batch update aggregation interval (seconds)	`5`	`BATCH_UPDATE_INTERVAL=10`

Multi-Node and Security Configuration

Environment Variable	Description	Default Value	Example
`SESSION_SECRET`	Session secret (required for multi-machine deployment)	-	`SESSION_SECRET=random_string`
`CRYPTO_SECRET`	Encryption secret (for encrypting database content)	-	`CRYPTO_SECRET=your_crypto_secret`
`FRONTEND_BASE_URL`	Frontend base URL	-	`FRONTEND_BASE_URL=https://your-domain.com`
`SYNC_FREQUENCY`	Cache and database synchronization frequency (seconds)	`60`	`SYNC_FREQUENCY=60`
`NODE_TYPE`	Node type	`master`	`NODE_TYPE=slave`

[!INFO] Cluster Deployment For instructions on how to use these environment variables to build a complete cluster deployment, please refer to the Cluster Deployment Guide.

User and Token Configuration

Environment Variable	Description	Default Value	Example
`GENERATE_DEFAULT_TOKEN`	Generate initial Token for new registered users	`false`	`GENERATE_DEFAULT_TOKEN=true`
`NOTIFICATION_LIMIT_DURATION_MINUTE`	Notification limit duration (minutes)	`10`	`NOTIFICATION_LIMIT_DURATION_MINUTE=15`
`NOTIFY_LIMIT_COUNT`	Maximum number of notifications within the specified duration	`2`	`NOTIFY_LIMIT_COUNT=3`

Request Limit Configuration

Environment Variable	Description	Default Value	Example
`GLOBAL_API_RATE_LIMIT`	Global API rate limit (per IP, three minutes)	`180`	`GLOBAL_API_RATE_LIMIT=100`
`GLOBAL_WEB_RATE_LIMIT`	Global Web rate limit (per IP, three minutes)	`60`	`GLOBAL_WEB_RATE_LIMIT=30`
`RELAY_TIMEOUT`	Relay request timeout (seconds)	`0`	`RELAY_TIMEOUT=60`
`STREAMING_TIMEOUT`	Streaming single response timeout (seconds)	`300`	`STREAMING_TIMEOUT=120`
`MAX_FILE_DOWNLOAD_MB`	Maximum file download size (MB)	`20`	`MAX_FILE_DOWNLOAD_MB=50`
`GLOBAL_API_RATE_LIMIT_ENABLE`	Global API rate limit switch	`true`	`GLOBAL_API_RATE_LIMIT_ENABLE=false`
`GLOBAL_API_RATE_LIMIT_DURATION`	Global API rate limit window (seconds)	`180`	`GLOBAL_API_RATE_LIMIT_DURATION=120`
`GLOBAL_WEB_RATE_LIMIT_ENABLE`	Global Web rate limit switch	`true`	`GLOBAL_WEB_RATE_LIMIT_ENABLE=false`
`GLOBAL_WEB_RATE_LIMIT_DURATION`	Global Web rate limit window (seconds)	`180`	`GLOBAL_WEB_RATE_LIMIT_DURATION=120`
`CRITICAL_RATE_LIMIT_ENABLE`	Critical operation rate limit switch	`true`	`CRITICAL_RATE_LIMIT_ENABLE=false`
`CRITICAL_RATE_LIMIT`	Critical operation rate limit count	`20`	`CRITICAL_RATE_LIMIT=10`
`CRITICAL_RATE_LIMIT_DURATION`	Critical operation rate limit window (seconds)	`1200`	`CRITICAL_RATE_LIMIT_DURATION=600`

[!WARNING] RELAY_TIMEOUT Setting Warning Exercise caution when setting the RELAY_TIMEOUT environment variable. Setting it too short may lead to the following issues:

The upstream API completes the request and charges, but the local system fails to complete billing due to timeout.

Causes billing desynchronization, potentially leading to system losses.

It is recommended not to set it unless you know what you are doing.

Channel Management Configuration

Environment Variable	Description	Default Value	Example
`CHANNEL_UPDATE_FREQUENCY`	Periodically update Channel balance (minutes)	-	`CHANNEL_UPDATE_FREQUENCY=1440`
`CHANNEL_TEST_FREQUENCY`	Periodically check Channels (minutes)	-	`CHANNEL_TEST_FREQUENCY=1440`
`POLLING_INTERVAL`	Request interval when batch updating Channels (seconds)	`0`	`POLLING_INTERVAL=5`

Model and Request Processing Configuration

Environment Variable	Description	Default Value	Example
`FORCE_STREAM_OPTION`	Override client stream_options parameter	`true`	`FORCE_STREAM_OPTION=false`
`GET_MEDIA_TOKEN`	Whether to count image tokens	`true`	`GET_MEDIA_TOKEN=false`
`GET_MEDIA_TOKEN_NOT_STREAM`	Whether to count image tokens in non-streaming mode	`false`	`GET_MEDIA_TOKEN_NOT_STREAM=false`
`UPDATE_TASK`	Whether to update asynchronous tasks (MJ, Suno)	`true`	`UPDATE_TASK=false`
`CountToken`	Whether to count text tokens	`true`	`CountToken=false`
`TASK_PRICE_PATCH`	Task price patch (comma separated)	`""`	`TASK_PRICE_PATCH=suno=0.8,mj=1.2`

Specific Model Configuration

Environment Variable	Description	Default Value	Example
`AZURE_DEFAULT_API_VERSION`	Azure Channel default API version	`2025-04-01-preview`	`AZURE_DEFAULT_API_VERSION=2023-05-15`
`COHERE_SAFETY_SETTING`	Cohere model safety setting	`NONE`	`COHERE_SAFETY_SETTING=CONTEXTUAL`
`GEMINI_VISION_MAX_IMAGE_NUM`	Gemini model maximum image count	`16`	`GEMINI_VISION_MAX_IMAGE_NUM=8`
`DIFY_DEBUG`	Dify Channel output workflow and node information	`true`	`DIFY_DEBUG=false`

Other Configuration

Environment Variable	Description	Default Value	Example
`ERROR_LOG_ENABLED`	Whether to record and display error logs on the frontend	false	`ERROR_LOG_ENABLED=true`

Analytics and Statistics

Environment Variable	Description	Default Value	Example
`UMAMI_WEBSITE_ID`	Umami Website ID	-	`UMAMI_WEBSITE_ID=xxxx-xxxx`
`UMAMI_SCRIPT_URL`	Umami Script URL	`https://analytics.umami.is/script.js`	`UMAMI_SCRIPT_URL=https://umami.example.com/script.js`
`GOOGLE_ANALYTICS_ID`	Google Analytics Site ID	-	`GOOGLE_ANALYTICS_ID=G-XXXXXXX`

Metadata Synchronization

Environment Variable	Description	Default Value	Example
`SYNC_UPSTREAM_BASE`	Model/Vendor metadata upstream address	`https://basellm.github.io/llm-metadata`	`SYNC_UPSTREAM_BASE=https://mirror.example.com/llm-metadata`
`SYNC_HTTP_TIMEOUT_SECONDS`	Sync HTTP timeout (seconds)	`10`	`SYNC_HTTP_TIMEOUT_SECONDS=15`
`SYNC_HTTP_RETRY`	Sync retry count	`3`	`SYNC_HTTP_RETRY=5`
`SYNC_HTTP_MAX_MB`	Maximum response body size (MB)	`10`	`SYNC_HTTP_MAX_MB=20`

Frontend Configuration

Environment Variable	Description	Default Value	Example
`VITE_REACT_APP_SERVER_URL`	Frontend base address for backend requests	-	`VITE_REACT_APP_SERVER_URL=https://api.example.com`

Deprecated Environment Variables

The following environment variables have been deprecated. Please use the corresponding options in the System Settings interface:

Environment Variable	Alternative Method
`GEMINI_MODEL_MAP`	Please set in System Settings - Model Related Settings
`GEMINI_SAFETY_SETTING`	Please set in System Settings - Model Related Settings

Multi-Machine Deployment Example

In multi-machine deployment scenarios, the following environment variables must be set:

Master Node Configuration

# Database Configuration - Use remote database
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# Security Configuration
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis Cache Configuration
REDIS_CONN_STRING=redis://default:password@redis-server:6379

Slave Node Configuration

# Database Configuration - Use the same remote database
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# Security Configuration - Use the same secrets as the master node
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis Cache Configuration - Use the same Redis as the master node
REDIS_CONN_STRING=redis://default:password@redis-server:6379

# Node Type Setting
NODE_TYPE=slave

# Optional: Frontend Base URL
FRONTEND_BASE_URL=https://your-domain.com

# Optional: Sync Frequency
SYNC_FREQUENCY=60

[!TIP] Complete Cluster Configuration This is just a basic multi-node configuration example. For complete cluster deployment configuration, architectural description, and best practices, please refer to the Cluster Deployment Guide.

Docker Compose Environment Variable Example

Below is a brief example of setting environment variables in a Docker Compose configuration file:

services:
  new-api:
    image: calciumion/new-api:latest
    environment:
      - TZ=Asia/Shanghai
      - SQL_DSN=root:123456@tcp(mysql:3306)/oneapi
      - REDIS_CONN_STRING=redis://default:redispw@redis:6379
      - SESSION_SECRET=your_unique_session_secret
      - CRYPTO_SECRET=your_unique_crypto_secret
      - MEMORY_CACHE_ENABLED=true
      - GENERATE_DEFAULT_TOKEN=true
      - STREAMING_TIMEOUT=120
      - CHANNEL_UPDATE_FREQUENCY=1440

For the complete Docker Compose configuration, including more environment variable setting options, please refer to the Docker Compose Configuration Instructions document.

No modification is required under normal circumstances

Environment Variable	Description	Default Value	Example
`LINUX_DO_TOKEN_ENDPOINT`	LinuxDo Token Endpoint	`https://connect.linux.do/oauth2/token`	`LINUX_DO_TOKEN_ENDPOINT=https://connect.linux.do/oauth2/token`
`LINUX_DO_USER_ENDPOINT`	LinuxDo User Endpoint	`https://connect.linux.do/api/user`	`LINUX_DO_USER_ENDPOINT=https://connect.linux.do/api/user`

Environment Variable	Description	Default Value	Example
`ENABLE_PPROF`	Enable pprof performance analysis	`false`	`ENABLE_PPROF=true`
`DEBUG`	Enable debug mode	`false`	`DEBUG=true`
`GIN_MODE`	Gin running mode	-	`GIN_MODE=release`

Environment Variable Configuration Guide

On this page