toms-fast 0.2.1__py3-none-any.whl

tomskit/cli/templates_config.py

@@ -0,0 +1,122 @@
+"""
+脚手架模板配置文件
+定义项目目录结构和文件模板
+
+注意：模板内容已迁移到 templates/ 目录下的模块化文件中：
+- templates/base.py - 基础模板
+- templates/extensions.py - 扩展模板
+- templates/fastapi.py - FastAPI 模板
+- templates/celery.py - Celery 模板
+"""
+
+from typing import Callable
+
+from .templates import get_all_templates
+
+
+# 基础目录结构（所有类型都需要）
+BASE_DIRECTORIES = {
+    "extensions": True,  # 扩展功能初始化目录
+    "tests": True,
+    "logs": False,
+    "run": False,
+}
+
+# FastAPI 相关目录
+FASTAPI_DIRECTORIES = {
+    "app/controllers": True,  # controllers 目录（__init__.py 为空）
+    "app/controllers/users": True,
+    "app/middleware": True,  # 中间件目录
+    "app/models": True,
+    "app/schemas": True,
+    "app/services": True,
+    "app/utils": True,
+    "migrations": True,  # 数据库迁移目录
+    "migrations/versions": True,  # 迁移版本目录
+}
+
+# Celery 相关目录
+CELERY_DIRECTORIES = {
+    "tasks": True,
+}
+
+
+def get_directory_structure(project_type: str) -> dict[str, bool]:
+    """根据项目类型返回目录结构"""
+    directories = BASE_DIRECTORIES.copy()
+    
+    if project_type in ("fastapi", "full"):
+        directories.update(FASTAPI_DIRECTORIES)
+    
+    if project_type in ("celery", "full"):
+        directories.update(CELERY_DIRECTORIES)
+    
+    return directories
+
+
+# 基础文件模板（所有类型都需要）
+BASE_FILES = {
+    ".env.example": "env_example",
+    ".gitignore": "gitignore",
+    "pyproject.toml": "pyproject_toml",
+    "README.md": "readme_md",
+    "extensions/__init__.py": "extensions_init_py",
+    "extensions/ext_logger.py": "extensions_logger_py",
+    "tests/__init__.py": "tests_init_py",
+}
+
+# FastAPI 相关文件
+FASTAPI_FILES = {
+    "main.py": "main_py",
+    "app/__init__.py": "app_init_py",
+    "app/config.py": "config_py",
+    "app/middleware/__init__.py": "middleware_init_py",
+    "app/middleware/request_id.py": "middleware_request_id_py",
+    "app/middleware/resource_cleanup.py": "middleware_resource_cleanup_py",
+    "extensions/ext_database.py": "extensions_database_py",
+    "extensions/ext_redis.py": "extensions_redis_py",
+    "app/controllers/__init__.py": "controllers_init_py",
+    "app/controllers/users/__init__.py": "users_init_py",
+    "app/controllers/users/resources.py": "users_resources_py",
+    "app/controllers/users/schemas.py": "users_schemas_py",
+    "app/controllers/users/module.py": "users_module_py",
+    "app/models/__init__.py": "models_init_py",
+    "app/models/user.py": "user_model_py",
+    "tests/test_users.py": "test_users_py",
+    "migrations/__init__.py": "migrations_init_py",
+    "migrations/alembic.ini": "alembic_ini",
+    "migrations/env.py": "migrations_env_py",
+    "migrations/script.py.mako": "migrations_script_py_mako",
+    "migrations/versions/__init__.py": "migrations_versions_init_py",
+}
+
+# Celery 相关文件
+CELERY_FILES = {
+    "celery_app.py": "celery_app_py",
+    "extensions/ext_celery.py": "extensions_celery_py",
+    "tasks/__init__.py": "tasks_init_py",
+    "tasks/example_task.py": "example_task_py",
+}
+
+
+def get_file_templates(project_type: str) -> dict[str, str]:
+    """根据项目类型返回文件模板映射"""
+    files = BASE_FILES.copy()
+    
+    if project_type in ("fastapi", "full"):
+        files.update(FASTAPI_FILES)
+    
+    if project_type in ("celery", "full"):
+        files.update(CELERY_FILES)
+    
+    return files
+
+
+# 文件模板内容生成函数
+def get_template_functions(project_name: str, project_type: str = "full") -> dict[str, Callable[[], str]]:
+    """
+    根据项目类型返回所有模板函数
+    
+    注意：模板内容已迁移到 templates/ 模块中，此函数现在只是转发调用
+    """
+    return get_all_templates(project_name, project_type)

