@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-repo/fastapi-backend/src/core/init_app.py

@@ -0,0 +1,330 @@
+import asyncio
+from functools import partial
+
+from aerich import Command
+from fastapi import FastAPI
+from fastapi.exceptions import (
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+)
+from fastapi.middleware import Middleware
+from fastapi.middleware.cors import CORSMiddleware
+from slowapi import _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from tortoise.exceptions import DoesNotExist, IntegrityError
+from tortoise.expressions import Q
+
+from api import api_router
+from api.api.model import Api
+from api.api.repository import api_repository
+from api.base import limiter
+from api.menu.model import Menu
+from api.menu.schema import MenuType
+from api.role.model import Role
+from api.user.model import User
+from api.user.repository import user_repository
+from api.user.schema import UserCreateDTO
+from config.settings import settings
+from core.exceptions import (
+    DoesNotExistHandle,
+    HttpExcHandle,
+    IntegrityHandle,
+    RequestValidationHandle,
+    ResponseValidationHandle,
+)
+from core.middlewares import (
+    BackGroundTaskMiddleware,
+    HttpAuditLogMiddleware,
+    RequestLoggingMiddleware,
+    SecurityHeadersMiddleware,
+)
+from log import logger
+from utils.cache import cache_manager
+
+
+def make_middlewares():
+    middleware = [
+        Middleware(
+            CORSMiddleware,
+            allow_origins=settings.CORS_ORIGINS_LIST,
+            allow_credentials=settings.CORS_ALLOW_CREDENTIALS,
+            allow_methods=settings.CORS_ALLOW_METHODS,
+            allow_headers=settings.CORS_ALLOW_HEADERS,
+        ),
+        Middleware(SecurityHeadersMiddleware),  # 安全头中间件
+        Middleware(RequestLoggingMiddleware),  # 请求日志中间件
+        Middleware(BackGroundTaskMiddleware),
+        Middleware(
+            HttpAuditLogMiddleware,
+            methods=["GET", "POST", "PUT", "DELETE"],
+            exclude_paths=[
+                "/api/v1/base/access_token",
+                "/docs",
+                "/openapi.json",
+            ],
+        ),
+    ]
+    return middleware
+
+
+def register_exceptions(app: FastAPI):
+    app.add_exception_handler(DoesNotExist, DoesNotExistHandle)
+    app.add_exception_handler(HTTPException, HttpExcHandle)
+    app.add_exception_handler(IntegrityError, IntegrityHandle)
+    app.add_exception_handler(RequestValidationError, RequestValidationHandle)
+    app.add_exception_handler(ResponseValidationError, ResponseValidationHandle)
+    # 注册限流异常处理
+    app.state.limiter = limiter
+    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+
+def register_routers(app: FastAPI):
+    app.include_router(api_router)
+
+
+async def init_superuser():
+    logger.info("🔧 开始初始化超级管理员用户...")
+    user = await user_repository.model.exists()
+    if not user:
+        await user_repository.create_user(
+            UserCreateDTO(
+                username="admin",
+                email="admin@admin.com",
+                password="abcd1234",
+                is_active=True,
+                is_superuser=True,
+            )
+        )
+        logger.info("✅ 超级管理员用户创建成功 - 用户名: admin")
+    else:
+        logger.info("ℹ️ 超级管理员用户已存在，跳过创建")
+
+
+async def init_menus():
+    logger.info("🔧 开始初始化系统菜单...")
+    menus = await Menu.exists()
+    if not menus:
+        parent_menu = await Menu.create(
+            menu_type=MenuType.CATALOG,
+            name="系统管理",
+            path="/system",
+            order=1,
+            parent_id=0,
+            icon="carbon:gui-management",
+            is_hidden=False,
+            component="Layout",
+            keepalive=False,
+            redirect="/system/user",
+        )
+        children_menu = [
+            Menu(
+                menu_type=MenuType.MENU,
+                name="用户管理",
+                path="user",
+                order=1,
+                parent_id=parent_menu.id,
+                icon="material-symbols:person-outline-rounded",
+                is_hidden=False,
+                component="/system/user",
+                keepalive=False,
+            ),
+            Menu(
+                menu_type=MenuType.MENU,
+                name="角色管理",
+                path="role",
+                order=2,
+                parent_id=parent_menu.id,
+                icon="carbon:user-role",
+                is_hidden=False,
+                component="/system/role",
+                keepalive=False,
+            ),
+            Menu(
+                menu_type=MenuType.MENU,
+                name="菜单管理",
+                path="menu",
+                order=3,
+                parent_id=parent_menu.id,
+                icon="material-symbols:list-alt-outline",
+                is_hidden=False,
+                component="/system/menu",
+                keepalive=False,
+            ),
+            Menu(
+                menu_type=MenuType.MENU,
+                name="API管理",
+                path="api",
+                order=4,
+                parent_id=parent_menu.id,
+                icon="ant-design:api-outlined",
+                is_hidden=False,
+                component="/system/api",
+                keepalive=False,
+            ),
+            Menu(
+                menu_type=MenuType.MENU,
+                name="部门管理",
+                path="dept",
+                order=5,
+                parent_id=parent_menu.id,
+                icon="mingcute:department-line",
+                is_hidden=False,
+                component="/system/dept",
+                keepalive=False,
+            ),
+            Menu(
+                menu_type=MenuType.MENU,
+                name="审计日志",
+                path="auditlog",
+                order=6,
+                parent_id=parent_menu.id,
+                icon="ph:clipboard-text-bold",
+                is_hidden=False,
+                component="/system/auditlog",
+                keepalive=False,
+            ),
+        ]
+        await Menu.bulk_create(children_menu)
+        await Menu.create(
+            menu_type=MenuType.MENU,
+            name="一级菜单",
+            path="/top-menu",
+            order=2,
+            parent_id=0,
+            icon="material-symbols:featured-play-list-outline",
+            is_hidden=False,
+            component="/top-menu",
+            keepalive=False,
+            redirect="",
+        )
+        logger.info("✅ 系统菜单初始化成功 - 菜单数量: 8")
+    else:
+        logger.info("ℹ️ 系统菜单已存在，跳过初始化")
+
+
+async def init_apis():
+    logger.info("🔧 开始初始化API数据...")
+    apis = await api_repository.model.exists()
+    if not apis:
+        await api_repository.refresh_api()
+        api_count = await Api.all().count()
+        logger.info(f"✅ API数据初始化成功 - API数量: {api_count}")
+    else:
+        api_count = await Api.all().count()
+        logger.info(f"ℹ️ API数据已存在，跳过初始化 - 当前API数量: {api_count}")
+
+
+async def init_db():
+    command = Command(tortoise_config=settings.TORTOISE_ORM)
+    try:
+        await command.init_db(safe=True)
+    except FileExistsError:
+        pass
+
+    await command.init()
+    try:
+        await command.migrate(no_input=True)
+    except AttributeError as e:
+        logger.error(f"数据库迁移失败: {e}")
+        logger.warning("请手动检查数据库和migrations状态")
+        # 不再自动删除migrations文件夹，避免意外丢失迁移历史
+        # 如需重置migrations，请手动执行：rm -rf migrations && uv run aerich init-db
+        raise RuntimeError("数据库迁移失败，请检查数据库连接和migrations状态") from e
+
+    await command.upgrade(run_in_transaction=True)
+
+
+async def init_roles():
+    logger.info("🔧 开始初始化用户角色...")
+    roles = await Role.exists()
+    if not roles:
+        admin_role = await Role.create(
+            name="管理员",
+            desc="管理员角色",
+        )
+        user_role = await Role.create(
+            name="普通用户",
+            desc="普通用户角色",
+        )
+
+        # 分配所有API给管理员角色
+        all_apis = await Api.all()
+        await admin_role.apis.add(*all_apis)
+        # 分配所有菜单给管理员和普通用户
+        all_menus = await Menu.all()
+        await admin_role.menus.add(*all_menus)
+        await user_role.menus.add(*all_menus)
+
+        # 为普通用户分配基本API
+        basic_apis = await Api.filter(Q(method__in=["GET"]) | Q(tags="基础模块"))
+        await user_role.apis.add(*basic_apis)
+
+        logger.info("✅ 用户角色初始化成功 - 角色: 管理员, 普通用户")
+    else:
+        role_count = await Role.all().count()
+        logger.info(f"ℹ️ 用户角色已存在，跳过初始化 - 当前角色数量: {role_count}")
+
+
+async def init_data():
+    logger.info("🚀 系统初始化开始...")
+
+    logger.info("🔧 开始数据库初始化和迁移...")
+    await init_db()
+    logger.info("✅ 数据库初始化完成")
+    # 开发环境跳过数据检查,直接返回
+    if settings.APP_ENV == "development" and (await User.exists()):
+        logger.info("ℹ️  当前为开发环境且数据已存在,跳过初始化")
+        return
+
+    # 以下初始化可以并行执行
+    await asyncio.gather(
+        init_superuser(),
+        init_menus(),
+        init_apis(),
+    )
+    # init_apis() 先执行,在数据库中创建所有 API 权限记录
+    # init_roles() 后执行,可以查询到这些 API 记录并建立角色-API 的多对多关系
+    await init_roles()
+
+    logger.info("🎉 系统初始化完成！")
+
+
+async def startup():
+    """应用启动事件"""
+    logger.info("🚀 FastAPI应用启动中...")
+
+    # 并行连接 Redis 和数据库
+    await asyncio.gather(
+        cache_manager.connect(),
+        init_db(),
+        return_exceptions=True,  # 允许部分失败
+    )
+
+
+async def shutdown():
+    """应用关闭事件"""
+    logger.info("🛑 FastAPI应用关闭中...")
+
+    # 断开Redis连接
+    await cache_manager.disconnect()
+
+
+async def init_app(app: FastAPI):
+    """应用启动时初始化"""
+    # 注册启动和关闭事件
+    app.add_event_handler("startup", startup)
+    app.add_event_handler("shutdown", shutdown)
+    logger.info("🎉 FastAPI应用启动完成！")
+
+
+async def stop_app(app: FastAPI):
+    """应用关闭时清理"""
+    logger.info("🔧 开始停止系统服务...")
+    logger.info("👋 系统服务已关闭")
+
+
+def register_startup_event(app: FastAPI):
+    """注册启动和关闭事件"""
+    app.add_event_handler("startup", partial(init_app, app))
+    app.add_event_handler("shutdown", partial(stop_app, app))

