dv-platform 0.1.0__tar.gz

dv_platform-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: dv-platform
+Version: 0.1.0
+Summary: Git-like dataset version management platform: FastAPI backend + dv CLI, single pip install
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: boto3>=1.34
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+
+# 数据集版本管理平台（Dataset Version Platform）
+
+> 一个“类 Git”的数据集版本管理平台：**内容寻址存储（CAS）+ 控制面/数据面分离 + 引用计数 GC**。
+> 本仓库按照《数据集版本管理平台-技术路线.md》实现，覆盖里程碑 **M1 ~ M4**（并包含 M5 的 diff 等基础能力）。
+
+## 核心特性（对照技术路线需求）
+
+| # | 需求 | 实现 |
+|---|------|------|
+| 1 | 数据集版本管理与控制（类 Git） | Blob/Tree/Commit 三对象模型、提交历史、分支、标签、diff、append-only 回滚 |
+| 2 | 不同版本存云端、可恢复 | 对象存储 + 不可变提交 + 任意版本检出（零拷贝） |
+| 3 | 命令行上传 | `dv add/commit/push`，上传前按 sha256 去重（跳过已存在 blob） |
+| 4 | 命令行快速下载 | `dv pull/fetch/clone/checkout`，多线程并行下载 + sha256 校验 |
+| 5 | Web 展示数据集/版本/下载命令 | 数据集列表/详情、版本历史、文件清单/目录树、一键复制下载命令卡片 |
+| 6 | Web 端删除数据集并同步清理云端存储 | 删除接口 + blob 引用计数 + 物理删除对象，共享文件不误删 |
+| 7 | 数据集最小化保存在 Web 端 | 控制面只存元数据（哈希/清单/大小），文件内容全部在对象存储 |
+
+## 总体架构
+
+```
+┌─────────────┐   ┌─────────────┐
+│  Web UI     │   │  CLI (dv)   │
+│  (React+AntD)│   │  (Typer)   │
+└──────┬──────┘   └──────┬──────┘
+       ▼                 ▼
+┌──────────────────────────────────────┐
+│ 控制面 Control Plane (FastAPI)       │
+│  ├─ 认证/鉴权: JWT + API Token       │
+│  ├─ 数据集/版本/分支/标签 CRUD        │
+│  ├─ 版本引擎: commit/tree/blob       │
+│  ├─ 预签名 URL 签发（上传/下载）      │
+│  ├─ 存储清理: 引用计数 + 删除 GC      │
+│  └─ 审计日志                          │
+│  元数据库: PostgreSQL / SQLite(开发)  │
+└───────────────┬──────────────────────┘
+                ▼
+┌──────────────────────────────────────┐
+│ 数据面 Data Plane                    │
+│  对象存储: 本地盘(开发) / MinIO / S3  │
+│  objects/<sha256> 内容寻址，跨版本去重│
+└──────────────────────────────────────┘
+```
+
+- **控制面只走元数据，数据面直连对象存储**：大文件不经过应用服务器。
+- **Blob 引用计数**：同一 blob 被多个数据集引用时 `ref_count > 1`；删除数据集只对 `ref_count` 归零的 blob 做物理删除。
+
+## 目录结构
+
+```
+backend/            FastAPI 后端（版本引擎、存储适配、RBAC、审计、删除 GC）
+  app/
+    engine.py         版本引擎：hash/tree/commit/ref_count/删除
+    storage.py        存储适配：LocalStorage（本地盘）+ S3Storage（MinIO/OSS/COS/S3）
+    routers/          auth / tokens / datasets / versions / storage / audit
+  tests/             pytest 集成测试（7 个用例，覆盖核心流程）
+cli/                dv 命令行（Typer + httpx + rich）
+  dv/cli.py           全部子命令
+  dv/transfer.py      并行上传/下载、sha256 扫描与校验
+web/                React + TypeScript + Vite + AntD 前端
+scripts/            demo_seed.py 演示数据；get_token.py 等
+docker-compose.yml  Postgres + MinIO + backend
+```
+
+## 快速开始（开发环境）
+
+### 1. 后端
+
+```bash
+python -m venv .venv
+.venv\Scripts\pip install -r backend/requirements.txt      # Windows
+# 或  source .venv/bin/pip install -r backend/requirements.txt   # Linux/macOS
+
+cd backend
+..\.venv\Scripts\python -m uvicorn app.main:app --port 8000
+```
+
+首次启动自动建库。访问：
+- Web UI: http://localhost:8000
+- API 文档: http://localhost:8000/docs
+- 健康检查: http://localhost:8000/api/v1/health
+
+默认管理员账号由 `/api/v1/auth/bootstrap` 创建（用户名 `admin`，密码来自 `DV_FIRST_ADMIN_PASSWORD`，默认 `admin123`）。
+也可以 POST `/api/v1/auth/register` 注册新用户（第一个注册用户为 admin）。
+
+### 2. 加载演示数据（可选）
+
+```bash
+.venv\Scripts\python scripts\demo_seed.py
+```
+
+### 3. CLI
+
+```bash
+.venv\Scripts\pip install -e ./cli        # 安装 dv 命令
+
+dv login --token <API_TOKEN> --url http://localhost:8000
+dv create default/my-dataset --visibility public
+cd workdir
+dv init default/my-dataset
+dv add ./images ./labels.csv
+dv status
+dv commit -m "v1: 初始数据"
+dv push                       # 上传新 blob（去重）+ 创建云端版本
+dv log
+dv tag v1.0
+dv diff v1 HEAD
+dv rollback v1 -m "回滚到 v1"
+dv fetch default/my-dataset v1.0 -o ./data
+dv clone default/my-dataset -o ./copy
+dv ls --version v1.0
+dv dataset delete default/my-dataset --yes
+```
+
+API Token 可在 Web 端或 `POST /api/v1/tokens` 创建（CLI 用长期 Token，Web 用 JWT）。
+
+### 4. Web UI
+
+```bash
+cd web
+npm install
+npm run build        # 构建到 web/dist，后端自动挂载
+# 开发模式（热更新，代理 /api 到 :8000）:
+npm run dev          # http://localhost:5173
+```
+
+## API 一览（节选）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/auth/login · register · bootstrap | 认证 |
+| POST/GET/DELETE | /api/v1/tokens | API Token 管理（CLI） |
+| POST | /api/v1/datasets | 创建数据集 |
+| GET | /api/v1/datasets | 数据集列表（搜索/分页） |
+| GET | /api/v1/datasets/{id} | 数据集详情 |
+| **DELETE** | **/api/v1/datasets/{id}** | **删除数据集：元数据 + 引用计数归零对象的物理删除，返回释放字节** |
+| GET | /api/v1/datasets/{id}/storage-info | 删除前影响范围（版本数/占用/共享 blob） |
+| POST | /api/v1/datasets/{id}/presign/upload | 上传意向：哈希清单 → 仅返回缺失 blob 的预签名 URL（去重） |
+| POST | /api/v1/datasets/{id}/commits | 创建版本（校验声明哈希均已存在） |
+| GET | /api/v1/datasets/{id}/commits | 版本历史 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/manifest | 版本文件清单 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/presign/download | 版本下载预签名 URL 列表 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/download-command | 下载命令（Web 展示用） |
+| GET | /api/v1/datasets/{id}/tree/{ref} | 目录树浏览 |
+| GET | /api/v1/datasets/{id}/diff?base=&head= | 版本差异 |
+| POST | /api/v1/datasets/{id}/rollback | 回滚（append-only 新提交） |
+| POST/GET/DELETE | /api/v1/datasets/{id}/tags · branches | 标签 / 分支 |
+| GET | /api/v1/datasets/{id}/stats | 存储统计 |
+| GET | /api/v1/audit/logs | 审计日志（admin） |
+
+`ref` 支持：tag 名、分支名、`HEAD`/`latest`、`vN` 序号、commit 哈希（前缀）。
+
+## 存储后端切换
+
+默认 `DV_STORAGE_BACKEND=local`（本地盘模拟对象存储，预签名 URL 为 HMAC 签名 API URL）。
+切换到 S3 兼容对象存储（MinIO/OSS/COS/AWS S3）：
+
+```bash
+DV_STORAGE_BACKEND=s3 \
+DV_S3_ENDPOINT=http://localhost:9000 \
+DV_S3_BUCKET=datasets \
+DV_S3_ACCESS_KEY=... \
+DV_S3_SECRET_KEY=... \
+.venv\Scripts\python -m uvicorn app.main:app --port 8000
+```
+
+CLI/Web 代码路径完全一致（都走预签名 URL 直传/直下）。
+
+## Docker Compose（Postgres + MinIO + 后端）
+
+```bash
+# 先构建前端（把 web/dist 打进镜像）
+cd web && npm install && npm run build && cd ..
+
+docker compose up -d --build
+# Web/API: http://localhost:8000    MinIO 控制台: http://localhost:9001
+```
+
+## 测试
+
+```bash
+.venv\Scripts\python -m pytest backend/tests -q
+```
+
+覆盖：认证/Token、数据集 CRUD、上传去重、提交/标签/diff/回滚、下载校验、
+**RBAC（非 owner 删除返回 403）**、**跨数据集共享 blob 的引用计数与删除 GC**、物理对象释放。
+
+## 里程碑对照
+
+- ✅ M1 版本引擎 + CLI：三对象模型、add/commit/log/tag/rollback、本地盘对象存储、控制面只存元数据
+- ✅ M2 云存储：S3 适配 + 预签名直传直下 + 去重 + 并发下载（分片/断点续传留作增强）
+- ✅ M3 Web UI v1：列表/详情/版本历史/文件清单/目录树/下载命令卡片，元数据驱动渲染
+- ✅ M4 平台化：删除 + 引用计数 + 存储同步清理、RBAC、Token、审计、存储统计
+- 🔜 M5 进阶：分片断点续传、Merkle 分层树、软删除回收站、Webhooks、SDK
+
+## 关键设计说明
+
+- **最小化存储**：数据库只存哈希/清单/大小，文件内容永不入库；相同内容全平台只存一份。
+- **删除原子性**：元数据删除与引用计数更新在同一事务；物理删除失败可由 `gc_jobs` 兜底重试。
+- **完整性**：上传 PUT 时校验 `sha256(body)==key`；下载后校验 sha256。
+- **安全**：私有桶 + 短时效预签名 URL（默认 15 分钟）+ 数据集级 RBAC + 全量审计。
+## 前端界面（ModelScope 风格）
+
+Web 界面参考 ModelScope 社区风格设计：
+
+- 顶部品牌导航 + 「新建数据集」入口 + 用户菜单
+- 首页：渐变 Hero 搜索区 + 数据集卡片网格（彩色图标、描述、版本/文件/大小标签、可见性徽标、更新时间）
+- 详情页：头部大图标 + 统计条（版本/文件/大小/最新版本/更新时间）+ **复制下载命令** 卡片 + 删除入口（owner）
+- 标签页：数据集介绍（自动渲染 README.md）、文件（左侧目录树 + 文件表 + 单文件下载）、版本历史、标签、分支、版本差异
+- 登录页：渐变品牌背景 + 居中卡片
+
+构建：`cd web && npm run build`（产物 `web/dist`，由后端自动托管）。
+UI 冒烟测试：`scripts/ui_check.py`、`scripts/ui_check2.py`（Playwright，自动登录并检查列表/详情/文件/版本/diff/删除弹窗）。
+页面截图：`scripts/ui_check.py` 运行后输出到 `.shots/`。
+
+## 下载进度
+
+- **CLI**：`dv push / pull / fetch / clone / checkout` 均显示 rich 进度条——字节进度、文件数、当前文件、传输速度与剩余时间；下载按流式分块实时刷新，且断点续传（已存在且哈希匹配的文件自动跳过）。可用 `--no-progress` 关闭。
+- **Web 详情页**：新增「下载全部（ZIP）」按钮，弹窗实时显示百分比、当前文件与已下载文件数，完成后打包为 `<数据集名>.zip` 下载。
+
+## 账号注册 与 Token 管理
+
+- **注册**：登录页有「立即注册」入口（用户名/邮箱/密码/确认密码），第一个注册用户自动成为管理员；注册成功即自动登录。
+- **Web Token 管理**（导航栏「Token 管理」）：创建 Token（名称 + 过期时间：永不过期/7/30/90/365 天）、列表展示过期时间与最近使用、吊销；明文仅在创建弹窗显示一次，可一键复制。
+- **CLI**：`dv token create --name X [--expires 2027-01-01T00:00:00]`、`dv token list`、`dv token revoke <id>`。
+- 所有 API 响应均带 `Cache-Control: no-store`，前端请求亦禁用缓存，保证列表变更即时可见。
+
+## README 展示（ModelScope 风格）
+
+- 每个数据集详情页**默认展示 README.md**（「数据集介绍」标签页），风格对齐 ModelScope：
+  - GitHub 风格 Markdown 渲染：标题锚点链接、表格、代码块语法高亮（highlight.js）、引用块、任务列表、分隔线
+  - 相对路径图片自动解析为数据集内文件的预签名 URL（支持懒加载）
+  - 外部链接新窗口打开
+  - 支持 README 中的原生 HTML（rehype-raw）
+- 头部有 `README.md` 标识与「下载 README.md」按钮
+- 无 README 时展示引导空态（含 `dv add README.md && dv commit ... && dv push` 示例）
+
+## 打包安装为 Python 库（推荐部署方式）
+
+仓库根目录的 `pyproject.toml` 把 **后端（`backend/app`）** 与 **CLI（`cli/dv`）** 打包成
+**一个发行版 `dv-platform`**，`pip install` 后即可得到两个命令：
+
+| 命令 | 作用 |
+|------|------|
+| `dv` | 数据集版本管理 CLI（不变） |
+| `dv-server` | 启动/管理后端服务（前台或后台守护进程） |
+
+```bash
+# 在仓库根目录（含 pyproject.toml）
+pip install .            # 或开发模式: pip install -e .
+pip install ".[test]"    # 可选：测试依赖
+```
+
+> 如果环境里以前用 `pip install -e ./cli` 装过旧版 `dv-cli`，先执行 `pip uninstall dv-cli`，
+> 避免与新版 `dv-platform` 里的 `dv` 包/`dv` 命令冲突。
+
+### 快速开始
+
+```bash
+# 1) 后台启动服务（默认数据目录 ~/.dvserver，监听 0.0.0.0:8000）
+dv-server start
+dv-server status
+
+# 自定义端口 / 数据目录 / 前台运行
+dv-server start --port 9000 --data-dir D:\dvdata
+dv-server run --host 127.0.0.1 --port 8000        # 前台（Ctrl+C 停止）
+dv-server stop --port 9000
+dv-server restart
+dv-server logs --tail 50
+```
+
+需要开机自启时，可把 `dv-server start` 加入 Windows 任务计划程序（开机触发）或 systemd 单元。
+
+```bash
+# 2) 首次创建管理员账号（admin / admin123，见数据目录 .env 可改）
+#    http://127.0.0.1:8000/docs  -> POST /api/v1/auth/bootstrap
+#    或
+#    Web UI http://127.0.0.1:8000 （若构建了前端并以 DV_WEB_DIST 指向 web/dist）
+
+# 3) CLI 使用
+dv login --token <API_TOKEN> --url http://127.0.0.1:8000
+dv create team/my-dataset
+dv clone team/my-dataset -o ./data
+```
+
+### `dv-server` 数据目录（data dir）
+
+所有可变数据（SQLite `dv.db`、本地对象存储 `./storage`、`.env`、PID、日志）都落在
+**数据目录**内，因此服务可放在任意位置、完全自包含：
+
+- `run`（前台）：默认使用当前目录；
+- `start/stop/status/restart/logs`（守护进程）：默认 `~/.dvserver`（可用 `DV_SERVER_DIR` 或 `--data-dir` 覆盖）。
+
+首次 `start` 会自动生成 `.env`（含随机 `DV_JWT_SECRET`，重启后凭据保持有效）。
+生产建议：`DV_DATABASE_URL` 换 PostgreSQL、`DV_STORAGE_BACKEND=s3` 指向 MinIO/OSS/S3，
+并把 `DV_PUBLIC_BASE_URL` 设为客户端可达的地址（预签名 URL 以此为基准）。
+
+### 多客户端并发上传/下载
+
+- 上传/下载走预签名 URL（S3 后端直连对象存储，完全不经过应用进程）；
+- 本地后端（`DV_STORAGE_BACKEND=local`）的 PUT/GET 已改为**流式收发**：上传边收边写临时文件
+  并校验 sha256 后原子改名，下载用 `FileResponse` 流式返回，多客户端并发传大文件不会把文件整体载入内存；
+- SQLite（开发默认）开启 WAL + `busy_timeout=30000`，且每个事务以 `BEGIN IMMEDIATE` 开始，
+  多个客户端同时上传相同 blob（去重竞态）或同时向同一数据集 push 时不会出现
+  “database is locked”/重复版本号/丢更新；
+- 同一台机器多客户端并行传输建议保持 `--workers 1`；要横向扩容请换 PostgreSQL + S3 再加大 workers。

