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 全部通过。

app/controllers/__init__.py

@@ -1,6 +1,17 @@
 """Controller 层：API 路由。"""
 
+from .chunk_upload_controller import router as chunk_upload_router
+from .file_admin_controller import router as file_admin_router
 from .file_controller import router as file_router
 from .system_controller import router as system_router
+from .tunnel_controller import router as tunnel_router
+from .whiteboard_controller import router as whiteboard_router
 
-__all__ = ["file_router", "system_router"]
+__all__ = [
+    "chunk_upload_router",
+    "file_admin_router",
+    "file_router",
+    "system_router",
+    "tunnel_router",
+    "whiteboard_router",
+]

app/controllers/chunk_upload_controller.py

@@ -0,0 +1,93 @@
+"""分片上传接口：创建会话 / 查状态 / 传分片 / 完成拼接。
+
+支持大文件分片上传与断点续传。前端先创建会话拿 upload_id，逐片上传，
+可随时查 status 获取已传分片以补传缺失部分，最后 complete 触发拼接入库。
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..dao.upload_session_dao import UploadSessionDAO
+from ..dao.uploaded_file_dao import UploadedFileDAO
+from ..schemas.chunk import (
+    ChunkUploadResponse,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    SessionStatusResponse,
+)
+from ..schemas.file import FileUploadResponse
+from ..services.chunk_upload_service import ChunkUploadService
+
+router = APIRouter(prefix="/api/files/chunk-uploads", tags=["chunk-upload"])
+
+
+def _service(db: Session = Depends(get_db)) -> ChunkUploadService:
+    return ChunkUploadService(UploadSessionDAO(db), UploadedFileDAO(db))
+
+
+@router.post(
+    "",
+    response_model=CreateSessionResponse,
+    summary="创建分片上传会话",
+    description=(
+        "客户端把文件切成固定大小的分片后，先调本接口创建会话。"
+        "服务端生成 upload_id 返回，后续上传分片、查状态、完成拼接都需要它。"
+    ),
+)
+def create_session(
+    body: CreateSessionRequest,
+    service: ChunkUploadService = Depends(_service),
+) -> CreateSessionResponse:
+    return service.create_session(body)
+
+
+@router.get(
+    "/{upload_id}/status",
+    response_model=SessionStatusResponse,
+    summary="查询会话状态（断点续传）",
+    description="返回已上传分片下标集合，前端据此只补传缺失分片。",
+)
+def session_status(
+    upload_id: str,
+    service: ChunkUploadService = Depends(_service),
+) -> SessionStatusResponse:
+    return service.get_status(upload_id)
+
+
+@router.post(
+    "/{upload_id}/chunks/{index}",
+    response_model=ChunkUploadResponse,
+    summary="上传单个分片",
+    description=(
+        "请求体为单个分片的原始二进制。分片可乱序上传，重传同一分片会覆盖。"
+        "返回当前已上传的分片下标集合。"
+    ),
+)
+async def upload_chunk(
+    upload_id: str,
+    index: int,
+    request: Request,
+    service: ChunkUploadService = Depends(_service),
+) -> ChunkUploadResponse:
+    uploaded = service.write_chunk(upload_id, index, await request.body())
+    return ChunkUploadResponse(upload_id=upload_id, index=index, uploaded_chunks=uploaded)
+
+
+@router.post(
+    "/{upload_id}/complete",
+    response_model=FileUploadResponse,
+    summary="完成拼接并入库",
+    description=(
+        "服务端校验分片齐全后，按顺序拼接为完整文件、流式计算 sha256，"
+        "按 sha256 去重（命中则返回旧行不重复落盘），最后原子改名入库。"
+        "重复调用幂等，返回同一 file_id。"
+    ),
+)
+def complete_session(
+    upload_id: str,
+    service: ChunkUploadService = Depends(_service),
+) -> FileUploadResponse:
+    return service.complete(upload_id)

app/controllers/file_admin_controller.py

@@ -0,0 +1,111 @@
+"""文件管理接口（Basic Auth，鉴权同 docs）。
+
+与公开的 /api/files 区分：本路由面向「文件浏览页」，提供列表 / 查询 / 下载 / 删除，
+均需 docs 凭据。公开路由（user.py 依赖的查重、查询、下载）保留不变。
+
+硬删除策略：删 DB 行 + 删磁盘文件（unlink missing_ok），列表只展示仍存在的行。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..dao.uploaded_file_dao import UploadedFileDAO
+from ..schemas.file import FileListResponse, UploadedFileOut
+from ..security import require_docs_auth
+from ..services.upload_service import UploadService
+
+router = APIRouter(prefix="/api/admin/files", tags=["files-admin"])
+
+
+def _service(db: Session = Depends(get_db)) -> UploadService:
+    return UploadService(UploadedFileDAO(db))
+
+
+class DeleteResult(BaseModel):
+    deleted: bool
+
+
+@router.get(
+    "",
+    response_model=FileListResponse,
+    summary="列出已上传文件（需鉴权）",
+    description="供文件浏览页使用；字段同公开 /api/files，但要求 docs Basic Auth。",
+)
+def list_files(
+    limit: int = 100,
+    offset: int = 0,
+    service: UploadService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> FileListResponse:
+    total, items = service.list_files(limit=limit, offset=offset)
+    return FileListResponse(total=total, items=items)
+
+
+@router.get(
+    "/{file_id}",
+    response_model=UploadedFileOut,
+    summary="查询单个文件元数据（需鉴权）",
+)
+def get_file(
+    file_id: int,
+    service: UploadService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> UploadedFileOut:
+    out = service.get_out(file_id)
+    if out is None:
+        raise HTTPException(404, "文件不存在")
+    return out
+
+
+@router.get(
+    "/{file_id}/download",
+    summary="下载文件（需鉴权，校验磁盘存在）",
+    description="文件实体不在磁盘上时返回 410 Gone。",
+)
+def download_file(
+    file_id: int,
+    service: UploadService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> FileResponse:
+    out, path = service.get_out_with_disk_path(file_id)
+    if out is None:
+        raise HTTPException(404, "文件不存在")
+    if path is None or not path.exists():
+        raise HTTPException(410, "文件实体已不在磁盘上")
+    return FileResponse(
+        path=str(path),
+        media_type=out.content_type or "application/octet-stream",
+        filename=out.original_filename,
+    )
+
+
+@router.delete(
+    "/{file_id}",
+    response_model=DeleteResult,
+    summary="硬删除文件（需鉴权）",
+    description="删除 DB 行与磁盘文件实体；不可恢复。列表随后不再显示。",
+)
+def delete_file(
+    file_id: int,
+    service: UploadService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> DeleteResult:
+    out, path = service.get_out_with_disk_path(file_id)
+    if out is None:
+        return DeleteResult(deleted=False)
+    # 先删磁盘文件，再删 DB 行；磁盘文件缺失不阻断 DB 清理
+    if path is not None:
+        try:
+            Path(path).unlink(missing_ok=True)
+        except Exception:
+            # 即使磁盘删除失败也继续清 DB 行，保证列表不再显示
+            pass
+    service.dao.delete(file_id)
+    return DeleteResult(deleted=True)

app/controllers/file_controller.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
 from fastapi.responses import FileResponse
 from sqlalchemy.orm import Session
@@ -13,7 +11,6 @@ from ..dao.uploaded_file_dao import UploadedFileDAO
 from ..schemas.file import (
     FileListResponse,
     FileUploadResponse,
-    SftpRegisterRequest,
     UploadedFileOut,
 )
 from ..services.upload_service import UploadService
@@ -32,7 +29,7 @@ def _service(db: Session = Depends(get_db)) -> UploadService:
     description=(
         "multipart/form-data 上传，按 1 MiB 分片流式落盘，内存占用恒定；"
         "落盘过程中计算 SHA-256 并入库。\n\n"
-        "极大或极慢的传输建议改用 SFTP（详见 README），HTTP 链路受 Apache 代理 300s 超时限制。"
+        "极大或极慢的传输建议改用分片上传接口（/api/files/chunk-uploads）或 SFTP。"
     ),
 )
 async def upload_file(
@@ -70,26 +67,6 @@ def file_exists(
     return out
 
 
-@router.post(
-    "/register-sftp",
-    response_model=FileUploadResponse,
-    summary="登记一个已通过 SFTP 落盘的文件",
-    description=(
-        "客户端先把文件 SFTP 到 ``incoming/<name>``，再用本接口登记入库。"
-        "服务端会计算 sha256（已存在则去重）、把文件原子改名到 ``YYYY/MM/<uuid>.<ext>``、写 DB 行。"
-    ),
-)
-def register_sftp(
-    body: SftpRegisterRequest,
-    service: UploadService = Depends(_service),
-) -> FileUploadResponse:
-    return service.register_sftp(
-        filename=body.filename,
-        original_filename=body.original_filename,
-        uploaded_by=body.uploaded_by,
-    )
-
-
 @router.get("/{file_id}", response_model=UploadedFileOut, summary="查询单个文件元数据")
 def get_file(file_id: int, service: UploadService = Depends(_service)) -> UploadedFileOut:
     out = service.get_out(file_id)
@@ -100,10 +77,9 @@ def get_file(file_id: int, service: UploadService = Depends(_service)) -> Upload
 
 @router.get("/{file_id}/download", summary="下载文件")
 def download_file(file_id: int, service: UploadService = Depends(_service)) -> FileResponse:
-    out = service.get_out(file_id)
+    out, path = service.get_out_with_disk_path(file_id)
     if out is None:
         raise HTTPException(404, "文件不存在")
-    path: Path | None = service.resolve_disk_path(file_id)
     if path is None or not path.exists():
         raise HTTPException(410, "文件实体已不在磁盘上")
     return FileResponse(

app/controllers/tunnel_controller.py

@@ -0,0 +1,97 @@
+"""反向隧道 HTTP 路由：/api/userPort/{userName}。
+
+把进来的 HTTP 请求反代到该 user 当前活跃隧道对应的本地端口
+（SSH remote forward 绑定的 127.0.0.1:tunnel_port），经隧道回指 user 的本地服务。
+"""
+
+from __future__ import annotations
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..dao.tunnel_session_dao import TunnelSessionDAO
+from ..services.tunnel_service import TunnelService
+
+router = APIRouter(prefix="/api/userPort", tags=["tunnel"])
+
+# 不应透传给上游的 hop-by-hop / 控制头
+_HOP_BY_HOP = {
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailers", "transfer-encoding", "upgrade", "host", "content-length",
+}
+
+
+def _service(db: Session = Depends(get_db)) -> TunnelService:
+    return TunnelService(TunnelSessionDAO(db))
+
+
+async def _proxy(request: Request, session, prefix: str) -> Response:
+    """把请求透传到该 user 当前活跃隧道对应的本地端口。
+
+    去掉 /api/userPort/{userName} 前缀后才是上游路径，根路径补 /。
+    """
+    upstream_path = request.url.path.replace(prefix, "", 1) or "/"
+    url = f"http://127.0.0.1:{session.tunnel_port}{upstream_path}"
+    if request.url.query:
+        url += f"?{request.url.query}"
+
+    body = await request.body()
+    headers = {k: v for k, v in request.headers.items() if k.lower() not in _HOP_BY_HOP}
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            upstream = await client.request(
+                request.method, url, content=body, headers=headers,
+            )
+    except httpx.RequestError as exc:
+        raise HTTPException(502, f"隧道端口不可达：{exc}") from exc
+
+    resp_headers = {k: v for k, v in upstream.headers.items() if k.lower() not in _HOP_BY_HOP}
+    return Response(content=upstream.content, status_code=upstream.status_code,
+                    headers=resp_headers)
+
+
+# 根路径：/api/userPort/{userName}
+@router.api_route(
+    "/{userName}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+    summary="反代到指定 user 的隧道端口（根路径）",
+    description=(
+        "查 DB 该 user 当前活跃的隧道端口，把请求透传到 127.0.0.1:tunnel_port"
+        "（经 SSH 反向隧道回指 user 的本地服务）。无活跃隧道返回 502。"
+    ),
+)
+async def proxy_to_tunnel(
+    userName: str,
+    request: Request,
+    service: TunnelService = Depends(_service),
+) -> Response:
+    session = service.get_active(userName)
+    if session is None:
+        raise HTTPException(502, f"无活跃隧道：user={userName}")
+    return await _proxy(request, session, f"/api/userPort/{userName}")
+
+
+# 子路径：/api/userPort/{userName}/... —— 反向代理必须能透传任意路径与查询串，
+# 否则上游服务里所有非根路由都会 404。
+@router.api_route(
+    "/{userName}/{upstream_path:path}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+    summary="反代到指定 user 的隧道端口（子路径透传）",
+    description=(
+        "把 /api/userPort/{userName}/<path> 透传到 127.0.0.1:tunnel_port/<path>。"
+        "无活跃隧道返回 502。"
+    ),
+)
+async def proxy_to_tunnel_path(
+    userName: str,
+    upstream_path: str,
+    request: Request,
+    service: TunnelService = Depends(_service),
+) -> Response:
+    session = service.get_active(userName)
+    if session is None:
+        raise HTTPException(502, f"无活跃隧道：user={userName}")
+    return await _proxy(request, session, f"/api/userPort/{userName}")

app/controllers/whiteboard_controller.py

@@ -0,0 +1,220 @@
+"""白板接口：REST（访问/管理）+ WebSocket（实时同步）。
+
+路由：
+    GET    /whiteboard/{board_id}        公开：访问白板，不存在则新建
+    WS     /ws/whiteboard/{board_id}     公开：实时协作 + 心跳
+    GET    /api/admin/whiteboards        Basic Auth：管理页列表
+    DELETE /api/admin/whiteboards/{id}   Basic Auth：删除白板
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..dao.whiteboard_dao import WhiteboardDAO
+from ..schemas.whiteboard import WhiteboardListResponse, WhiteboardOut
+from ..security import require_docs_auth
+from ..services.whiteboard_hub import Connection, get_hub
+from ..services.whiteboard_service import WhiteboardService
+
+logger = logging.getLogger("zikai.whiteboard")
+
+router = APIRouter(tags=["whiteboard"])
+
+
+def _service(db: Session = Depends(get_db)) -> WhiteboardService:
+    """REST 路径的 service：注入 hub 以便删除时踢出连接。"""
+    return WhiteboardService(WhiteboardDAO(db), hub=get_hub())
+
+
+# ---------------- 公开 REST ----------------
+
+@router.get(
+    "/whiteboard/{board_id}",
+    response_model=WhiteboardOut,
+    summary="访问白板（不存在则新建）",
+    description="任何人凭 board_id 即可访问；不存在时自动创建空板并返回。",
+)
+def get_whiteboard(board_id: str, service: WhiteboardService = Depends(_service)) -> WhiteboardOut:
+    return service.get_or_create(board_id)
+
+
+# ---------------- 管理 REST（Basic Auth） ----------------
+
+@router.get(
+    "/api/admin/whiteboards",
+    response_model=WhiteboardListResponse,
+    summary="列出所有白板（需鉴权）",
+    description="供白板管理页使用：board_id / 创建时间 / 修改次数 / 上次修改时间。",
+)
+def list_whiteboards(
+    limit: int = Query(100, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+    service: WhiteboardService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> WhiteboardListResponse:
+    total, items = service.list_all(limit=limit, offset=offset)
+    return WhiteboardListResponse(total=total, items=items)
+
+
+@router.delete(
+    "/api/admin/whiteboards/{board_id}",
+    summary="删除白板（需鉴权）",
+    description="删 DB 行，并关闭该 board 的所有在线 WebSocket 连接。",
+)
+def delete_whiteboard(
+    board_id: str,
+    service: WhiteboardService = Depends(_service),
+    _: str = Depends(require_docs_auth),
+) -> dict:
+    ok = service.delete(board_id)
+    if not ok:
+        raise HTTPException(404, "白板不存在")
+    return {"deleted": True}
+
+
+# ---------------- WebSocket（公开，实时同步 + 心跳） ----------------
+
+@router.websocket("/ws/whiteboard/{board_id}")
+async def whiteboard_ws(websocket: WebSocket, board_id: str) -> None:
+    """白板实时协作端点。
+
+    协议（JSON 文本帧）：
+        client -> server:
+            {"type":"hello","client_id":"..."}   首帧（可选，未带则服务端生成）
+            {"type":"ping"}                      心跳，服务端回 pong 并刷新计时
+            {"type":"stroke","stroke":{...}}     新增笔画，持久化并广播给他人
+            {"type":"clear"}                     清空，持久化并广播给所有人
+        server -> client:
+            {"type":"init","strokes":[...],"stroke_count":n}
+            {"type":"pong"}
+            {"type":"stroke","stroke":{...},"client_id":"..."}
+            {"type":"cleared","client_id":"..."}
+            {"type":"error","msg":"..."}
+    """
+    # 路径层只做最基本校验，详细校验交给 service（service 会查表）
+    hub = get_hub()
+    # 先 accept，便于对非法 board_id 也回一条 error 再关闭
+    await websocket.accept()
+
+    # 读取首帧 hello（或任意帧）拿 client_id
+    try:
+        first = await websocket.receive_text()
+    except WebSocketDisconnect:
+        return
+
+    client_id = _extract_client_id(first) or uuid.uuid4().hex[:12]
+
+    # 校验 board_id 并加载白板（不存在则新建）
+    from ..database import get_session_local
+    try:
+        board = _with_db(lambda db: WhiteboardService(WhiteboardDAO(db), hub=hub).get_or_create(board_id))
+    except HTTPException as exc:
+        await _safe_send(websocket, {"type": "error", "msg": exc.detail})
+        await _safe_close(websocket)
+        return
+
+    # 注册连接并下发 init
+    conn = Connection(websocket=websocket, board_id=board_id, client_id=client_id)
+    await hub.register(conn)
+    await _safe_send(websocket, {
+        "type": "init",
+        "strokes": board.strokes,
+        "stroke_count": board.stroke_count,
+    })
+
+    # 主循环：收消息 -> 处理 -> 广播
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            msg = _parse(raw)
+            if msg is None:
+                continue
+            mtype = msg.get("type")
+            if mtype == "ping":
+                conn.touch()
+                await _safe_send(websocket, {"type": "pong"})
+                continue
+            # 任何有效业务帧都视为活性证据
+            conn.touch()
+            if mtype == "stroke":
+                stroke = msg.get("stroke") or {}
+                try:
+                    _with_db(lambda db: WhiteboardService(WhiteboardDAO(db), hub=hub).append_stroke(board_id, stroke))
+                except HTTPException as exc:
+                    await _safe_send(websocket, {"type": "error", "msg": exc.detail})
+                    continue
+                # 广播给他人（发送者本地已画，不回推）
+                await hub.broadcast(
+                    board_id,
+                    {"type": "stroke", "stroke": stroke, "client_id": client_id},
+                    exclude=conn,
+                )
+            elif mtype == "clear":
+                try:
+                    _with_db(lambda db: WhiteboardService(WhiteboardDAO(db), hub=hub).clear(board_id))
+                except HTTPException as exc:
+                    await _safe_send(websocket, {"type": "error", "msg": exc.detail})
+                    continue
+                # clear 广播给所有人（含发送者，用于确认）
+                await hub.broadcast(
+                    board_id, {"type": "cleared", "client_id": client_id}
+                )
+            else:
+                await _safe_send(websocket, {"type": "error", "msg": f"未知消息类型 {mtype}"})
+    except WebSocketDisconnect:
+        pass
+    except Exception as exc:  # pragma: no cover
+        logger.warning("白板 WS 异常 board=%s client=%s: %s", board_id, client_id, exc)
+    finally:
+        await hub.disconnect(conn)
+
+
+# ---------------- helpers ----------------
+
+def _with_db(fn):
+    """在独立 Session 中执行 fn 并返回结果；用完即关。供 WS 路径每帧独立事务使用。"""
+    from ..database import get_session_local
+    db = get_session_local()()
+    try:
+        return fn(db)
+    finally:
+        db.close()
+
+def _extract_client_id(raw: str) -> str | None:
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    cid = data.get("client_id") if isinstance(data, dict) else None
+    if isinstance(cid, str) and cid:
+        return cid
+    return None
+
+
+def _parse(raw: str) -> dict | None:
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+async def _safe_send(ws: WebSocket, msg: dict) -> None:
+    try:
+        await ws.send_json(msg)
+    except Exception:  # pragma: no cover
+        pass
+
+
+async def _safe_close(ws: WebSocket) -> None:
+    try:
+        await ws.close()
+    except Exception:  # pragma: no cover
+        pass