package/dist-repo/fastapi-backend/src/core/middlewares/__init__.py

@@ -0,0 +1,13 @@
+from .background_task_middleware import BackGroundTaskMiddleware
+from .http_audit_log_middleware import HttpAuditLogMiddleware
+from .request_logging_middleware import RequestLoggingMiddleware
+from .security_headers_middleware import SecurityHeadersMiddleware
+from .simple_base_middleware import SimpleBaseMiddleware
+
+__all__ = [
+    "BackGroundTaskMiddleware",
+    "HttpAuditLogMiddleware",
+    "RequestLoggingMiddleware",
+    "SecurityHeadersMiddleware",
+    "SimpleBaseMiddleware",
+]

package/dist-repo/fastapi-backend/src/core/middlewares/background_task_middleware.py

@@ -0,0 +1,11 @@
+from core.tasks.bgtask import BgTasks
+
+from .simple_base_middleware import SimpleBaseMiddleware
+
+
+class BackGroundTaskMiddleware(SimpleBaseMiddleware):
+    async def before_request(self, request):
+        await BgTasks.init_bg_tasks_obj()
+
+    async def after_request(self, request):
+        await BgTasks.execute_tasks()

package/dist-repo/fastapi-backend/src/core/middlewares/http_audit_log_middleware.py