tomskit/logger/README.md

@@ -0,0 +1,466 @@
+# Logger Module Guide
+
+该模块提供了结构化的日志配置和追踪 ID 支持，支持应用日志、访问日志、SQL 日志和 Celery 日志的分离，适用于 FastAPI 异步环境。
+
+## 模块概述
+
+Logger 模块基于 Python 标准库 `logging`，提供了完整的日志管理功能。主要特性包括：
+
+- 🔍 **追踪 ID 支持**：基于 `ContextVar` 实现线程/协程安全的追踪 ID，支持分布式追踪
+- 📝 **多类型日志**：支持应用日志、访问日志、SQL 日志和 Celery 日志的独立配置
+- 🔄 **日志轮转**：支持按时间自动轮转日志文件，可配置备份数量
+- 🎨 **自定义格式**：支持自定义日志格式，自动注入追踪 ID 和前缀
+- 🔇 **日志降噪**：自动管理第三方库日志级别，减少噪音
+- 🛠️ **配置管理**：基于 Pydantic Settings 的配置类，支持环境变量
+
+**Import Path:**
+```python
+from tomskit.logger import (
+    setup_logging,
+    LoggerConfig,
+    set_app_trace_id,
+    get_app_trace_id
+)
+```
+
+## 核心类和函数
+
+### LoggerConfig
+
+日志配置类，继承自 `pydantic_settings.BaseSettings`，用于管理日志系统的各项参数。
+
+```python
+class LoggerConfig(BaseSettings):
+    # === 基础配置 ===
+    LOG_PREFIX: str = Field(default="", ...)
+    LOG_DIR: str = Field(default="logs", ...)
+    LOG_NAME: str = Field(default="apps", ...)
+    LOG_LEVEL: str = Field(default="INFO", ...)
+    LOG_FORMAT: str = Field(default="[%(asctime)s] [%(levelname)s] [%(name)s] [trace_id=%(trace_id)s] %(message)s", ...)
+    LOG_USE_UTC: bool = Field(default=False, ...)
+    LOG_DATE_FORMAT: str = Field(default="%Y-%m-%d %H:%M:%S", ...)
+    LOG_BACKUP_COUNT: int = Field(default=0, ...)
+    LOG_ROTATE_WHEN: str = Field(default="midnight", ...)
+    
+    # === 访问日志配置 ===
+    LOG_ACCESS_NAME: str = Field(default="access", ...)
+    LOG_ACCESS_FORMAT: str = Field(default='%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"', ...)
+    
+    # === SQL 日志配置 ===
+    LOG_SQL_ENABLED: bool = Field(default=False, ...)
+    LOG_SQL_NAME: str = Field(default="sql", ...)
+    LOG_SQL_LEVEL: str = Field(default="INFO", ...)
+    
+    # === Celery 日志配置 ===
+    LOG_CELERY_ENABLED: bool = Field(default=False, ...)
+    LOG_CELERY_NAME: str = Field(default="celery", ...)
+    LOG_CELERY_LEVEL: str = Field(default="INFO", ...)
+    
+    # === 第三方库日志配置 ===
+    LOG_THIRD_PARTY_LEVEL: str = Field(default="WARNING", ...)
+```
+
+**配置属性说明：**
+
+**基础配置：**
+- `LOG_PREFIX`: 日志前缀，会添加到每条日志记录中，默认为空字符串
+- `LOG_DIR`: 日志文件存储目录，默认为 `logs`
+- `LOG_NAME`: 应用日志文件名（不含扩展名），默认为 `apps`
+- `LOG_LEVEL`: 应用日志级别，可选值：`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`，默认为 `INFO`
+- `LOG_FORMAT`: 应用日志格式，支持 `%(trace_id)s` 和 `%(prefix)s` 占位符，默认为 `[%(asctime)s] [%(levelname)s] [%(name)s] [trace_id=%(trace_id)s] %(message)s`
+- `LOG_USE_UTC`: 是否使用 UTC 时间，默认为 `False`（使用本地时间）
+- `LOG_DATE_FORMAT`: 日志日期时间格式，默认为 `%Y-%m-%d %H:%M:%S`
+- `LOG_BACKUP_COUNT`: 日志文件备份数量，`0` 表示不保留历史文件，默认为 `0`
+- `LOG_ROTATE_WHEN`: 日志轮转时间单位，可选值：`midnight`, `D`, `H`, `M`, `S`，默认为 `midnight`（每天午夜轮转）
+
+**访问日志配置：**
+- `LOG_ACCESS_NAME`: 访问日志文件名（不含扩展名），默认为 `access`
+- `LOG_ACCESS_FORMAT`: 访问日志格式（Apache Common Log Format），默认为 `%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"`
+
+**SQL 日志配置：**
+- `LOG_SQL_ENABLED`: 是否启用独立的 SQL 日志文件，默认为 `False`（合并到应用日志）
+- `LOG_SQL_NAME`: SQL 日志文件名（不含扩展名），默认为 `sql`
+- `LOG_SQL_LEVEL`: SQL 日志级别，默认为 `INFO`
+
+**Celery 日志配置：**
+- `LOG_CELERY_ENABLED`: 是否启用独立的 Celery 日志文件，默认为 `False`（合并到应用日志）
+- `LOG_CELERY_NAME`: Celery 日志文件名（不含扩展名），默认为 `celery`
+- `LOG_CELERY_LEVEL`: Celery 日志级别，默认为 `INFO`
+
+**第三方库日志配置：**
+- `LOG_THIRD_PARTY_LEVEL`: 第三方库日志级别（用于降噪），默认为 `WARNING`
+
+**使用示例：**
+```python
+from tomskit.logger.config import LoggerConfig
+
+# 基础配置
+config = LoggerConfig(
+    LOG_DIR="logs",
+    LOG_NAME="apps",
+    LOG_LEVEL="INFO",
+    LOG_PREFIX="[MyApp]"
+)
+
+# 启用 SQL 日志分离
+sql_config = LoggerConfig(
+    LOG_SQL_ENABLED=True,
+    LOG_SQL_LEVEL="DEBUG"
+)
+
+# 启用 Celery 日志分离
+celery_config = LoggerConfig(
+    LOG_CELERY_ENABLED=True,
+    LOG_CELERY_LEVEL="INFO"
+)
+```
+
+### setup_logging
+
+配置日志系统的主函数，设置应用日志、访问日志、SQL 日志和 Celery 日志的处理器和格式化器。
+
+```python
+def setup_logging(settings: LoggerConfig) -> None: ...
+```
+
+**功能特性：**
+- 自动创建日志目录（如果不存在）
+- 配置控制台和文件处理器
+- 设置日志轮转策略
+- 管理框架日志（uvicorn、fastapi）
+- 管理第三方库日志级别
+- 支持追踪 ID 自动注入
+
+**方法说明：**
+- 配置 Root Logger：所有 `getLogger(__name__)` 会冒泡到这里
+- 配置访问日志：单独处理 uvicorn/gunicorn 访问日志，不冒泡到 root
+- 配置框架日志：管理 uvicorn 和 fastapi 日志
+- 配置 SQL 日志：根据 `LOG_SQL_ENABLED` 决定是否分离到独立文件
+- 配置 Celery 日志：根据 `LOG_CELERY_ENABLED` 决定是否分离到独立文件
+- 第三方库降噪：自动设置 HTTP 客户端、AWS SDK 等库的日志级别
+
+**异常处理：**
+- `OSError`: 当日志目录创建失败时抛出
+- `PermissionError`: 当没有权限创建日志文件时抛出
+
+### TraceIdFormatter
+
+追踪 ID 格式化器，继承自 `logging.Formatter`，自动为每条日志记录注入 `trace_id` 和 `prefix`。
+
+```python
+class TraceIdFormatter(logging.Formatter):
+    def __init__(self, prefix: str = "", *args, **kwargs) -> None: ...
+    
+    def format(self, record: logging.LogRecord) -> str: ...
+```
+
+**功能特性：**
+- 自动从上下文变量获取追踪 ID
+- 自动注入日志前缀
+- 确保所有日志都包含追踪信息
+
+**使用说明：**
+- `LOG_FORMAT` 中需要包含 `%(trace_id)s` 和 `%(prefix)s` 才能显示
+- 追踪 ID 通过 `ContextVar` 实现，支持异步环境
+
+### Trace ID 管理函数
+
+追踪 ID 上下文变量和辅助函数，用于在请求生命周期中管理追踪 ID。
+
+```python
+def set_app_trace_id(trace_id: str) -> None: ...
+def get_app_trace_id() -> str: ...
+```
+
+**功能特性：**
+- 使用 `ContextVar` 实现线程/协程安全的上下文变量
+- 支持异步环境（FastAPI、asyncio）
+- 自动添加到所有日志记录中
+
+**方法说明：**
+- `set_app_trace_id(trace_id)`: 设置当前请求的追踪 ID，通常在 FastAPI 中间件中调用
+- `get_app_trace_id()`: 获取当前请求的追踪 ID，如果未设置则返回默认值 `"-"`
+
+## 完整使用示例
+
+### 基础使用
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 创建配置
+config = LoggerConfig(
+    LOG_DIR="logs",
+    LOG_NAME="apps",
+    LOG_LEVEL="INFO",
+    LOG_PREFIX="[MyApp]"
+)
+
+# 初始化日志系统
+setup_logging(config)
+
+# 现在可以使用标准 logging 模块
+import logging
+logger = logging.getLogger(__name__)
+
+logger.info("这是一条信息日志")
+logger.warning("这是一条警告日志")
+logger.error("这是一条错误日志")
+```
+
+### 在 FastAPI 中使用
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.middleware.base import BaseHTTPMiddleware
+import uuid
+import logging
+from tomskit.logger import setup_logging, LoggerConfig, set_app_trace_id
+
+# 创建配置
+log_config = LoggerConfig(
+    LOG_DIR="logs",
+    LOG_NAME="apps",
+    LOG_LEVEL="INFO",
+    LOG_PREFIX="[FastAPI]"
+)
+
+# 初始化日志系统
+setup_logging(log_config)
+
+app = FastAPI()
+
+# 追踪 ID 中间件
+class TraceIdMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        # 生成或获取追踪 ID
+        trace_id = request.headers.get("X-Trace-Id", str(uuid.uuid4()))
+        set_app_trace_id(trace_id)
+        
+        response = await call_next(request)
+        response.headers["X-Trace-Id"] = trace_id
+        return response
+
+app.add_middleware(TraceIdMiddleware)
+
+logger = logging.getLogger(__name__)
+
+@app.get("/")
+async def root():
+    logger.info("处理根路径请求")
+    return {"message": "Hello World"}
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int):
+    logger.info(f"读取物品 {item_id}")
+    return {"item_id": item_id}
+```
+
+### 启用 SQL 日志分离
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 启用 SQL 日志分离
+config = LoggerConfig(
+    LOG_SQL_ENABLED=True,
+    LOG_SQL_LEVEL="DEBUG",  # 查看详细的 SQL 查询
+    LOG_SQL_NAME="sql"
+)
+
+setup_logging(config)
+
+# SQL 日志会写入 logs/sql.log 文件
+# 应用日志会写入 logs/apps.log 文件
+```
+
+### 启用 Celery 日志分离
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 启用 Celery 日志分离
+config = LoggerConfig(
+    LOG_CELERY_ENABLED=True,
+    LOG_CELERY_LEVEL="INFO",
+    LOG_CELERY_NAME="celery"
+)
+
+setup_logging(config)
+
+# Celery 日志会写入 logs/celery.log 文件
+# 应用日志会写入 logs/apps.log 文件
+```
+
+### 自定义日志格式
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 自定义日志格式
+config = LoggerConfig(
+    LOG_FORMAT="[%(asctime)s] [%(levelname)-8s] [%(name)s] [trace_id=%(trace_id)s] [%(prefix)s] %(message)s",
+    LOG_DATE_FORMAT="%Y-%m-%d %H:%M:%S.%f",
+    LOG_PREFIX="[MyService]"
+)
+
+setup_logging(config)
+```
+
+### 配置日志轮转
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 配置日志轮转：每天午夜轮转，保留 30 个备份文件
+config = LoggerConfig(
+    LOG_ROTATE_WHEN="midnight",
+    LOG_BACKUP_COUNT=30
+)
+
+setup_logging(config)
+
+# 或者按小时轮转
+hourly_config = LoggerConfig(
+    LOG_ROTATE_WHEN="H",
+    LOG_BACKUP_COUNT=24  # 保留 24 小时的历史日志
+)
+
+setup_logging(hourly_config)
+```
+
+### 使用 UTC 时间
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 使用 UTC 时间
+config = LoggerConfig(
+    LOG_USE_UTC=True,
+    LOG_DATE_FORMAT="%Y-%m-%d %H:%M:%S UTC"
+)
+
+setup_logging(config)
+```
+
+### 在业务代码中使用追踪 ID
+
+```python
+import logging
+from tomskit.logger import get_app_trace_id
+
+logger = logging.getLogger(__name__)
+
+def process_order(order_id: int):
+    trace_id = get_app_trace_id()
+    logger.info(f"开始处理订单 {order_id}，追踪 ID: {trace_id}")
+    
+    # 业务逻辑...
+    
+    logger.info(f"订单 {order_id} 处理完成")
+```
+
+### 在异步任务中使用
+
+```python
+import asyncio
+import logging
+from tomskit.logger import set_app_trace_id, get_app_trace_id
+
+logger = logging.getLogger(__name__)
+
+async def async_task(task_id: int, trace_id: str):
+    # 在异步任务中设置追踪 ID
+    set_app_trace_id(trace_id)
+    
+    logger.info(f"开始执行异步任务 {task_id}")
+    
+    # 业务逻辑...
+    await asyncio.sleep(1)
+    
+    logger.info(f"异步任务 {task_id} 执行完成")
+    return {"task_id": task_id, "trace_id": get_app_trace_id()}
+```
+
+## 环境变量配置
+
+Logger 模块支持通过环境变量进行配置，所有 `LoggerConfig` 中的字段都可以通过环境变量设置：
+
+**基础配置：**
+- `LOG_PREFIX`: 日志前缀
+- `LOG_DIR`: 日志文件存储目录
+- `LOG_NAME`: 应用日志文件名
+- `LOG_LEVEL`: 应用日志级别
+- `LOG_FORMAT`: 应用日志格式
+- `LOG_USE_UTC`: 是否使用 UTC 时间（`true`/`false`）
+- `LOG_DATE_FORMAT`: 日志日期时间格式
+- `LOG_BACKUP_COUNT`: 日志文件备份数量
+- `LOG_ROTATE_WHEN`: 日志轮转时间单位
+
+**访问日志配置：**
+- `LOG_ACCESS_NAME`: 访问日志文件名
+- `LOG_ACCESS_FORMAT`: 访问日志格式
+
+**SQL 日志配置：**
+- `LOG_SQL_ENABLED`: 是否启用独立的 SQL 日志文件（`true`/`false`）
+- `LOG_SQL_NAME`: SQL 日志文件名
+- `LOG_SQL_LEVEL`: SQL 日志级别
+
+**Celery 日志配置：**
+- `LOG_CELERY_ENABLED`: 是否启用独立的 Celery 日志文件（`true`/`false`）
+- `LOG_CELERY_NAME`: Celery 日志文件名
+- `LOG_CELERY_LEVEL`: Celery 日志级别
+
+**第三方库日志配置：**
+- `LOG_THIRD_PARTY_LEVEL`: 第三方库日志级别
+
+**使用示例：**
+```bash
+# 通过环境变量配置
+export LOG_DIR="/var/log/myapp"
+export LOG_LEVEL="DEBUG"
+export LOG_SQL_ENABLED="true"
+export LOG_CELERY_ENABLED="true"
+```
+
+```python
+from tomskit.logger import setup_logging, LoggerConfig
+
+# 自动从环境变量读取配置
+config = LoggerConfig()
+setup_logging(config)
+```
+
+## 日志文件结构
+
+配置完成后，日志文件会按照以下结构组织：
+
+```
+logs/
+├── apps.log              # 应用日志（主日志）
+├── apps.log.2024-01-01   # 轮转后的历史日志
+├── access.log            # 访问日志（uvicorn/gunicorn）
+├── access.log.2024-01-01 # 轮转后的访问日志
+├── sql.log               # SQL 日志（如果启用）
+├── sql.log.2024-01-01    # 轮转后的 SQL 日志
+├── celery.log            # Celery 日志（如果启用）
+└── celery.log.2024-01-01 # 轮转后的 Celery 日志
+```
+
+## 注意事项
+
+1. **初始化顺序**：在使用日志功能之前必须先调用 `setup_logging()` 进行初始化
+2. **追踪 ID 设置**：追踪 ID 需要在请求开始时设置（通常在中间件中），否则会使用默认值 `"-"`
+3. **日志格式**：如果要在日志中显示追踪 ID 和前缀，`LOG_FORMAT` 中必须包含 `%(trace_id)s` 和 `%(prefix)s`
+4. **日志目录权限**：确保应用有权限在 `LOG_DIR` 指定的目录中创建和写入文件
+5. **日志轮转**：日志轮转会在指定的时间点自动进行，轮转后的文件会添加日期后缀
+6. **备份数量**：`LOG_BACKUP_COUNT=0` 表示不保留历史文件，轮转时会直接覆盖旧文件
+7. **异步环境**：追踪 ID 使用 `ContextVar` 实现，完全支持异步环境，无需担心线程安全问题
+8. **第三方库日志**：模块会自动管理常见第三方库的日志级别，减少日志噪音
+9. **访问日志分离**：访问日志（uvicorn/gunicorn）会自动分离到独立文件，不会冒泡到 root logger
+10. **框架日志管理**：uvicorn 和 fastapi 的日志会自动配置，无需手动设置
+
+## 相关文档
+
+- [Logger Guide](../../docs/specs/logger_guide.md) - 详细的日志使用指南
+- [Python logging 文档](https://docs.python.org/3/library/logging.html) - Python 标准库日志文档

tomskit/logger/__init__.py

@@ -0,0 +1,4 @@
+from tomskit.logger.logger import setup_logging, set_app_trace_id, get_app_trace_id
+from tomskit.logger.config import LoggerConfig
+
+__all__ = ["setup_logging", "LoggerConfig", "set_app_trace_id", "get_app_trace_id"]

tomskit/logger/config.py

@@ -0,0 +1,106 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class LoggerConfig(BaseSettings):
+    """
+    日志配置类
+    
+    用于配置日志系统的各项参数，包括日志级别、格式、文件路径、轮转策略等。
+    支持应用日志、访问日志、SQL 日志和 Celery 日志的独立配置。
+    """
+    # === 基础配置 ===
+    LOG_PREFIX: str = Field(
+        description="日志前缀，会添加到每条日志记录中",
+        default="",
+    )
+    
+    LOG_DIR: str = Field(
+        description="日志文件存储目录",
+        default="logs",
+    )
+
+    LOG_NAME: str = Field(
+        description="应用日志文件名（不含扩展名）",
+        default="apps",
+    )
+
+    LOG_LEVEL: str = Field(
+        description="应用日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+        default="INFO",
+    )
+
+    LOG_FORMAT: str = Field(
+        description="应用日志格式，支持 %(trace_id)s 和 %(prefix)s 占位符",
+        default="[%(asctime)s] [%(levelname)s] [%(name)s] [trace_id=%(trace_id)s] %(message)s",
+    )
+
+    LOG_USE_UTC: bool = Field(
+        description="是否使用 UTC 时间",
+        default=False,
+    )
+
+    LOG_DATE_FORMAT: str = Field(
+        description="日志日期时间格式",
+        default="%Y-%m-%d %H:%M:%S",
+    )
+
+    LOG_BACKUP_COUNT: int = Field(
+        description="日志文件备份数量，0 表示不保留历史文件",
+        default=0,
+    )
+
+    LOG_ROTATE_WHEN: str = Field(
+        description="日志轮转时间单位 (midnight, D, H, M, S)",
+        default="midnight",
+    )
+
+    # === 访问日志配置 ===
+    LOG_ACCESS_NAME: str = Field(
+        description="访问日志文件名（不含扩展名）",
+        default="access",
+    )
+
+    LOG_ACCESS_FORMAT: str = Field(
+        description="访问日志格式（Apache Common Log Format）",
+        default='%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"',
+    )
+
+    # === SQL 日志配置 ===
+    LOG_SQL_ENABLED: bool = Field(
+        description="是否启用独立的 SQL 日志文件",
+        default=False,
+    )
+
+    LOG_SQL_NAME: str = Field(
+        description="SQL 日志文件名（不含扩展名）",
+        default="sql",
+    )
+
+    LOG_SQL_LEVEL: str = Field(
+        description="SQL 日志级别",
+        default="INFO",
+    )
+
+    # === Celery 日志配置 ===
+    LOG_CELERY_ENABLED: bool = Field(
+        description="是否启用独立的 Celery 日志文件",
+        default=False,
+    )
+
+    LOG_CELERY_NAME: str = Field(
+        description="Celery 日志文件名（不含扩展名）",
+        default="celery",
+    )
+
+    LOG_CELERY_LEVEL: str = Field(
+        description="Celery 日志级别",
+        default="INFO",
+    )
+
+    # === 第三方库日志配置 ===
+    LOG_THIRD_PARTY_LEVEL: str = Field(
+        description="第三方库日志级别（用于降噪）",
+        default="WARNING",
+    )
+