Merge pull request #3 from east-and-west-magic/optimize-refresh

CLAUDE.md

@@ -0,0 +1,189 @@
+# CLAUDE.md
+
+此文件为 Claude Code (claude.ai/code) 在此存储库中工作时提供指导。
+
+## 项目概述
+
+**LogDisplayer** 是一个基于 FastAPI 的日志聚合和显示系统，可以从多个端点/源收集日志，将其存储在本地，并同步到 Hugging Face 数据集。它提供了一个 Web UI，用于查看和管理带有 JWT 令牌用户认证的日志。
+
+**技术栈：**
+- 后端：FastAPI + Uvicorn（Python 3.10+）
+- 数据存储：Hugging Face Datasets、Pandas
+- 云同步：Hugging Face Hub API
+- 后台任务：APScheduler
+- 前端：Jinja2 模板（HTML/CSS/JavaScript）
+- 部署：Docker
+
+## 开发设置与命令
+
+### 前置要求
+- Python 3.10+
+- pip 包管理器
+- 环境变量：`hf_token`（Hugging Face 令牌）、`SECRET_KEY`（用于 JWT 解析）
+
+### 安装依赖
+```bash
+pip install -r requirements.txt
+```
+
+### 运行应用程序
+```bash
+# 标准开发运行
+uvicorn main:app --host 0.0.0.0 --port 7860
+
+# 带自动重载的开发运行
+uvicorn main:app --reload --host 0.0.0.0 --port 7860
+```
+
+应用将在 `http://localhost:7860` 可用
+
+### Docker 开发
+```bash
+# 构建 Docker 镜像
+docker build -t log-displayer .
+
+# 运行 Docker 容器
+docker run -p 7860:7860 \
+  -e hf_token="your_hf_token" \
+  -e SECRET_KEY="your_secret_key" \
+  log-displayer
+```
+
+### 测试
+当前没有配置正式的测试框架。手动测试脚本位于 `scratch/`：
+- `scratch/test_dataset_to_dict.py` - 测试数据集转换
+- `scratch/test_glob.py` - 测试文件搜索
+
+运行手动测试：
+```bash
+python scratch/test_dataset_to_dict.py
+python scratch/test_glob.py
+```
+
+## 架构概览
+
+### 核心组件
+
+**1. main.py（FastAPI 应用）**
+- 初始化 FastAPI 应用，配置 CORS 中间件
+- 定义 3 个主要端点：
+  - `POST /{end}` - 接受日志，包含消息体、可选的令牌头和源头
+  - `GET /healthcheck` - 健康检查端点
+  - `GET /` 或 `GET ""` - 使用所有日志渲染 HTML 模板
+- 实例化和管理 `LoggingHelper` 实例
+
+**2. logging_helper.py（日志管理引擎）**
+- `LoggingHelper` 类处理所有日志持久化和同步
+- **关键方法：**
+  - `addlog(log)` - 将日志添加到内存缓冲区
+  - `pull()` - 从 Hugging Face 下载今天的日志
+  - `push()` - 将缓冲的日志上传到 Hugging Face 数据集（标记缓存需要刷新）
+  - `push_yesterday()` - 归档昨天的日志
+  - `refresh()` - **[优化]** 返回所有日志作为排序的字典列表，使用 DataFrame 缓存机制避免重复加载
+  - `_load_all_logs()` - **[新增]** 从磁盘加载所有日志文件并合并成 DataFrame
+- **后台同步：** 使用 APScheduler 定期推送日志（默认：60 秒间隔）
+- **文件组织：** 日志在 HF 中组织为 `{year}/{month}/{day}/*.json`
+- **缓冲策略：** 内存中的 Hugging Face 数据集字典，按文件路径和需要推送状态跟踪
+- **缓存策略：** DataFrame 缓存 + 智能失效。只在 push() 完成或首次加载时重新读取磁盘文件
+
+**3. utils.py（辅助函数）**
+- `beijing()` - 返回 Asia/Shanghai 时区的当前时间
+- `parse_token(token)` - 解码 JWT 令牌以提取 uid 和用户名
+- `decode_jwt(token)` - 使用 SECRET_KEY 解码 JWT
+- `md5(text)` - 生成 MD5 哈希（用于日志文件名）
+- `json_to_str(obj)` - 将 JSON 转换为紧凑字符串格式
+
+**4. static/index.html（前端模板）**
+- 带有中文 UI 的 Jinja2 模板
+- 显示带有排序和过滤的日志表格
+- 显示列：类型、来源、用户、时间戳、内容
+
+### 数据流
+
+```
+日志 POST 请求
+  → main.py add_log()
+  → parse_token() 获取用户信息
+  → logging_helper.addlog()（添加到缓冲区）
+  → APScheduler 每 60 秒触发 push()
+  → logging_helper.push()（保存到本地 JSON，上传到 HF）
+  → 设置 cache_needs_refresh = True
+
+日志显示请求（带缓存优化）
+  → GET / 或 GET ""
+  → logging_helper.refresh()
+  → 调用 push()（如无新日志，快速返回）
+  → 检查缓存：
+     - 如果 cache_needs_refresh == True 或缓存为空 → _load_all_logs()（从磁盘加载）
+     - 否则 → 直接返回缓存的 DataFrame
+  → 返回排序的字典列表
+  → Jinja2 渲染 HTML 模板
+```
+
+### 环境变量
+
+必需：
+- `hf_token` - Hugging Face API 令牌，用于认证
+- `SECRET_KEY` - 用于 JWT 解码的密钥（用于解析用户令牌）
+
+### 关键设计模式
+
+1. **两级缓冲：** 内存缓冲 + 磁盘存储。日志在 Python 对象中缓冲，定期写入 JSON，然后推送到 Hugging Face。
+2. **基于日期的组织：** 日志自动组织到年/月/日目录中，便于归档数据管理。
+3. **后台同步：** APScheduler 确保定期推送日志，而不会阻止主请求处理程序。
+4. **无状态端点：** 每个请求都是独立的；用户信息在每次调用时从 JWT 令牌中提取。
+5. **DataFrame 缓存（性能优化）：** `refresh()` 方法缓存合并后的 DataFrame。只有在 `push()` 完成后才重新加载磁盘文件，避免每次刷新都重复读取和解析所有 JSON 文件。
+
+## 重要文件与职责
+
+| 文件 | 行数 | 用途 |
+|------|------|------|
+| [main.py](main.py) | 74 | FastAPI 应用初始化、端点定义 |
+| [logging_helper.py](logging_helper.py) | 235 | 核心日志持久化、缓冲、HF 同步和缓存机制 |
+| [utils.py](utils.py) | 64 | 时区、JWT 解析、哈希工具函数 |
+| [static/index.html](static/index.html) | ~400 | Jinja2 Web UI 模板 |
+| [requirements.txt](requirements.txt) | 10 | Python 依赖 |
+| [Dockerfile](Dockerfile) | - | Docker 镜像定义 |
+| [data/logs/](data/logs/) | - | 本地日志文件存储 |
+
+## 性能优化说明
+
+### 首页刷新优化（v1.1）
+
+**问题：** 之前每次刷新首页都需要从磁盘重新加载所有 JSON 日志文件，在日志数量较多时会导致加载时间过长。
+
+**解决方案：** 实现了 DataFrame 缓存机制。
+
+**具体改进：**
+
+1. **DataFrame 内存缓存** - 在 LoggingHelper 中添加 `cached_df` 变量存储合并后的 DataFrame
+2. **智能缓存失效** - 只有在调用 `push()` 方法写入新日志到磁盘后，才设置 `cache_needs_refresh = True` 标记
+3. **增量加载** - 新增 `_load_all_logs()` 私有方法，只在必要时（首次加载或 push 完成后）从磁盘重新加载数据
+
+**性能改进：**
+- **首次刷新：** 需要加载所有 JSON 文件（不可避免）
+- **后续刷新（无新日志）：** 直接返回缓存，避免磁盘 I/O，响应时间从秒级降低到毫秒级
+- **后续刷新（有新日志）：** push() 完成后重新加载，但由于 push() 已经处理完新日志，只需一次加载即可
+
+**相关代码变更：**
+- [logging_helper.py:43-45](logging_helper.py#L43-L45) - 添加缓存变量初始化
+- [logging_helper.py:172](logging_helper.py#L172) - push() 方法中标记缓存失效
+- [logging_helper.py:199-216](logging_helper.py#L199-L216) - 新增 _load_all_logs() 方法
+- [logging_helper.py:218-234](logging_helper.py#L218-L234) - 优化后的 refresh() 方法
+
+## 常见开发任务
+
+### 添加新的日志类型
+1. POST 到 `/{end}`，其中 `{end}` 是日志类型（例如 `/web`、`/mobile`、`/api`）
+2. LoggingHelper 自动在缓冲区中创建新条目，按日期组织
+
+### 调试日志
+- 查看 uvicorn 控制台输出，了解 add_log() 和 push() 中的打印语句
+- 查看 `data/logs/{year}/{month}/{day}/` 中的本地 JSON 文件以获取存储的日志
+- 检查 `data/logs/` 中下载的 HF 数据集
+
+### 修改同步间隔
+在 `logging_helper.py` 初始化（main.py 第 25-28 行）中调整 `synchronize_interval` 参数（以秒为单位）
+
+### 扩展 JWT 有效负载
+修改 utils.py 中的 `parse_token()` 以从 JWT 有效负载中提取其他字段，然后更新 main.py 中 add_log() 中的日志架构

logging_helper.py

@@ -5,15 +5,17 @@ a module of logs saving and backuping
 import os
 import datasets as ds
 from apscheduler.schedulers.background import BackgroundScheduler
-from tqdm import tqdm
 from utils import beijing, md5, json_to_str
 from huggingface_hub import HfApi
 import pandas as pd
-import glob
+from datetime import datetime, date, timedelta
+from zoneinfo import ZoneInfo
 
 hf = HfApi()
 hf.token = os.environ.get("hf_token")
 
+TIMEZONE = ZoneInfo("Asia/Shanghai")
+
 
 class LoggingHelper:
 
@@ -22,6 +24,7 @@ class LoggingHelper:
         repo_id: str,
         local_dir: str = "data/logs",
         synchronize_interval: int = 60,
+        cache_days: int = 30,
     ):
         """
         :param repo_id: the repo_id of the dataset in huggingface
@@ -29,6 +32,7 @@ class LoggingHelper:
         :param synchronize_interval: the interval of synchronizing between local and huggingface
 
         """
+        self.cache_days = cache_days
         self.local_dir = local_dir
         self.repo_id = repo_id
         self.synchronize_interval = synchronize_interval
@@ -36,10 +40,15 @@ class LoggingHelper:
         self.scheduler = BackgroundScheduler()
         self.buffer = dict[str, ds.Dataset]()
         self.need_push = dict[str, bool]()
+        self.timestamps = dict[str, str]()
         self.today = beijing().date()
         ds.disable_progress_bar()
         self.dataframe: pd.DataFrame
+        self.dataframe_refresh_needed = True
+        # 首先下载所有数据
         self.pull()
+        # 加载最近30天的日志数据到内存
+        self.load_logs()
         self.start_synchronize()
 
     def addlog(self, log: dict):
@@ -51,8 +60,10 @@ class LoggingHelper:
             self.buffer[remotepath] = self.buffer[remotepath].add_item(log)  # type: ignore
         else:
             self.buffer[remotepath] = ds.Dataset.from_dict({})
+            self.timestamps[remotepath] = beijing().isoformat(timespec="microseconds")
             self.buffer[remotepath] = self.buffer[remotepath].add_item(log)  # type: ignore
         self.need_push[remotepath] = True
+        self.dataframe_refresh_needed = True
         print("[addlog] Added a log to buffer")
 
     def remotedir(self):
@@ -62,36 +73,6 @@ class LoggingHelper:
         day = now.day.__str__()
         return "/".join([year, month, day])
 
-    def pull(self):
-        try:
-            self.download()
-            remotedir = self.remotedir()
-            print(f"[pull] today dir: {remotedir}")
-            filenames = hf.list_repo_files(
-                repo_id=self.repo_id,
-                repo_type=self.repo_type,
-            )
-            files_to_load = [
-                filename
-                for filename in filenames
-                if filename not in self.buffer
-                and filename.startswith(remotedir)
-                and filename.endswith(".json")
-            ]
-            print(f"[pull] total {len(files_to_load)} to load")
-            for filename in tqdm(files_to_load):
-                print()
-                path = os.sep.join([self.local_dir, filename])
-                with open(path, "r") as f:
-                    data = f.read()
-                if len(data) != 0:
-                    self.buffer[filename] = ds.Dataset.from_json(path)  # type: ignore
-                    self.need_push[filename] = False
-            return True
-        except Exception as e:
-            print(f"[pull] {type(e)}: {e}")
-            return False
-
     def push_yesterday(self) -> bool:
         try:
             year = self.today.year.__str__()
@@ -102,9 +83,6 @@ class LoggingHelper:
             for filename in self.buffer.keys():
                 if not filename.startswith(remotedir):
                     continue
-                if not self.need_push[filename]:
-                    del self.buffer[filename]
-                    del self.need_push[filename]
                 files_to_push.append(filename)
             if len(files_to_push) == 0:
                 return True
@@ -169,18 +147,160 @@ class LoggingHelper:
             print(f"[push] {type(e)}: {e}")
             return False
 
-    def download(self):
-        print("[download] Starting downloading")
+    def pull(self):
+        print("[pull] Starting downloading")
         try:
             res = hf.snapshot_download(
                 repo_id=self.repo_id,
-                repo_type="dataset",
+                repo_type=self.repo_type,
                 local_dir=self.local_dir,
             )
-            print(f"[download] Downloaded to {res}")
+            print(f"[pull] Downloaded to {res}")
+            remotepathes = hf.list_repo_files(
+                repo_id=self.repo_id, repo_type=self.repo_type
+            )
+            jsonfiles = [f for f in remotepathes if f.endswith(".json")]
+            print(f"[pull] {len(jsonfiles)} files found in remote repo")
+            print("[pull] Parsing timestamps")
+            for remotepath in jsonfiles:
+                try:
+                    parts = remotepath.split("/")
+                    year, month, day = parts[0], parts[1], parts[2]
+                    date_obj = date(int(year), int(month), int(day))
+                    timestamp = (
+                        datetime.combine(date_obj, datetime.min.time())
+                        .astimezone(TIMEZONE)
+                        .isoformat(timespec="microseconds")
+                    )
+                    self.timestamps[remotepath] = timestamp
+                except Exception as e:
+                    print(f"[pull] Error parsing timestamp of {remotepath}: {e}")
+                    continue
+            print("[pull] Done")
+        except Exception as e:
+            print(f"[pull] {type(e)}: {e}")
+        print("[pull] Done")
+
+    def get_pathes_between(self, from_date: date, to_date: date) -> dict[str, str]:
+        """
+        获取指定日期范围内的路径列表
+
+        :param from_date: 开始日期（格式：YYYY-MM-DD 或 datetime.date），含该日期
+        :param to_date: 结束日期（格式：YYYY-MM-DD 或 datetime.date），含该日期
+        :return: 日期范围内的路径列表，格式为 ["YYYY/MM/DD", ...]
+        """
+        pathes = {}
+        current_date = from_date
+        while current_date <= to_date:
+            key = f"{current_date.year}/{current_date.month}/{current_date.day}"
+            value = datetime.combine(current_date, datetime.min.time()).isoformat(
+                timespec="microseconds"
+            )
+            pathes[key] = value
+            current_date += timedelta(days=1)
+        return pathes
+
+    def load_logs(
+        self, from_timestamp: str | None = None, to_timestamp: str | None = None
+    ):
+        """
+        在启动时加载最近30天的日志数据到内存buffer
+        """
+        try:
+
+            start_timestamp = self.cutoff_timestamp()
+            end_timestamp = (
+                beijing()
+                .replace(hour=23, minute=59, second=59, microsecond=999999)
+                .isoformat(timespec="microseconds")
+            )
+            from_timestamp = from_timestamp or start_timestamp
+            to_timestamp = to_timestamp or end_timestamp
+            total_files_loaded = 0
+            for remotepath, timestamp in self.timestamps.items():
+                if timestamp < from_timestamp or timestamp > to_timestamp:
+                    continue
+                localpath = "/".join([self.local_dir, remotepath])
+                print(f"[load_logs] Loading file {localpath}")
+                # 检查该文件是否存在
+                if not os.path.exists(localpath):
+                    print(f"[load_logs] File not found: {localpath}")
+                    continue
+                try:
+                    # 检查文件是否为空
+                    if os.path.getsize(localpath) == 0:
+                        print(f"[load_logs] Skipping empty file: {remotepath}")
+                        continue
+                    if remotepath in self.buffer:
+                        print(f"[load_logs] File already loaded: {remotepath}")
+                        continue
+                    # 加载JSON数据到Dataset
+                    dataset = ds.Dataset.from_json(localpath)
+                    if isinstance(dataset, ds.Dataset):
+                        self.buffer[remotepath] = dataset
+                        self.need_push[remotepath] = False
+                        self.timestamps[remotepath] = timestamp
+                        total_files_loaded += 1
+                except Exception as e:
+                    print(f"[load_logs] Error loading {remotepath}: {e}")
+                    continue
+            if total_files_loaded > 0:
+                self.dataframe_refresh_needed = True
+            print(f"[load_logs] Successfully loaded {total_files_loaded} log files")
+            print(f"[load_logs] Total datasets in buffer: {len(self.buffer)}")
+        except Exception as e:
+            print(f"[load_logs] Error: {type(e)}: {e}")
+
+    def cutoff_timestamp(self) -> str:
+        """
+        计算用于清理日志的截止时间戳
+
+        :return: 截止时间戳，格式为 ISO 8601 字符串
+        """
+        cutoff_date = self.today - timedelta(days=self.cache_days)
+        cutoff_timestamp = (
+            datetime.combine(cutoff_date, datetime.min.time())
+            .astimezone(TIMEZONE)
+            .isoformat(timespec="microseconds")
+        )
+        return cutoff_timestamp
+
+    def cleanup_old_logs(self):
+        """
+        清理buffer中超过30天的日志数据
+
+        保留逻辑：保留最近cache_days天的日志
+        删除逻辑：删除早于 (today - cache_days) 的所有日志
+        """
+        try:
+            print("[cleanup_old_logs] Starting cleanup of old logs")
+            # 计算应该保留的最早日期（含这一天）
+            start_timestamp = self.cutoff_timestamp()
+            removed_count = 0
+            for filepath in list(self.buffer.keys()):
+                # filepath 格式类似 "2025/9/23/xx.json"
+                # 提取日期部分 "2025/9/23"
+                try:
+                    timestamp = self.timestamps[filepath]
+                    # 如果文件日期早于截断日期，则删除
+                    if timestamp >= start_timestamp:
+                        continue
+                    del self.buffer[filepath]
+                    del self.need_push[filepath]
+                    removed_count += 1
+                    print(f"[cleanup_old_logs] Removed {filepath}")
+                except (ValueError, IndexError) as e:
+                    print(f"[cleanup_old_logs] Error parsing filepath {filepath}: {e}")
+                    continue
+
+            print(f"[cleanup_old_logs] Cleaned up {removed_count} old log files")
+            print(
+                f"[cleanup_old_logs] Remaining datasets in buffer: {len(self.buffer)}"
+            )
+            print("[cleanup_old_logs] Done")
+
         except Exception as e:
-            print(f"[download] {type(e)}: {e}")
-        print("[download] Done")
+            print(f"[cleanup_old_logs] Error: {type(e)}: {e}")
 
     def start_synchronize(self):
         self.scheduler.add_job(
@@ -188,20 +308,67 @@ class LoggingHelper:
             "interval",
             seconds=self.synchronize_interval,
         )
+        # 添加每日清理任务，在每天凌晨2点执行
+        self.scheduler.add_job(
+            self.cleanup_old_logs,
+            "cron",
+            hour=2,
+            minute=0,
+        )
         self.scheduler.start()
 
-    def refresh(self) -> list[dict]:
-        self.push()
-        files = glob.glob("**/*.json", root_dir=self.local_dir, recursive=True)
-        filepathes = [os.sep.join([self.local_dir, file]) for file in files]
-        datasets = []
-        for path in tqdm(filepathes):
-            path = str(path)
-            datasets.append(ds.Dataset.from_json(path))
-        df = pd.DataFrame()
-        if datasets:
-            dataset: ds.Dataset = ds.concatenate_datasets(datasets)
-            df = dataset.to_pandas()
-            assert isinstance(df, pd.DataFrame)
-            df = df.sort_values(by="timestamp", ascending=False)
+    def refresh_dataframe(self) -> pd.DataFrame:
+        """内存中所有日志数据合并为一个DataFrame"""
+        datasets = list(self.buffer.values())
+        merged_dataset = ds.concatenate_datasets(datasets)
+        self.dataframe = merged_dataset.to_pandas()  # type: ignore
+        print(f"[refresh_dataframe] Loaded {len(self.dataframe)} logs")  # type: ignore
+        self.dataframe_refresh_needed = False
+        return self.dataframe  # type: ignore
+
+    def refresh(self, from_date: str | None, to_date: str | None) -> list[dict]:
+        """
+        获取刷新后的日志列表，支持查询任意时间范围的日志（包括超过30天前的日志）
+
+        当查询超过30天前的日志时，会动态从磁盘加载相应数据。
+        基于timestamp字段进行日期过滤。时间戳格式为 ISO 8601 格式（如 "2025-09-08T16:01:07.526954+08:00"）
+
+        :param from_date: 开始日期（格式：YYYY-MM-DD 或 datetime.date），含该日期的所有日志
+        :param to_date: 结束日期（格式：YYYY-MM-DD 或 datetime.date），含该日期的所有日志
+        :return: 按时间戳降序排列的日志字典列表
+        """
+        from_timestamp = None
+        if from_date is not None:
+            from_datetime = datetime.strptime(from_date, "%Y-%m-%d").astimezone(
+                TIMEZONE
+            )
+            from_timestamp = from_datetime.isoformat(timespec="microseconds")
+        to_timestamp = None
+        if to_date is not None:
+            to_datetime = (
+                datetime.strptime(to_date, "%Y-%m-%d")
+                .astimezone(TIMEZONE)
+                .replace(hour=23, minute=59, second=59, microsecond=999999)
+            )
+            to_timestamp = to_datetime.isoformat(timespec="microseconds")
+
+        print(
+            f"[refresh] Starting to load logs from {from_timestamp} to {to_timestamp}"
+        )
+        # 如果查询范围超出缓存范围，则加载相应的日志文件
+        self.load_logs(from_timestamp=from_timestamp, to_timestamp=to_timestamp)
+        if self.dataframe_refresh_needed:
+            self.refresh_dataframe()
+        df = self.dataframe
+        print(f"[refresh] Filtering logs from {from_date} to {to_date}")
+        # 创建日期范围过滤条件
+        filter_condition = pd.Series([True] * len(df), index=df.index)
+        if from_timestamp is not None:
+            filter_condition = filter_condition & (df["timestamp"] >= from_timestamp)
+        if to_timestamp is not None:
+            filter_condition = filter_condition & (df["timestamp"] <= to_timestamp)
+        df = df[filter_condition]
+        # 按timestamp降序排序（最新日志在前）
+        df = df.sort_values(by="timestamp", ascending=False)
+        print(f"[refresh] Returning {len(df)} logs")
         return df.to_dict(orient="records")

main.py

@@ -1,8 +1,9 @@
-from fastapi import FastAPI, Body, Header, Request
+from fastapi import FastAPI, Body, Header, Request, Query
 from fastapi.middleware.cors import CORSMiddleware
 from utils import beijing, parse_token
 from logging_helper import LoggingHelper
 from fastapi.templating import Jinja2Templates
+import datetime
 
 
 app = FastAPI(
@@ -65,8 +66,26 @@ templates = Jinja2Templates(directory="static")
 
 @app.get("")
 @app.get("/")
-async def root(request: Request):
-    data = logger.refresh()
+async def root(
+    request: Request,
+    from_date: str | None = Query(None),
+    to_date: str | None = Query(None),
+):
+    """
+    首页端点，支持日期范围查询
+
+    查询参数：
+    - from_date: 开始日期（格式：YYYY-MM-DD），不指定时默认加载今天
+    - to_date: 结束日期（格式：YYYY-MM-DD），不指定时默认为今天
+    """
+    # 如果没有指定日期范围，默认加载今天的日志
+    if from_date is None and to_date is None:
+        today = beijing().date().strftime("%Y-%m-%d")
+        from_date = today  # 今天的日志
+        to_date = today
+        print(f"[root] No date range specified, using today: {from_date} to {to_date}")
+
+    data = logger.refresh(from_date=from_date, to_date=to_date)
     return templates.TemplateResponse(
         "index.html",
         {"request": request, "data": data},

static/index.html

@@ -134,6 +134,71 @@
             box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
         }
 
+        .date-filter-container {
+            display: flex;
+            align-items: center;
+            gap: 15px;
+            margin-top: 20px;
+            flex-wrap: wrap;
+        }
+
+        .date-input-group {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+        }
+
+        .date-input-group label {
+            font-weight: 500;
+            color: #495057;
+            min-width: 60px;
+        }
+
+        .date-input-group input[type="date"] {
+            padding: 10px 15px;
+            border: 2px solid #e9ecef;
+            border-radius: 8px;
+            font-size: 14px;
+            background: white;
+            cursor: pointer;
+            transition: all 0.3s ease;
+        }
+
+        .date-input-group input[type="date"]:focus {
+            outline: none;
+            border-color: #667eea;
+            box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+        }
+
+        .date-shortcuts {
+            display: flex;
+            gap: 8px;
+            flex-wrap: wrap;
+        }
+
+        .date-shortcut-btn {
+            padding: 8px 15px;
+            border: 1px solid #e9ecef;
+            background: white;
+            border-radius: 8px;
+            cursor: pointer;
+            font-size: 13px;
+            color: #495057;
+            transition: all 0.3s ease;
+        }
+
+        .date-shortcut-btn:hover {
+            background: #667eea;
+            color: white;
+            border-color: #667eea;
+        }
+
+        .date-shortcut-btn.active {
+            background: #667eea;
+            color: white;
+            border-color: #667eea;
+        }
+
         .main {
             padding: 30px;
         }
@@ -228,8 +293,6 @@
             line-height: 1.4;
         }
 
-
-
         .timestamp {
             color: #6c757d;
             font-size: 0.9rem;
@@ -324,6 +387,19 @@
                 min-width: auto;
             }
 
+            .date-filter-container {
+                flex-direction: column;
+                align-items: stretch;
+            }
+
+            .date-input-group {
+                flex-direction: column;
+            }
+
+            .date-input-group label {
+                min-width: auto;
+            }
+
             .stats {
                 justify-content: center;
             }
@@ -360,7 +436,24 @@
                 <button class="btn btn-secondary" onclick="refreshLogs()">刷新</button>
             </div>
 
+            <div class="date-filter-container">
+                <div class="date-input-group">
+                    <label for="fromDate">开始日期：</label>
+                    <input type="date" id="fromDate">
+                </div>
+                <div class="date-input-group">
+                    <label for="toDate">结束日期：</label>
+                    <input type="date" id="toDate">
+                </div>
+                <button class="btn btn-primary" onclick="filterByDate()">过滤</button>
 
+                <div class="date-shortcuts">
+                    <button class="date-shortcut-btn" onclick="setDateRange('today')">今天</button>
+                    <button class="date-shortcut-btn" onclick="setDateRange('week')">最近7天</button>
+                    <button class="date-shortcut-btn" onclick="setDateRange('month')">最近30天</button>
+                    <button class="date-shortcut-btn" onclick="setDateRange('all')">全部</button>
+                </div>
+            </div>
         </div>
 
         <div class="main">
@@ -383,7 +476,7 @@
             <div class="no-data" id="noData" style="display: none;">
                 <div>📋</div>
                 <h3>暂无数据</h3>
-                <p>没有找到匹配的错误日志</p>
+                <p>没有找到匹配的日志</p>
             </div>
 
             <div class="pagination" id="pagination">
@@ -414,13 +507,124 @@
         let totalPages = 1;
         let filteredLogs = [...data];
         let searchTerm = '';
+        let currentDateFilter = null; // 记录当前的日期过滤范围
 
         // 初始化页面
         function initPage() {
+            // 从URL参数中读取日期范围
+            const urlParams = new URLSearchParams(window.location.search);
+            const fromDate = urlParams.get('from_date');
+            const toDate = urlParams.get('to_date');
+
+            if (fromDate) {
+                document.getElementById('fromDate').value = fromDate;
+            }
+            if (toDate) {
+                document.getElementById('toDate').value = toDate;
+            }
+
             renderLogs();
             updatePagination();
         }
 
+        // 获取今天的日期（YYYY-MM-DD格式）
+        function getTodayDate() {
+            const today = new Date();
+            return today.toISOString().split('T')[0];
+        }
+
+        // 获取指定天数前的日期
+        function getDateBefore(days) {
+            const date = new Date();
+            date.setDate(date.getDate() - days);
+            return date.toISOString().split('T')[0];
+        }
+
+        // 设置日期范围快捷选项
+        function setDateRange(range) {
+            const today = getTodayDate();
+
+            switch(range) {
+                case 'today':
+                    document.getElementById('fromDate').value = today;
+                    document.getElementById('toDate').value = today;
+                    break;
+                case 'week':
+                    document.getElementById('fromDate').value = getDateBefore(6);
+                    document.getElementById('toDate').value = today;
+                    break;
+                case 'month':
+                    document.getElementById('fromDate').value = getDateBefore(29);
+                    document.getElementById('toDate').value = today;
+                    break;
+                case 'all':
+                    document.getElementById('fromDate').value = '';
+                    document.getElementById('toDate').value = '';
+                    break;
+            }
+
+            // 更新快捷按钮的active状态
+            updateShortcutButtons(range);
+        }
+
+        // 更新快捷按钮的样式
+        function updateShortcutButtons(active) {
+            const buttons = document.querySelectorAll('.date-shortcut-btn');
+            buttons.forEach((btn, index) => {
+                const ranges = ['today', 'week', 'month', 'all'];
+                btn.classList.remove('active');
+                if (ranges[index] === active) {
+                    btn.classList.add('active');
+                }
+            });
+        }
+
+        // 按日期过滤
+        function filterByDate() {
+            const fromDate = document.getElementById('fromDate').value;
+            const toDate = document.getElementById('toDate').value;
+
+            if (!fromDate && !toDate) {
+                // 如果两个都为空，加载所有数据
+                currentDateFilter = null;
+                refreshFromServer(null, null);
+                return;
+            }
+
+            if (fromDate && toDate) {
+                if (fromDate > toDate) {
+                    alert('开始日期不能晚于结束日期');
+                    return;
+                }
+            }
+
+            // 记录当前的日期过滤
+            currentDateFilter = { from_date: fromDate, to_date: toDate };
+
+            // 刷新并带上日期参数
+            refreshFromServer(fromDate, toDate);
+        }
+
+        // 从服务器刷新数据，支持日期参数
+        function refreshFromServer(fromDate, toDate) {
+            let url = window.location.pathname;
+            const params = new URLSearchParams();
+
+            if (fromDate) {
+                params.append('from_date', fromDate);
+            }
+            if (toDate) {
+                params.append('to_date', toDate);
+            }
+
+            if (params.toString()) {
+                url += '?' + params.toString();
+            }
+
+            // 重新加载页面
+            window.location.href = url;
+        }
+
         // 改变每页显示数量
         function changePageSize() {
             const select = document.getElementById('pageSize');
@@ -533,11 +737,11 @@
         // 搜索日志
         function searchLogs() {
             searchTerm = document.getElementById('searchInput').value.trim();
-            
+
             if (searchTerm === '') {
                 filteredLogs = [...data];
             } else {
-                filteredLogs = data.filter(log => 
+                filteredLogs = data.filter(log =>
                     log.username.toLowerCase().includes(searchTerm.toLowerCase())
                 );
             }
@@ -549,9 +753,25 @@
 
         // 刷新日志
         function refreshLogs() {
-            // 模拟刷新数据
-            console.log('刷新日志数据...');
-            initPage();
+            // 如果有日期过滤，使用带日期参数的刷新
+            if (currentDateFilter) {
+                refreshFromServer(currentDateFilter.from_date, currentDateFilter.to_date);
+            } else {
+                // 获取当前的URL参数
+                const urlParams = new URLSearchParams(window.location.search);
+                const fromDate = urlParams.get('from_date');
+                const toDate = urlParams.get('to_date');
+
+                if (fromDate || toDate) {
+                    refreshFromServer(fromDate, toDate);
+                } else {
+                    // 模拟刷新数据
+                    console.log('刷新日志数据...');
+                    currentPage = 1;
+                    renderLogs();
+                    updatePagination();
+                }
+            }
         }
 
         // 监听回车键搜索
@@ -561,8 +781,21 @@
             }
         });
 
+        // 监听日期输入框的回车键
+        document.getElementById('fromDate').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                filterByDate();
+            }
+        });
+
+        document.getElementById('toDate').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                filterByDate();
+            }
+        });
+
         // 页面加载完成后初始化
         document.addEventListener('DOMContentLoaded', initPage);
     </script>
 </body>