@@ -0,0 +1,175 @@
+import json
+import re
+from collections.abc import AsyncGenerator
+from datetime import datetime
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.responses import Response, StreamingResponse
+from fastapi.routing import APIRoute
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+
+from api.auditlog.model import AuditLog
+from api.user.model import User
+from core.dependencies.auth_dependency import AuthControl
+
+
+class HttpAuditLogMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, methods: list[str], exclude_paths: list[str]):
+        super().__init__(app)
+        self.methods = methods
+        self.exclude_paths = exclude_paths
+        self.audit_log_paths = ["/api/auditlog/list"]
+        self.max_body_size = 1024 * 1024  # 1MB 响应体大小限制
+
+    async def get_request_args(self, request: Request) -> dict:
+        args = {}
+        # 获取查询参数
+        for key, value in request.query_params.items():
+            args[key] = value
+
+        # 获取请求体
+        if request.method in ["POST", "PUT", "PATCH"]:
+            content_type = request.headers.get("content-type", "")
+
+            # 如果是文件上传请求，跳过请求体解析
+            if "multipart/form-data" in content_type:
+                return args
+
+            try:
+                body = await request.json()
+                args.update(body)
+            except json.JSONDecodeError:
+                try:
+                    body = await request.form()
+                    args.update(body)
+                except Exception:
+                    pass
+
+        return args
+
+    async def get_response_body(self, request: Request, response: Response) -> Any:
+        # 对于流式响应，不记录响应体
+        if isinstance(response, StreamingResponse):
+            return {"message": "[Streaming Response]"}
+
+        # 检查响应类型，如果是流式相关的响应类型也跳过
+        if hasattr(response, "body_iterator") and not hasattr(response, "body"):
+            return {"message": "[Streaming Response]"}
+
+        body = b""
+        # 检查Content-Length
+        content_length = response.headers.get("content-length")
+        if content_length and int(content_length) > self.max_body_size:
+            return {
+                "code": 0,
+                "msg": "Response too large to log",
+                "data": None,
+            }
+
+        try:
+            if hasattr(response, "body"):
+                body = response.body
+            else:
+                body_chunks = []
+                async for chunk in response.body_iterator:
+                    if not isinstance(chunk, bytes):
+                        chunk = chunk.encode(response.charset)
+                    body_chunks.append(chunk)
+
+                response.body_iterator = self._async_iter(body_chunks)
+                body = b"".join(body_chunks)
+        except Exception:
+            # 如果读取响应体失败，返回默认值
+            return {"message": "[Unable to read response body]"}
+
+        if any(request.url.path.startswith(path) for path in self.audit_log_paths):
+            try:
+                data = self.lenient_json(body)
+                # 只保留基本信息，去除详细的响应内容
+                if isinstance(data, dict):
+                    data.pop("response_body", None)
+                    if "data" in data and isinstance(data["data"], list):
+                        for item in data["data"]:
+                            item.pop("response_body", None)
+                return data
+            except Exception:
+                return None
+
+        return self.lenient_json(body)
+
+    def lenient_json(self, v: Any) -> Any:
+        if isinstance(v, str | bytes):
+            try:
+                return json.loads(v)
+            except (ValueError, TypeError):
+                pass
+        return v
+
+    async def _async_iter(self, items: list[bytes]) -> AsyncGenerator[bytes]:
+        for item in items:
+            yield item
+
+    async def get_request_log(self, request: Request, response: Response) -> dict:
+        """
+        根据request和response对象获取对应的日志记录数据
+        """
+        data: dict = {
+            "path": request.url.path,
+            "status": response.status_code,
+            "method": request.method,
+        }
+        # 路由信息
+        app: FastAPI = request.app
+        for route in app.routes:
+            if (
+                isinstance(route, APIRoute)
+                and route.path_regex.match(request.url.path)
+                and request.method in route.methods
+            ):
+                data["module"] = ",".join(route.tags) if route.tags else ""
+                data["summary"] = route.summary or ""
+        # 获取用户信息
+        try:
+            token = request.headers.get("token")
+            user_obj = None
+            if token:
+                user_obj: User = await AuthControl.is_authed(token)
+            data["user_id"] = user_obj.id if user_obj else 0
+            data["username"] = user_obj.username if user_obj else ""
+        except Exception:
+            data["user_id"] = 0
+            data["username"] = ""
+        return data
+
+    async def before_request(self, request: Request):
+        request_args = await self.get_request_args(request)
+        request.state.request_args = request_args
+
+    async def after_request(
+        self, request: Request, response: Response, process_time: int
+    ):
+        if request.method in self.methods:
+            for path in self.exclude_paths:
+                if re.search(path, request.url.path, re.I) is not None:
+                    return
+            data: dict = await self.get_request_log(request=request, response=response)
+            data["response_time"] = process_time
+
+            data["request_args"] = request.state.request_args
+            data["response_body"] = await self.get_response_body(request, response)
+            await AuditLog.create(**data)
+
+        return response
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        start_time: datetime = datetime.now()
+        await self.before_request(request)
+        response = await call_next(request)
+        end_time: datetime = datetime.now()
+        process_time = int((end_time.timestamp() - start_time.timestamp()) * 1000)
+        await self.after_request(request, response, process_time)
+        return response

