feat: 文件浏览页 + 共享白板 + 白板管理页（含补登记分片上传/隧道历史改动）

本次提交包含两批改动（7月2日遗留未入库 + 本次新功能），分述如下：【补登记：7月2日已上线但未提交的功能】 - 分片上传：chunk_upload_controller/service/dao + UploadSession model/schema，支持 4MiB 分片、乱序、断点续传、去重、幂等 complete；后台 reaper 清理过期会话。 - 反向隧道：tunnel_controller/service/dao + TunnelSession model/schema， SSH remote forward 经 /api/userPort/{userName} 反代到 user 本地服务。 - 上传页：views/upload_html.py（拖拽/多文件/分片/断点续传 UI）。 - config.py：StorageConfig.chunk_session_dir/ttl、TunnelConfig； requirements.txt 加 httpx；start.sh 清理 .work/ 残留； schema.sql 加 upload_session/tunnel_session 表；sftp_server 承载隧道转发。【本次新功能】 - 文件浏览页：GET /files（Basic Auth 同 docs）+ /api/admin/files（list/get/download/DELETE）。硬删除（DB 行 + 磁盘文件），删除后列表不再显示。前端 static/file_browser.*。 - 共享白板：GET /whiteboard/{id}（公开，不存在则新建）+ WS /ws/whiteboard/{id}。 MySQL 持久化（whiteboard 表），Canvas 实时同步，心跳 3s/5 次失活移除，清空/复制按钮，移动端兼容。WhiteboardHub 管理 {board_id: set[Connection]}， disconnect 幂等 + 空 set 清理防泄漏，broadcast 失败连接自动移除。 - 白板管理页：GET /whiteboard-admin（Basic Auth）+ /api/admin/whiteboards（list/DELETE）。删除时 hub.close_board 踢出在线连接。 - 清理：合并 UploadService.get_out_with_disk_path（下载/删除复用，消除重复 DB 读），移除无用 resolve_disk_path。 - config.py：WhiteboardConfig（heartbeat/threshold/board_id 长度/list_limit）； schema.sql 加 whiteboard 表；README 补新接口与心跳/内存说明。 - 验证：tests/manual_whiteboard_hub.py / _ws.py / _kick.py 全部通过。
2026-07-21 14:28:13 +00:00
parent e5a725fc91
commit fffba79022
48 changed files with 3569 additions and 216 deletions
--- a/app/dao/init.py
+++ b/app/dao/init.py
@@ -1,5 +1,7 @@
 """DAO 层：数据库访问的唯一入口。"""

+from .tunnel_session_dao import TunnelSessionDAO
 from .uploaded_file_dao import UploadedFileDAO
+from .upload_session_dao import UploadSessionDAO

