feat: implement WebDAV protocol support with WsgiDAV + account management API

Add complete WebDAV support: management REST API (CRUD accounts at /api/v1/webdav/accounts)
and DAV protocol endpoint (/dav) using WsgiDAV + a2wsgi bridge for client access via
HTTP Basic Auth. Includes Redis+TTLCache auth caching and integration tests (24 cases).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

routers/api/v1/webdav/__init__.py

@@ -1,110 +1,207 @@
+from typing import Annotated
+from uuid import UUID
+
 from fastapi import APIRouter, Depends
+from loguru import logger as l
 
 from middleware.auth import auth_required
-from sqlmodels import ResponseBase
+from middleware.dependencies import SessionDep
+from sqlmodels import (
+    Object,
+    User,
+    WebDAV,
+    WebDAVAccountResponse,
+    WebDAVCreateRequest,
+    WebDAVUpdateRequest,
+)
+from service.redis.webdav_auth_cache import WebDAVAuthCache
 from utils import http_exceptions
+from utils.password.pwd import Password
 
-# WebDAV 管理路由
 webdav_router = APIRouter(
     prefix='/webdav',
     tags=["webdav"],
 )
 
+
+def _check_webdav_enabled(user: User) -> None:
+    """检查用户组是否启用了 WebDAV 功能"""
+    if not user.group.web_dav_enabled:
+        http_exceptions.raise_forbidden("WebDAV 功能未启用")
+
+
+def _to_response(account: WebDAV) -> WebDAVAccountResponse:
+    """将 WebDAV 数据库模型转换为响应 DTO"""
+    return WebDAVAccountResponse(
+        id=account.id,
+        name=account.name,
+        root=account.root,
+        readonly=account.readonly,
+        use_proxy=account.use_proxy,
+        created_at=str(account.created_at),
+        updated_at=str(account.updated_at),
+    )
+
+
 @webdav_router.get(
     path='/accounts',
-    summary='获取账号信息',
-    description='Get account information for WebDAV.',
-    dependencies=[Depends(auth_required)],
+    summary='获取账号列表',
 )
-def router_webdav_accounts() -> ResponseBase:
+async def list_accounts(
+    session: SessionDep,
+    user: Annotated[User, Depends(auth_required)],
+) -> list[WebDAVAccountResponse]:
     """
-    Get account information for WebDAV.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the account information.
+    列出当前用户所有 WebDAV 账户
+
+    认证：JWT Bearer Token
     """
-    http_exceptions.raise_not_implemented()
+    _check_webdav_enabled(user)
+    user_id: UUID = user.id
+
+    accounts: list[WebDAV] = await WebDAV.get(
+        session,
+        WebDAV.user_id == user_id,
+        fetch_mode="all",
+    )
+    return [_to_response(a) for a in accounts]
+
 
 @webdav_router.post(
     path='/accounts',
-    summary='新建账号',
-    description='Create a new WebDAV account.',
-    dependencies=[Depends(auth_required)],
+    summary='创建账号',
+    status_code=201,
 )
-def router_webdav_create_account() -> ResponseBase:
+async def create_account(
+    session: SessionDep,
+    user: Annotated[User, Depends(auth_required)],
+    request: WebDAVCreateRequest,
+) -> WebDAVAccountResponse:
     """
-    Create a new WebDAV account.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the created account.
-    """
-    http_exceptions.raise_not_implemented()
+    创建 WebDAV 账户
 
-@webdav_router.delete(
-    path='/accounts/{id}',
-    summary='删除账号',
-    description='Delete a WebDAV account by its ID.',
-    dependencies=[Depends(auth_required)],
-)
-def router_webdav_delete_account(id: str) -> ResponseBase:
-    """
-    Delete a WebDAV account by its ID.
-    
-    Args:
-        id (str): The ID of the account to be deleted.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the deletion operation.
-    """
-    http_exceptions.raise_not_implemented()
+    认证：JWT Bearer Token
 