package/dist-repo/fastapi-backend/src/core/middlewares/request_logging_middleware.py

@@ -0,0 +1,67 @@
+from datetime import datetime
+
+from fastapi.responses import Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+
+from log import logger
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """请求日志中间件"""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """处理请求并记录日志"""
+        start_time = datetime.now()
+
+        # 记录请求开始
+        logger.info(
+            f"请求开始: {request.method} {request.url.path}",
+            extra={
+                "method": request.method,
+                "path": request.url.path,
+                "query_params": dict(request.query_params),
+                "client_ip": request.client.host if request.client else None,
+                "user_agent": request.headers.get("user-agent"),
+            },
+        )
+
+        try:
+            response = await call_next(request)
+
+            # 计算处理时间
+            end_time = datetime.now()
+            process_time = (end_time - start_time).total_seconds() * 1000
+
+            # 记录请求完成
+            logger.info(
+                f"请求完成: {request.method} {request.url.path} - {response.status_code} ({process_time:.2f}ms)",
+                extra={
+                    "method": request.method,
+                    "path": request.url.path,
+                    "status_code": response.status_code,
+                    "process_time_ms": process_time,
+                },
+            )
+
+            return response
+
+        except Exception as e:
+            # 计算处理时间
+            end_time = datetime.now()
+            process_time = (end_time - start_time).total_seconds() * 1000
+
+            # 记录请求异常
+            logger.error(
+                f"请求异常: {request.method} {request.url.path} - {str(e)} ({process_time:.2f}ms)",
+                extra={
+                    "method": request.method,
+                    "path": request.url.path,
+                    "error": str(e),
+                    "process_time_ms": process_time,
+                },
+            )
+
+            raise

