iTi-Flask/docs/CONFIGURATION.md

配置

配置类是 dataclass。 默认环境是 dev。

环境选择

APP_ENV=dev uv run uvicorn main:app --reload
APP_ENV=prod uv run uvicorn main:app

也可以显式传入：

from iti import create_app

app = create_app(config_name="test", config_mapping=config)

默认数据库

dev/test/prod 默认都使用 MySQL。 设置 DATABASE_DIALECT=postgresql 时，默认连接串改为 PostgreSQL。 DATABASE_URL 始终优先。

mysql+pymysql://root:password@127.0.0.1:3306/iti_dev?charset=utf8mb4
mysql+pymysql://root:password@127.0.0.1:3306/iti_test?charset=utf8mb4
mysql+pymysql://root:password@127.0.0.1:3306/iti_prod?charset=utf8mb4
postgresql+psycopg://postgres:password@127.0.0.1:5432/iti_dev

可用环境变量覆盖：

DATABASE_URL=mysql+pymysql://user:pass@host:3306/app?charset=utf8mb4
DATABASE_DIALECT=mysql
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_DATABASE=iti_dev

DATABASE_DIALECT=postgresql
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=iti_dev

单元测试可以传入 SQLite 配置。 这不改变默认配置。

env 文件

框架会从当前目录加载第一个存在的文件：

1. .env.local
2. .env.<APP_ENV>
3. .env

APP_ENV_DIR 可指定查找目录。

常用字段

字段	说明
app_name	FastAPI 标题
debug	debug 标记
secret_key	框架密钥
jwt_secret_key	JWT 密钥
database_url	SQLAlchemy URL
cors_origins	CORS origin 列表
health_enabled	是否注册 /health 和 /ready
ready_check_db	/ready 是否执行 DB ping
response_envelope_http_status	envelope 响应使用的 HTTP 状态码，默认 200
response_envelope_enabled	是否启用自动 envelope
raw_response_paths	跳过自动 envelope 的路径，支持 *，默认包含 /health、/ready、/docs、/openapi.json
docs_ui_enabled	/docs 选择页展示的文档 UI，默认 swagger、scalar、redoc
ratelimit_enabled	是否启用内存限流
cache_default_timeout	默认缓存秒数
file_storage	文件存储配置
services	服务客户端配置
service_tokens	可信服务 token
tasks_enabled	是否启动单机任务调度线程
exchange_enabled	是否默认自动挂载本地交换模块
exchange_default_storage	导入导出默认文件存储类型
exchange_storage	导入导出文件存储配置
log_dir	运行日志目录
log_file_enabled	是否写滚动日志文件
audit_enabled	是否发送审计事件
audit_service_name	审计接收服务名，默认 audit

业务项目覆盖

from dataclasses import dataclass

from iti.config import DevConfig as BaseDevConfig


class DevConfig(BaseDevConfig):
    def __init__(self) -> None:
        super().__init__()
        self.app_name = "my-app"
        self.ready_check_db = True


config = {"dev": DevConfig, "default": DevConfig}