-</html>
+</html>

utils.py

@@ -61,3 +61,43 @@ def md5(text: list[str | bytes] | str | bytes | None = None) -> str:
 
 def json_to_str(obj: dict | list) -> str:
     return json.dumps(obj, separators=(",", ":"))
+
+
+def validate_date_format(date_str: str, format_str: str = "%Y-%m-%d") -> bool:
+    """
+    验证日期字符串的格式是否正确
+
+    :param date_str: 要验证的日期字符串
+    :param format_str: 期望的日期格式（默认：YYYY-MM-DD）
+    :return: 如果格式正确返回 True，否则返回 False
+    """
+    if not date_str:
+        return True  # 空值被认为是有效的（可选参数）
+
+    try:
+        from datetime import datetime as dt
+        dt.strptime(date_str, format_str)
+        return True
+    except ValueError:
+        return False
+
+
+def parse_date_range(from_date: str | None, to_date: str | None) -> tuple[str | None, str | None] | tuple[str, str]:
+    """
+    解析和验证日期范围
+
+    :param from_date: 开始日期（格式：YYYY-MM-DD）
+    :param to_date: 结束日期（格式：YYYY-MM-DD）
+    :return: 验证后的日期范围元组 (from_date, to_date)
+    :raises ValueError: 如果日期格式不正确或范围无效
+    """
+    if from_date and not validate_date_format(from_date):
+        raise ValueError(f"Invalid from_date format: {from_date}")
+
+    if to_date and not validate_date_format(to_date):
+        raise ValueError(f"Invalid to_date format: {to_date}")
+
+    if from_date and to_date and from_date > to_date:
+        raise ValueError(f"from_date ({from_date}) cannot be after to_date ({to_date})")
+
+    return from_date, to_date