refactor(time): 重构应用程序中的日期时间处理

- 新增工具模块 `datetime_utils.py`，用于统一处理UTC和上海时区
- 在 `manager.py`、`models.py` 等后端文件中，将直接操作日期时间的代码替换为工具函数
- 更新前端组件，使用 `dayjs` 进行时区感知的日期格式化和解析
- 移除冗余的日期格式化逻辑，将其集中到工具函数中
- 通过确保所有时间戳均以亚洲/上海时区显示，提升用户体验

Author: xerrors

.env.template

@@ -41,3 +41,6 @@ NEO4J_PASSWORD=
 # Servies
 YUXI_SUPER_ADMIN_NAME=
 YUXI_SUPER_ADMIN_PASSWORD=
+
+# MinerU
+MINERU_API_KEY=

docs/changelog/roadmap.md

@@ -2,35 +2,31 @@
 
 路线图可能会经常变更，如果有强烈的建议，可以在 [issue](https://github.com/xerrors/Yuxi-Know/issues) 中提。
 
-## Version 0.3.x
+- [2025/10/13] 0.3.0 进入 beta 测试环节，不会再封装新的特性，仅作 bug 层面的修复
 
 
-🐛**BUGs**
+**Bugs**
 - [ ] 调用统计的统计结果疑似有问题（Token 计算方法可能也不对）
 
 
----
-
-💭 **Features Todo**
+**Next**
 
 - [ ] 添加对于上传文件的支持
-- [ ] 知识图谱的上传和可视化，支持属性，标签的展示
+- [ ] 知识图谱的上传和可视化，支持属性，标签的展示 <Badge type="info" text="0.4" />
 - [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
-- [ ] 开发与生产环境隔离，构建生产镜像（0.4）
-- [x] 添加统计信息
-- [ ] 支持 MinerU 2.5 的解析方法（含API方法）
-- [x] 移除自定义模型支持
+- [ ] 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
+- [ ] 支持 MinerU 2.5 的解析方法（含API方法）<Badge type="info" text="0.3.5" />
+- [ ] 优化全局配置的管理模型，优化配置管理
 
-📝 **Base**
+**Later**
 
-- [ ] 优化全局配置的管理模型，以及配置文件的管理，子配置的管理
-- [x] 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。
-- [ ] 新增 files 模块，用来管理文件上传，下载等
+下面的功能**可能**会放在后续版本实现，暂时未定
 
-## 未来可能会支持
+- [ ] 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
+
+**Done**
 
-下面的功能**可能**会放在后续版本实现，暂时未定
 
 - [x] 添加测试脚本，覆盖最常见的功能（已覆盖API）
-- [x] 优化对文档信息的检索展示（检索结果页、详情页）
-- [ ] 集成 LangFuse (观望)添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
+- [x] 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。
+- [x] 优化对文档信息的检索展示（检索结果页、详情页）

docs/intro/quick-start.md

@@ -14,12 +14,13 @@
 
 ```bash
 # 克隆稳定版本
-git clone --branch 0.2.2 --depth 1 https://github.com/xerrors/Yuxi-Know.git
+git clone --branch v0.2.2 --depth 1 https://github.com/xerrors/Yuxi-Know.git
 cd Yuxi-Know
 ```
 
 ::: warning 版本说明
-- `0.2.2`: 当前稳定版本（推荐）
+- `v0.2.2`: 当前稳定版本（推荐）
+- `v0.3.0-beta`：最新的 Beta 测试版
 - `main`: 最新开发版本（不稳定，新特性可能会导致新 bug）
 :::
 

server/routers/auth_router.py

@@ -1,4 +1,3 @@
-from datetime import datetime
 import re
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status, UploadFile, File
@@ -13,6 +12,7 @@
 from server.utils.user_utils import generate_unique_user_id, validate_username, is_valid_phone_number
 from server.utils.common_utils import log_operation
 from src.storage.minio import upload_image_to_minio
+from src.utils.datetime_utils import utc_now
 
 # 创建路由器
 auth = APIRouter(prefix="/auth", tags=["authentication"])
@@ -151,7 +151,7 @@ async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends(
 
     # 登录成功，重置失败计数器
     user.reset_failed_login()
-    user.last_login = datetime.now()
+    user.last_login = utc_now()
     db.commit()
 
     # 生成访问令牌
@@ -220,7 +220,7 @@ async def initialize_admin(admin_data: InitializeAdmin, db: Session = Depends(ge
         avatar=None,  # 初始化时头像为空
         password_hash=hashed_password,
         role="superadmin",
-        last_login=datetime.now(),
+        last_login=utc_now(),
     )
 
     db.add(new_admin)
@@ -527,7 +527,7 @@ async def delete_user(
     hash_suffix = hashlib.md5(user.user_id.encode()).hexdigest()[:4]
 
     user.is_deleted = 1
-    user.deleted_at = datetime.now()
+    user.deleted_at = utc_now()
     user.username = f"已注销用户-{hash_suffix}"
     user.phone_number = None  # 清空手机号，释放该手机号供其他用户使用
     user.password_hash = "DELETED"  # 禁止登录

server/routers/chat_router.py

@@ -306,7 +306,11 @@ async def stream_messages():
                 else:
                     yield make_chunk(msg=msg.model_dump(), metadata=metadata, status="loading")
 
-            if conf.enable_content_guard and hasattr(full_msg, "content") and await content_guard.check(full_msg.content):
+            if (
+                conf.enable_content_guard
+                and hasattr(full_msg, "content")
+                and await content_guard.check(full_msg.content)
+            ):
                 logger.warning("Sensitive content detected in final message")
                 yield make_chunk(message="检测到敏感内容，已中断输出", status="error")
                 return

server/routers/dashboard_router.py

@@ -16,6 +16,7 @@
 from server.utils.auth_middleware import get_db
 from src.storage.conversation import ConversationManager
 from src.storage.db.models import User
+from src.utils.datetime_utils import UTC, ensure_shanghai, shanghai_now, utc_now
 from src.utils.logging_config import logger
 
 
@@ -231,7 +232,7 @@ async def get_user_activity_stats(
     try:
         from src.storage.db.models import User, Conversation
 
-        now = datetime.utcnow()
+        now = utc_now()
 
         # Conversations may store either the numeric user primary key or the login user_id string.
         # Join condition accounts for both representations.
@@ -305,7 +306,7 @@ async def get_tool_call_stats(
     try:
         from src.storage.db.models import ToolCall
 
-        now = datetime.utcnow()
+        now = utc_now()
 
         # 基础工具调用统计
         total_calls = db.query(func.count(ToolCall.id)).scalar() or 0
@@ -746,30 +747,30 @@ async def get_call_timeseries_stats(
         from src.storage.db.models import Conversation, Message, ToolCall
 
         # 计算时间范围（使用北京时间 UTC+8）
-        now = datetime.utcnow()
-        local_now = now + timedelta(hours=8)
+        now = utc_now()
+        local_now = shanghai_now()
 
         if time_range == "7hours":
             intervals = 7
             # 包含当前小时：从6小时前开始
             start_time = now - timedelta(hours=intervals - 1)
             group_format = func.strftime("%Y-%m-%d %H:00", func.datetime(Message.created_at, "+8 hours"))
-            base_local_time = start_time + timedelta(hours=8)
+            base_local_time = ensure_shanghai(start_time)
         elif time_range == "7weeks":
             intervals = 7
             # 包含当前周：从6周前开始，并对齐到当周周一 00:00
             local_start = local_now - timedelta(weeks=intervals - 1)
             local_start = local_start - timedelta(days=local_start.weekday())
             local_start = local_start.replace(hour=0, minute=0, second=0, microsecond=0)
-            start_time = local_start - timedelta(hours=8)
+            start_time = local_start.astimezone(UTC)
             group_format = func.strftime("%Y-%W", func.datetime(Message.created_at, "+8 hours"))
             base_local_time = local_start
         else:  # 7days (default)
             intervals = 7
             # 包含当前天：从6天前开始
             start_time = now - timedelta(days=intervals - 1)
             group_format = func.strftime("%Y-%m-%d", func.datetime(Message.created_at, "+8 hours"))
-            base_local_time = start_time + timedelta(hours=8)
+            base_local_time = ensure_shanghai(start_time)
 
         # 根据类型查询数据
         if type == "models":

server/services/tasker.py

@@ -3,20 +3,20 @@
 import os
 import uuid
 from dataclasses import asdict, dataclass, field
-from datetime import datetime
 from pathlib import Path
 from typing import Any
 from collections.abc import Awaitable, Callable
 
 from src.config import config
 from src.utils.logging_config import logger
+from src.utils.datetime_utils import utc_isoformat
 
 TaskCoroutine = Callable[["TaskContext"], Awaitable[Any]]
 TERMINAL_STATUSES = {"success", "failed", "cancelled"}
 
 
 def _utc_timestamp() -> str:
-    return datetime.utcnow().isoformat() + "Z"
+    return utc_isoformat()
 
 
 @dataclass
@@ -142,7 +142,7 @@ async def list_tasks(self, status: str | None = None) -> list[dict[str, Any]]:
             tasks = list(self._tasks.values())
         if status:
             tasks = [task for task in tasks if task.status == status]
-        tasks.sort(key=lambda item: item.created_at, reverse=True)
+        tasks.sort(key=lambda item: item.created_at or utc_isoformat(), reverse=True)
         return [task.to_dict() for task in tasks]
 
     async def get_task(self, task_id: str) -> dict[str, Any] | None:

server/utils/auth_utils.py

@@ -1,10 +1,12 @@
 import hashlib
 import os
-from datetime import datetime, timedelta
+from datetime import timedelta
 from typing import Any
 
 import jwt
 
+from src.utils.datetime_utils import utc_now
+
 # JWT配置
 JWT_SECRET_KEY = os.environ.get("JWT_SECRET_KEY", "yuxi_know_secure_key")
 JWT_ALGORITHM = "HS256"
@@ -46,9 +48,9 @@ def create_access_token(data: dict[str, Any], expires_delta: timedelta | None =
 
         # 设置过期时间
         if expires_delta:
-            expire = datetime.utcnow() + expires_delta
+            expire = utc_now() + expires_delta
         else:
-            expire = datetime.utcnow() + timedelta(seconds=JWT_EXPIRATION)
+            expire = utc_now() + timedelta(seconds=JWT_EXPIRATION)
 
         to_encode.update({"exp": expire})
 

server/utils/migrate.py

@@ -5,10 +5,10 @@
 import os
 import shutil
 import sqlite3
-from datetime import datetime
 from pathlib import Path
 
 from src.utils import logger
+from src.utils.datetime_utils import shanghai_now
 
 
 class DatabaseMigrator:
@@ -30,7 +30,7 @@ def backup_database(self) -> str:
             return ""
 
         self.ensure_backup_dir()
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        timestamp = shanghai_now().strftime("%Y%m%d_%H%M%S")
         backup_filename = f"server_backup_{timestamp}.db"
         backup_path = os.path.join(self.backup_dir, backup_filename)
 

src/knowledge/base.py

@@ -1,11 +1,10 @@
 import json
 import os
-import time
 from abc import ABC, abstractmethod
-from datetime import datetime
 from typing import Any
 
 from src.utils import logger
+from src.utils.datetime_utils import coerce_any_to_utc_datetime, utc_isoformat
 
 
 class KnowledgeBaseException(Exception):
@@ -54,6 +53,34 @@ def __init__(self, work_dir: str):
 
         # 自动加载元数据
         self._load_metadata()
+        self._normalize_metadata_state()
+
+    @staticmethod
+    def _normalize_timestamp(value: Any) -> str | None:
+        """Convert persisted timestamps to a normalized UTC ISO string."""
+        try:
+            dt_value = coerce_any_to_utc_datetime(value)
+        except (TypeError, ValueError) as exc:  # noqa: BLE001
+            logger.warning(f"Invalid timestamp encountered: {value!r} ({exc})")
+            return None
+
+        if not dt_value:
+            return None
+        return utc_isoformat(dt_value)
+
+    def _normalize_metadata_state(self) -> None:
+        """Ensure in-memory metadata uses normalized timestamp formats."""
+        for meta in self.databases_meta.values():
+            if "created_at" in meta:
+                normalized = self._normalize_timestamp(meta.get("created_at"))
+                if normalized:
+                    meta["created_at"] = normalized
+
+        for file_info in self.files_meta.values():
+            if "created_at" in file_info:
+                normalized = self._normalize_timestamp(file_info.get("created_at"))
+                if normalized:
+                    file_info["created_at"] = normalized
 
     @property
     @abstractmethod
@@ -117,7 +144,7 @@ def create_database(
             "embed_info": embed_info,
             "llm_info": llm_info,
             "metadata": kwargs,
-            "created_at": datetime.now().isoformat(),
+            "created_at": utc_isoformat(),
         }
         self._save_metadata()
 
@@ -237,17 +264,24 @@ def get_database_info(self, db_id: str) -> dict | None:
         db_files = {}
         for file_id, file_info in self.files_meta.items():
             if file_info.get("database_id") == db_id:
+                created_at = self._normalize_timestamp(file_info.get("created_at"))
                 db_files[file_id] = {
                     "file_id": file_id,
                     "filename": file_info.get("filename", ""),
                     "path": file_info.get("path", ""),
                     "type": file_info.get("file_type", ""),
                     "status": file_info.get("status", "done"),
-                    "created_at": file_info.get("created_at", time.time()),
+                    "created_at": created_at,
                 }
 
         # 按创建时间倒序排序文件列表
-        sorted_files = dict(sorted(db_files.items(), key=lambda x: x[1].get("created_at", 0), reverse=True))
+        sorted_files = dict(
+            sorted(
+                db_files.items(),
+                key=lambda item: item[1].get("created_at") or "",
+                reverse=True,
+            )
+        )
 
         meta["files"] = sorted_files
         meta["row_count"] = len(sorted_files)
@@ -273,17 +307,24 @@ def get_databases(self) -> dict:
             db_files = {}
             for file_id, file_info in self.files_meta.items():
                 if file_info.get("database_id") == db_id:
+                    created_at = self._normalize_timestamp(file_info.get("created_at"))
                     db_files[file_id] = {
                         "file_id": file_id,
                         "filename": file_info.get("filename", ""),
                         "path": file_info.get("path", ""),
                         "type": file_info.get("file_type", ""),
                         "status": file_info.get("status", "done"),
-                        "created_at": file_info.get("created_at", time.time()),
+                        "created_at": created_at,
                     }
 
             # 按创建时间倒序排序文件列表
-            sorted_files = dict(sorted(db_files.items(), key=lambda x: x[1].get("created_at", 0), reverse=True))
+            sorted_files = dict(
+                sorted(
+                    db_files.items(),
+                    key=lambda item: item[1].get("created_at") or "",
+                    reverse=True,
+                )
+            )
 
             db_dict["files"] = sorted_files
             db_dict["row_count"] = len(sorted_files)
@@ -495,13 +536,14 @@ def _load_metadata(self):
 
     def _save_metadata(self):
         """保存元数据"""
+        self._normalize_metadata_state()
         meta_file = os.path.join(self.work_dir, f"metadata_{self.kb_type}.json")
         try:
             data = {
                 "databases": self.databases_meta,
                 "files": self.files_meta,
                 "kb_type": self.kb_type,
-                "updated_at": datetime.now().isoformat(),
+                "updated_at": utc_isoformat(),
             }
             with open(meta_file, "w", encoding="utf-8") as f:
                 json.dump(data, f, ensure_ascii=False, indent=2)