chakcy/chongming_lite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify: 代码注释

Browse Source
This commit is contained in:
chakcy
2026-04-26 21:57:17 +08:00
parent d13ad1f907
commit 3fbd7764af
32 changed files with 2029 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/chongming/__init__.py
+34 -9
View File
@@ -4,32 +4,57 @@ from .app.core.logger import get_logger
def serve():
"""
使用 uvicorn 启动服务
从配置文件中加载服务器配置和日志配置，然后使用 uvicorn 启动应用服务。
该函数适用于开发环境或单进程部署场景。
Returns:
None: 该函数不返回值，会阻塞运行直到服务停止
"""
config = load_config()
env = config["default"]["env"]
server_config = config[env]["server"]
log_config = config[env]["logging"]
logget = get_logger("app")
logget.info(f"启动服务: {server_config}")
logget.info(f"启动日志: {log_config}")
logger = get_logger("app")
logger.info(f"启动服务: {server_config}")
logger.info(f"启动日志: {log_config}")
uvicorn.run("chongming.app:app", **server_config)
def gunicorn_serve():
"""使用 gunicorn 启动服务"""
"""
使用 gunicorn 启动服务
通过 gunicorn 作为进程管理器启动应用，使用 UvicornWorker 作为 worker 类型，
支持多进程部署，适用于生产环境。
从配置文件中读取服务器配置，动态设置 gunicorn 的 worker 数量、绑定地址和端口等参数。
Returns:
None: 该函数不返回值，会阻塞运行直到服务停止
"""
import sys
from gunicorn.app.wsgiapp import run
config = load_config()
env = config["default"]["env"]
server_config = config[env]["server"]
# 设置 gunicorn 参数
# 构建 gunicorn 命令行参数并启动服务
sys.argv = [
"gunicorn",
"chongming.app:app",
"-k", "uvicorn.workers.UvicornWorker",
"-w", f"{server_config.get('workers', 4)}",
"-b", f"{server_config.get('host', '0.0.0.0')}:{server_config.get('port', 8000)}"
"-k",
"uvicorn.workers.UvicornWorker",
"-w",
f"{server_config.get('workers', 4)}",
"-b",
f"{server_config.get('host', '0.0.0.0')}:{server_config.get('port', 8000)}",
]
run()
if __name__ == "__main__":
serve()
src/chongming/app/__init__.py
+56 -17
View File
@@ -31,9 +31,28 @@ except KeyError: # pragma: no cover
raise ValueError("配置不存在")
# 生命周期管理
@asynccontextmanager
async def lifespan(app: FastAPI):
"""
应用生命周期管理函数，负责应用的启动和关闭时的资源初始化与清理。
在应用启动时：
- 初始化JWT缓存
- 创建异步数据库引擎和会话工厂
- 在开发环境下创建数据库表
- 初始化定时任务服务
在应用关闭时：
- 关闭定时任务服务
- 释放数据库引擎资源
- 关闭缓存连接
参数:
app: FastAPI应用实例
Yields:
None: 应用运行期间保持上下文激活
"""
from plugins import hello
from plugins.jwt.jwt_cache import get_jwt_cache
@@ -46,17 +65,14 @@ async def lifespan(app: FastAPI):
if database_config is None:
raise ValueError("配置不存在")
# 启动时：创建引擎和会话工厂，初始化数据库表
engine = create_async_engine(database["url"], **database_config)
async_session_maker = async_sessionmaker(
engine, class_=AsyncSession, expire_on_commit=False
)
# 将资源存储到 app.state
app.state.engine = engine
app.state.async_session_maker = async_session_maker
# 创建表（异步方式）
if env == "development":
async with engine.begin() as conn:
if database_type == "sqlite":
@@ -72,22 +88,19 @@ async def lifespan(app: FastAPI):
if "already exists" in str(e):
raise
# 启动时：初始化任务服务
task_service = get_task_service_instance(
config, get_logger("scheduler"), async_session_maker
)
app.state.task_service = task_service
await task_service.start(init_tasks_callback)
yield # 应用运行期间
yield
# 关闭时：释放引擎
await task_service.shutdown(wait=True)
await engine.dispose()
cache.close()
# 创建 FastAPI 应用
cors = config[env].get("cors", {})
app = FastAPI(
title=config["default"]["app"]["name"],
@@ -99,15 +112,29 @@ app = FastAPI(
lifespan=lifespan,
)
# 添加 CORS 中间件
app.add_middleware(CORSMiddleware, **cors)
# 添加路由
app.include_router(api_router, prefix=config["default"]["prefix"])
@app.middleware("http")
async def access_log_middleware(request: Request, call_next):
"""
HTTP访问日志中间件，记录每个请求的详细信息。
记录的信息包括：
- 请求方法和路径
- 响应状态码
- 请求处理时长（毫秒）
- 客户端IP地址
参数:
request: FastAPI请求对象
call_next: 下一个中间件或路由处理函数
返回:
Response: 处理后的响应对象
"""
start = time.perf_counter()
response = await call_next(request)
duration = (time.perf_counter() - start) * 1000
@@ -116,15 +143,19 @@ async def access_log_middleware(request: Request, call_next):
logger.info(
f"{request.method} {request.url.path} status={response.status_code} "
f"duration={duration:.2f}ms client={client}",
extra={"status_code": response.status_code}, # ← 关键
extra={"status_code": response.status_code},
)
return response
# 根路由
@app.get("/", summary="根路径")
async def root():
"""根路径，返回应用信息"""
"""
根路径端点，返回应用的基本信息。
返回:
dict: 包含应用名称、版本、文档地址和健康检查地址的字典
"""
return {
"message": f"欢迎使用 {config['default']['app']['name']}",
"version": config["default"]["app"]["version"],
@@ -154,7 +185,6 @@ async def root():
# )
# return {"status": "success", "job_id": job.id}
# 挂载静态文件
config = get_config()
IMAGE_DIR = Path(f"./{config['default']['upload_path']}/images")
app.mount(
@@ -163,17 +193,26 @@ app.mount(
name="images",
)
# 挂载前端静态文件
if vfs_db_path := config[env].get("file_system", {}).get("path", None):
logger.info("静态文件已存在，将使用静态文件服务")
static_files_handler = SVFSStaticFiles(directory="/", vfs_db_path=vfs_db_path)
app.mount("/static", static_files_handler, name="static")
# 全局异常处理器
@app.exception_handler(Exception)
async def global_exception_handler(_: Request, exc: Exception):
"""全局异常处理器"""
"""
全局异常处理器，捕获并处理应用中未捕获的异常。
在调试模式下返回详细的异常信息，在生产模式下返回通用错误提示。
参数:
_: FastAPI请求对象（未使用）
exc: 捕获到的异常对象
返回:
JSONResponse: 包含错误信息的JSON响应，状态码为500
"""
logger.error(f"全局异常: {exc}")
return JSONResponse(
status_code=500,
src/chongming/app/api/deps.py
+11
View File
@@ -15,12 +15,23 @@ async def get_current_user(
获取当前用户依赖项
验证访问令牌并返回用户信息
Args:
credentials: HTTP授权凭证，包含Bearer token
Returns:
TokenData: 验证通过后的用户令牌数据
Raises:
HTTPException: 当访问令牌无效时抛出401未授权异常
"""
auth_service = get_auth_service()
# 提取并验证访问令牌
token = credentials.credentials
token_data = await auth_service.validate_access_token(token)
# 令牌验证失败时抛出未授权异常
if token_data is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
src/chongming/app/api/routers/auth.py
+98 -2
View File
@@ -30,6 +30,21 @@ async def register(
user_data: UserCreate,
session: AsyncSession = Depends(get_session),
):
"""
用户注册接口
创建新用户账户，检查邮箱是否已被注册，如果邮箱未被注册则创建新用户。
Args:
user_data: 用户注册数据，包含邮箱、密码、用户名和全名等信息
session: 数据库会话对象，用于执行数据库操作
Returns:
UserRead: 创建成功的用户信息，包含用户ID、邮箱、用户名等字段
Raises:
HTTPException: 当邮箱已被注册时抛出400错误
"""
existing = await UserService.get_user_by_email(user_data.email, session)
if existing:
raise HTTPException(
@@ -63,6 +78,25 @@ async def login(
request: Request,
session: AsyncSession = Depends(get_session),
):
"""
用户登录接口
验证用户凭据并生成访问令牌和刷新令牌。依次检查邮箱是否存在、密码是否正确、用户是否被禁用。
Args:
user_data: 用户登录数据，包含邮箱和密码
request: FastAPI请求对象，用于获取客户端信息
session: 数据库会话对象，用于查询用户信息
Returns:
TokenResponse: 包含访问令牌(access_token)、刷新令牌(refresh_token)和令牌类型(token_type)的响应对象
Raises:
HTTPException:
- 400错误：当邮箱不存在时
- 401错误：当密码错误时
- 402错误：当用户账户被禁用时
"""
user = await UserService.get_user_by_email(user_data.email, session)
if not user:
raise HTTPException(
@@ -93,6 +127,22 @@ async def refresh_token(
credentials: HTTPAuthorizationCredentials = Depends(refresh_scheme),
session: AsyncSession = Depends(get_session),
):
"""
刷新访问令牌接口
使用有效的刷新令牌获取新的访问令牌。验证刷新令牌的有效性，如果有效则生成新的访问令牌。
Args:
request: FastAPI请求对象，用于获取客户端信息
credentials: HTTP认证凭证，从请求头中提取的刷新令牌
session: 数据库会话对象，用于验证令牌状态
Returns:
RefreshTokenResponse: 包含新的访问令牌(access_token)和令牌类型(token_type)的响应对象
Raises:
HTTPException: 当刷新令牌无效或已过期时抛出401错误
"""
auth_service = get_auth_service()
refresh_token = credentials.credentials
@@ -112,6 +162,17 @@ async def refresh_token(
async def logout(
credentials: HTTPAuthorizationCredentials = Depends(access_scheme),
):
"""
用户登出接口
使当前的访问令牌失效，实现单设备登出功能。
Args:
credentials: HTTP认证凭证，从请求头中提取的访问令牌
Returns:
Userlogout: 登出成功响应，包含成功消息和状态码200
"""
auth_service = get_auth_service()
token = credentials.credentials
await auth_service.logout(token)
@@ -120,6 +181,17 @@ async def logout(
@router.post("/logout-all", summary="登出所有设备", response_model=Userlogout)
async def logout_all(current_user: TokenData = Depends(get_current_user)):
"""
登出所有设备接口
使指定用户的所有活跃会话令牌失效，实现多设备同时登出功能。
Args:
current_user: 当前登录用户的令牌数据，包含用户ID等信息
Returns:
Userlogout: 登出成功响应，包含成功消息和状态码200
"""
auth_service = get_auth_service()
await auth_service.logout_all(current_user.user_id)
@@ -128,7 +200,17 @@ async def logout_all(current_user: TokenData = Depends(get_current_user)):
@router.get("/sessions", summary="获取用户会话")
async def get_sessions(current_user: TokenData = Depends(get_current_user)):
"""获取用户的所有活跃会话"""
"""
获取用户会话列表接口
查询并返回指定用户的所有活跃会话信息，包括每个会话的设备信息和创建时间等。
Args:
current_user: 当前登录用户的令牌数据，包含用户ID等信息
Returns:
UserSession: 用户会话信息对象，包含用户ID、会话列表和会话总数
"""
auth_service = get_auth_service()
sessions = await auth_service.get_user_sessions(current_user.user_id)
@@ -147,7 +229,21 @@ async def get_current_user_info(
session: AsyncSession = Depends(get_session),
current_user: TokenData = Depends(get_current_user),
):
"""获取当前登录用户的信息"""
"""
获取当前用户信息接口
根据当前登录用户的令牌信息，从数据库中查询并返回完整的用户资料。
Args:
session: 数据库会话对象，用于查询用户信息
current_user: 当前登录用户的令牌数据，包含用户ID等信息
Returns:
UserRead: 用户详细信息，包含用户ID、邮箱、用户名、全名、激活状态等字段
Raises:
HTTPException: 当用户不存在时抛出404错误
"""
user = await UserService.get_user_by_id(UUID(current_user.user_id), session)
if not user:
raise HTTPException(
src/chongming/app/api/routers/todo.py
+58
View File
@@ -18,6 +18,16 @@ async def create_todo(
todo: TodoCreate,
session: AsyncSession = Depends(get_session),
):
"""
创建新的待办事项
Args:
todo: 待办事项创建请求体，包含待办事项的详细信息
session: 数据库会话对象，用于执行数据库操作
Returns:
TodoRead: 创建成功的待办事项对象，包含完整的待办事项信息
"""
return await TodoService.create_todo(todo, session)
@@ -25,11 +35,35 @@ async def create_todo(
async def read_todos(
offset: int = 0, limit: int = 100, session: AsyncSession = Depends(get_session)
):
"""
获取待办事项列表
Args:
offset: 分页偏移量，默认为0，用于指定从第几条记录开始查询
limit: 每页返回的最大记录数，默认为100，用于限制返回结果的数量
session: 数据库会话对象，用于执行数据库操作
Returns:
List[TodoRead]: 待办事项列表，包含指定范围内的所有待办事项
"""
return await TodoService.get_todos(offset, limit, session)
@router.get("/{todo_id}", response_model=TodoRead)
async def read_todo(todo_id: int, session: AsyncSession = Depends(get_session)):
"""
根据ID获取单个待办事项
Args:
todo_id: 待办事项的唯一标识符
session: 数据库会话对象，用于执行数据库操作
Returns:
TodoRead: 查询到的待办事项对象
Raises:
HTTPException: 当待办事项不存在时抛出404错误
"""
todo = await TodoService.get_todo_by_id(todo_id, session)
if not todo:
raise HTTPException(status_code=404, detail="Todo not found")
@@ -40,12 +74,36 @@ async def read_todo(todo_id: int, session: AsyncSession = Depends(get_session)):
async def update_todo(
todo_id: int, todo_update: TodoUpdate, session: AsyncSession = Depends(get_session)
):
"""
更新待办事项信息
Args:
todo_id: 待办事项的唯一标识符
todo_update: 待办事项更新请求体，包含需要更新的字段信息
session: 数据库会话对象，用于执行数据库操作
Returns:
TodoRead: 更新后的待办事项对象，包含最新的待办事项信息
"""
todo = await TodoService.update_todo(todo_id, todo_update, session)
return todo
@router.delete("/{todo_id}")
async def delete_todo(todo_id: int, session: AsyncSession = Depends(get_session)):
"""
删除待办事项
Args:
todo_id: 待办事项的唯一标识符
session: 数据库会话对象，用于执行数据库操作
Returns:
dict: 包含操作结果的字典，{"ok": True} 表示删除成功
Raises:
HTTPException: 当待办事项不存在时抛出404错误
"""
is_deleted = await TodoService.delete_todo(todo_id, session)
if not is_deleted:
raise HTTPException(status_code=404, detail="Todo not found")
src/chongming/app/api/routers/upload.py
+33
View File
@@ -16,6 +16,8 @@ upload_image_service = UploadService(
class UploadResponse(BaseModel):
"""图片上传响应数据模型"""
url: str
filename: str
file_type: str
@@ -23,13 +25,44 @@ class UploadResponse(BaseModel):
@router.post("/image", response_model=UploadResponse)
async def upload_image(file: UploadFile = File(...)):
"""
上传图片文件接口
该接口用于接收用户上传的图片文件，进行格式验证后保存到服务器，
并返回文件的访问URL、文件名和文件类型信息。
Args:
file (UploadFile): 上传的文件对象，必须为图片格式
Returns:
UploadResponse: 包含以下字段的响应对象：
- url (str): 上传文件的访问URL
- filename (str): 保存后的文件名
- file_type (str): 文件扩展名（如 .jpg, .png 等）
Raises:
HTTPException:
- 400: 当文件类型不是图片格式时
- 400: 当文件名为空时
- 400: 当文件扩展名不在允许列表中时
Note:
支持的图片格式包括：.jpg, .jpeg, .png, .gif, .webp
需要用户认证才能访问此接口
"""
# 验证文件内容类型是否为图片
if not file.content_type or not file.content_type.startswith("image/"):
raise HTTPException(status_code=400, detail="Invalid file type")
# 验证文件名是否存在
if file.filename is None:
raise HTTPException(status_code=400, detail="Invalid file name")
# 检查文件扩展名是否在允许的范围内
ext = os.path.splitext(file.filename)[1].lower()
if ext not in [".jpg", ".jpeg", ".png", ".gif", ".webp"]:
raise HTTPException(status_code=400, detail="Invalid file type")
# 执行文件上传操作
url, filename = await upload_image_service.upload(file)
return UploadResponse(url=url, filename=filename, file_type=ext)
src/chongming/app/core/cache.py
+182 -33
View File
@@ -1,3 +1,10 @@
"""
磁盘缓存模块
基于 diskcache 实现的本地磁盘缓存系统，提供类似 Redis 的 API 接口。
支持过期时间设置、TTL 查询、键模式匹配等功能。
"""
import time
from typing import Any, Optional
@@ -7,7 +14,29 @@ from ..core.config import get_config
class Cache:
"""
磁盘缓存类
封装 diskcache 提供统一的缓存操作接口，支持：
- 键值对存储与检索
- 过期时间管理（秒/毫秒）
- TTL 查询
- 键模式匹配
- 批量操作
Attributes:
_cache: diskcache.Cache 实例，负责实际的磁盘缓存操作
"""
def __init__(self):
"""
初始化缓存实例
从配置中读取缓存存储路径，创建 diskcache.Cache 实例。
Raises:
KeyError: 当配置中缺少 cache.cache_store_path 时
"""
config = get_config()
cache_dir = config["cache"]["cache_store_path"]
self._cache = diskcache.Cache(cache_dir)
@@ -23,14 +52,23 @@ class Cache:
"""
设置缓存
将键值对存储到缓存中，可选设置过期时间。内部使用元组 (value, expire_at)
存储，以支持自定义的过期检查逻辑。
Args:
key: 键
value: 值
ex: 过期时间（秒）
px: 过期时间（毫秒）
key: 缓存键，字符串类型
value: 缓存值，可以是任意可序列化的 Python 对象
ex: 过期时间（秒），与 px 互斥，优先使用 ex
px: 过期时间（毫秒），当 ex 为 None 时生效
raw: 是否原始存储（当前未使用，保留参数兼容性）
Returns:
bool: 是否设置成功
bool: 设置成功返回 True，发生异常返回 False
Note:
- ex 和 px 不能同时设置，ex 优先级更高
- 过期时间在存储时计算绝对时间戳，便于后续检查
- 异常会被捕获并打印错误信息，不会抛出异常
"""
try:
expire_at = None
@@ -54,14 +92,21 @@ class Cache:
def get(self, key: str, default: Any = None) -> Any:
"""
获取缓存
获取缓存值
根据键获取缓存值，自动检查并清理已过期的缓存项。
如果键不存在或已过期，返回默认值。
Args:
key: 键
default: 默认值
key: 缓存键
default: 当键不存在或已过期时的返回值，默认为 None
Returns:
缓存的值，如果key不存在或已过期返回default
Any: 缓存的值，如果key不存在或已过期返回default
Note:
- 发现过期数据时会主动删除，避免脏数据累积
- 异常情况下返回 default 值，保证调用安全性
"""
try:
stored = self._cache.get(key)
@@ -81,13 +126,19 @@ class Cache:
def delete(self, *keys: str) -> int:
"""
删除一个或多个key
删除一个或多个缓存键
批量删除指定的缓存键，返回成功删除的数量。
Args:
keys: 要删除的key
*keys: 可变参数，要删除的键列表
Returns:
成功删除的数量
int: 成功删除的键数量
Note:
- 逐个删除，某个键删除失败不影响其他键
- 只统计实际存在的键的删除操作
"""
deleted = 0
for key in keys:
@@ -97,26 +148,36 @@ class Cache:
def exists(self, key: str) -> bool:
"""
检查key是否存在且未过期
检查键是否存在且未过期
通过尝试获取值来判断键的有效性，比直接检查更可靠，
因为会触发过期检查和清理逻辑。
Args:
key: 键
key: 要检查的缓存键
Returns:
bool: 是否存在
bool: 键存在且未过期返回 True，否则返回 False
"""
return self.get(key, None) is not None
def expire(self, key: str, _time: int) -> bool:
"""
设置过期时间
更新键的过期时间
重新设置指定键的过期时间，保持原值不变。
如果键不存在，操作失败。
Args:
key: 键
time: 过期时间（秒）
key: 缓存键
_time: 新的过期时间（秒），从当前时间开始计算
Returns:
bool: 是否设置成功
bool: 设置成功返回 True，键不存在或异常返回 False
Note:
- 需要先读取原值，再重新存储以更新过期时间
- 原子性不保证，高并发场景可能有问题
"""
try:
stored = self._cache.get(key)
@@ -133,13 +194,22 @@ class Cache:
def ttl(self, key: str) -> int:
"""
获取key的剩余存活时间
获取键的剩余生存时间（Time To Live）
计算键距离过期的剩余秒数。
Args:
key: 键
key: 缓存键
Returns:
int: 剩余秒数，-1表示永不过期，-2表示key不存在
int: 剩余秒数，返回值含义：
- >= 0: 剩余存活秒数
- -1: 键存在但永不过期
- -2: 键不存在
Note:
- 返回值为整数，向下取整
- 即使剩余时间为负数也返回 0，表示即将过期
"""
try:
stored = self._cache.get(key)
@@ -158,13 +228,21 @@ class Cache:
def keys(self, pattern: Optional[str] = None) -> list:
"""
获取所有key，支持简单的通配符匹配（*）
获取所有缓存键，支持通配符模式匹配
遍历所有缓存键，可根据前缀模式过滤。
Args:
pattern: 匹配模式，如 "user:*"
pattern: 匹配模式，仅支持前缀通配，如 "user:*" 匹配所有 "user:" 开头的键
None 或空字符串返回所有键
Returns:
list: key列表
list: 匹配的键列表，按迭代顺序排列
Note:
- 仅支持简单的 "*" 后缀通配，不支持复杂模式
- 大量键时性能较差，建议谨慎使用
- pattern 中的 "*" 会被替换为空字符串作为前缀
"""
all_keys = list(self._cache.iterkeys())
@@ -175,7 +253,17 @@ class Cache:
return all_keys
def clear(self) -> bool:
"""清空所有缓存。"""
"""
清空所有缓存
删除缓存目录中的所有数据，包括未过期的项。
Returns:
bool: 清空成功返回 True，异常返回 False
Warning:
此操作不可逆，会删除所有缓存数据
"""
try:
self._cache.clear()
return True
@@ -184,12 +272,36 @@ class Cache:
return False
def size(self) -> int:
"""获取当前缓存数量（不含过期但尚未清理的项）。"""
"""
获取当前有效缓存项数量
统计当前未过期的缓存键数量。
Returns:
int: 有效缓存项的数量
Note:
- 不包含已过期但尚未清理的项
- 需要遍历所有键，大数据量时可能有性能开销
"""
# diskcache 的 __len__ 会返回当前有效条目数
return len(list(self._cache.iterkeys()))
def get_all(self) -> dict:
"""获取所有未过期的缓存数据。"""
"""
获取所有未过期的缓存数据
遍历所有缓存键，返回有效的键值对字典。
自动过滤过期数据。
Returns:
dict: 所有有效缓存的键值对，格式为 {key: value}
Note:
- 会触发每个键的过期检查
- 大数据量时内存占用较高，谨慎使用
- 返回的是快照，不保证原子性
"""
result = {}
for key in self._cache.iterkeys():
value = self.get(str(key)) # get 内部会检查并清理过期
@@ -198,7 +310,15 @@ class Cache:
return result
def close(self):
"""关闭缓存。"""
"""
关闭缓存连接
释放 diskcache 占用的资源，包括文件句柄等。
应在应用退出时调用。
Note:
关闭后不应再使用该实例，除非重新初始化
"""
self._cache.close()
@@ -206,6 +326,18 @@ _cache: Optional[Cache] = None
def get_cache() -> Cache:
"""
获取全局缓存单例
使用懒加载模式创建缓存实例，确保整个应用中只有一个 Cache 实例。
Returns:
Cache: 全局缓存实例
Note:
- 线程不安全，多线程环境需要额外同步
- 首次调用时初始化，后续调用返回同一实例
"""
global _cache
if _cache is None:
_cache = Cache()
@@ -217,13 +349,30 @@ def cached(ttl: Optional[int] = None):
"""
函数结果缓存装饰器
自动缓存函数的返回值，相同参数的调用直接从缓存返回，
避免重复计算。适用于纯函数或副作用小的函数。
Args:
ttl: 缓存时间（秒），None表示永不过期
ttl: 缓存生存时间（秒），None 表示永不过期
Returns:
callable: 装饰器函数
Example:
@cached(ttl=60)
def get_user(user_id: int):
return {"id": user_id, "name": "test"}
>>> @cached(ttl=60)
... def get_user(user_id: int):
... return {"id": user_id, "name": "test"}
>>>
>>> # 第一次调用执行函数并缓存
>>> get_user(1)
>>> # 60秒内再次调用直接返回缓存结果
>>> get_user(1)
Note:
- 缓存键由函数名 + 位置参数 + 关键字参数组成
- 参数必须是可哈希的，否则会导致错误
- 不适合缓存大型对象或频繁变化的数据
- 不同参数组合会生成不同的缓存键
"""
def decorator(func):
src/chongming/app/core/config.py
+55 -1
View File
@@ -3,6 +3,7 @@ from pathlib import Path
from typing import TypedDict, Literal, Optional, cast, List
# 根据Python版本选择合适的TOML解析库和Required类型
if sys.version_info >= (3, 11):
import tomllib
from typing import Required
@@ -14,6 +15,8 @@ else:
class DefaultApp(TypedDict):
"""应用默认配置结构"""
name: str
version: str
description: str
@@ -21,6 +24,8 @@ class DefaultApp(TypedDict):
class Default(TypedDict):
"""系统默认配置结构，包含应用信息、环境、路径等基础配置"""
app: DefaultApp
env: Literal["production", "development"]
prefix: str
@@ -28,11 +33,15 @@ class Default(TypedDict):
class SqliteConnectionArgs(TypedDict, total=False):
"""SQLite数据库连接参数配置"""
timeout: int
check_same_thread: bool
class DatabaseSqlite(TypedDict, total=False):
"""SQLite数据库连接池及行为配置"""
echo: bool
pool_size: int
max_overflow: int
@@ -43,6 +52,8 @@ class DatabaseSqlite(TypedDict, total=False):
class Database(TypedDict, total=False):
"""数据库配置结构，支持SQLite、MySQL、PostgreSQL三种数据库类型"""
type: Required[Literal["sqlite", "mysql", "postgresql"]]
url: Required[str]
generate_schemas: bool
@@ -52,6 +63,8 @@ class Database(TypedDict, total=False):
class Security(TypedDict):
"""安全相关配置，包括JWT令牌和安全策略设置"""
secret_key: str
algorithm: Literal["HS256"]
access_token_expire_minutes: int
@@ -60,6 +73,8 @@ class Security(TypedDict):
class Server(TypedDict, total=False):
"""服务器运行配置，包含主机、端口、工作进程等设置"""
host: Required[str]
port: Required[int]
reload: bool
@@ -68,6 +83,8 @@ class Server(TypedDict, total=False):
class Logging(TypedDict):
"""日志系统配置，定义日志级别、输出格式和文件管理策略"""
level: str
file: str
format: str
@@ -76,6 +93,8 @@ class Logging(TypedDict):
class Cors(TypedDict, total=False):
"""跨域资源共享(CORS)配置"""
allow_origins: List[str]
allow_credentials: bool
allow_methods: List[str]
@@ -83,16 +102,22 @@ class Cors(TypedDict, total=False):
class ModuleSystem(TypedDict, total=False):
"""模块系统配置，定义模块加载类型和路径"""
type: str
path: List[str]
class FileSystem(TypedDict, total=False):
"""文件系统配置，定义存储类型和路径"""
type: str
path: str
class Env(TypedDict, total=False):
"""环境特定配置结构，用于开发和生产环境的差异化配置"""
debug: Required[bool]
server: Required[Server]
logging: Required[Logging]
@@ -102,14 +127,20 @@ class Env(TypedDict, total=False):
class Scheduler(TypedDict):
"""任务调度器配置"""
job_store_path: str
class Cache(TypedDict):
"""缓存系统配置"""
cache_store_path: str
class Config(TypedDict):
"""完整配置结构，整合所有配置项，包含默认配置、数据库、调度器、缓存、安全和环境配置"""
default: Default
database: Database
scheduler: Scheduler
@@ -120,17 +151,40 @@ class Config(TypedDict):
def load_config(config_path: Path = Path("config.toml")) -> Config:
"""从 TOML 文件加载配置"""
"""
从TOML配置文件加载配置数据
Args:
config_path: 配置文件路径，默认为当前目录下的config.toml
Returns:
Config: 解析后的配置字典对象
Raises:
FileNotFoundError: 当配置文件不存在时抛出异常
"""
if not config_path.exists():
raise FileNotFoundError(f"配置文件不存在: {config_path}")
with open(config_path, "rb") as f:
return cast(Config, tomllib.load(f))
# 全局配置缓存变量，避免重复加载配置文件
_config: Optional[Config] = None
def get_config(config_path: str = "config.toml") -> Config:
"""
获取应用程序配置（带缓存机制）
首次调用时加载配置文件并缓存，后续调用直接返回缓存的配置对象
Args:
config_path: 配置文件路径，默认为config.toml
Returns:
Config: 配置字典对象
"""
global _config
if _config is None:
_config = load_config(Path(config_path))
src/chongming/app/core/logger.py
+78 -2
View File
@@ -14,7 +14,19 @@ log_config = config[env]["logging"]
class ColoredFormatter(logging.Formatter):
"""为 status_code 添加颜色的日志格式化器"""
"""
为 HTTP 状态码添加颜色的日志格式化器
根据 HTTP 状态码的首位数字为日志消息中的状态码添加不同颜色：
- 2xx: 绿色（成功）
- 3xx: 青色（重定向）
- 4xx: 黄色（客户端错误）
- 5xx: 红色（服务器错误）
Attributes:
COLORS: 状态码首位数字到 ANSI 颜色代码的映射字典
RESET: ANSI 重置颜色代码
"""
COLORS = {
"2": "\033[32m", # 绿色 2xx
@@ -25,6 +37,18 @@ class ColoredFormatter(logging.Formatter):
RESET = "\033[0m"
def format(self, record):
"""
格式化日志记录，为状态码添加颜色
如果日志记录包含 status_code 属性，则查找消息中的 "status=数字" 模式
并为其添加对应的颜色代码。格式化完成后恢复原始消息以避免影响其他 handler。
Args:
record: 日志记录对象，应包含 msg 属性和可选的 status_code 属性
Returns:
str: 格式化后的日志消息字符串，状态码部分可能包含 ANSI 颜色代码
"""
# 保存原始消息
original_msg = record.msg
# 如果日志记录包含 status_code 属性，则为其添加颜色
@@ -44,7 +68,17 @@ class ColoredFormatter(logging.Formatter):
class ExcludeWatchFilesFilter(logging.Filter):
"""
日志过滤器，用于排除第三方库的日志输出
过滤掉来自 watchfiles、aiosqlite、apscheduler、sqlalchemy 等库的日志记录，
避免这些库的详细日志污染应用日志输出。
"""
def __init__(self):
"""
初始化过滤器，设置需要过滤的日志名称前缀列表
"""
super().__init__()
self._filter_starts_with_tulpe = (
"watchfiles",
@@ -55,8 +89,17 @@ class ExcludeWatchFilesFilter(logging.Filter):
"sqlalchemy.engine.Engine",
)
# 重写过滤方法
def filter(self, record):
"""
判断是否应该保留该日志记录
Args:
record: 日志记录对象，包含 name 属性表示日志来源
Returns:
bool: 如果日志名称不以过滤列表中的任何前缀开头则返回 True（保留），
否则返回 False（过滤掉）
"""
return not record.name.startswith(self._filter_starts_with_tulpe)
@@ -64,6 +107,27 @@ _configured_loggers = set()
def setup_logging(logger: logging.Logger, log_name: str = "app"):
"""
配置日志系统，包括文件和控制台输出
为指定的 logger 配置以下功能：
1. 设置日志级别和格式
2. 创建按日期命名的轮转文件处理器（支持文件大小限制和备份数量控制）
3. 创建带颜色格式化的控制台处理器
4. 应用过滤器排除第三方库日志
该函数具有防重复配置机制，同一个 log_name 只会配置一次。
Args:
logger: 需要配置的 logging.Logger 实例
log_name: 日志名称标识，用于区分不同的日志配置和生成日志文件名，默认为 "app"
Returns:
None
Raises:
无显式抛出异常，但可能因文件系统权限问题导致目录创建或文件写入失败
"""
if log_name in _configured_loggers:
return
_configured_loggers.add(log_name)
@@ -110,6 +174,18 @@ def setup_logging(logger: logging.Logger, log_name: str = "app"):
def get_logger(name: str) -> logging.Logger:
"""
获取配置好的日志记录器实例
根据名称获取或创建 logger 实例，并自动调用 setup_logging 进行配置。
如果该名称的 logger 已经配置过，则直接返回已配置的实例。
Args:
name: 日志记录器名称，通常使用模块名如 __name__
Returns:
logging.Logger: 已配置完成的日志记录器实例，可直接用于记录日志
"""
logger = logging.getLogger(name)
setup_logging(logger, name)
return logger
src/chongming/app/core/security.py
+29 -6
View File
@@ -1,13 +1,36 @@
# src/chongming/app/core/security.py
import bcrypt
def get_password_hash(password: str) -> str:
"""
对明文密码进行哈希加密
使用bcrypt算法对密码进行加盐哈希处理,确保密码存储的安全性。
Args:
password: 需要加密的明文密码字符串
Returns:
加密后的密码哈希字符串,采用UTF-8编码
"""
salt = bcrypt.gensalt()
hashed = bcrypt.hashpw(password.encode('utf-8'), salt)
return hashed.decode('utf-8')
hashed = bcrypt.hashpw(password.encode("utf-8"), salt)
return hashed.decode("utf-8")
def verify_password(plain_password: str, hashed_password: str) -> bool:
"""
验证明文密码与哈希密码是否匹配
将明文密码与已存储的哈希密码进行比对,用于用户登录时的密码验证。
Args:
plain_password: 用户输入的明文密码
hashed_password: 数据库中存储的哈希密码
Returns:
密码匹配返回True,否则返回False
"""
return bcrypt.checkpw(
plain_password.encode('utf-8'),
hashed_password.encode('utf-8')
)
plain_password.encode("utf-8"), hashed_password.encode("utf-8")
)
src/chongming/app/core/static_files.py
+40 -2
View File
@@ -5,18 +5,56 @@ from sqlite_vfs.core import SQLiteVFS
class SVFSStaticFiles(StaticFiles):
"""
基于 SQLite VFS 的静态文件服务类
该类继承自 FastAPI 的 StaticFiles，使用 SQLite 虚拟文件系统来存储和提供静态文件。
支持单页应用（SPA）的路由回退机制，当请求的文件不存在时，会自动返回 index.html。
"""
def __init__(self, directory, vfs_db_path="static.svfs"):
"""
初始化 SVFSStaticFiles 实例
参数:
directory (str): 静态文件的根目录路径
vfs_db_path (str): SQLite VFS 数据库文件路径，默认为 "static.svfs"
返回值:
无
"""
vfs_db_path = vfs_db_path
self._vfs = SQLiteVFS(vfs_db_path, compress=False)
super().__init__(directory=directory)
async def get_response(self, path: str, scope):
"""
根据请求路径获取对应的静态文件响应
该方法处理静态文件的请求逻辑，包括：
1. 路径标准化处理
2. 文件存在性检查
3. SPA 路由回退支持
4. 目录索引处理
5. MIME 类型自动识别
参数:
path (str): 请求的文件路径
scope: ASGI 作用域对象，包含请求上下文信息
返回值:
Response: FastAPI 响应对象，包含文件内容和正确的 Content-Type
异常:
HTTPException: 当文件不存在且无法回退到 index.html 时，抛出 404 错误
"""
# 统一路径格式：以 / 开头，并将 Windows 反斜杠转为正斜杠
normalized_path = "/" + path.replace("\\", "/")
# 获取文件信息
file_info = self._vfs.get_file_info(normalized_path)
# 处理文件不存在的情况，尝试 SPA 回退机制
if file_info is None:
# SPA 回退：如果不是静态资源扩展名，尝试返回 index.html
if not any(
@@ -38,7 +76,7 @@ class SVFSStaticFiles(StaticFiles):
return Response(content=content, media_type="text/html")
raise HTTPException(status_code=404, detail="File not found")
# 如果是目录，也返回 index.html（某些情况）
# 处理目录请求，返回目录下的 index.html
if file_info["is_directory"]:
index_info = self._vfs.get_file_info(f"{normalized_path}/index.html")
if index_info:
@@ -46,7 +84,7 @@ class SVFSStaticFiles(StaticFiles):
return Response(content=content, media_type="text/html")
raise HTTPException(status_code=404, detail="Directory index not found")
# 读取文件内容
# 读取文件内容并确定 MIME 类型
content = self._vfs.read_file(normalized_path)
content_type = file_info.get("content_type") or "application/octet-stream"
# 简单根据扩展名补充 MIME 类型（可选）
src/chongming/app/model/http_error.py
+20
View File
@@ -3,9 +3,29 @@ from typing import Optional
class Detail(BaseModel):
"""
HTTP错误详情模型
用于封装HTTP错误的详细信息，包括错误消息和错误代码。
Attributes:
message (str): 错误描述信息
code (int): 错误状态码或业务错误码
"""
message: str
code: int
class HTTPError(BaseModel):
"""
HTTP错误响应模型
用于标准化HTTP错误响应的数据结构，符合RESTful API规范。
Attributes:
detail (Optional[Detail]): 错误详情对象，包含具体的错误信息和错误码。
如果为None，表示没有详细的错误信息。
"""
detail: Optional[Detail] = None
src/chongming/app/model/permission.py
+18 -6
View File
@@ -8,17 +8,29 @@ if TYPE_CHECKING:
from .role import Role
# ---------- 权限表 ----------
class Permission(SQLModel, table=True):
"""权限项，如 user:create, order:delete"""
"""
权限模型类，用于定义系统中的权限项。
权限采用资源:操作的格式进行标识，例如：
- user:create 表示创建用户的权限
- order:delete 表示删除订单的权限
Attributes:
id: 权限的唯一标识符，主键，自增
name: 权限标识符，唯一且建立索引，格式为"资源:操作"
description: 权限的描述信息，可选字段
resource: 资源名称，建立索引，如 user、order、product 等
action: 操作类型，如 create、read、update、delete 等
roles: 关联的角色列表，通过 RolePermission 中间表实现多对多关系
"""
id: Optional[int] = Field(default=None, primary_key=True)
name: str = Field(unique=True, index=True) # 权限标识符
name: str = Field(unique=True, index=True)
description: Optional[str] = None
resource: str = Field(index=True) # 资源，如 user, order, product
action: str # 操作，如 create, read, update, delete
resource: str = Field(index=True)
action: str
# 多对多关联
roles: List["Role"] = Relationship(
back_populates="permissions", link_model=RolePermission
)
src/chongming/app/model/relationship_table.py
+20 -2
View File
@@ -4,14 +4,32 @@ from sqlmodel import SQLModel, Field
# ---------- 关联表 ----------
class UserRole(SQLModel, table=True):
"""用户角色关联表"""
"""
用户角色关联表
用于实现用户与角色之间的多对多关系。
每个记录表示一个用户拥有的一个角色。
Attributes:
user_id: 用户ID，外键关联到user表的id字段，作为复合主键的一部分
role_id: 角色ID，外键关联到role表的id字段，作为复合主键的一部分
"""
user_id: UUID = Field(foreign_key="user.id", primary_key=True)
role_id: int = Field(foreign_key="role.id", primary_key=True)
class RolePermission(SQLModel, table=True):
"""角色权限关联表"""
"""
角色权限关联表
用于实现角色与权限之间的多对多关系。
每个记录表示一个角色拥有的一项权限。
Attributes:
role_id: 角色ID，外键关联到role表的id字段，作为复合主键的一部分
permission_id: 权限ID，外键关联到permission表的id字段，作为复合主键的一部分
"""
role_id: int = Field(foreign_key="role.id", primary_key=True)
permission_id: int = Field(foreign_key="permission.id", primary_key=True)
src/chongming/app/model/role.py
+25
View File
@@ -12,6 +12,21 @@ if TYPE_CHECKING:
# ---------- 角色表 ----------
class Role(SQLModel, table=True):
"""
角色模型类，用于定义系统中的用户角色。
该类继承自SQLModel，映射到数据库中的角色表。每个角色可以有多个用户和多个权限，
通过中间表UserRole和RolePermission实现多对多关系。
Attributes:
id: 角色的唯一标识符，主键，自增
name: 角色名称，具有唯一性约束和索引，例如：admin, manager, operator, viewer
description: 角色的描述信息，可选字段
is_only_user: 标识该角色是否仅限单个用户使用，默认为False
users: 与该角色关联的用户列表，通过UserRole中间表建立多对多关系
permissions: 与该角色关联的权限列表，通过RolePermission中间表建立多对多关系
"""
id: Optional[int] = Field(default=None, primary_key=True)
name: str = Field(unique=True, index=True) # admin, manager, operator, viewer
description: Optional[str] = None
@@ -23,5 +38,15 @@ class Role(SQLModel, table=True):
class RoleUpdate(BaseModel):
"""
角色更新请求模型类，用于接收角色更新时的参数。
该类继承自Pydantic的BaseModel，所有字段均为可选，允许部分更新角色信息。
Attributes:
name: 更新后的角色名称，可选字段
description: 更新后的角色描述信息，可选字段
"""
name: Optional[str] = None
description: Optional[str] = None
src/chongming/app/model/todo.py
+47
View File
@@ -5,24 +5,71 @@ from sqlmodel import SQLModel, Field
# 定义模型
class TodoBase(SQLModel):
"""
Todo任务的基础模型类，包含任务的通用字段。
Attributes:
title: 任务标题，必填字段
description: 任务描述，可选字段，默认为None
completed: 任务完成状态，布尔值，默认为False
"""
title: str
description: Optional[str] = None
completed: bool = False
class Todo(TodoBase, table=True):
"""
Todo任务的数据库表模型类，继承自TodoBase。
该类对应数据库中的todo表，用于存储和查询任务数据。
Attributes:
id: 任务唯一标识符，主键，由数据库自动生成
"""
id: Optional[int] = Field(default=None, primary_key=True)
class TodoCreate(TodoBase):
"""
创建Todo任务时使用的请求模型类。
继承自TodoBase，用于接收前端传入的新建任务数据。
不包含id字段，因为id由数据库自动生成。
"""
pass
class TodoRead(TodoBase):
"""
读取Todo任务时使用的响应模型类。
继承自TodoBase，用于向客户端返回任务数据。
包含完整的任务信息，包括自动生成的id字段。
Attributes:
id: 任务唯一标识符，整数类型，必填字段
"""
id: int
class TodoUpdate(SQLModel):
"""
更新Todo任务时使用的请求模型类。
所有字段均为可选，允许部分更新任务信息。
只有提供的字段会被更新，未提供的字段保持原值。
Attributes:
title: 任务标题，可选字段
description: 任务描述，可选字段
completed: 任务完成状态，可选字段
"""
title: Optional[str] = None
description: Optional[str] = None
completed: Optional[bool] = None
src/chongming/app/model/user.py
+76 -4
View File
@@ -11,16 +11,41 @@ if TYPE_CHECKING:
class UserBase(SQLModel):
"""
用户基础模型
定义用户的核心属性，作为其他用户相关模型的基类。
包含用户的基本信息和状态标识。
Attributes:
email: 用户邮箱地址，唯一且建立索引
username: 用户名，可选，最大长度50字符
full_name: 用户全名，可选，最大长度100字符
is_active: 用户激活状态，默认为True
is_superuser: 是否为超级管理员，默认为False
created_at: 创建时间，可选字段
"""
email: str = Field(unique=True, index=True)
username: Optional[str] = Field(default=None, max_length=50)
full_name: Optional[str] = Field(default=None, max_length=100)
is_active: bool = Field(default=True)
is_superuser: bool = Field(default=False)
created_at: Optional[str] = Field(default=None) # 可自动填充，此处略
created_at: Optional[str] = Field(default=None)
class User(UserBase, table=True):
"""用户模型"""
"""
用户数据库模型
继承自UserBase，用于数据库表映射。
包含用户的完整信息以及与角色的多对多关系。
Attributes:
id: 用户唯一标识符，UUID类型，自动生成
hashed_password: 加密后的密码
roles: 用户关联的角色列表，通过UserRole中间表实现多对多关系
"""
id: UUID = Field(default_factory=uuid4, primary_key=True)
hashed_password: str
@@ -28,28 +53,75 @@ class User(UserBase, table=True):
class UserCreate(UserBase):
"""用户创建模型"""
"""
用户创建请求模型
用于创建新用户时的数据验证和传输。
在UserBase基础上增加了密码字段。
Attributes:
password: 用户明文密码，用于创建时传入
"""
password: str
class UserRead(UserBase):
"""用户读取模型"""
"""
用户读取响应模型
用于向客户端返回用户信息。
在UserBase基础上增加了用户ID字段。
Attributes:
id: 用户唯一标识符，UUID类型
"""
id: UUID
class UserLogin(BaseModel):
"""
用户登录请求模型
用于处理用户登录时的数据验证。
Attributes:
email: 用户邮箱地址
password: 用户密码
"""
email: str
password: str
class Userlogout(BaseModel):
"""
用户登出响应模型
用于返回登出操作的结果。
Attributes:
code: 响应状态码，默认为200表示成功
message: 响应消息，默认为"logout success"
"""
code: int = 200
message: str = "logout success"
class UserSession(BaseModel):
"""
用户会话信息模型
用于存储和返回用户的会话相关信息。
Attributes:
user_id: 用户唯一标识符
sessions: 会话列表，每个会话为字典类型，键值均为字符串或None
count: 会话总数
"""
user_id: str
sessions: List[Dict[str, Optional[str]]]
count: int
src/chongming/app/service/auth.py
+88 -10
View File
@@ -24,13 +24,24 @@ class AuthService:
async def authenticate_user(
self, email: str, password: str, session: AsyncSession
) -> Optional[User]:
"""验证用户凭据"""
"""
验证用户凭据
通过邮箱和密码验证用户身份，使用 bcrypt 进行密码哈希比对。
Args:
email: 用户邮箱地址
password: 用户明文密码
session: 数据库异步会话对象
Returns:
验证成功返回 User 对象，失败返回 None
"""
user = await UserService.get_user_by_email(email, session)
if not user:
return None
if not bcrypt.checkpw(
password.encode('utf-8'),
user.hashed_password.encode('utf-8')
password.encode("utf-8"), user.hashed_password.encode("utf-8")
):
return None
@@ -42,7 +53,20 @@ class AuthService:
request: Optional[Request] = None,
device_id: Optional[str] = None,
) -> TokenResponse:
"""为用户创建访问和刷新令牌"""
"""
为用户创建访问和刷新令牌
根据用户信息和请求上下文生成 JWT access token 和 refresh token，
同时记录设备信息用于安全审计。
Args:
user: 已验证的用户对象
request: FastAPI 请求对象，用于提取客户端信息（可选）
device_id: 设备唯一标识符（可选）
Returns:
TokenResponse 对象，包含 access_token、refresh_token 及过期时间
"""
# 获取用户数据
user_data = {
@@ -89,7 +113,17 @@ class AuthService:
)
async def validate_access_token(self, token: str) -> Optional[TokenData]:
"""验证访问令牌"""
"""
验证访问令牌
校验 JWT access token 的有效性和完整性，提取用户身份信息。
Args:
token: JWT access token 字符串
Returns:
验证成功返回 TokenData 对象（包含 user_id、username、email），失败返回 None
"""
validation = self.jwt_cache.validate_token(token, token_type="access")
if not validation:
return None
@@ -107,7 +141,20 @@ class AuthService:
session: AsyncSession,
request: Optional[Request] = None,
) -> Optional[str]:
"""使用刷新令牌获取新的访问令牌"""
"""
使用刷新令牌获取新的访问令牌
验证 refresh token 的有效性，确认用户仍然存在，然后生成新的 access token。
保持原有的设备信息以确保会话连续性。
Args:
refresh_token: JWT refresh token 字符串
session: 数据库异步会话对象
request: FastAPI 请求对象，用于提取客户端信息（可选）
Returns:
验证成功返回新的 access token 字符串，失败返回 None
"""
validation = self.jwt_cache.validate_token(refresh_token, token_type="refresh")
if not validation:
return None
@@ -145,15 +192,39 @@ class AuthService:
return new_access_token
async def logout(self, token: str):
"""用户登出 - 使令牌失效"""
"""
用户登出 - 使令牌失效
将指定的 token 加入黑名单，使其立即失效。
Args:
token: 需要失效的 JWT token 字符串
"""
self.jwt_cache.invalidate_token(token)
async def logout_all(self, user_id: str):
"""使用户的所有令牌失效"""
"""
使用户的所有令牌失效
强制注销用户的所有活跃会话，适用于密码修改或安全事件场景。
Args:
user_id: 用户 ID 字符串
"""
self.jwt_cache.invalidate_user_tokens(str(user_id))
async def get_user_sessions(self, user_id: str):
"""获取用户的活跃会话"""
"""
获取用户的活跃会话
查询指定用户当前所有有效的 token 会话信息。
Args:
user_id: 用户 ID 字符串
Returns:
用户活跃会话列表
"""
return self.jwt_cache.get_user_sessions(str(user_id))
@@ -162,7 +233,14 @@ _auth_service = None
def get_auth_service() -> AuthService:
"""获取认证服务实例（单例模式）"""
"""
获取认证服务实例（单例模式）
确保整个应用中只有一个 AuthService 实例，避免重复初始化。
Returns:
AuthService 单例实例
"""
global _auth_service
if _auth_service is None:
_auth_service = AuthService()
src/chongming/app/service/permission.py
+81
View File
@@ -11,6 +11,8 @@ from .role import RoleService
class PermissionService:
"""权限服务类，提供权限的创建、查询、分配和解除绑定等功能"""
@classmethod
async def create_permission(
cls,
@@ -20,6 +22,16 @@ class PermissionService:
action: str,
description: Optional[str] = None,
) -> Permission:
"""
创建新的权限记录
:param session: 数据库会话对象
:param name: 权限名称
:param resource: 资源标识
:param action: 操作类型
:param description: 权限描述，可选
:return: 创建的权限对象
"""
permission = Permission(
name=name, resource=resource, action=action, description=description
)
@@ -32,12 +44,26 @@ class PermissionService:
async def get_permission_by_id(
cls, session: AsyncSession, permission_id: int
) -> Optional[Permission]:
"""
根据ID获取权限
:param session: 数据库会话对象
:param permission_id: 权限ID
:return: 权限对象，如果不存在则返回None
"""
return await session.get(Permission, permission_id)
@classmethod
async def get_permission_by_name(
cls, session: AsyncSession, name: str
) -> Optional[Permission]:
"""
根据名称获取权限
:param session: 数据库会话对象
:param name: 权限名称
:return: 权限对象，如果不存在则返回None
"""
result = await session.execute(
select(Permission).where(Permission.name == name)
)
@@ -47,6 +73,14 @@ class PermissionService:
async def assign_permission_to_role(
cls, session: AsyncSession, role_id: int, permission_id: int
) -> RolePermission:
"""
将权限分配给角色
:param session: 数据库会话对象
:param role_id: 角色ID
:param permission_id: 权限ID
:return: 创建的角色权限关联对象
"""
role_permission = RolePermission(role_id=role_id, permission_id=permission_id)
session.add(role_permission)
await session.commit()
@@ -60,21 +94,41 @@ class PermissionService:
user_id: UUID,
permission_id: int,
) -> User:
"""
将权限分配给用户
如果用户没有专属角色，则会为用户创建一个专属角色，然后将权限分配给该角色
:param session: 数据库会话对象
:param user_id: 用户UUID
:param permission_id: 权限ID
:return: 更新后的用户对象
:raises HTTPException: 当权限或用户不存在时抛出404错误，当角色或权限ID无效时抛出500错误
"""
# 验证权限是否存在
permission = await cls.get_permission_by_id(session, permission_id)
if not permission:
raise HTTPException(status_code=404, detail="Permission not found")
# 验证用户是否存在
user = await UserService.get_user_by_id(user_id, session)
if user is None:
raise HTTPException(status_code=404, detail="用户不存在")
# 获取或创建用户的专属角色
role = await RoleService.get_role_by_name(session, str(user_id))
if role is None:
role = await RoleService.create_role(
session, str(user_id), is_only_user=True
)
# 验证角色和权限ID的有效性
if role.id is None:
raise HTTPException(status_code=500, detail="角色ID无效")
if permission.id is None:
raise HTTPException(status_code=500, detail="权限ID无效")
# 将权限分配给角色
await cls.assign_permission_to_role(session, role.id, permission.id)
user.roles.append(role)
await session.commit()
@@ -85,9 +139,21 @@ class PermissionService:
async def unbind_permission_from_role(
cls, session: AsyncSession, role_id: int, permission_id: int
) -> Role:
"""
从角色中解除权限绑定
:param session: 数据库会话对象
:param role_id: 角色ID
:param permission_id: 权限ID
:return: 更新后的角色对象
:raises HTTPException: 当角色不存在时抛出404错误
"""
# 验证角色是否存在
role = await RoleService.get_role_by_id(session, role_id)
if role is None:
raise HTTPException(status_code=404, detail="Role not found")
# 从角色的权限列表中移除指定权限
role.permissions = [p for p in role.permissions if p.id != permission_id]
await session.commit()
await session.refresh(role)
@@ -97,12 +163,27 @@ class PermissionService:
async def unbind_permission_from_user(
cls, session: AsyncSession, user_id: UUID, permission_id: int
):
"""
从用户中解除权限绑定
通过找到用户的专属角色，从该角色中移除指定权限
:param session: 数据库会话对象
:param user_id: 用户UUID
:param permission_id: 权限ID
:raises HTTPException: 当用户或角色不存在时抛出404错误
"""
# 验证用户是否存在
user = await UserService.get_user_by_id(user_id, session)
if not user:
raise HTTPException(status_code=404, detail="User not found")
# 获取用户的专属角色
role = await RoleService.get_role_by_name(session, str(user.id))
if role is None:
raise HTTPException(status_code=404, detail="Role not found")
# 从角色权限列表中移除指定权限
role.permissions = [
permission
for permission in role.permissions
src/chongming/app/service/role.py
+90
View File
@@ -10,6 +10,8 @@ from ..service.user import UserService
class RoleService:
"""角色服务类，提供角色管理相关的业务逻辑"""
@staticmethod
async def create_role(
session: AsyncSession,
@@ -17,6 +19,18 @@ class RoleService:
description: Optional[str] = None,
is_only_user: bool = False,
) -> Role:
"""
创建新角色
Args:
session: 数据库会话对象
name: 角色名称
description: 角色描述，可选
is_only_user: 是否仅用于用户，默认为False
Returns:
Role: 创建成功的角色对象
"""
role = Role(name=name, description=description, is_only_user=is_only_user)
session.add(role)
await session.commit()
@@ -30,6 +44,14 @@ class RoleService:
user_id: UUID,
role_id: int,
):
"""
为用户分配角色
Args:
session: 数据库会话对象
user_id: 用户UUID
role_id: 角色ID
"""
user_role = UserRole(user_id=user_id, role_id=role_id)
session.add(user_role)
await session.commit()
@@ -37,6 +59,16 @@ class RoleService:
@classmethod
async def get_role_by_name(cls, session: AsyncSession, name: str) -> Optional[Role]:
"""
根据角色名称查询角色
Args:
session: 数据库会话对象
name: 角色名称
Returns:
Optional[Role]: 找到的角色对象，未找到则返回None
"""
result = await session.execute(select(Role).where(Role.name == name))
return result.scalar_one_or_none()
@@ -44,6 +76,16 @@ class RoleService:
async def get_role_by_id(
cls, session: AsyncSession, role_id: int
) -> Optional[Role]:
"""
根据角色ID查询角色
Args:
session: 数据库会话对象
role_id: 角色ID
Returns:
Optional[Role]: 找到的角色对象，未找到则返回None
"""
result = await session.get(Role, role_id)
return result
@@ -53,9 +95,25 @@ class RoleService:
user_id: UUID,
role_id: int,
):
"""
从用户解绑角色
Args:
session: 数据库会话对象
user_id: 用户UUID
role_id: 角色ID
Returns:
User: 更新后的用户对象
Raises:
HTTPException: 当用户不存在时抛出404错误
"""
user = await UserService.get_user_by_id(user_id, session)
if user is None:
raise HTTPException(status_code=404, detail="User not found")
# 过滤掉指定角色，保留其他角色
user.roles = [role for role in user.roles if role.id != role_id]
await session.commit()
await session.refresh(user)
@@ -66,14 +124,30 @@ class RoleService:
role_id: int,
session: AsyncSession,
) -> bool:
"""
删除角色
Args:
role_id: 角色ID
session: 数据库会话对象
Returns:
bool: 删除成功返回True
Raises:
HTTPException: 当角色被使用时抛出400错误，角色不存在时抛出404错误
"""
# 检查角色是否被用户使用
result = await session.execute(
select(UserRole).where(UserRole.role_id == role_id)
)
if result.scalars().all():
raise HTTPException(status_code=400, detail="Role is not empty")
role = await RoleService.get_role_by_id(session, role_id)
if role is None:
raise HTTPException(status_code=404, detail="Role not found")
await session.delete(role)
await session.commit()
return True
@@ -85,9 +159,25 @@ class RoleService:
role_update: RoleUpdate,
session: AsyncSession,
) -> Optional[Role]:
"""
更新角色信息
Args:
role_id: 角色ID
role_update: 角色更新数据对象
session: 数据库会话对象
Returns:
Optional[Role]: 更新后的角色对象
Raises:
HTTPException: 当角色不存在时抛出404错误
"""
role = await cls.get_role_by_id(session, role_id)
if role is None:
raise HTTPException(status_code=404, detail="Role not found")
# 只更新提供的字段，保持原有值不变
role.name = role_update.name if role_update.name else role.name
role.description = (
role_update.description if role_update.description else role.description
src/chongming/app/service/todo.py
+56
View File
@@ -7,8 +7,20 @@ from ..model.todo import TodoCreate, Todo, TodoUpdate
class TodoService:
"""待办事项服务类，提供待办事项的增删改查操作"""
@staticmethod
async def create_todo(todo: TodoCreate, session: AsyncSession) -> Todo:
"""
创建新的待办事项
Args:
todo: 待办事项创建数据对象，包含待办事项的初始信息
session: 异步数据库会话对象，用于执行数据库操作
Returns:
Todo: 创建成功后的待办事项对象，包含生成的ID等信息
"""
db_todo = Todo.model_validate(todo)
session.add(db_todo)
await session.commit()
@@ -21,6 +33,17 @@ class TodoService:
limit: int,
session: AsyncSession,
) -> Sequence[Todo]:
"""
获取待办事项列表（支持分页）
Args:
offset: 查询偏移量，指定从第几条记录开始查询
limit: 查询限制数量，指定最多返回多少条记录
session: 异步数据库会话对象，用于执行数据库操作
Returns:
Sequence[Todo]: 待办事项对象列表，按查询条件返回的结果集
"""
result = await session.execute(select(Todo).offset(offset).limit(limit))
todos = result.scalars().all()
return todos
@@ -30,6 +53,16 @@ class TodoService:
todo_id: int,
session: AsyncSession,
) -> Optional[Todo]:
"""
根据ID获取单个待办事项
Args:
todo_id: 待办事项的唯一标识ID
session: 异步数据库会话对象，用于执行数据库操作
Returns:
Optional[Todo]: 如果找到则返回待办事项对象，否则返回None
"""
todo = await session.get(Todo, todo_id)
return todo
@@ -39,9 +72,22 @@ class TodoService:
todo_update: TodoUpdate,
session: AsyncSession,
) -> Optional[Todo]:
"""
更新待办事项信息
Args:
todo_id: 待办事项的唯一标识ID
todo_update: 待办事项更新数据对象，包含需要更新的字段信息
session: 异步数据库会话对象，用于执行数据库操作
Returns:
Optional[Todo]: 如果更新成功则返回更新后的待办事项对象，如果待办事项不存在则返回None
"""
todo = await session.get(Todo, todo_id)
if not todo:
return None
# 提取需要更新的字段数据，排除未设置的字段
update_data = todo_update.model_dump(exclude_unset=True)
for key, value in update_data.items():
@@ -57,6 +103,16 @@ class TodoService:
todo_id: int,
session: AsyncSession,
) -> bool:
"""
删除待办事项
Args:
todo_id: 待办事项的唯一标识ID
session: 异步数据库会话对象，用于执行数据库操作
Returns:
bool: 如果删除成功返回True，如果待办事项不存在返回False
"""
todo = await session.get(Todo, todo_id)
if not todo:
return False
src/chongming/app/service/uploads.py
+40
View File
@@ -13,7 +13,22 @@ config = get_config()
class UploadService:
"""
文件上传服务类
提供文件上传功能，支持将上传的文件保存到指定目录，
并生成唯一的文件名以避免冲突。
"""
def __init__(self, upload_dir: str, chunk_size: int, file_type: str):
"""
初始化上传服务
Args:
upload_dir: 文件上传的根目录路径
chunk_size: 文件读取的块大小（字节），用于控制内存使用
file_type: 文件类型标识，用于创建对应的子目录
"""
self.upload_dir = upload_dir
self.file_type = file_type
self.chunk_size = chunk_size
@@ -21,12 +36,35 @@ class UploadService:
UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
async def upload(self, file_data: UploadFile):
"""
异步上传文件
接收上传的文件数据，生成唯一文件名，并将文件分块写入到服务器磁盘。
上传成功后返回文件的访问URL和新文件名。
Args:
file_data: FastAPI的UploadFile对象，包含上传的文件数据和元信息
Returns:
tuple: 包含两个元素的元组
- str: 文件的完整访问URL路径
- str: 生成的新文件名（UUID + 原始扩展名）
Raises:
HTTPException:
- 400: 当文件名为空或无效时抛出
- 500: 当文件写入过程中发生异常时抛出
"""
if file_data.filename is None:
raise HTTPException(status_code=400, detail="Invalid file name")
# 提取文件扩展名并生成唯一的UUID文件名
ext = os.path.splitext(file_data.filename)[1].lower()
new_filename = f"{uuid.uuid4().hex}{ext}"
file_path = os.path.join(self.upload_dir, self.file_type, new_filename)
try:
# 分块读取上传文件并异步写入磁盘，避免大文件占用过多内存
async with aiofiles.open(file_path, "wb") as out_file:
while chunk := await file_data.read(self.chunk_size):
await out_file.write(chunk)
@@ -34,6 +72,8 @@ class UploadService:
raise HTTPException(status_code=500, detail=str(e))
finally:
await file_data.close()
# 构建并返回文件的访问URL和新文件名
return (
f"{config['default']['prefix']}/{self.file_type}/{new_filename}".replace(
"\\", "/"
src/chongming/app/service/user.py
+37
View File
@@ -9,19 +9,56 @@ from ..core.security import get_password_hash
class UserService:
"""用户服务类，提供用户相关的业务逻辑操作"""
@staticmethod
async def get_user_by_email(email: str, session: AsyncSession) -> Optional[User]:
"""
根据邮箱地址查询用户
Args:
email: 用户的邮箱地址
session: 异步数据库会话
Returns:
如果找到则返回用户对象，否则返回None
"""
result = await session.execute(select(User).where(User.email == email)) # type: ignore
return result.scalar_one_or_none()
@staticmethod
async def get_user_by_id(user_id: UUID, session: AsyncSession) -> Optional[User]:
"""
根据用户ID查询用户
Args:
user_id: 用户的UUID标识
session: 异步数据库会话
Returns:
如果找到则返回用户对象，否则返回None
"""
return await session.get(User, user_id)
@staticmethod
async def create_user(
session: AsyncSession, email: str, password: str, **kwargs
) -> User:
"""
创建新用户
Args:
session: 异步数据库会话
email: 用户的邮箱地址
password: 用户的明文密码，将自动进行哈希加密
**kwargs: 其他用户属性参数
Returns:
创建成功的用户对象
Raises:
IntegrityError: 当邮箱已存在时可能抛出完整性错误
"""
hashed = get_password_hash(password)
user = User(email=email, hashed_password=hashed, **kwargs)
session.add(user)
src/chongming/app/task/__init__.py
+14
View File
@@ -8,6 +8,20 @@ config = get_config()
async def init_tasks_callback(task_service: TaskService):
"""
初始化任务回调函数
在开发环境下自动添加数据库初始化定时任务。
Args:
task_service (TaskService): 任务服务实例，用于管理和调度定时任务
Returns:
None: 此函数不返回任何值
Note:
仅在开发环境（env == "development"）下执行数据库初始化任务
"""
if config["default"]["env"] == "development":
await task_service.add_date_job(
src/chongming/app/task/dev_init_db.py
+50
View File
@@ -10,6 +10,23 @@ logger = get_logger("scheduler")
async def dev_init_admin(session):
"""
初始化系统管理员用户
检查是否存在邮箱为"admin"的管理员用户，如果不存在则创建一个新的超级管理员账户。
该函数用于系统首次部署时的管理员账户初始化。
Args:
session: 数据库会话对象，用于执行数据库操作
Returns:
None
Note:
- 默认管理员邮箱和密码均为"admin"
- 如果管理员已存在，则跳过创建并记录日志
- 新创建的用户具有超级管理员权限（is_superuser=True）
"""
admin_user = await UserService.get_user_by_email("admin", session)
if admin_user: # type: ignore
logger.info("管理员用户已存在") # type: ignore
@@ -18,6 +35,24 @@ async def dev_init_admin(session):
async def init_permission(session):
"""
初始化系统权限数据
遍历所有预定义的权限常量，检查数据库中是否已存在对应权限记录。
对于不存在的权限，创建新的权限记录并关联对应的资源和操作类型。
Args:
session: 数据库会话对象，用于执行数据库操作
Returns:
None
Note:
- 权限格式为"resource:action"，例如"user:create"
- 使用冒号分隔资源和操作，如果缺少操作部分则默认为空字符串
- 已存在的权限会被跳过，避免重复创建
- 每个新创建的权限都会记录到日志中
"""
for permission in PermissionConstant.get_all():
parts = permission.split(":", 1)
resource = parts[0]
@@ -35,6 +70,21 @@ async def init_permission(session):
async def init_db():
"""
执行数据库初始化流程
协调执行所有数据库初始化任务，包括管理员账户创建和权限数据初始化。
该函数是系统启动时数据库初始化的入口点。
Returns:
None
Note:
- 通过任务服务获取异步会话工厂
- 如果会话工厂未初始化，则直接返回不执行任何操作
- 按顺序执行：先初始化管理员，再初始化权限
- 使用异步上下文管理器确保会话正确关闭
"""
task_service = get_task_service_instance()
if task_service.async_session_maker is None:
return
src/chongming/scripts/build.py
+91 -13
View File
@@ -1,21 +1,31 @@
import platform
from module_bank import PythonToSQLite
from module_bank.encryption import Encryption
import os
from pathlib import Path
import platform
import shutil
import subprocess
import sys
import asyncio
from pathlib import Path
from module_bank import PythonToSQLite
from module_bank.encryption import Encryption
from sqlite_vfs.core import SQLiteVFS
from sqlite_vfs.folder_packer import FolderPacker
is_windows = platform.system() == "Windows"
def build_vue_web():
"""打包 Vue Web"""
"""
打包 Vue Web 前端项目
该函数执行以下操作:
1. 运行 npm build 命令构建 Vue 项目
2. 将构建产物打包到 SQLite VFS 虚拟文件系统中
Returns:
None: 无返回值,通过打印信息反馈执行结果
"""
# 构建 Vue Web 命令
dist_dir = "./src/chongming-web/dist"
output_db = "./build/static.svfs"
@@ -43,12 +53,12 @@ def build_vue_web():
print("Vue Web 打包成功")
if result.stdout:
print(result.stdout)
# 检查 dist 目录是否存在
if not os.path.exists(dist_dir):
print(f"错误: dist 目录不存在: {dist_dir}")
return
vfs = SQLiteVFS(output_db, compress=False)
packer = FolderPacker(
sqlite_vfs=vfs,
@@ -58,12 +68,27 @@ def build_vue_web():
try:
packer.pack_folder(dist_dir)
print(f"✅ 打包完成，文件保存为 {output_db}")
print(f"✅ 打包完成,文件保存为 {output_db}")
finally:
vfs.close()
def run_pyarmor_obfuscate():
"""
使用 PyArmor 对关键 Python 文件进行代码混淆
该函数遍历预定义的文件列表,对每个文件执行 pyarmor gen 命令进行混淆处理,
以保护源代码不被轻易反编译。
处理的文件包括:
- main.py (主入口文件)
- server.py (服务器文件)
- utils/launch.py (启动工具)
- utils/config.py (配置工具)
Returns:
None: 无返回值,遇到错误时提前返回
"""
# pyarmor obfuscate --output=obfuscated_script.py original_script.py
obfuscate_files = [
("main.py", "./"),
@@ -89,7 +114,18 @@ def run_pyarmor_obfuscate():
def run_pyinstaller():
"""运行 PyInstaller 打包成可执行文件"""
"""
使用 PyInstaller 将应用打包成单文件可执行程序
该函数根据操作系统平台(Windows/非Windows)构建不同的 PyInstaller 命令,
包含所有必要的隐藏导入以确保依赖库被正确打包。
Windows 和非 Windows 平台的主要区别:
- 非 Windows 平台额外包含 gunicorn 相关模块
Returns:
None: 无返回值,通过打印信息反馈执行结果
"""
try:
# 构建 PyInstaller 命令
if is_windows:
@@ -230,19 +266,36 @@ def run_pyinstaller():
result = subprocess.run(cmd, cwd="./build", capture_output=True, text=True)
if result.returncode == 0:
print("PyInstaller 打包成功！")
print("PyInstaller 打包成功!")
print(result.stdout)
else:
print("PyInstaller 打包失败！")
print("PyInstaller 打包失败!")
print("错误信息:", result.stderr)
except FileNotFoundError:
print("错误：未找到 PyInstaller，请先安装 PyInstaller：pip install pyinstaller")
print("错误:未找到 PyInstaller,请先安装 PyInstaller:pip install pyinstaller")
except Exception as e:
print(f"PyInstaller 执行出错: {e}")
async def init_database():
"""
异步初始化数据库
该函数执行以下操作:
1. 从配置中读取数据库连接信息
2. 创建异步数据库引擎和会话工厂
3. 设置 SQLite 优化参数(WAL 模式和同步策略)
4. 创建所有 SQLModel 定义的数据库表
5. 初始化权限系统和默认管理员账户
Raises:
ValueError: 当数据库配置不存在时抛出
OperationalError: 当数据库操作出现异常时抛出(已存在表的情况除外)
Returns:
None: 无返回值
"""
from sqlalchemy.ext.asyncio import create_async_engine
from sqlmodel import SQLModel, text
from sqlalchemy.exc import OperationalError
@@ -284,6 +337,23 @@ async def init_database():
async def main():
"""
主构建流程函数
该函数协调整个应用的构建过程,按顺序执行以下步骤:
1. 加密打包 Python 模块(app 和 plugins)到 SQLite 数据库文件
2. 创建并准备 build 目录结构
3. 复制必要的源文件和配置文件到 build 目录
4. 注入动态生成的加密密钥到配置文件
5. 对关键文件进行代码混淆
6. 使用 PyInstaller 打包成可执行文件
7. 清理临时构建文件
8. 初始化数据库
9. 构建 Vue 前端项目
Returns:
None: 无返回值
"""
# 打包模块
key = Encryption.generate_key()
resources_path = Path("resources")
@@ -367,4 +437,12 @@ async def main():
def build():
"""
构建入口函数
该函数作为整个构建流程的入口点,通过 asyncio.run() 启动异步主构建流程。
Returns:
None: 无返回值
"""
asyncio.run(main())