dv_platform-0.1.0/README.md

@@ -0,0 +1,305 @@
+# 数据集版本管理平台（Dataset Version Platform）
+
+> 一个“类 Git”的数据集版本管理平台：**内容寻址存储（CAS）+ 控制面/数据面分离 + 引用计数 GC**。
+> 本仓库按照《数据集版本管理平台-技术路线.md》实现，覆盖里程碑 **M1 ~ M4**（并包含 M5 的 diff 等基础能力）。
+
+## 核心特性（对照技术路线需求）
+
+| # | 需求 | 实现 |
+|---|------|------|
+| 1 | 数据集版本管理与控制（类 Git） | Blob/Tree/Commit 三对象模型、提交历史、分支、标签、diff、append-only 回滚 |
+| 2 | 不同版本存云端、可恢复 | 对象存储 + 不可变提交 + 任意版本检出（零拷贝） |
+| 3 | 命令行上传 | `dv add/commit/push`，上传前按 sha256 去重（跳过已存在 blob） |
+| 4 | 命令行快速下载 | `dv pull/fetch/clone/checkout`，多线程并行下载 + sha256 校验 |
+| 5 | Web 展示数据集/版本/下载命令 | 数据集列表/详情、版本历史、文件清单/目录树、一键复制下载命令卡片 |
+| 6 | Web 端删除数据集并同步清理云端存储 | 删除接口 + blob 引用计数 + 物理删除对象，共享文件不误删 |
+| 7 | 数据集最小化保存在 Web 端 | 控制面只存元数据（哈希/清单/大小），文件内容全部在对象存储 |
+
+## 总体架构
+
+```
+┌─────────────┐   ┌─────────────┐
+│  Web UI     │   │  CLI (dv)   │
+│  (React+AntD)│   │  (Typer)   │
+└──────┬──────┘   └──────┬──────┘
+       ▼                 ▼
+┌──────────────────────────────────────┐
+│ 控制面 Control Plane (FastAPI)       │
+│  ├─ 认证/鉴权: JWT + API Token       │
+│  ├─ 数据集/版本/分支/标签 CRUD        │
+│  ├─ 版本引擎: commit/tree/blob       │
+│  ├─ 预签名 URL 签发（上传/下载）      │
+│  ├─ 存储清理: 引用计数 + 删除 GC      │
+│  └─ 审计日志                          │
+│  元数据库: PostgreSQL / SQLite(开发)  │
+└───────────────┬──────────────────────┘
+                ▼
+┌──────────────────────────────────────┐
+│ 数据面 Data Plane                    │
+│  对象存储: 本地盘(开发) / MinIO / S3  │
+│  objects/<sha256> 内容寻址，跨版本去重│
+└──────────────────────────────────────┘
+```
+
+- **控制面只走元数据，数据面直连对象存储**：大文件不经过应用服务器。
+- **Blob 引用计数**：同一 blob 被多个数据集引用时 `ref_count > 1`；删除数据集只对 `ref_count` 归零的 blob 做物理删除。
+
+## 目录结构
+
+```
+backend/            FastAPI 后端（版本引擎、存储适配、RBAC、审计、删除 GC）
+  app/
+    engine.py         版本引擎：hash/tree/commit/ref_count/删除
+    storage.py        存储适配：LocalStorage（本地盘）+ S3Storage（MinIO/OSS/COS/S3）
+    routers/          auth / tokens / datasets / versions / storage / audit
+  tests/             pytest 集成测试（7 个用例，覆盖核心流程）
+cli/                dv 命令行（Typer + httpx + rich）
+  dv/cli.py           全部子命令
+  dv/transfer.py      并行上传/下载、sha256 扫描与校验
+web/                React + TypeScript + Vite + AntD 前端
+scripts/            demo_seed.py 演示数据；get_token.py 等
+docker-compose.yml  Postgres + MinIO + backend
+```
+
+## 快速开始（开发环境）
+
+### 1. 后端
+
+```bash
+python -m venv .venv
+.venv\Scripts\pip install -r backend/requirements.txt      # Windows
+# 或  source .venv/bin/pip install -r backend/requirements.txt   # Linux/macOS
+
+cd backend
+..\.venv\Scripts\python -m uvicorn app.main:app --port 8000
+```
+
+首次启动自动建库。访问：
+- Web UI: http://localhost:8000
+- API 文档: http://localhost:8000/docs
+- 健康检查: http://localhost:8000/api/v1/health
+
+默认管理员账号由 `/api/v1/auth/bootstrap` 创建（用户名 `admin`，密码来自 `DV_FIRST_ADMIN_PASSWORD`，默认 `admin123`）。
+也可以 POST `/api/v1/auth/register` 注册新用户（第一个注册用户为 admin）。
+
+### 2. 加载演示数据（可选）
+
+```bash
+.venv\Scripts\python scripts\demo_seed.py
+```
+
+### 3. CLI
+
+```bash
+.venv\Scripts\pip install -e ./cli        # 安装 dv 命令
+
+dv login --token <API_TOKEN> --url http://localhost:8000
+dv create default/my-dataset --visibility public
+cd workdir
+dv init default/my-dataset
+dv add ./images ./labels.csv
+dv status
+dv commit -m "v1: 初始数据"
+dv push                       # 上传新 blob（去重）+ 创建云端版本
+dv log
+dv tag v1.0
+dv diff v1 HEAD
+dv rollback v1 -m "回滚到 v1"
+dv fetch default/my-dataset v1.0 -o ./data
+dv clone default/my-dataset -o ./copy
+dv ls --version v1.0
+dv dataset delete default/my-dataset --yes
+```
+
+API Token 可在 Web 端或 `POST /api/v1/tokens` 创建（CLI 用长期 Token，Web 用 JWT）。
+
+### 4. Web UI
+
+```bash
+cd web
+npm install
+npm run build        # 构建到 web/dist，后端自动挂载
+# 开发模式（热更新，代理 /api 到 :8000）:
+npm run dev          # http://localhost:5173
+```
+
+## API 一览（节选）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/auth/login · register · bootstrap | 认证 |
+| POST/GET/DELETE | /api/v1/tokens | API Token 管理（CLI） |
+| POST | /api/v1/datasets | 创建数据集 |
+| GET | /api/v1/datasets | 数据集列表（搜索/分页） |
+| GET | /api/v1/datasets/{id} | 数据集详情 |
+| **DELETE** | **/api/v1/datasets/{id}** | **删除数据集：元数据 + 引用计数归零对象的物理删除，返回释放字节** |
+| GET | /api/v1/datasets/{id}/storage-info | 删除前影响范围（版本数/占用/共享 blob） |
+| POST | /api/v1/datasets/{id}/presign/upload | 上传意向：哈希清单 → 仅返回缺失 blob 的预签名 URL（去重） |
+| POST | /api/v1/datasets/{id}/commits | 创建版本（校验声明哈希均已存在） |
+| GET | /api/v1/datasets/{id}/commits | 版本历史 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/manifest | 版本文件清单 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/presign/download | 版本下载预签名 URL 列表 |
+| GET | /api/v1/datasets/{id}/versions/{ref}/download-command | 下载命令（Web 展示用） |
+| GET | /api/v1/datasets/{id}/tree/{ref} | 目录树浏览 |
+| GET | /api/v1/datasets/{id}/diff?base=&head= | 版本差异 |
+| POST | /api/v1/datasets/{id}/rollback | 回滚（append-only 新提交） |
+| POST/GET/DELETE | /api/v1/datasets/{id}/tags · branches | 标签 / 分支 |
+| GET | /api/v1/datasets/{id}/stats | 存储统计 |
+| GET | /api/v1/audit/logs | 审计日志（admin） |
+
+`ref` 支持：tag 名、分支名、`HEAD`/`latest`、`vN` 序号、commit 哈希（前缀）。
+
+## 存储后端切换
+
+默认 `DV_STORAGE_BACKEND=local`（本地盘模拟对象存储，预签名 URL 为 HMAC 签名 API URL）。
+切换到 S3 兼容对象存储（MinIO/OSS/COS/AWS S3）：
+
+```bash
+DV_STORAGE_BACKEND=s3 \
+DV_S3_ENDPOINT=http://localhost:9000 \
+DV_S3_BUCKET=datasets \
+DV_S3_ACCESS_KEY=... \
+DV_S3_SECRET_KEY=... \
+.venv\Scripts\python -m uvicorn app.main:app --port 8000
+```
+
+CLI/Web 代码路径完全一致（都走预签名 URL 直传/直下）。
+
+## Docker Compose（Postgres + MinIO + 后端）
+
+```bash
+# 先构建前端（把 web/dist 打进镜像）
+cd web && npm install && npm run build && cd ..
+
+docker compose up -d --build
+# Web/API: http://localhost:8000    MinIO 控制台: http://localhost:9001
+```
+
+## 测试
+
+```bash
+.venv\Scripts\python -m pytest backend/tests -q
+```
+
+覆盖：认证/Token、数据集 CRUD、上传去重、提交/标签/diff/回滚、下载校验、
+**RBAC（非 owner 删除返回 403）**、**跨数据集共享 blob 的引用计数与删除 GC**、物理对象释放。
+
+## 里程碑对照
+
+- ✅ M1 版本引擎 + CLI：三对象模型、add/commit/log/tag/rollback、本地盘对象存储、控制面只存元数据
+- ✅ M2 云存储：S3 适配 + 预签名直传直下 + 去重 + 并发下载（分片/断点续传留作增强）
+- ✅ M3 Web UI v1：列表/详情/版本历史/文件清单/目录树/下载命令卡片，元数据驱动渲染
+- ✅ M4 平台化：删除 + 引用计数 + 存储同步清理、RBAC、Token、审计、存储统计
+- 🔜 M5 进阶：分片断点续传、Merkle 分层树、软删除回收站、Webhooks、SDK
+
+## 关键设计说明
+
+- **最小化存储**：数据库只存哈希/清单/大小，文件内容永不入库；相同内容全平台只存一份。
+- **删除原子性**：元数据删除与引用计数更新在同一事务；物理删除失败可由 `gc_jobs` 兜底重试。
+- **完整性**：上传 PUT 时校验 `sha256(body)==key`；下载后校验 sha256。
+- **安全**：私有桶 + 短时效预签名 URL（默认 15 分钟）+ 数据集级 RBAC + 全量审计。
+## 前端界面（ModelScope 风格）
+
+Web 界面参考 ModelScope 社区风格设计：
+
+- 顶部品牌导航 + 「新建数据集」入口 + 用户菜单
+- 首页：渐变 Hero 搜索区 + 数据集卡片网格（彩色图标、描述、版本/文件/大小标签、可见性徽标、更新时间）
+- 详情页：头部大图标 + 统计条（版本/文件/大小/最新版本/更新时间）+ **复制下载命令** 卡片 + 删除入口（owner）
+- 标签页：数据集介绍（自动渲染 README.md）、文件（左侧目录树 + 文件表 + 单文件下载）、版本历史、标签、分支、版本差异
+- 登录页：渐变品牌背景 + 居中卡片
+
+构建：`cd web && npm run build`（产物 `web/dist`，由后端自动托管）。
+UI 冒烟测试：`scripts/ui_check.py`、`scripts/ui_check2.py`（Playwright，自动登录并检查列表/详情/文件/版本/diff/删除弹窗）。
+页面截图：`scripts/ui_check.py` 运行后输出到 `.shots/`。
+
+## 下载进度
+
+- **CLI**：`dv push / pull / fetch / clone / checkout` 均显示 rich 进度条——字节进度、文件数、当前文件、传输速度与剩余时间；下载按流式分块实时刷新，且断点续传（已存在且哈希匹配的文件自动跳过）。可用 `--no-progress` 关闭。
+- **Web 详情页**：新增「下载全部（ZIP）」按钮，弹窗实时显示百分比、当前文件与已下载文件数，完成后打包为 `<数据集名>.zip` 下载。
+
+## 账号注册 与 Token 管理
+
+- **注册**：登录页有「立即注册」入口（用户名/邮箱/密码/确认密码），第一个注册用户自动成为管理员；注册成功即自动登录。
+- **Web Token 管理**（导航栏「Token 管理」）：创建 Token（名称 + 过期时间：永不过期/7/30/90/365 天）、列表展示过期时间与最近使用、吊销；明文仅在创建弹窗显示一次，可一键复制。
+- **CLI**：`dv token create --name X [--expires 2027-01-01T00:00:00]`、`dv token list`、`dv token revoke <id>`。
+- 所有 API 响应均带 `Cache-Control: no-store`，前端请求亦禁用缓存，保证列表变更即时可见。
+
+## README 展示（ModelScope 风格）
+
+- 每个数据集详情页**默认展示 README.md**（「数据集介绍」标签页），风格对齐 ModelScope：
+  - GitHub 风格 Markdown 渲染：标题锚点链接、表格、代码块语法高亮（highlight.js）、引用块、任务列表、分隔线
+  - 相对路径图片自动解析为数据集内文件的预签名 URL（支持懒加载）
+  - 外部链接新窗口打开
+  - 支持 README 中的原生 HTML（rehype-raw）
+- 头部有 `README.md` 标识与「下载 README.md」按钮
+- 无 README 时展示引导空态（含 `dv add README.md && dv commit ... && dv push` 示例）
+
+## 打包安装为 Python 库（推荐部署方式）
+
+仓库根目录的 `pyproject.toml` 把 **后端（`backend/app`）** 与 **CLI（`cli/dv`）** 打包成
+**一个发行版 `dv-platform`**，`pip install` 后即可得到两个命令：
+
+| 命令 | 作用 |
+|------|------|
+| `dv` | 数据集版本管理 CLI（不变） |
+| `dv-server` | 启动/管理后端服务（前台或后台守护进程） |
+
+```bash
+# 在仓库根目录（含 pyproject.toml）
+pip install .            # 或开发模式: pip install -e .
+pip install ".[test]"    # 可选：测试依赖
+```
+
+> 如果环境里以前用 `pip install -e ./cli` 装过旧版 `dv-cli`，先执行 `pip uninstall dv-cli`，
+> 避免与新版 `dv-platform` 里的 `dv` 包/`dv` 命令冲突。
+
+### 快速开始
+
+```bash
+# 1) 后台启动服务（默认数据目录 ~/.dvserver，监听 0.0.0.0:8000）
+dv-server start
+dv-server status
+
+# 自定义端口 / 数据目录 / 前台运行
+dv-server start --port 9000 --data-dir D:\dvdata
+dv-server run --host 127.0.0.1 --port 8000        # 前台（Ctrl+C 停止）
+dv-server stop --port 9000
+dv-server restart
+dv-server logs --tail 50
+```
+
+需要开机自启时，可把 `dv-server start` 加入 Windows 任务计划程序（开机触发）或 systemd 单元。
+
+```bash
+# 2) 首次创建管理员账号（admin / admin123，见数据目录 .env 可改）
+#    http://127.0.0.1:8000/docs  -> POST /api/v1/auth/bootstrap
+#    或
+#    Web UI http://127.0.0.1:8000 （若构建了前端并以 DV_WEB_DIST 指向 web/dist）
+
+# 3) CLI 使用
+dv login --token <API_TOKEN> --url http://127.0.0.1:8000
+dv create team/my-dataset
+dv clone team/my-dataset -o ./data
+```
+
+### `dv-server` 数据目录（data dir）
+
+所有可变数据（SQLite `dv.db`、本地对象存储 `./storage`、`.env`、PID、日志）都落在
+**数据目录**内，因此服务可放在任意位置、完全自包含：
+
+- `run`（前台）：默认使用当前目录；
+- `start/stop/status/restart/logs`（守护进程）：默认 `~/.dvserver`（可用 `DV_SERVER_DIR` 或 `--data-dir` 覆盖）。
+
+首次 `start` 会自动生成 `.env`（含随机 `DV_JWT_SECRET`，重启后凭据保持有效）。
+生产建议：`DV_DATABASE_URL` 换 PostgreSQL、`DV_STORAGE_BACKEND=s3` 指向 MinIO/OSS/S3，
+并把 `DV_PUBLIC_BASE_URL` 设为客户端可达的地址（预签名 URL 以此为基准）。
+
+### 多客户端并发上传/下载
+
+- 上传/下载走预签名 URL（S3 后端直连对象存储，完全不经过应用进程）；
+- 本地后端（`DV_STORAGE_BACKEND=local`）的 PUT/GET 已改为**流式收发**：上传边收边写临时文件
+  并校验 sha256 后原子改名，下载用 `FileResponse` 流式返回，多客户端并发传大文件不会把文件整体载入内存；
+- SQLite（开发默认）开启 WAL + `busy_timeout=30000`，且每个事务以 `BEGIN IMMEDIATE` 开始，
+  多个客户端同时上传相同 blob（去重竞态）或同时向同一数据集 push 时不会出现
+  “database is locked”/重复版本号/丢更新；
+- 同一台机器多客户端并行传输建议保持 `--workers 1`；要横向扩容请换 PostgreSQL + S3 再加大 workers。

