Configuration
About 2704 wordsAbout 9 min
Tips
When configuring plugins or deployment parameters, have AI check backend/core/conf.py, .env, plugin [settings], and configuration priority together with fba skills to reduce environment-related issues.
fba configuration lives in backend/core/conf.py. All application and plugin settings should be placed in this file. Settings tagged with env default to environment variable configuration.
Configuration Standards
fba splits configuration into static and dynamic. Static configuration is resolved when Settings is initialized; dynamic configuration is loaded on demand from the parameter-config plugin during business runtime.
Configuration Priority
Effective priority from highest to lowest:
Static configuration priority is defined by Settings.settings_customise_sources():
System env vars -> .env -> Plugin settings -> conf.py defaultsEarlier sources take higher priority. Plugin [settings] in plugin.toml only provide hot-pluggable defaults and cannot override system environment variables or .env.
Dynamic configuration is not a Pydantic Settings source. It is a runtime override layer applied after static configuration is resolved. When business code calls the dynamic config loader, values from the parameter-config plugin override same-named values already resolved into the settings singleton. Fields that are not configured or not mapped are left unchanged by that load.
Usage Boundaries
- System environment variables: for container, CI/CD, and production injection — secrets, connection info, and environment-specific settings
.env: for local or single-machine deployment; do not commit real secrets- Plugin
[settings]: non-sensitive, public, hot-pluggable default values for plugins conf.py: field declarations, type constraints, and built-in defaults — the global configuration contract- Dynamic configuration: business settings that need to be adjusted at runtime via the admin UI; only fields explicitly declared in the loader with type converters may be overridden
Environment Configuration
ENVIRONMENT Literal['dev', 'prod'] env
Environment mode. When set to prod, OpenAPI-related online docs are disabled.
FastAPI Configuration
FASTAPI_API_V1_PATH str
API version path configuration
FASTAPI_TITLE str
OpenAPI online docs title
FASTAPI_DESCRIPTION str
OpenAPI online docs description
FASTAPI_DOCS_URL str
Swagger docs URL
FASTAPI_REDOC_URL str
ReDoc docs URL
FASTAPI_OPENAPI_URL str | None
OpenAPI JSON data URL
FASTAPI_STATIC_FILES bool
Whether to enable FastAPI static file serving
Database Configuration
DATABASE_TYPE Literal['mysql', 'postgresql'] env
Database type. Only postgresql and mysql are supported. Check third-party plugin compatibility.
DATABASE_HOST str env
Database host address
DATABASE_PORT int env
Database port number
DATABASE_USER str env
Database username
DATABASE_PASSWORD str env
Database password
DATABASE_ECHO bool | Literal['debug']
Whether to output SQLAlchemy operation logs
DATABASE_POOL_ECHO bool | Literal['debug']
Whether to output SQLAlchemy pool operation logs
DATABASE_SCHEMA str
Database name to connect to
DATABASE_CHARSET str
Database charset (MySQL only)
DATABASE_PK_MODE Literal['autoincrement', 'snowflake']
Database primary-key mode. More details: Switch primary key
Caution
Do not change this setting casually!!! It can cause fatal issues!!!
Redis Configuration
REDIS_HOST str env
Redis server host address
REDIS_PORT int env
Redis server port number
REDIS_PASSWORD str env
Redis password
REDIS_DATABASE int env
Default Redis logical database index used globally (0–15)
REDIS_TIMEOUT int
Socket read/write timeout and Redis TCP connection timeout
Cache Configuration
CACHE_LOCAL_ENABLED bool
Whether to enable local cache
CACHE_LOCAL_MAXSIZE int
Local cache maximum capacity
CACHE_LOCAL_TTL int
Local cache TTL (seconds)
CACHE_REDIS_TTL int
Redis cache TTL (seconds)
CACHE_CONFIG_REDIS_PREFIX str
Redis prefix for system config cache
CACHE_DICT_REDIS_PREFIX str
Redis prefix for dictionary cache
CACHE_PUBSUB_CHANNEL str
Cache invalidation pub/sub channel
CACHE_PUBSUB_RECONNECT_DELAY int
Cache pub/sub reconnect delay (seconds)
CACHE_PUBSUB_MAX_RECONNECT_ATTEMPTS int
Cache pub/sub maximum reconnect attempts
Snowflake
SNOWFLAKE_ENABLED bool
Whether to enable the Snowflake algorithm as the distributed primary-key generation strategy
SNOWFLAKE_DATACENTER_ID int | None env
Snowflake datacenter ID
SNOWFLAKE_WORKER_ID int | None env
Snowflake worker ID
Warning
SNOWFLAKE_DATACENTER_ID and SNOWFLAKE_WORKER_ID must both be non-None or both be None.
When both are non-None, Snowflake uses these values (suitable for single-machine, single-process scenarios).
When both are None, Snowflake allocates them automatically (suitable for multi-thread, multi-process, and distributed scenarios).
SNOWFLAKE_REDIS_PREFIX str
Redis prefix for Snowflake configuration storage
SNOWFLAKE_HEARTBEAT_INTERVAL_SECONDS int
Heartbeat interval (seconds) after Snowflake configuration is stored in Redis
Warning
This value should not be greater than SNOWFLAKE_NODE_TTL_SECONDS
SNOWFLAKE_NODE_TTL_SECONDS int
TTL (seconds) for Snowflake configuration stored in Redis
Token Configuration
TOKEN_SECRET_KEY str env
Secret key for token generation and parsing, used to prevent token tampering. Generate with: secrets.token_urlsafe(32)
Caution
Keep this value secure to avoid malicious attacks.
TOKEN_ALGORITHM str
Token encryption algorithm
TOKEN_EXPIRE_SECONDS int
Token expiration time (seconds)
TOKEN_REFRESH_EXPIRE_SECONDS int
Refresh token expiration time (seconds)
TOKEN_REDIS_PREFIX str
Redis prefix for token storage
TOKEN_EXTRA_INFO_REDIS_PREFIX str
Redis prefix for token extra info storage
TOKEN_ONLINE_REDIS_PREFIX str
Redis prefix for token online status storage
TOKEN_REFRESH_REDIS_PREFIX str
Redis prefix for refresh token storage
TOKEN_REQUEST_UNDERLYING_SECURITY bool
Whether to enable request-level underlying security checks
TOKEN_REQUEST_PATH_EXCLUDE list[str]
JWT / RBAC route whitelist. Requests matching these paths will not have token authenticity checked.
Warning
fba uses JWT middleware to parse tokens, obtain user info, and assign it to the FastAPI request object. If a route is included in this configuration, request.user will be unavailable.
TOKEN_REQUEST_PATH_EXCLUDE_PATTERN list[Pattern[str]]
JWT / RBAC route whitelist as regex patterns matched from the start of the route. Matching request paths will not have token authenticity checked. Same caveats as above.
User Security Configuration
USER_LOCK_REDIS_PREFIX str
Redis prefix for user lock storage
USER_LOCK_THRESHOLD int
Password-error lock threshold. 0 disables locking.
USER_LOCK_SECONDS int
User lock duration (seconds)
USER_PASSWORD_EXPIRY_DAYS int
Password validity period in days. 0 means never expires.
USER_PASSWORD_REMINDER_DAYS int
Password expiry reminder in days. 0 means no reminder.
USER_PASSWORD_HISTORY_CHECK_COUNT int
Number of historical passwords checked to prevent reuse
USER_PASSWORD_MIN_LENGTH int
Minimum password length
USER_PASSWORD_MAX_LENGTH int
Maximum password length
USER_PASSWORD_REQUIRE_SPECIAL_CHAR bool
Whether passwords require special characters
Login Configuration
LOGIN_CAPTCHA_ENABLED bool
Whether to enable login captcha
LOGIN_CAPTCHA_REDIS_PREFIX str
Redis prefix for login captcha storage
LOGIN_CAPTCHA_EXPIRE_SECONDS int
Login captcha expiration time (seconds)
LOGIN_FAILURE_PREFIX str
Redis prefix for login failure storage
JWT Configuration
JWT_USER_REDIS_PREFIX str
Redis prefix used by JWT middleware to store user info
RBAC Configuration
RBAC_ROLE_MENU_MODE bool
Whether to enable RBAC role-menu mode
RBAC_ROLE_MENU_EXCLUDE list[str]
When role-menu mode is enabled, permission identifiers that skip RBAC authorization (when the API permission identifier matches the user's menu permission identifier)
Cookie Configuration
COOKIE_REFRESH_TOKEN_KEY str
Cookie key name when storing the refresh token
COOKIE_REFRESH_TOKEN_EXPIRE_SECONDS int
Cookie expiration time for the refresh token (seconds)
Data Permission Configuration
DATA_PERMISSION_MODEL_EXCLUDE list[str]
SQLAlchemy models excluded from data filtering
DATA_PERMISSION_COLUMN_EXCLUDE list[str]
SQLAlchemy model columns excluded from data filtering, e.g. id, password
DATA_PERMISSION_MODEL_TEMPLATE_VARIABLES list[dict[str, str]]
Template variables available for data-rule models
DATA_PERMISSION_COLUMN_TEMPLATE_VARIABLES list[dict[str, str]]
Template variables available for data-rule columns
DATA_PERMISSION_TEMPLATE_VARIABLES list[dict[str, str]]
Template variables available for data-rule values
Socket.IO Configuration
WS_NO_AUTH_MARKER str
Marker that skips user authentication when connecting to the Socket.IO service
Caution
Keep this value secure to avoid malicious attacks.
CORS Configuration
CORS_ALLOWED_ORIGINS list[str]
Allowed origins for cross-origin requests, without a trailing /, e.g. http//127.0.0.1:8000
CORS_EXPOSE_HEADERS list[str]
Exposed headers for cross-origin responses; these headers may be added to request headers
Middleware Configuration
MIDDLEWARE_CORS bool
Whether to enable the CORS middleware
Request Limiter Configuration
REQUEST_LIMITER_REDIS_PREFIX str
Redis prefix for recording request rate information
Time Configuration
DATETIME_TIMEZONE str
Global timezone
DATETIME_FORMAT str
Format used when converting datetime to string
File Upload Configuration
Warning
Some settings may be overridden by nginx.
UPLOAD_READ_SIZE int
Buffer size when reading file content during upload
UPLOAD_IMAGE_EXT_INCLUDE list[str]
Allowed image file types for upload
UPLOAD_IMAGE_SIZE_MAX int
Maximum allowed image file size
UPLOAD_VIDEO_EXT_INCLUDE list[str]
Allowed video file types for upload
UPLOAD_VIDEO_SIZE_MAX int
Maximum allowed video file size
Demo Mode Configuration
DEMO_MODE bool
Whether to enable demo mode. When enabled, only GET and OPTIONS requests are allowed.
DEMO_MODE_EXCLUDE set[tuple[str, str]]
APIs that are not rate-restricted when demo mode is enabled
IP Location Configuration
IP_LOCATION_PARSE Literal['online', 'offline', 'false']
Mode for resolving the requester's location information
IP_LOCATION_REDIS_PREFIX str
Redis prefix for location information storage
IP_LOCATION_EXPIRE_SECONDS int
Location information cache duration (seconds)
Trace ID
TRACE_ID_REQUEST_HEADER_KEY str
Trace ID request header key name
TRACE_ID_LOG_LENGTH int
Trace ID log length; must be less than or equal to 32
TRACE_ID_LOG_DEFAULT_VALUE str
Default Trace ID value in logs
Logging
LOG_FORMAT str
Log content format (shared by console and file)
Logging (Console)
LOG_STD_LEVEL str
Log level
Logging (File)
LOG_FILE_ACCESS_LEVEL str
Access log level
LOG_FILE_ERROR_LEVEL str
Error log level
LOG_ACCESS_FILENAME str
Access log filename
LOG_ERROR_FILENAME str
Error log filename
Operation Logs
OPERA_LOG_PATH_EXCLUDE list[str]
Operation log path exclusions. Request paths in this list will not record operation logs.
OPERA_LOG_REDACT_KEYS list[str]
Keys to redact from API request parameters in operation logs
OPERA_LOG_QUEUE_MAXSIZE int
Operation log queue maximum capacity
OPERA_LOG_QUEUE_BATCH_CONSUME_SIZE int
Operation log queue batch consume size. When the limit is reached, operation logs are written to the database in batches.
OPERA_LOG_QUEUE_TIMEOUT int
Operation log queue timeout. When the limit is reached, operation logs are written to the database in batches.
OPERA_LOG_BODY_MAX_SIZE int
Maximum number of bytes of request body content recorded in operation logs
Plugin Configuration
PLUGIN_REQUIRED list[str]
Plugins that must be loaded when the project starts
PLUGIN_PIP_CHINA bool
Whether to use a China mirror when downloading plugin dependencies via pip
PLUGIN_PIP_INDEX_URL str
Index URL when downloading plugin dependencies via pip
PLUGIN_PIP_MAX_RETRY int
Maximum pip download retry count
PLUGIN_REDIS_PREFIX str
Redis prefix for plugin information storage
I18n Configuration
I18N_DEFAULT_LANGUAGE str
Default language for internationalized responses
Grafana Configuration
GRAFANA_METRICS_ENABLE bool
Whether to enable the Grafana suite
Warning
If you do not need observability integration, we recommend leaving this disabled.
GRAFANA_OTLP_GRPC_ENDPOINT str
Grafana OTLP gRPC endpoint for sending telemetry data
GRAFANA_PROMETHEUS_APP_NAME str
Application name identifying the backend service in Prometheus
GRAFANA_CELERY_OTEL_SERVICE_NAME str
Service name used when Celery workers report OpenTelemetry data
GRAFANA_METRICS_PATH str
Path Prometheus uses to scrape FastAPI metrics
GRAFANA_PROMETHEUS_EXEMPLAR_TRACE_ID_KEY str
Label key name for correlating Trace IDs in Prometheus exemplars
App: Task
CELERY_BROKER_REDIS_DATABASE int env
Redis logical database used by the Celery broker
CELERY_RABBITMQ_HOST str env
Host address for Celery connecting to RabbitMQ
CELERY_RABBITMQ_PORT int env
Port for Celery connecting to RabbitMQ
CELERY_RABBITMQ_USERNAME str env
Username for Celery connecting to RabbitMQ
CELERY_RABBITMQ_PASSWORD str env
Password for Celery connecting to RabbitMQ
CELERY_BROKER Literal['rabbitmq', 'redis']
Celery broker mode (defaults to Redis in development; forced to RabbitMQ in production)
CELERY_RABBITMQ_VHOST str
vhost for Celery connecting to RabbitMQ
CELERY_REDIS_PREFIX str
Redis prefix for Celery data storage
CELERY_TASK_MAX_RETRIES int
Maximum retry count when a Celery task fails
Plugin: Code Generator
CODE_GENERATOR_DOWNLOAD_ZIP_FILENAME str
ZIP archive filename when downloading generated code
Plugin: OAuth2
OAUTH2_GITHUB_CLIENT_ID str env
GitHub client ID
OAUTH2_GITHUB_CLIENT_SECRET str env
GitHub client secret
OAUTH2_GOOGLE_CLIENT_ID str env
Google client ID
OAUTH2_GOOGLE_CLIENT_SECRET str env
Google client secret
OAUTH2_STATE_REDIS_PREFIX str
Redis prefix for OAuth2 state information storage
OAUTH2_STATE_EXPIRE_SECONDS int
OAuth2 state information expiration time in Redis (seconds)
OAUTH2_GITHUB_REDIRECT_URI str
GitHub redirect URI; must match the GitHub OAuth Apps configuration
OAUTH2_GOOGLE_REDIRECT_URI str
Google redirect URI; must match the Google OAuth 2.0 client configuration
OAUTH2_FRONTEND_LOGIN_REDIRECT_URI str
Frontend redirect URI after successful login
OAUTH2_FRONTEND_BINDING_REDIRECT_URI str
Frontend redirect URI after successful binding
Plugin: Email
EMAIL_USERNAME str env
Email sender username
EMAIL_PASSWORD str env
Email sender password
EMAIL_HOST str
Email service host address
EMAIL_PORT int
Email service host port
EMAIL_SSL bool
Whether to enable SSL when sending email
EMAIL_CAPTCHA_REDIS_PREFIX str
Redis prefix for email captcha storage
EMAIL_CAPTCHA_EXPIRE_SECONDS int
Email captcha cache duration (seconds)