package/dist-repo/fastapi-backend/src/core/middlewares/security_headers_middleware.py

@@ -0,0 +1,48 @@
+from fastapi.responses import Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """安全头中间件"""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        response = await call_next(request)
+
+        # 添加安全头
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+
+        # 为Swagger UI和ReDoc设置更宽松的CSP策略
+        if request.url.path in ["/docs", "/redoc"]:
+            response.headers["Content-Security-Policy"] = (
+                "default-src 'self'; "
+                "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net https://unpkg.com; "
+                "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://unpkg.com; "
+                "img-src 'self' data: https: blob:; "
+                "font-src 'self' data: https://cdn.jsdelivr.net https://unpkg.com; "
+                "connect-src 'self' https://cdn.jsdelivr.net https://unpkg.com; "
+                "worker-src 'self' blob:; "
+                "child-src 'self' blob:"
+            )
+        else:
+            response.headers["Content-Security-Policy"] = (
+                "default-src 'self'; "
+                "script-src 'self' 'unsafe-inline' 'unsafe-eval'; "
+                "style-src 'self' 'unsafe-inline'; "
+                "img-src 'self' data: https:; "
+                "font-src 'self' data:; "
+                "connect-src 'self'"
+            )
+
+        # 仅在HTTPS环境下添加HSTS头
+        if request.url.scheme == "https":
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=31536000; includeSubDomains"
+            )
+
+        return response

package/dist-repo/fastapi-backend/src/core/middlewares/simple_base_middleware.py

@@ -0,0 +1,24 @@
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+class SimpleBaseMiddleware:
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope, receive=receive)
+
+        response = await self.before_request(request) or self.app
+        await response(request.scope, request.receive, send)
+        await self.after_request(request)
+
+    async def before_request(self, request: Request):
+        return self.app
+
+    async def after_request(self, request: Request):
+        return None