dv_platform-0.1.0/backend/app/__init__.py

@@ -0,0 +1 @@
+"""Dataset Version Management Platform - backend package."""

dv_platform-0.1.0/backend/app/config.py

@@ -0,0 +1,28 @@
+"""Application settings (env-prefixed with DV_)."""
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DV_", env_file=".env", extra="ignore")
+
+    app_name: str = "Dataset Version Platform"
+    database_url: str = "sqlite:///./dv.db"
+    storage_backend: str = "local"          # local | s3
+    storage_root: str = "./storage"         # local backend object root
+    s3_endpoint: str = "http://localhost:9000"
+    s3_bucket: str = "datasets"
+    s3_access_key: str = ""
+    s3_secret_key: str = ""
+    s3_region: str = "us-east-1"
+    presign_ttl: int = 900                  # seconds (15 min)
+    jwt_secret: str = "dev-secret-change-me-0123456789abcdef0123456789"
+    jwt_algorithm: str = "HS256"
+    jwt_expire_minutes: int = 10080         # 7 days
+    public_base_url: str = "http://localhost:8000"
+    web_dist: str = ""                     # optional: absolute path to a built web/dist to serve
+    first_admin_password: str = "admin123"
+    chunk_size: int = 8 * 1024 * 1024       # 8MB reference chunk for docs
+
+
+settings = Settings()
+