--- url: /fastapi_best_architecture_docs/backend/reference/conf.md --- ::: tip 配置插件或部署参数时，可以让 AI 结合 [fba skills](https://skills.sh/fastapi-practices/skills/fba) 检查 backend/core/conf.py、.env、插件 \[settings] 和配置优先级，减少环境差异导致的问题 ::: fba 配置文件位于 `backend/core/conf.py` ，所有应用和插件的配置都应统一放置在此文件内，包含 标签的配置默认为环境变量配置 ## 环境配置 ### `ENVIRONMENT` 指定环境模式，当设置为 `prod` 时，openapi 相关在线文档将被禁止访问 ## FastAPI 配置 ### `FASTAPI_API_V1_PATH` API 版本号配置 ### `FASTAPI_TITLE` openapi 相关在线文档标头配置 ### `FASTAPI_DESCRIPTION` openapi 相关在线文档描述信息 ### `FASTAPI_DOCS_URL` docs 在线文档地址 ### `FASTAPI_REDOC_URL` redoc 在线文档地址 ### `FASTAPI_OPENAPI_URL` openapi JSON 数据在线地址 ### `FASTAPI_STATIC_FILES` 是否开启 FastAPI 静态文件服务 ## 数据库配置 ### `DATABASE_TYPE` 数据库类型，仅支持 `postgresql` 和 `mysql`，需注意第三方插件兼容性 ### `DATABASE_HOST` 数据库的主机地址 ### `DATABASE_PORT` 数据库的端口号 ### `DATABASE_USER` 数据库用户名 ### `DATABASE_PASSWORD` 数据库认证密码 ### `DATABASE_ECHO` 是否输出 sqlalchemy 操作日志 ### `DATABASE_POOL_ECHO` 是否输出 sqlalchemy 线程池操作日志 ### `DATABASE_SCHEMA` 需要连接的数据库 ### `DATABASE_CHARSET` 数据库字符集，仅用于 mysql ### `DATABASE_PK_MODE` 数据库主键模式，更多详情：[切换主键](./pk.md) ::: caution 不要随意更新此配置！！！否则将导致致命问题！！！ ::: ## Redis 配置 ### `REDIS_HOST` Redis 服务器的主机地址 ### `REDIS_PORT` Redis 服务器的端口号 ### `REDIS_PASSWORD` Redis 认证密码 ### `REDIS_DATABASE` 全局默认使用的 Redis 逻辑数据库索引（0 - 15） ### `REDIS_TIMEOUT` Socket 读写操作的超时时间和 Redis 建立 TCP 连接时的超时时间 ## 缓存配置 ### `CACHE_LOCAL_ENABLED` 是否启用本地缓存 ### `CACHE_LOCAL_MAXSIZE` 本地缓存最大容量 ### `CACHE_LOCAL_TTL` 本地缓存过期时长（秒） ### `CACHE_REDIS_TTL` Redis 缓存过期时长（秒） ### `CACHE_CONFIG_REDIS_PREFIX` 系统配置缓存存储到 Redis 时的前缀 ### `CACHE_DICT_REDIS_PREFIX` 字典缓存存储到 Redis 时的前缀 ### `CACHE_PUBSUB_CHANNEL` 缓存失效发布订阅频道 ### `CACHE_PUBSUB_RECONNECT_DELAY` 缓存发布订阅重连延迟（秒） ### `CACHE_PUBSUB_MAX_RECONNECT_ATTEMPTS` 缓存发布订阅最大重连次数 ## Snowflake（雪花算法） ### `SNOWFLAKE_ENABLED` 是否启用雪花算法作为分布式主键生成方案 ### `SNOWFLAKE_DATACENTER_ID` 雪花算法数据中心 ID ### `SNOWFLAKE_WORKER_ID` 雪花算法工作机器 ID ::: warning `SNOWFLAKE_DATACENTER_ID` 和 `SNOWFLAKE_WORKER_ID` 仅允许同时非 None 或同时为 None 同时非 None 时，雪花算法将应用此配置（适用于单机单进程场景） 同时为 None 时，雪花算法将自动分配此配置（适用于多线程，多进程，分布式等场景） ::: ### `SNOWFLAKE_REDIS_PREFIX` 雪花算法配置存储到 Redis 时的前缀 ### `SNOWFLAKE_HEARTBEAT_INTERVAL_SECONDS` 雪花算法配置存储到 Redis 后的心跳检测间隔时间（秒） ::: warning 此配置不应大于 `SNOWFLAKE_NODE_TTL_SECONDS` ::: ### `SNOWFLAKE_NODE_TTL_SECONDS` 雪花算法配置存储到 Redis 时的生存时间（秒） ## Token 配置 ### `TOKEN_SECRET_KEY` token 生成和解析密钥，用于防止 token 被恶意篡改，密钥生成：`secrets.token_urlsafe(32)` ::: danger 请妥善保管此值，以免遭受恶意攻击 ::: ### `TOKEN_ALGORITHM` token 加密算法 ### `TOKEN_EXPIRE_SECONDS` token 过期时长（秒） ### `TOKEN_REFRESH_EXPIRE_SECONDS` 刷新 token 过期时长（秒） ### `TOKEN_REDIS_PREFIX` token 存储到 Redis 时的前缀 ### `TOKEN_EXTRA_INFO_REDIS_PREFIX` token 扩展信息存储到 Redis 时的前缀 ### `TOKEN_ONLINE_REDIS_PREFIX` token 在线状态存储到 Redis 时的前缀 ### `TOKEN_REFRESH_REDIS_PREFIX` 刷新 token 存储到 Redis 时的前缀 ### `TOKEN_REQUEST_PATH_EXCLUDE` JWT / RBAC 路由白名单，在此配置内的请求地址将不会校验 token 的真伪性 ::: warning fba 内通过 JWT 中间件解析 token 获取用户信息，并将用户信息赋值给 FastAPI request 对象，如果路由包含在此配置中， `request.user` 将不可用 ::: ### `TOKEN_REQUEST_PATH_EXCLUDE_PATTERN` JWT / RBAC 路由白名单正则模式，从路由头部开始匹配，与之匹配的请求地址将不会校验 token 真伪性，注意项同上 ## 用户安全配置 ### `USER_LOCK_REDIS_PREFIX` 用户锁定存储到 Redis 时的前缀 ### `USER_LOCK_THRESHOLD` 用户密码错误锁定阈值，0 表示禁用锁定 ### `USER_LOCK_SECONDS` 用户锁定时长（秒） ### `USER_PASSWORD_EXPIRY_DAYS` 用户密码有效期，0 表示永不过期 ### `USER_PASSWORD_REMINDER_DAYS` 用户密码到期提醒，0 表示不提醒 ### `USER_PASSWORD_HISTORY_CHECK_COUNT` 用户密码历史检查数量，避免重复使用历史密码 ### `USER_PASSWORD_MIN_LENGTH` 用户密码最小长度 ### `USER_PASSWORD_MAX_LENGTH` 用户密码最大长度 ### `USER_PASSWORD_REQUIRE_SPECIAL_CHAR` 用户密码需要特殊字符 ## 登录配置 ### `LOGIN_CAPTCHA_ENABLED` 是否开启登录验证码 ### `LOGIN_CAPTCHA_REDIS_PREFIX` 登录验证码存储到 Redis 时的前缀 ### `LOGIN_CAPTCHA_EXPIRE_SECONDS` 登录验证码过期时长（秒） ### `LOGIN_FAILURE_PREFIX` 登录失败存储到 Redis 时的前缀 ## JWT 配置 ### `JWT_USER_REDIS_PREFIX` JWT 中间件存储用户信息到 Redis 时的前缀 ## RBAC 配置 [更多详情](./RBAC.md){.read-more} ### `RBAC_ROLE_MENU_MODE` 是否开启 RBAC 角色菜单模式 ### `RBAC_ROLE_MENU_EXCLUDE` 开启 RBAC 角色菜单模式时，跳过 RBAC 鉴权的标识（当接口权限标识和用户菜单权限标识相同时） ## Cookie 配置 ### `COOKIE_REFRESH_TOKEN_KEY` 将刷新 token 存储到 cookie 时的键名 ### `COOKIE_REFRESH_TOKEN_EXPIRE_SECONDS` 将刷新 token 存储到 cookie 时的过期时长（秒） ## 数据权限配置 ### `DATA_PERMISSION_MODEL_EXCLUDE` 排除允许进行数据过滤的 SQLA 模型 ### `DATA_PERMISSION_COLUMN_EXCLUDE` 排除允许进行数据过滤的 SQLA 模型列，例如 id, password 等 ### `DATA_PERMISSION_MODEL_TEMPLATE_VARIABLES` 数据规则模型可用模板变量 ### `DATA_PERMISSION_COLUMN_TEMPLATE_VARIABLES` 数据规则字段可用模板变量 ### `DATA_PERMISSION_TEMPLATE_VARIABLES` 数据规则值可用模板变量 ## Socket.IO 配置 ### `WS_NO_AUTH_MARKER` 连接 socket.io 服务时跳过用户验证的标记 ::: danger 请妥善保管此值，以免遭受恶意攻击 ::: ## CORS 配置 ### `CORS_ALLOWED_ORIGINS` 跨域请求时允许的来源，末尾不带 `/`，例如：`http//127.0.0.1:8000` ### `CORS_EXPOSE_HEADERS` 跨域公开标头，允许将此标头添加到请求标头中 ## 中间件配置 ### `MIDDLEWARE_CORS` 是否启用跨域中间件 ## 请求限制配置 ### `REQUEST_LIMITER_REDIS_PREFIX` 记录请求频率信息到 Redis 时的前缀 ## 时间配置 ### `DATETIME_TIMEZONE` 全局时区 ### `DATETIME_FORMAT` 将时间转为时间字符串的格式 ## 文件上传配置 ::: warning 部分配置可能被 nginx 覆盖 ::: ### `UPLOAD_READ_SIZE` 上传文件时，每次读取文件内容的缓冲大小 ### `UPLOAD_IMAGE_EXT_INCLUDE` 允许上传的图片文件类型 ### `UPLOAD_IMAGE_SIZE_MAX` 允许上传的图片文件最大尺寸 ### `UPLOAD_VIDEO_EXT_INCLUDE` 允许上传的视频文件类型 ### `UPLOAD_VIDEO_SIZE_MAX` 允许上传的视频文件最大尺寸 ## 演示模式配置 ### `DEMO_MODE` 是否开启演示模式，开启时，仅允许访问 `GET` 和 `OPTIONS` 请求 ### `DEMO_MODE_EXCLUDE` 开启演示模式时，不进行请求限制的接口 ## IP 定位配置 ### `IP_LOCATION_PARSE` 请求发起者的定位信息获取模式 ### `IP_LOCATION_REDIS_PREFIX` 定位信息存储到 Redis 时的前缀 ### `IP_LOCATION_EXPIRE_SECONDS` 定位信息缓存时长（秒） ## Trace ID ### `TRACE_ID_REQUEST_HEADER_KEY` 跟踪 ID 请求头键名 ### `TRACE_ID_LOG_LENGTH` 跟踪 ID 日志长度，必须小于等于 32 ### `TRACE_ID_LOG_DEFAULT_VALUE` 跟踪 ID 日志默认值 ## 日志 ### `LOG_FORMAT` 日志内容格式（控制台和文件同享） ## 日志（控制台） ### `LOG_STD_LEVEL` 日志记录级别 ## 日志（文件） ### `LOG_FILE_ACCESS_LEVEL` 访问日志记录级别 ### `LOG_FILE_ERROR_LEVEL` 错误日志记录级别 ### `LOG_ACCESS_FILENAME` 访问日志文件名 ### `LOG_ERROR_FILENAME` 错误日志文件名 ## 操作日志 ### `OPERA_LOG_PATH_EXCLUDE` 操作日志路径排除，在此配置内的请求地址不会记录操作日志 ### `OPERA_LOG_REDACT_KEYS` 脱敏操作日志中的接口请求参数 ### `OPERA_LOG_QUEUE_MAXSIZE` 操作日志队列最大容量 ### `OPERA_LOG_QUEUE_BATCH_CONSUME_SIZE` 操作日志队列批量消费大小，达到上限后，操作日志将批量写入数据库 ### `OPERA_LOG_QUEUE_TIMEOUT` 操作日志队列超时时长，达到上限后，操作日志将批量写入数据库 ### `OPERA_LOG_BODY_MAX_SIZE` 操作日志记录请求体内容的最大字节数 ## 插件配置 ### `PLUGIN_REQUIRED` 项目启动时必须加载的插件列表 ### `PLUGIN_PIP_CHINA` 通过 pip 下载插件依赖时，是否使用国内源 ### `PLUGIN_PIP_INDEX_URL` 通过 pip 下载插件依赖时的索引地址 ### `PLUGIN_PIP_MAX_RETRY` pip 下载最大重试次数 ### `PLUGIN_REDIS_PREFIX` 插件信息存储到 Redis 时的前缀 ## I18n 配置 ### `I18N_DEFAULT_LANGUAGE` 国际化响应的默认语言 ## Grafana 配置 ### `GRAFANA_METRICS_ENABLE` 是否启用 Grafana 套件 ::: warning 如果不需要可观测性集成，不建议启用此功能 ::: ### `GRAFANA_OTLP_GRPC_ENDPOINT` Grafana OTLP 协议 grpc 地址，用于发送遥测数据 ### `GRAFANA_PROMETHEUS_APP_NAME` Prometheus 中标识后端服务的应用名称 ### `GRAFANA_CELERY_OTEL_SERVICE_NAME` Celery Worker 上报 OpenTelemetry 数据时使用的服务名称 ### `GRAFANA_METRICS_PATH` Prometheus 抓取 FastAPI 指标数据的路径 ### `GRAFANA_PROMETHEUS_EXEMPLAR_TRACE_ID_KEY` Prometheus exemplar 中关联 Trace ID 的标签键名 ## 应用：Task ### `CELERY_BROKER_REDIS_DATABASE` Celery 代理使用的 Redis 逻辑数据库 ### `CELERY_RABBITMQ_HOST` Celery 连接 RabbitMQ 服务的主机地址 ### `CELERY_RABBITMQ_PORT` Celery 连接 RabbitMQ 服务的主机端口号 ### `CELERY_RABBITMQ_USERNAME` Celery 连接 RabbitMQ 服务的用户名 ### `CELERY_RABBITMQ_PASSWORD` Celery 连接 RabbitMQ 服务的密码 ### `CELERY_BROKER` Celery 代理模式（开发模式默认使用 Redis，生产模式强制切换为 RabbitMQ） ### `CELERY_RABBITMQ_VHOST` Celery 连接 RabbitMQ 服务的 vhost ### `CELERY_REDIS_PREFIX` Celery 数据存储到 Redis 时的前缀 ### `CELERY_TASK_MAX_RETRIES` Celery 任务执行失败时的最大重试次数 ## 插件：Code Generator ### `CODE_GENERATOR_DOWNLOAD_ZIP_FILENAME` 下载代码时的 ZIP 压缩包文件名 ## 插件：OAuth2 ### `OAUTH2_GITHUB_CLIENT_ID` GitHub 客户端 ID ### `OAUTH2_GITHUB_CLIENT_SECRET` GitHub 客户端密钥 ### `OAUTH2_GOOGLE_CLIENT_ID` Google 客户端 ID ### `OAUTH2_GOOGLE_CLIENT_SECRET` Google 客户端密钥 ### `OAUTH2_STATE_REDIS_PREFIX` OAuth2 状态信息存储到 Redis 时的前缀 ### `OAUTH2_STATE_EXPIRE_SECONDS` OAuth2 状态信息存储到 Redis 时的过期时间（秒） ### `OAUTH2_GITHUB_REDIRECT_URI` GitHub 重定向地址，必须与 GitHub OAuth Apps 配置保持一致 ### `OAUTH2_GOOGLE_REDIRECT_URI` Google 重定向地址，必须与 Google OAuth 2.0 客户端配置保持一致 ### `OAUTH2_FRONTEND_LOGIN_REDIRECT_URI` 登陆成功后，重定向到前端的地址 ### `OAUTH2_FRONTEND_BINDING_REDIRECT_URI` 绑定成功后，重定向到前端的地址 ## 插件：Email ### `EMAIL_USERNAME` 电子邮箱发件用户 ### `EMAIL_PASSWORD` 电子邮箱发件用户密码 ### `EMAIL_HOST` 电子邮箱服务主机地址 ### `EMAIL_PORT` 电子邮箱服务主机端口号 ### `EMAIL_SSL` 发送电子邮件时，是否开启 SSL ### `EMAIL_CAPTCHA_REDIS_PREFIX` 电子邮件验证码存储到 Redis 时的前缀 ### `EMAIL_CAPTCHA_EXPIRE_SECONDS` 电子邮件验证码缓存时长（秒）