-@webdav_router.post(
-    path='/mount',
-    summary='新建目录挂载',
-    description='Create a new WebDAV mount point.',
-    dependencies=[Depends(auth_required)],
-)
-def router_webdav_create_mount() -> ResponseBase:
+    错误处理：
+    - 403: WebDAV 功能未启用
+    - 400: 根目录路径不存在或不是目录
+    - 409: 账户名已存在
     """
-    Create a new WebDAV mount point.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the created mount point.
-    """
-    http_exceptions.raise_not_implemented()
+    _check_webdav_enabled(user)
+    user_id: UUID = user.id
+
+    # 验证账户名唯一
+    existing = await WebDAV.get(
+        session,
+        (WebDAV.name == request.name) & (WebDAV.user_id == user_id),
+    )
+    if existing:
+        http_exceptions.raise_conflict("账户名已存在")
+
+    # 验证 root 路径存在且为目录
+    root_obj = await Object.get_by_path(session, user_id, request.root)
+    if not root_obj or not root_obj.is_folder:
+        http_exceptions.raise_bad_request("根目录路径不存在或不是目录")
+
+    # 创建账户
+    account = WebDAV(
+        name=request.name,
+        password=Password.hash(request.password),
+        root=request.root,
+        readonly=request.readonly,
+        use_proxy=request.use_proxy,
+        user_id=user_id,
+    )
+    account = await account.save(session)
+
+    l.info(f"用户 {user_id} 创建 WebDAV 账户: {account.name}")
+    return _to_response(account)
 
-@webdav_router.delete(
-    path='/mount/{id}',
-    summary='删除目录挂载',
-    description='Delete a WebDAV mount point by its ID.',
-    dependencies=[Depends(auth_required)],
-)
-def router_webdav_delete_mount(id: str) -> ResponseBase:
-    """
-    Delete a WebDAV mount point by its ID.
-    
-    Args:
-        id (str): The ID of the mount point to be deleted.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the deletion operation.
-    """
-    http_exceptions.raise_not_implemented()
 
 @webdav_router.patch(
-    path='accounts/{id}',
-    summary='更新账号信息',
-    description='Update WebDAV account information by ID.',
-    dependencies=[Depends(auth_required)],
+    path='/accounts/{account_id}',
+    summary='更新账号',
 )
-def router_webdav_update_account(id: str) -> ResponseBase:
+async def update_account(
+    session: SessionDep,
+    user: Annotated[User, Depends(auth_required)],
+    account_id: int,
+    request: WebDAVUpdateRequest,
+) -> WebDAVAccountResponse:
     """
-    Update WebDAV account information by ID.
-    
-    Args:
-        id (str): The ID of the account to be updated.
-    
-    Returns:
-        ResponseBase: A model containing the response data for the updated account.
+    更新 WebDAV 账户
+
+    认证：JWT Bearer Token
+
+    错误处理：
+    - 403: WebDAV 功能未启用
+    - 404: 账户不存在
+    - 400: 根目录路径不存在或不是目录
     """
-    http_exceptions.raise_not_implemented()
+    _check_webdav_enabled(user)
+    user_id: UUID = user.id
+
+    account = await WebDAV.get(
+        session,
+        (WebDAV.id == account_id) & (WebDAV.user_id == user_id),
+    )
+    if not account:
+        http_exceptions.raise_not_found("WebDAV 账户不存在")
+
+    # 验证 root 路径
+    if request.root is not None:
+        root_obj = await Object.get_by_path(session, user_id, request.root)
+        if not root_obj or not root_obj.is_folder:
+            http_exceptions.raise_bad_request("根目录路径不存在或不是目录")
+
+    # 密码哈希后原地替换，update() 会通过 model_dump(exclude_unset=True) 只取已设置字段
+    is_password_changed = request.password is not None
+    if is_password_changed:
+        request.password = Password.hash(request.password)
+
+    account = await account.update(session, request)
+
+    # 密码变更时清除认证缓存
+    if is_password_changed:
+        await WebDAVAuthCache.invalidate_account(user_id, account.name)
+
+    l.info(f"用户 {user_id} 更新 WebDAV 账户: {account.name}")
+    return _to_response(account)
+
+
+@webdav_router.delete(
+    path='/accounts/{account_id}',
+    summary='删除账号',
+    status_code=204,
+)
+async def delete_account(
+    session: SessionDep,
+    user: Annotated[User, Depends(auth_required)],
+    account_id: int,
+) -> None:
+    """
+    删除 WebDAV 账户
+
+    认证：JWT Bearer Token
+
+    错误处理：
+    - 403: WebDAV 功能未启用
+    - 404: 账户不存在
+    """
+    _check_webdav_enabled(user)
+    user_id: UUID = user.id
+
+    account = await WebDAV.get(
+        session,
+        (WebDAV.id == account_id) & (WebDAV.user_id == user_id),
+    )
+    if not account:
+        http_exceptions.raise_not_found("WebDAV 账户不存在")
+
+    account_name = account.name
+    await WebDAV.delete(session, account)
+
+    # 清除认证缓存
+    await WebDAVAuthCache.invalidate_account(user_id, account_name)
+
+    l.info(f"用户 {user_id} 删除 WebDAV 账户: {account_name}")

