🔧 Environment Variables Configuration Guide¶
This document provides all environment variables supported by New API and their configuration instructions. You can customize the system behavior by setting these environment variables.
Tip
New API supports reading environment variables from a .env
file. Please refer to the .env.example
file and rename it to .env
when using.
🔄 Basic Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
PORT |
Service listening port | 3000 |
PORT=8080 |
TZ |
Timezone setting | Asia/Shanghai |
TZ=America/New_York |
💾 Database Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
SQL_DSN |
Database connection string | SQLite (data/one-api.db) | SQL_DSN=root:123456@tcp(localhost:3306)/oneapi |
SQL_MAX_IDLE_CONNS |
Max idle connections in pool | 100 |
SQL_MAX_IDLE_CONNS=50 |
SQL_MAX_OPEN_CONNS |
Max open connections in pool | 1000 |
SQL_MAX_OPEN_CONNS=500 |
SQL_CONN_MAX_LIFETIME |
Max connection lifetime (minutes) | 60 |
SQL_CONN_MAX_LIFETIME=120 |
LOG_SQL_DSN |
Separate database connection string for logs | - | LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi_logs |
SQLITE_BUSY_TIMEOUT |
SQLite lock wait timeout (ms) | 3000 |
SQLITE_BUSY_TIMEOUT=5000 |
📦 Cache Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
REDIS_CONN_STRING |
Redis connection string | - | REDIS_CONN_STRING=redis://default:redispw@localhost:6379 |
MEMORY_CACHE_ENABLED |
Enable in-memory cache | false |
MEMORY_CACHE_ENABLED=true |
REDIS_CONN_POOL_SIZE |
Redis connection pool size | - | REDIS_CONN_POOL_SIZE=10 |
REDIS_PASSWORD |
Redis cluster or sentinel mode password | - | REDIS_PASSWORD=your_password |
REDIS_MASTER_NAME |
Redis sentinel mode master name | - | REDIS_MASTER_NAME=mymaster |
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 & Security Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
SESSION_SECRET |
Session secret (required for multi-node 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 sync frequency (seconds) | 600 |
SYNC_FREQUENCY=60 |
NODE_TYPE |
Node type | master |
NODE_TYPE=slave |
INITIAL_ROOT_TOKEN |
Root user token created on first startup | - | INITIAL_ROOT_TOKEN=your_token |
INITIAL_ROOT_ACCESS_TOKEN |
System admin token created on first startup | - | INITIAL_ROOT_ACCESS_TOKEN=your_token |
Cluster Deployment
For how to use these environment variables to build a complete cluster deployment, please refer to the Cluster Deployment Guide.
👤 User & Token Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
DEFAULT_QUOTA |
Default quota for new users | 0 |
DEFAULT_QUOTA=10 |
GLOBAL_USER_QUOTA |
Global user quota limit | - | GLOBAL_USER_QUOTA=100 |
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 |
Max notifications in specified duration | 2 |
NOTIFY_LIMIT_COUNT=3 |
🚦 Request Limiting Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
GLOBAL_API_RATE_LIMIT |
Global API rate limit (per IP, 3 minutes) | 180 |
GLOBAL_API_RATE_LIMIT=100 |
GLOBAL_WEB_RATE_LIMIT |
Global Web rate limit (per IP, 3 minutes) | 60 |
GLOBAL_WEB_RATE_LIMIT=30 |
RELAY_TIMEOUT |
Relay request timeout (seconds) | - | RELAY_TIMEOUT=60 |
USER_CONTENT_REQUEST_TIMEOUT |
User content download timeout (seconds) | - | USER_CONTENT_REQUEST_TIMEOUT=30 |
STREAMING_TIMEOUT |
Streaming single reply timeout (seconds) | 60 |
STREAMING_TIMEOUT=120 |
MAX_FILE_DOWNLOAD_MB |
Max file download size (MB) | 20 |
MAX_FILE_DOWNLOAD_MB=50 |
RELAY_TIMEOUT Setting Warning
Be cautious when setting the RELAY_TIMEOUT
environment variable. If set too short, it may cause the following issues:
- The upstream API has completed the request and billed, but the local system did not complete billing due to timeout
- Causes billing desynchronization, which may lead to system loss
- It is recommended not to set unless you know what you are doing
📡 Channel Management Configuration¶
Environment Variable | Description | Default | 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 |
ENABLE_METRIC |
Disable channels based on request success rate | false |
ENABLE_METRIC=true |
METRIC_QUEUE_SIZE |
Request success rate statistics queue size | 10 |
METRIC_QUEUE_SIZE=20 |
METRIC_SUCCESS_RATE_THRESHOLD |
Request success rate threshold | 0.8 |
METRIC_SUCCESS_RATE_THRESHOLD=0.7 |
TEST_PROMPT |
User prompt for model testing | Print your model name exactly... |
TEST_PROMPT=Hello |
🤖 Model & Request Handling Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
FORCE_STREAM_OPTION |
Override client stream_options parameter | true |
FORCE_STREAM_OPTION=false |
GET_MEDIA_TOKEN |
Count image tokens | true |
GET_MEDIA_TOKEN=false |
GET_MEDIA_TOKEN_NOT_STREAM |
Count image tokens in non-stream mode | true |
GET_MEDIA_TOKEN_NOT_STREAM=false |
UPDATE_TASK |
Update async tasks (MJ, Suno) | true |
UPDATE_TASK=false |
ENFORCE_INCLUDE_USAGE |
Force return usage in stream mode | false |
ENFORCE_INCLUDE_USAGE=true |
TIKTOKEN_CACHE_DIR |
Tiktoken encoder cache directory, for storing tokenizer files to avoid network download | - | TIKTOKEN_CACHE_DIR=/cache/tiktoken |
DATA_GYM_CACHE_DIR |
DataGym cache directory | - | DATA_GYM_CACHE_DIR=/cache/data_gym |
Tiktoken File Configuration
After downloading tiktoken files, please rename them as follows:
cl100k_base.tiktoken
rename to9b5ad71b2ce5302211f9c61530b329a4922fc6a4
o200k_base.tiktoken
rename tofb374d419588a4632f3f557e76b4b70aebbca790
These files should be placed in the directory specified by TIKTOKEN_CACHE_DIR
to improve token calculation performance and reduce network dependency.
Tiktoken Configuration Example
# Docker environment example
TIKTOKEN_CACHE_DIR=/app/data/tiktoken
# Then download and rename tiktoken files into this directory:
/app/data/tiktoken/9b5ad71b2ce5302211f9c61530b329a4922fc6a4
/app/data/tiktoken/fb374d419588a4632f3f557e76b4b70aebbca790
Tiktoken is the tokenizer used by OpenAI to calculate the number of tokens in text. By caching these files locally, you can avoid downloading from the network every time the system starts, improving stability and performance, especially in network-restricted environments.
🔎 Specific Model Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
AZURE_DEFAULT_API_VERSION |
Default API version for Azure channel | 2024-12-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 max image number | 16 |
GEMINI_VISION_MAX_IMAGE_NUM=8 |
GEMINI_VERSION |
Gemini version | v1 |
GEMINI_VERSION=v1beta |
DIFY_DEBUG |
Output workflow and node info for Dify channel | true |
DIFY_DEBUG=false |
📨 Other Configuration¶
Environment Variable | Description | Default | Example |
---|---|---|---|
EMAIL_SERVER |
Email server configuration | - | EMAIL_SERVER=smtp.example.com:25 |
EMAIL_FROM |
Email sender address | - | EMAIL_FROM=noreply@example.com |
EMAIL_PASSWORD |
Email server password | - | EMAIL_PASSWORD=yourpassword |
ERROR_LOG_ENABLE |
Record and display error logs on frontend | false | ERROR_LOG_ENABLED=true |
⚠️ Deprecated Environment Variables¶
The following environment variables are deprecated. Please use the corresponding options in the system settings interface:
Environment Variable | Replacement |
---|---|
GEMINI_MODEL_MAP |
Please set in System Settings - Model Related Settings |
GEMINI_SAFETY_SETTING |
Please set in System Settings - Model Related Settings |
🌍 Multi-Node Deployment Example¶
In multi-node deployment scenarios, you must set the following environment variables:
👑 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 master node
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret
# Redis cache configuration - use the same Redis as 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
Full Cluster Configuration
This is just a basic multi-node configuration example. For full cluster deployment configuration, architecture explanation, and best practices, please refer to the Cluster Deployment Guide.
🐳 Environment Variables Example in Docker Compose¶
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 a complete Docker Compose configuration, including more environment variable options, please refer to the Docker Compose Configuration Guide document.