-__all__ = ["UploadedFileDAO"]
+__all__ = ["TunnelSessionDAO", "UploadedFileDAO", "UploadSessionDAO"]
--- a/app/dao/tunnel_session_dao.py
+++ b/app/dao/tunnel_session_dao.py
@@ -0,0 +1,63 @@
+"""TunnelSession 的 DAO。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import select, update
+from sqlalchemy.orm import Session
+
+from ..models.tunnel_session import TunnelSession
+
+
+class TunnelSessionDAO:
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    def create(self, session: TunnelSession) -> TunnelSession:
+        self.db.add(session)
+        self.db.commit()
+        self.db.refresh(session)
+        return session
+
+    def get_active_by_user(self, user_name: str) -> TunnelSession | None:
+        """返回该 user 当前活跃的隧道会话(至多一条)。"""
+        stmt = (
+            select(TunnelSession)
+            .where(TunnelSession.user_name == user_name)
+            .where(TunnelSession.status == "active")
+            .order_by(TunnelSession.started_at.desc())
+            .limit(1)
+        )
+        return self.db.scalars(stmt).first()
+
+    def get_active_by_port(self, tunnel_port: int) -> TunnelSession | None:
+        stmt = (
+            select(TunnelSession)
+            .where(TunnelSession.tunnel_port == tunnel_port)
+            .where(TunnelSession.status == "active")
+            .limit(1)
+        )
+        return self.db.scalars(stmt).first()
+
+    def list_active(self) -> list[TunnelSession]:
+        stmt = select(TunnelSession).where(TunnelSession.status == "active")
+        return list(self.db.scalars(stmt).all())
+
+    def close(self, session: TunnelSession) -> None:
+        """标记会话结束。"""
+        session.ended_at = datetime.now()
+        session.status = "closed"
+        self.db.commit()
+
+    def close_active_by_user(self, user_name: str) -> int:
+        """关闭该 user 所有 active 会话(断开清理用),返回关闭条数。"""
+        stmt = (
+            update(TunnelSession)
+            .where(TunnelSession.user_name == user_name)
+            .where(TunnelSession.status == "active")
+            .values(status="closed", ended_at=datetime.now())
+        )
+        result = self.db.execute(stmt)
+        self.db.commit()
+        return result.rowcount or 0
--- a/app/dao/upload_session_dao.py
+++ b/app/dao/upload_session_dao.py
@@ -0,0 +1,57 @@
+"""UploadSession 的 DAO。"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..models.upload_session import UploadSession
+
+
+class UploadSessionDAO:
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    def create(self, session: UploadSession) -> UploadSession:
+        self.db.add(session)
+        self.db.commit()
+        self.db.refresh(session)
+        return session
+
+    def get_by_upload_id(self, upload_id: str) -> UploadSession | None:
+        stmt = (
+            select(UploadSession)
+            .where(UploadSession.upload_id == upload_id)
+            .limit(1)
+        )
+        return self.db.scalars(stmt).first()
+
+    def mark_uploaded(self, session: UploadSession, chunks: list[int]) -> UploadSession:
+        """更新已上传分片集合（整体替换，避免并发追加丢失）。"""
+        session.uploaded_chunks = sorted(set(chunks))
+        self.db.commit()
+        self.db.refresh(session)
+        return session
+
+    def mark_completed(self, session: UploadSession, file_id: int) -> UploadSession:
+        session.file_id = file_id
+        session.status = "completed"
+        self.db.commit()
+        self.db.refresh(session)
+        return session
+
+    def list_stale(self, ttl_seconds: int) -> list[UploadSession]:
+        """返回 pending 且 updated_at 早于 cutoff 的会话（被放弃的上传）。"""
+        cutoff = datetime.now() - timedelta(seconds=ttl_seconds)
+        stmt = (
+            select(UploadSession)
+            .where(UploadSession.status == "pending")
+            .where(UploadSession.updated_at < cutoff)
+        )
+        return list(self.db.scalars(stmt).all())
+
+    def delete(self, session: UploadSession) -> None:
+        self.db.delete(session)
+        self.db.commit()
--- a/app/dao/whiteboard_dao.py
+++ b/app/dao/whiteboard_dao.py
@@ -0,0 +1,84 @@
+"""Whiteboard 的 DAO。
+
+所有写操作均在该层 commit，service 不直接操作 session。
+get_or_create 用于「访问即新建」语义（路由 GET /whiteboard/{id} 不存在则建）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from ..models.whiteboard import Whiteboard
+
+
+class WhiteboardDAO:
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    def create(self, board: Whiteboard) -> Whiteboard:
+        self.db.add(board)
+        self.db.commit()
+        self.db.refresh(board)
+        return board
+
+    def get(self, board_id: str) -> Whiteboard | None:
+        stmt = select(Whiteboard).where(Whiteboard.board_id == board_id).limit(1)
+        return self.db.scalars(stmt).first()
+
+    def get_or_create(self, board_id: str) -> Whiteboard:
+        """存在则返回，否则新建空板。利用 unique 约束兜底并发首访。"""
+        board = self.get(board_id)
+        if board is not None:
+            return board
+        board = Whiteboard(board_id=board_id, strokes=[], stroke_count=0)
+        try:
+            return self.create(board)
+        except Exception:
+            # 并发下另一事务已插入：回滚后重新读
+            self.db.rollback()
+            return self.get(board_id)  # type: ignore[return-value]
+
+    def append_strokes(self, board_id: str, new_strokes: list[Any]) -> Whiteboard | None:
+        """把新笔画追加到 strokes 数组尾部，stroke_count 自增。"""
+        board = self.get(board_id)
+        if board is None:
+            return None
+        board.strokes = [*board.strokes, *new_strokes]
+        board.stroke_count = (board.stroke_count or 0) + len(new_strokes)
+        self.db.commit()
+        self.db.refresh(board)
+        return board
+
+    def replace_strokes(self, board_id: str, strokes: list[Any]) -> Whiteboard | None:
+        """整体替换 strokes（清空时传 []），stroke_count 自增 1。"""
+        board = self.get(board_id)
+        if board is None:
+            return None
+        board.strokes = list(strokes)
+        board.stroke_count = (board.stroke_count or 0) + 1
+        self.db.commit()
+        self.db.refresh(board)
+        return board
+
+    def list_all(self, limit: int = 100, offset: int = 0) -> list[Whiteboard]:
+        stmt = (
+            select(Whiteboard)
+            .order_by(Whiteboard.updated_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+        return list(self.db.scalars(stmt).all())
+
+    def count(self) -> int:
+        return self.db.scalar(select(func.count()).select_from(Whiteboard)) or 0
+
+    def delete(self, board_id: str) -> bool:
+        board = self.get(board_id)
+        if board is None:
+            return False
+        self.db.delete(board)
+        self.db.commit()
+        return True