routers/dav/README.md

@@ -1 +0,0 @@
-# WebDAV 操作路由

routers/dav/__init__.py

@@ -0,0 +1,35 @@
+"""
+WebDAV 协议入口
+
+使用 WsgiDAV + a2wsgi 提供 WebDAV 协议支持。
+WsgiDAV 在 a2wsgi 的线程池中运行，不阻塞 FastAPI 事件循环。
+"""
+from a2wsgi import WSGIMiddleware
+from wsgidav.wsgidav_app import WsgiDAVApp
+
+from .domain_controller import DiskNextDomainController
+from .provider import DiskNextDAVProvider
+
+_wsgidav_config: dict[str, object] = {
+    "provider_mapping": {
+        "/": DiskNextDAVProvider(),
+    },
+    "http_authenticator": {
+        "domain_controller": DiskNextDomainController,
+        "accept_basic": True,
+        "accept_digest": False,
+        "default_to_digest": False,
+    },
+    "verbose": 1,
+    # 使用 WsgiDAV 内置的内存锁管理器
+    "lock_storage": True,
+    # 禁用 WsgiDAV 的目录浏览器（纯 DAV 协议）
+    "dir_browser": {
+        "enable": False,
+    },
+}
+
+_wsgidav_app = WsgiDAVApp(_wsgidav_config)
+
+dav_app = WSGIMiddleware(_wsgidav_app, workers=10)
+"""ASGI 应用，挂载到 /dav 路径"""

routers/dav/domain_controller.py

@@ -0,0 +1,148 @@
+"""
+WebDAV 认证控制器
+
+实现 WsgiDAV 的 BaseDomainController 接口，使用 HTTP Basic Auth
+通过 DiskNext 的 WebDAV 账户模型进行认证。
+
+用户名格式: {email}/{webdav_account_name}
+"""
+import asyncio
+from uuid import UUID
+
+from loguru import logger as l
+from wsgidav.dc.base_dc import BaseDomainController
+
+from routers.dav.provider import EventLoopRef, _get_session
+from service.redis.webdav_auth_cache import WebDAVAuthCache
+from sqlmodels.user import User, UserStatus
+from sqlmodels.webdav import WebDAV
+from utils.password.pwd import Password, PasswordStatus
+
+
+async def _authenticate(
+    email: str,
+    account_name: str,
+    password: str,
+) -> tuple[UUID, int] | None:
+    """
+    异步认证 WebDAV 用户。
+
+    :param email: 用户邮箱
+    :param account_name: WebDAV 账户名
+    :param password: 明文密码
+    :return: (user_id, webdav_id) 或 None
+    """
+    # 1. 查缓存
+    cached = await WebDAVAuthCache.get(email, account_name, password)
+    if cached is not None:
+        return cached
+
+    # 2. 缓存未命中，查库验证
+    async with _get_session() as session:
+        user = await User.get(session, User.email == email, load=User.group)
+        if not user:
+            return None
+        if user.status != UserStatus.ACTIVE:
+            return None
+        if not user.group.web_dav_enabled:
+            return None
+
+        account = await WebDAV.get(
+            session,
+            (WebDAV.name == account_name) & (WebDAV.user_id == user.id),
+        )
+        if not account:
+            return None
+
+        status = Password.verify(account.password, password)
+        if status == PasswordStatus.INVALID:
+            return None
+
+        user_id: UUID = user.id
+        webdav_id: int = account.id
+
+    # 3. 写入缓存
+    await WebDAVAuthCache.set(email, account_name, password, user_id, webdav_id)
+
+    return user_id, webdav_id
+
+
+class DiskNextDomainController(BaseDomainController):
+    """
+    DiskNext WebDAV 认证控制器
+
+    用户名格式: {email}/{webdav_account_name}
+    密码: WebDAV 账户密码（创建账户时设置）
+    """
+
+    def __init__(self, wsgidav_app: object, config: dict[str, object]) -> None:
+        super().__init__(wsgidav_app, config)
+
+    def get_domain_realm(self, path_info: str, environ: dict[str, object]) -> str:
+        """返回 realm 名称"""
+        return "DiskNext WebDAV"
+
+    def require_authentication(self, realm: str, environ: dict[str, object]) -> bool:
+        """所有请求都需要认证"""
+        return True
+
+    def is_share_anonymous(self, path_info: str) -> bool:
+        """不支持匿名访问"""
+        return False
+
+    def supports_http_digest_auth(self) -> bool:
+        """不支持 Digest 认证（密码存的是 Argon2 哈希，无法反推）"""
+        return False
+
+    def basic_auth_user(
+        self,
+        realm: str,
+        user_name: str,
+        password: str,
+        environ: dict[str, object],
+    ) -> bool:
+        """
+        HTTP Basic Auth 认证。
+
+        用户名格式: {email}/{webdav_account_name}
+        在 WSGI 线程中通过 anyio.from_thread.run 调用异步认证逻辑。
+        """
+        # 解析用户名
+        if "/" not in user_name:
+            l.debug(f"WebDAV 认证失败: 用户名格式无效 '{user_name}'")
+            return False
+
+        email, account_name = user_name.split("/", 1)
+        if not email or not account_name:
+            l.debug(f"WebDAV 认证失败: 用户名格式无效 '{user_name}'")
+            return False
+
+        # 在 WSGI 线程中调用异步认证
+        future = asyncio.run_coroutine_threadsafe(
+            _authenticate(email, account_name, password),
+            EventLoopRef.get(),
+        )
+        result = future.result()
+
+        if result is None:
+            l.debug(f"WebDAV 认证失败: {email}/{account_name}")
+            return False
+
+        user_id, webdav_id = result
+
+        # 将认证信息存入 environ，供 Provider 使用
+        environ["disknext.user_id"] = user_id
+        environ["disknext.webdav_id"] = webdav_id
+        environ["disknext.email"] = email
+        environ["disknext.account_name"] = account_name
+
+        return True
+
+    def digest_auth_user(
+        self,
+        realm: str,
+        user_name: str,
+        environ: dict[str, object],
+    ) -> bool:
+        """不支持 Digest 认证"""
+        return False

routers/dav/provider.py

@@ -0,0 +1,594 @@
+"""
+DiskNext WebDAV 存储 Provider
+
+将 WsgiDAV 的文件操作映射到 DiskNext 的 Object 模型。
+所有异步数据库/文件操作通过 asyncio.run_coroutine_threadsafe() 桥接。
+"""
+import asyncio
+import io
+import mimetypes
+from pathlib import Path
+from typing import ClassVar
+from uuid import UUID
+
+from loguru import logger as l
+from wsgidav.dav_error import (
+    DAVError,
+    HTTP_FORBIDDEN,
+    HTTP_INSUFFICIENT_STORAGE,
+    HTTP_NOT_FOUND,
+)
+from wsgidav.dav_provider import DAVCollection, DAVNonCollection, DAVProvider
+
+from service.storage import LocalStorageService, adjust_user_storage
+from sqlmodels.database_connection import DatabaseManager
+from sqlmodels.object import Object, ObjectType
+from sqlmodels.physical_file import PhysicalFile
+from sqlmodels.policy import Policy
+from sqlmodels.user import User
+from sqlmodels.webdav import WebDAV
+
+
+class EventLoopRef:
+    """持有主线程事件循环引用，供 WSGI 线程使用"""
+    _loop: ClassVar[asyncio.AbstractEventLoop | None] = None
+
+    @classmethod
+    async def capture(cls) -> None:
+        """在 async 上下文中调用，捕获当前事件循环"""
+        cls._loop = asyncio.get_running_loop()
+
+    @classmethod
+    def get(cls) -> asyncio.AbstractEventLoop:
+        if cls._loop is None:
+            raise RuntimeError("事件循环尚未捕获，请先调用 EventLoopRef.capture()")
+        return cls._loop
+
+
+def _run_async(coro):  # type: ignore[no-untyped-def]
+    """在 WSGI 线程中通过 run_coroutine_threadsafe 运行协程"""
+    future = asyncio.run_coroutine_threadsafe(coro, EventLoopRef.get())
+    return future.result()
+
+
+def _get_session():  # type: ignore[no-untyped-def]
+    """获取数据库会话上下文管理器"""
+    return DatabaseManager._async_session_factory()
+
+
+# ==================== 异步辅助函数 ====================
+
+async def _get_webdav_account(webdav_id: int) -> WebDAV | None:
+    """获取 WebDAV 账户"""
+    async with _get_session() as session:
+        return await WebDAV.get(session, WebDAV.id == webdav_id)
+
+
+async def _get_object_by_path(user_id: UUID, path: str) -> Object | None:
+    """根据路径获取对象"""
+    async with _get_session() as session:
+        return await Object.get_by_path(session, user_id, path)
+
+
+async def _get_children(user_id: UUID, parent_id: UUID) -> list[Object]:
+    """获取目录子对象"""
+    async with _get_session() as session:
+        return await Object.get_children(session, user_id, parent_id)
+
+
+async def _get_object_by_id(object_id: UUID) -> Object | None:
+    """根据ID获取对象"""
+    async with _get_session() as session:
+        return await Object.get(session, Object.id == object_id, load=Object.physical_file)
+
+
+async def _get_user(user_id: UUID) -> User | None:
+    """获取用户（含 group 关系）"""
+    async with _get_session() as session:
+        return await User.get(session, User.id == user_id, load=User.group)
+
+
+async def _get_policy(policy_id: UUID) -> Policy | None:
+    """获取存储策略"""
+    async with _get_session() as session:
+        return await Policy.get(session, Policy.id == policy_id)
+
+
+async def _create_folder(
+    name: str,
+    parent_id: UUID,
+    owner_id: UUID,
+    policy_id: UUID,
+) -> Object:
+    """创建目录对象"""
+    async with _get_session() as session:
+        obj = Object(
+            name=name,
+            type=ObjectType.FOLDER,
+            size=0,
+            parent_id=parent_id,
+            owner_id=owner_id,
+            policy_id=policy_id,
+        )
+        obj = await obj.save(session)
+        return obj
+
+
+async def _create_file(
+    name: str,
+    parent_id: UUID,
+    owner_id: UUID,
+    policy_id: UUID,
+) -> Object:
+    """创建空文件对象"""
+    async with _get_session() as session:
+        obj = Object(
+            name=name,
+            type=ObjectType.FILE,
+            size=0,
+            parent_id=parent_id,
+            owner_id=owner_id,
+            policy_id=policy_id,
+        )
+        obj = await obj.save(session)
+        return obj
+
+
+async def _soft_delete_object(object_id: UUID) -> None:
+    """软删除对象（移入回收站）"""
+    from service.storage import soft_delete_objects
+
+    async with _get_session() as session:
+        obj = await Object.get(session, Object.id == object_id)
+        if obj:
+            await soft_delete_objects(session, [obj])
+
+
+async def _finalize_upload(
+    object_id: UUID,
+    physical_path: str,
+    size: int,
+    owner_id: UUID,
+    policy_id: UUID,
+) -> None:
+    """上传完成后更新对象元数据和物理文件记录"""
+    async with _get_session() as session:
+        # 获取存储路径（相对路径）
+        policy = await Policy.get(session, Policy.id == policy_id)
+        if not policy or not policy.server:
+            raise DAVError(HTTP_NOT_FOUND, "存储策略不存在")
+
+        base_path = Path(policy.server).resolve()
+        full_path = Path(physical_path).resolve()
+        storage_path = str(full_path.relative_to(base_path))
+
+        # 创建 PhysicalFile 记录
+        pf = PhysicalFile(
+            storage_path=storage_path,
+            size=size,
+            policy_id=policy_id,
+            reference_count=1,
+        )
+        pf = await pf.save(session)
+
+        # 更新 Object
+        obj = await Object.get(session, Object.id == object_id)
+        if obj:
+            obj.sqlmodel_update({'size': size, 'physical_file_id': pf.id})
+            session.add(obj)
+            await session.commit()
+
+        # 更新用户存储用量
+        if size > 0:
+            await adjust_user_storage(session, owner_id, size)
+
+
+async def _move_object(
+    object_id: UUID,
+    new_parent_id: UUID,
+    new_name: str,
+) -> None:
+    """移动/重命名对象"""
+    async with _get_session() as session:
+        obj = await Object.get(session, Object.id == object_id)
+        if obj:
+            obj.sqlmodel_update({'parent_id': new_parent_id, 'name': new_name})
+            session.add(obj)
+            await session.commit()
+
+
+async def _copy_object_recursive(
+    src_id: UUID,
+    dst_parent_id: UUID,
+    dst_name: str,
+    owner_id: UUID,
+) -> None:
+    """递归复制对象"""
+    from service.storage import copy_object_recursive
+
+    async with _get_session() as session:
+        src = await Object.get(session, Object.id == src_id)
+        if not src:
+            return
+        await copy_object_recursive(session, src, dst_parent_id, owner_id, new_name=dst_name)
+
+
+# ==================== 辅助工具 ====================
+
+def _get_environ_info(environ: dict[str, object]) -> tuple[UUID, int]:
+    """从 environ 中提取认证信息"""
+    user_id: UUID = environ["disknext.user_id"]  # type: ignore[assignment]
+    webdav_id: int = environ["disknext.webdav_id"]  # type: ignore[assignment]
+    return user_id, webdav_id
+
+
+def _resolve_dav_path(account_root: str, dav_path: str) -> str:
+    """
+    将 DAV 相对路径映射到 DiskNext 绝对路径。
+
+    :param account_root: 账户挂载根路径，如 "/" 或 "/docs"
+    :param dav_path: DAV 请求路径，如 "/" 或 "/photos/cat.jpg"
+    :return: DiskNext 内部路径，如 "/docs/photos/cat.jpg"
+    """
+    # 规范化根路径
+    root = account_root.rstrip("/")
+    if not root:
+        root = ""
+
+    # 规范化 DAV 路径
+    if not dav_path or dav_path == "/":
+        return root + "/" if root else "/"
+
+    if not dav_path.startswith("/"):
+        dav_path = "/" + dav_path
+
+    full = root + dav_path
+    return full if full else "/"
+
+
+def _check_readonly(environ: dict[str, object]) -> None:
+    """检查账户是否只读，只读则抛出 403"""
+    account = environ.get("disknext.webdav_account")
+    if account and getattr(account, 'readonly', False):
+        raise DAVError(HTTP_FORBIDDEN, "WebDAV 账户为只读模式")
+
+
+def _check_storage_quota(user: User, additional_bytes: int) -> None:
+    """检查存储配额"""
+    max_storage = user.group.max_storage
+    if max_storage > 0 and user.storage + additional_bytes > max_storage:
+        raise DAVError(HTTP_INSUFFICIENT_STORAGE, "存储空间不足")
+
+
+# ==================== Provider ====================
+
+class DiskNextDAVProvider(DAVProvider):
+    """DiskNext WebDAV 存储 Provider"""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def get_resource_inst(
+        self,
+        path: str,
+        environ: dict[str, object],
+    ) -> 'DiskNextCollection | DiskNextFile | None':
+        """
+        将 WebDAV 路径映射到资源对象。
+
+        首次调用时加载 WebDAV 账户信息并缓存到 environ。
+        """
+        user_id, webdav_id = _get_environ_info(environ)
+
+        # 首次请求时加载账户信息
+        if "disknext.webdav_account" not in environ:
+            account = _run_async(_get_webdav_account(webdav_id))
+            if not account:
+                return None
+            environ["disknext.webdav_account"] = account
+
+        account: WebDAV = environ["disknext.webdav_account"]  # type: ignore[no-redef]
+        disknext_path = _resolve_dav_path(account.root, path)
+
+        obj = _run_async(_get_object_by_path(user_id, disknext_path))
+        if not obj:
+            return None
+
+        if obj.is_folder:
+            return DiskNextCollection(path, environ, obj, user_id, account)
+        else:
+            return DiskNextFile(path, environ, obj, user_id, account)
+
+    def is_readonly(self) -> bool:
+        """只读由账户级别控制，不在 provider 级别限制"""
+        return False
+
+
+# ==================== Collection（目录） ====================
+
+class DiskNextCollection(DAVCollection):
+    """DiskNext 目录资源"""
+
+    def __init__(
+        self,
+        path: str,
+        environ: dict[str, object],
+        obj: Object,
+        user_id: UUID,
+        account: WebDAV,
+    ) -> None:
+        super().__init__(path, environ)
+        self._obj = obj
+        self._user_id = user_id
+        self._account = account
+
+    def get_display_info(self) -> dict[str, str]:
+        return {"type": "Directory"}
+
+    def get_member_names(self) -> list[str]:
+        """获取子对象名称列表"""
+        children = _run_async(_get_children(self._user_id, self._obj.id))
+        return [c.name for c in children]
+
+    def get_member(self, name: str) -> 'DiskNextCollection | DiskNextFile | None':
+        """获取指定名称的子资源"""
+        member_path = self.path.rstrip("/") + "/" + name
+        account_root = self._account.root
+        disknext_path = _resolve_dav_path(account_root, member_path)
+
+        obj = _run_async(_get_object_by_path(self._user_id, disknext_path))
+        if not obj:
+            return None
+
+        if obj.is_folder:
+            return DiskNextCollection(member_path, self.environ, obj, self._user_id, self._account)
+        else:
+            return DiskNextFile(member_path, self.environ, obj, self._user_id, self._account)
+
+    def get_creation_date(self) -> float | None:
+        if self._obj.created_at:
+            return self._obj.created_at.timestamp()
+        return None
+
+    def get_last_modified(self) -> float | None:
+        if self._obj.updated_at:
+            return self._obj.updated_at.timestamp()
+        return None
+
+    def create_empty_resource(self, name: str) -> 'DiskNextFile':
+        """创建空文件（PUT 操作的第一步）"""
+        _check_readonly(self.environ)
+
+        obj = _run_async(_create_file(
+            name=name,
+            parent_id=self._obj.id,
+            owner_id=self._user_id,
+            policy_id=self._obj.policy_id,
+        ))
+
+        member_path = self.path.rstrip("/") + "/" + name
+        return DiskNextFile(member_path, self.environ, obj, self._user_id, self._account)
+
+    def create_collection(self, name: str) -> 'DiskNextCollection':
+        """创建子目录（MKCOL）"""
+        _check_readonly(self.environ)
+
+        obj = _run_async(_create_folder(
+            name=name,
+            parent_id=self._obj.id,
+            owner_id=self._user_id,
+            policy_id=self._obj.policy_id,
+        ))
+
+        member_path = self.path.rstrip("/") + "/" + name
+        return DiskNextCollection(member_path, self.environ, obj, self._user_id, self._account)
+
+    def delete(self) -> None:
+        """软删除目录"""
+        _check_readonly(self.environ)
+        _run_async(_soft_delete_object(self._obj.id))
+
+    def copy_move_single(self, dest_path: str, *, is_move: bool) -> bool:
+        """复制或移动目录"""
+        _check_readonly(self.environ)
+
+        account_root = self._account.root
+        dest_disknext = _resolve_dav_path(account_root, dest_path)
+
+        # 解析目标父路径和新名称
+        if "/" in dest_disknext.rstrip("/"):
+            parent_path = dest_disknext.rsplit("/", 1)[0] or "/"
+            new_name = dest_disknext.rsplit("/", 1)[1]
+        else:
+            parent_path = "/"
+            new_name = dest_disknext.lstrip("/")
+
+        dest_parent = _run_async(_get_object_by_path(self._user_id, parent_path))
+        if not dest_parent:
+            raise DAVError(HTTP_NOT_FOUND, "目标父目录不存在")
+
+        if is_move:
+            _run_async(_move_object(self._obj.id, dest_parent.id, new_name))
+        else:
+            _run_async(_copy_object_recursive(
+                self._obj.id, dest_parent.id, new_name, self._user_id,
+            ))
+
+        return True
+
+    def support_recursive_delete(self) -> bool:
+        return True
+
+    def support_recursive_move(self, dest_path: str) -> bool:
+        return True
+
+
+# ==================== NonCollection（文件） ====================
+
+class DiskNextFile(DAVNonCollection):
+    """DiskNext 文件资源"""
+
+    def __init__(
+        self,
+        path: str,
+        environ: dict[str, object],
+        obj: Object,
+        user_id: UUID,
+        account: WebDAV,
+    ) -> None:
+        super().__init__(path, environ)
+        self._obj = obj
+        self._user_id = user_id
+        self._account = account
+        self._write_path: str | None = None
+        self._write_stream: io.BufferedWriter | None = None
+
+    def get_content_length(self) -> int | None:
+        return self._obj.size if self._obj.size else 0
+
+    def get_content_type(self) -> str | None:
+        # 尝试从文件名推断 MIME 类型
+        mime, _ = mimetypes.guess_type(self._obj.name)
+        return mime or "application/octet-stream"
+
+    def get_creation_date(self) -> float | None:
+        if self._obj.created_at:
+            return self._obj.created_at.timestamp()
+        return None
+
+    def get_last_modified(self) -> float | None:
+        if self._obj.updated_at:
+            return self._obj.updated_at.timestamp()
+        return None
+
+    def get_display_info(self) -> dict[str, str]:
+        return {"type": "File"}
+
+    def get_content(self) -> io.BufferedReader | None:
+        """
+        返回文件内容的可读流。
+
+        WsgiDAV 在线程中运行，可安全使用同步 open()。
+        """
+        obj_with_file = _run_async(_get_object_by_id(self._obj.id))
+        if not obj_with_file or not obj_with_file.physical_file:
+            return None
+
+        pf = obj_with_file.physical_file
+        policy = _run_async(_get_policy(obj_with_file.policy_id))
+        if not policy or not policy.server:
+            return None
+
+        full_path = Path(policy.server).resolve() / pf.storage_path
+        if not full_path.is_file():
+            l.warning(f"WebDAV: 物理文件不存在: {full_path}")
+            return None
+
+        return open(full_path, "rb")  # noqa: SIM115
+
+    def begin_write(self, *, content_type: str | None = None) -> io.BufferedWriter:
+        """
+        开始写入文件（PUT 操作）。
+
+        返回一个可写的文件流，WsgiDAV 将向其中写入请求体数据。
+        """
+        _check_readonly(self.environ)
+
+        # 检查配额
+        user = _run_async(_get_user(self._user_id))
+        if user:
+            content_length = self.environ.get("CONTENT_LENGTH")
+            if content_length:
+                _check_storage_quota(user, int(content_length))
+
+        # 获取策略以确定存储路径
+        policy = _run_async(_get_policy(self._obj.policy_id))
+        if not policy or not policy.server:
+            raise DAVError(HTTP_NOT_FOUND, "存储策略不存在")
+
+        storage_service = LocalStorageService(policy)
+        dir_path, storage_name, full_path = _run_async(
+            storage_service.generate_file_path(
+                user_id=self._user_id,
+                original_filename=self._obj.name,
+            )
+        )
+
+        self._write_path = full_path
+        self._write_stream = open(full_path, "wb")  # noqa: SIM115
+        return self._write_stream
+
+    def end_write(self, *, with_errors: bool) -> None:
+        """写入完成后的收尾工作"""
+        if self._write_stream:
+            self._write_stream.close()
+            self._write_stream = None
+
+        if with_errors or not self._write_path:
+            return
+
+        # 获取文件大小
+        file_path = Path(self._write_path)
+        if not file_path.exists():
+            return
+
+        size = file_path.stat().st_size
+
+        # 更新数据库记录
+        _run_async(_finalize_upload(
+            object_id=self._obj.id,
+            physical_path=self._write_path,
+            size=size,
+            owner_id=self._user_id,
+            policy_id=self._obj.policy_id,
+        ))
+
+        l.debug(f"WebDAV 文件写入完成: {self._obj.name}, size={size}")
+
+    def delete(self) -> None:
+        """软删除文件"""
+        _check_readonly(self.environ)
+        _run_async(_soft_delete_object(self._obj.id))
+
+    def copy_move_single(self, dest_path: str, *, is_move: bool) -> bool:
+        """复制或移动文件"""
+        _check_readonly(self.environ)
+
+        account_root = self._account.root
+        dest_disknext = _resolve_dav_path(account_root, dest_path)
+
+        # 解析目标父路径和新名称
+        if "/" in dest_disknext.rstrip("/"):
+            parent_path = dest_disknext.rsplit("/", 1)[0] or "/"
+            new_name = dest_disknext.rsplit("/", 1)[1]
+        else:
+            parent_path = "/"
+            new_name = dest_disknext.lstrip("/")
+
+        dest_parent = _run_async(_get_object_by_path(self._user_id, parent_path))
+        if not dest_parent:
+            raise DAVError(HTTP_NOT_FOUND, "目标父目录不存在")
+
+        if is_move:
+            _run_async(_move_object(self._obj.id, dest_parent.id, new_name))
+        else:
+            _run_async(_copy_object_recursive(
+                self._obj.id, dest_parent.id, new_name, self._user_id,
+            ))
+
+        return True
+
+    def support_content_length(self) -> bool:
+        return True
+
+    def get_etag(self) -> str | None:
+        """返回 ETag（基于ID和更新时间），WsgiDAV 会自动加双引号"""
+        if self._obj.updated_at:
+            return f"{self._obj.id}-{int(self._obj.updated_at.timestamp())}"
+        return None
+
+    def support_etag(self) -> bool:
+        return True
+
+    def support_ranges(self) -> bool:
+        return True