项目：X-Pan ｜ 版本：v1.0 ｜ 生成日期：2026-10-05 ｜ 依据：源码分析
X-Pan 是一个面向个人的分布式云存储系统（仓库根 README.md 自述："私人分布式存储系统"），定位为课程级企业架构实践项目。它把"把任意文件存到自己的云端"作为核心场景，覆盖了从用户注册、文件上传（秒传/分片/断点续传）、文件组织（目录树/标签/收藏/保险箱）、文件分发（分享链接/下载/WebDAV 挂载）、到运维保障（可观测性/熔断/限流/CI 测试门禁）的完整闭环。
目标用户与使用场景：
| 用户角色 | 使用场景 | 承载端 |
|---|---|---|
| 网盘所有者（个人） | 上传/管理/预览自己的文件，调整配额（上限 10TB），管理登录设备 | Web（Vue 3）、移动端（Flutter） |
| 分享接收者（匿名） | 凭分享链接 + 提取码浏览/下载/转存他人分享的文件 | Web 分享页 /share/:shareId（免登录） |
| 第三方客户端 | 经 WebDAV 协议接入（macOS Finder / Windows Explorer / RaiDrive / Cyberduck；当前实际开放 GET/HEAD/DELETE，挂载能力边界见《16》ADR-010） | WebDavController（/webdav/**，Basic Auth） |
| 开发/运维者 | 通过 Swagger 文档、Prometheus 指标、Grafana 面板、Jaeger 链路维护系统 | knife4j/springdoc、/actuator/prometheus、deploy/ |
需要特别澄清的一点（避免读者被"微服务"字样误导）：后端目前是"按微服务风格拆分的模块化单体（Modular Monolith）"——全部业务运行在一个 Spring Boot 进程（x-pan-parent/server，启动类 com.xiaoye.pan.server.XPanServerLauncher，端口 8081），不存在注册中心（Nacos/Eureka）与独立网关进程；"分布式"主要体现在存储层（MinIO 4 节点纠删码集群、多存储引擎路由）与多端接入上。模块间的"服务边界"以 Maven 模块与包结构固化，具备后续按边界拆分为真正微服务的条件。本文档集严格按源码事实描述这一架构。
从体量看，这套系统已远超"课程作业"的平均水位：后端约 90 个 REST 接口、17 个业务模块、20 张表；Web 端 26 个自研基础组件、18 个组合式函数；移动端 29 个页面；并配有 Prometheus/Grafana/Jaeger 观测栈与双端 CI。根目录的 CHANGELOG.md（遵循 Keep a Changelog 规范）与 CODE_AUDIT_2026-09-06.md 记录了清晰的演进脉络：项目按 P1~P4 阶段推进（P4 完成可观测性、实时通知与 CI/CD），2026-09-06 完成一次全仓库质量加固（修复 90+ 项问题，涵盖空壳模块清理、SQL 防御、配置安全），2026-09-28 摘除 CI 测试豁免、接入 MySQL/Redis 服务容器测试门禁（68 个用例全绿），并补齐 db.sql 中缺失的版本历史/离线下载两张表。release-artifacts/ 下保留 v1.0 的 Android APK 与 macOS 安装包产物，说明三端均已走到可发布状态。
"个人网盘"之所以值得作为企业级架构的练兵场，在于它是少数"业务人人秒懂、但技术纵深完整"的领域：上传要面对大文件与不稳定网络（秒传、分片、断点续传），存储要在成本与容量间权衡（多引擎路由、纠删码），分发要处理权限与链接时效（分享码、ptoken 预签名），运维要兜住下游故障（熔断、限流、重试）。这些问题在"待办列表""博客"类项目中要么不存在、要么规模太小显不出来，而在网盘场景里每一个都必须正面回答——这正是本项目的教学价值所在。
以下能力矩阵来自根 README.md 并经源码逐项核实（括号内为对应源码位置，相对 x-pan/）：
| 模块 | 能力 | 关键源码 |
|---|---|---|
| 认证 | 注册（幂等）、登录（多端并存）、登出、密保找回密码、在线改密、JWT token 生命周期中点自动续期 | x-pan-parent/server/.../modules/user/controller/UserController.java、common/aspect/CommonLoginAspect.java |
| 设备管理 | 登录设备指纹（UA+IP）记录、设备列表、远程下线指定设备 | modules/device/controller/DeviceController.java |
| 文件管理 | 文件列表（分页/排序/类型筛选）、创建文件夹、重命名、批量重命名、移动、复制、批量删除、批量打标签、面包屑、文件夹树 | modules/file/controller/FileController.java、service/impl/UserFileServiceImpl.java（约 2200 行） |
| 上传 | 单文件上传、文件秒传（MD5）、分片上传（5MB 分片）、已传分片查询（断点续传）、分片合并 | FileController.chunkUpload/mergeFile、前端 x-pan-fronted/src/composables/useUploader.ts |
| 下载/预览 | 单文件下载、批量打包 zip 下载、MinIO 大文件 302 预签名直链、Range 断点预览、短期 ptoken 预览签名 URL | FileController.download/preview/previewUrl/previewStream |
| 分享 | 创建分享（提取码/有效期/下载次数限制）、分享详情、分享文件列表、校验提取码、转存到我的网盘、匿名下载、访问/保存/下载统计 | modules/share/controller/ShareController.java、common/aspect/ShareCodeAspect.java |
| 回收站 | 软删除 + 级联还原、彻底删除、回收站统计、30 天过期自动清理 | modules/recycle/、common/schedule/task/CleanExpireRecycleFileTask.java |
| 离线下载 | HTTP/HTTPS 链接后台拉取，SSRF 防护（拒内网 IP/元数据地址/危险协议）+ 逐跳重定向校验（最多 5 跳） | modules/offline/controller/OfflineTaskController.java、service/impl/OfflineTaskServiceImpl.java |
| 隐私保险箱 | 独立密码（PBKDF2）、防爆破锁定、解锁状态缓存 30 分钟、移入/移出/永久删除 | modules/vault/controller/VaultController.java |
| 版本历史 | 文件多版本记录、版本详情、一键回滚、删除版本、单文件上限 50 版本自动裁剪 | modules/file/controller/FileHistoryController.java、sql/file_history.sql |
| 重复清理 | 基于 MD5 identifier 的重复文件分组、去重统计、释放冗余引用 | modules/file/dedup/controller/FileDedupController.java |
| 收藏 | 批量收藏/取消收藏、收藏列表 | modules/favorite/controller/FavoriteController.java |
| 在线解压 | ZIP 异步解压任务、任务进度查询 | modules/extract/controller/ExtractController.java、sql/extract_task.sql |
| 文档预览 | Office/PDF 转 PDF 预览（异步任务 + 轮询直链） | modules/preview/controller/PreviewController.java |
| 媒体增强 | 图片缩略图（磁盘缓存 + 按尺寸缩放）、视频封面、FFmpeg 关键帧雪碧图 | file/controller/ThumbnailController.java、VideoThumbnailController.java |
| AI 助手 | 文件文本提取 → LLM 摘要/自动打标（DeepSeek，可降级为规则打标） | modules/filetag/controller/FileTagController.java、modules/textextract/、前端 composables/useLLM.ts |
| 搜索 | 关键词搜索 + 高级筛选（类型/扩展名/大小/时间）、搜索联想、热搜榜、搜索历史 | FileController.search/suggest/hot、modules/user/entity/XPanUserSearchHistory.java |
| 实时通知 | WebSocket（/ws/notification）推送 + 通知中心落库（未读数/已读标记） | common/websocket/、modules/notification/ |
| 多存储引擎 | 本地文件系统 / MinIO / 阿里云 OSS / FastDFS 四实现，当前启用 Local+MinIO，按 50MB 阈值路由 | framework/storage-engine/、application.yaml 的 pan.storage.minio.* |
| WebDAV | 标准协议子集的最小可用面（实际开放 GET/HEAD/DELETE + OPTIONS 探测；PUT/MKCOL/MOVE/COPY 返回 501，PROPFIND/MKCOL/MOVE/COPY 未注册路由即 405，目录浏览不可用，见《16》ADR-010），Basic Auth，零第三方依赖手写实现 | modules/webdav/WebDavController.java |
| 可观测性 | Micrometer+Prometheus 指标、OpenTelemetry 链路（MDC 注入 traceId/spanId）、Resilience4j 熔断（MinIO/离线下载）、Redis 限流 | common/metrics/、common/log/LogMdcFilter.java、common/ratelimit/RedisRateLimiter.java、common/resilience/ |
这张能力矩阵可以按"三条线"来读。效率线解决"文件怎么进来、怎么找到"：上传三件套（秒传按 MD5 命中免传、分片把大文件切成 5MB 并行上传、断点续传借助已传分片查询跨会话续传）组合起来，意味着弱网环境传大文件不再是从零开始；搜索侧则有关键词 + 类型/扩展名/大小/时间的高级筛选、联想词与热搜榜。安全线解决"文件丢了、泄了怎么办"：删除先进回收站（30 天过期自动清理），重要文件放保险箱（独立 PBKDF2 密码 + 防爆破锁定，与登录密码隔离），误改可回滚版本历史（单文件上限 50 版自动裁剪），空间紧张可用重复清理按 MD5 分组释放冗余。增值线解决"文件存着之外还能干嘛"：Office/PDF 异步转 PDF 预览、图片缩略图、视频封面与关键帧雪碧图让内容"开箱即读"；AI 助手把文档文本抽出后交给 LLM 做摘要与自动打标，且设计了规则打标降级路径——LLM 不可用时功能退化为关键词规则而非不可用。关键流程的代码级走读（上传、登录鉴权、分享、离线下载）见《05-核心流程》。
x-pan-parent/）| 类别 | 选型 | 版本 | 选型理由（源自 pom/配置与代码注释） |
|---|---|---|---|
| 语言/运行时 | Java | 17 | 父 POM maven.compiler.source/target=17（x-pan-parent/pom.xml） |
| 核心框架 | Spring Boot | 3.4.13 | spring-boot-starter-parent 继承，统一依赖仲裁 |
| 持久化 | MyBatis-Plus | 3.5.9 | 单表 CRUD 零 SQL，ServiceImpl/QueryWrapper 提效；复杂查询走 XML（resources/mappers/） |
| 数据库 | MySQL + Druid | 8.0 / 1.2.25 | mysql-connector-j 8.4.0；连接池 Druid |
| 缓存 | Spring Cache + Redis + Caffeine | — | 双实现模块：framework/cache/cache-redis（登录态/限流/分布式状态）、cache-caffeine（可切换本地缓存） |
| 安全 | jjwt + PBKDF2 | 0.12.6 | PasswordUtil 用 PBKDF2WithHmacSHA256 1 万次迭代加盐哈希；JwtUtil 支持 CLIENT_ID/RENEWAL_TIME claim |
| 实时通信 | Spring WebSocket（原生，无 STOMP） | — | WebSocketConfig 注释："保持轻量"；心跳 30s |
| 熔断/重试 | Resilience4j | 2.2.0 | minioStorage/offlineDownload 两个熔断实例 + 重试策略，配置见 application.yaml |
| 链路追踪 | Micrometer Tracing + OpenTelemetry OTLP | — | W3C 传播，采样率 0.1，OTLP 导出默认关闭（management.otlp.tracing.export.enabled=false） |
| 监控 | Micrometer + Prometheus（actuator 暴露） | — | management.endpoints.web.exposure.include: health,info,metrics,prometheus |
| 对象存储 | MinIO SDK（启用）/ 阿里云 OSS SDK 3.18.5 / FastDFS client 1.27.2（依赖已注释） | — | server/pom.xml 中 oss/fastdfs 模块依赖被注释，仅 local/minio 生效 |
| API 文档 | springdoc-openapi 2.8.6 + knife4j 4.5.0 | — | 生产 profile 默认全关闭（knife4j.enable: false），dev/local 自动开启 |
| 工具 | Lombok 1.18.46、MapStruct 1.6.3（PO→Context→VO 转换）、Hutool 5.8.47（雪花 ID 等）、Fastjson2 2.0.64、Guava、commons-io/compress | — | 父 POM dependencyManagement 统一版本 |
注意：父 POM dependencyManagement 里声明了 rocketmq-spring-boot-starter 2.3.6，但全仓库没有任何 Java 代码/配置实际使用 RocketMQ（grep -r rocketmq 仅命中 pom），属于预留依赖而非在用组件——读者不要误以为存在消息队列。
后端选型有三处值得展开的权衡。多存储引擎抽象是本项目最核心的设计：framework/storage-engine/ 以"接口 + 抽象模板"定义引擎契约，local/minio/oss/fastdfs 四实现可插拔，当前按 50MB 阈值在本地盘与 MinIO 之间路由（小文件走本地减少网络开销，大文件走 MinIO 享受集群容量与纠删码冗余）；切换到 OSS 或 FastDFS 只需启用依赖与配置，业务代码零改动——这是"面向接口编程"在存储选型上的标准收益。Redis 作为强依赖（与 xyMall 的"可丢增强层"取向不同）：登录态缓存、限流、WebSocket 会话外置状态都在 Redis，缺失即启动失败，取的是实现简单与强一致语义；代价是单点依赖由部署侧的 compose 编排兜底。熔断只落在两个下游（minioStorage、offlineDownload）：不为每个远程调用配熔断，只对"外部对象存储"与"任意外网地址拉取"这两个最不可控的依赖做隔离，符合"熔断保护的是不可控依赖"的原则（模式汇总见《01-系统架构》第 6 节）。
x-pan-fronted/）| 类别 | 选型 | 说明 |
|---|---|---|
| 语言 | TypeScript 5.6（strict） | tsconfig.app.json 严格模式；npm run build 先跑 vue-tsc --noEmit |
| 框架 | Vue 3.5（Composition API + <script setup lang="ts">） | 全部页面组件 |
| 状态 | Pinia 2.3 | 5 个 store：user/file/navbar/task/breadcrumb（src/stores/） |
| 路由 | Vue Router 4.5（createWebHistory） | src/router/index.ts，全局守卫做登录校验 |
| UI | 自研 Base 组件库（26 个 Base 组件）+ Tailwind CSS 4* | src/components/base/；README 明确"未使用 Element Plus"（ElMessage 名字来自 composables/useToast.ts 的自有封装） |
| 构建 | Vite 5.4 + @tailwindcss/vite | dev 端口 5179；/api、/ws 代理到 8081（vite.config.ts） |
| HTTP | Axios 1.7（主实例）+ 原生 fetch/simple-http | src/utils/http.ts 拦截器处理 token 续期/code=10 重登录/traceId |
| 上传 | simple-uploader.js 0.6 + spark-md5 | 分片/秒传/断点续传协议核心（composables/useUploader.ts） |
| 实时 | 原生 WebSocket 封装 | composables/useWebSocket.ts（单例、指数退避重连、25s 心跳） |
| 预览 | pdfjs-dist、@vue-office（docx/xlsx/pptx/pdf）、ArtPlayer、APlayer、Shiki、vditor、jszip、pdf-lib、qrcode、fuse.js | 按需懒加载，vite.config.ts 手工拆 vendor chunk |
| 图标 | @lucide/vue | 全站线性图标 |
前端最值得注意的决策是自研 26 个 Base 组件而不引入 Element Plus（根 README.md 明确说明）：网盘的文件列表、拖拽上传、预览弹层等界面强定制，通用组件库反而要大量覆写样式；自研组件配合 Tailwind 4 让视觉与交互完全可控，代价是需要自己维护无障碍与边界场景。另一个要点是预览体系的懒加载：pdfjs、@vue-office、ArtPlayer、Shiki 等重量级预览依赖经 vite.config.ts 的 manualChunks 拆为独立 vendor chunk，按需加载，避免拖累首屏——这与后端"预签名 URL 302 直链"一起构成大文件预览的完整方案。
x-pan-mobile/）| 类别 | 选型 | 说明 |
|---|---|---|
| 框架 | Flutter 3.35 / Dart SDK ^3.9.2 | pubspec.yaml；支持 Android/iOS/macOS/Windows |
| 状态管理 | flutter_riverpod 2.6.1 | 5 个 provider：auth/file/notification/upload/view_mode（lib/providers/） |
| 网络 | dio 5.7 | lib/core/network/http_client.dart 单例 + 拦截器（token/clientId/traceId/续期/code=10 全局重登录） |
| 路由 | go_router 14.6.2 | lib/router/app_router.dart 仅注册 /、/login、/register 三条顶层路由 + 登录态 redirect；其余 29 个页面通过 Navigator.push 压栈 |
| 本地存储 | flutter_secure_storage 9.2.2（Token/Keychain/Keystore）、shared_preferences、upload_task_storage（断点续传任务持久化） | lib/core/storage/ |
| 媒体 | video_player+chewie、just_audio、flutter_pdfview/pdfx、webview_flutter、cached_network_image | 各类预览页 |
| 实时 | web_socket_channel 3.0.1 + flutter_local_notifications | lib/services/notification_service.dart、local_notification_service.dart |
| 其它 | file_picker、open_filex、crypto（MD5）、archive（XMind 解析）、flutter_markdown | pubspec.yaml |
x-pan-parent/server/Dockerfile（Maven 构建 → JRE 17 运行，非 root 用户 xpan，healthcheck 探活）；x-pan-fronted/Dockerfile（Node 20 构建 → nginx 1.27-alpine 托管静态资源 + 反代）。x-pan-parent/deploy/docker-compose.yml（MinIO 4 节点纠删码集群 + nginx 负载均衡）、docker-compose-server.yml、prometheus.yml、alerts.yml、grafana-dashboard.json。x-pan-parent/.github/workflows/ci.yml（编译/打包 + MySQL/Redis 服务容器测试门禁 68 用例 + GHCR 镜像推送）；x-pan-fronted/.github/workflows/ci.yml（vue-tsc 类型检查 + 构建 + 镜像推送）。x-pan/
├── README.md / CHANGELOG.md / DEV_GUIDELINES.md / CODE_AUDIT_2026-09-06.md # 根文档（线索）
├── release-artifacts/ # v1.0 发布产物（android apk / macos zip / release notes）
├── x-pan-parent/ # 后端：Maven 多模块（Spring Boot 3.4.13 / Java 17）
│ ├── pom.xml # 父 POM：统一 dependencyManagement（版本仲裁）
│ ├── run-local.sh # 本地启动脚本：导出 XPAN_* 环境变量后 mvn spring-boot:run
│ ├── framework/ # 通用框架层（可独立复用的"平台件"）
│ │ ├── core/ # 雪花ID/加密ID、JWT、PBKDF2、R 响应体、异常、AES128
│ │ ├── web/ # HttpLogFilter、CorsFilter、WebExceptionHandler、ID 加密序列化器
│ │ ├── cache/ # cache-core 常量 + cache-redis / cache-caffeine 双 CacheManager 实现
│ │ ├── orm/mybatis-plus/ # MP 装配与代码生成器
│ │ ├── schedule/ # 动态定时任务框架（ScheduleManager/ScheduleTaskHolder）
│ │ ├── swagger2/ # 接口文档配置（dev/local 才开启）
│ │ └── storage-engine/ # core（接口+抽象模板）/ local / minio / oss / fastdfs
│ ├── server/ # 业务服务（唯一可执行模块，x-pan-server.jar）
│ │ ├── src/main/java/.../server/
│ │ │ ├── XPanServerLauncher.java # 启动类：@SpringBootApplication + @MapperScan + @EnableScheduling
│ │ │ ├── common/ # 鉴权/分享码切面、限流、熔断、WS、指标、GC、定时任务、全局异常
│ │ │ └── modules/ # 17 个业务模块：user/device/file(含dedup)/filetag/share/recycle/
│ │ │ # offline/vault/favorite/extract/preview/textextract/notification/log/webdav
│ │ └── src/main/resources/ # application.yaml(+dev/local)、mappers/*.xml、sql/ 迁移脚本、logback-spring.xml
│ ├── distribution/ # 打包配置：conf/db.sql（全量 20 张表建表脚本）、assembly
│ ├── deploy/ # docker-compose（MinIO 4 节点）、prometheus/alerts/grafana、deploy.sh
│ └── .github/workflows/ci.yml # 后端 CI：编译+测试门禁（MySQL/Redis 服务容器）+ GHCR 镜像
├── x-pan-fronted/ # Web 前端：Vue 3.5 + TS strict + Pinia + Tailwind 4 + Vite 5
│ ├── vite.config.ts # dev 5179；/api→8081 反代；manualChunks 预览器vendor拆包
│ ├── nginx.conf / Dockerfile # 生产：SPA fallback + /api 反代 + /ws 升级头直通
│ └── src/
│ ├── api/ # 11 个业务 API 模块（user/file/share/recycle/offline/vault/…）
│ ├── composables/ # 18 个组合式函数（useUploader/useWebSocket/useLLM/useTheme/…）
│ ├── components/ # base/（26 个自研 Base 组件）+ file-table/preview/buttons/… 业务组件
│ ├── stores/ # Pinia：user/file/navbar/task/breadcrumb
│ ├── router/index.ts # 路由表 + 登录守卫（白名单/重定向/用户信息引导）
│ ├── layout/index.vue # 主布局：Header + Navbar + AppMain + 全窗拖拽上传
│ ├── views/ # login/register/forget/share/preview×6/list-page×12/error/protocol
│ └── utils/ # http.ts（axios 拦截器）、cookie.ts、md5.ts、preview 等
└── x-pan-mobile/ # 移动端：Flutter 3.35 + Riverpod + Dio + go_router
├── pubspec.yaml # 依赖清单
└── lib/
├── main.dart # 入口：ProviderScope + bootstrap 恢复登录态
├── core/ # config（API地址/分片5MB）/network（Dio 封装）/storage（安全存储）/theme
├── models/ # 后端 VO 映射（FileVO/UserInfo/ApiResponse…）
├── services/ # ~20 个 API 服务（upload/share/vault/offline/llm/notification…）
├── providers/ # Riverpod：auth/file/notification/upload/view_mode
├── router/app_router.go # go_router：/、/login、/register + 登录态 redirect
├── pages/ # 29 个页面（home/login/register/share/vault/offline/各预览页…）
└── widgets/ # 通用组件（app_list_item/category_grid/skeleton/responsive…）三端目录各自体现了清晰的职责切分。后端 framework/ 与 server/ 的边界与 xyMall 同源：framework 是不感知业务的平台件（雪花 ID、加密、存储引擎抽象、动态调度框架），server 的 common/ 放横切业务件（鉴权切面、限流、熔断、WS），modules/ 按领域切 17 个模块，模块内包结构完全同构。Web 端把"可复用逻辑"集中在 composables/（上传协议、WebSocket 重连、LLM 调用、主题切换都是组合式函数），页面只做组装；移动端则用 Riverpod provider 承担同等角色（providers/ 五个），且把"哪些页面进路由表"刻意收敛为三条顶层路由、其余页面压栈导航，登录态统一由 redirect 守卫处理。release-artifacts/ 与 db-backup/ 类的产物目录不参与构建，只作发布与追溯档案。
| 工具 | 版本 | 用途 |
|---|---|---|
| JDK | 17+ | 后端编译运行 |
| Maven | 3.8+ | 后端构建 |
| Node.js / npm | 20+ / 10+ | 前端构建 |
| Flutter | 3.35（Dart 3.9） | 移动端 |
| MySQL | 8.0+ | 持久化（库 x_pan，建表脚本 x-pan-parent/distribution/conf/db.sql） |
| Redis | 7.0 | 登录态缓存/限流（强依赖，密钥缺失启动失败） |
| MinIO | RELEASE.2025-04（或关闭） | 对象存储；pan.storage.minio.enabled=false 可退回本地存储 |
cd x-pan-parent
mysql -u root -p < distribution/conf/db.sql # 初始化 20 张表
export XPAN_DB_PASSWORD=xxx XPAN_REDIS_PASSWORD=xxx
export XPAN_JWT_SECRET=$(head -c 48 /dev/urandom | base64) # ≥32 字节
export XPAN_AES_KEY=$(openssl rand -hex 8) XPAN_AES_IV=$(openssl rand -hex 8) # 各 16 字节
mvn clean install -DskipTests
mvn -pl server spring-boot:run # 或 ./run-local.sh（本地已配好密钥）
# Swagger（dev profile）：http://localhost:8081/doc.html所有密钥通过 XPAN_* 环境变量注入，任何 yaml 中不允许出现密钥默认值（${ENV:} 空兜底，缺失即启动失败）——这是 DEV_GUIDELINES.md 第一节的硬性红线。
cd x-pan-fronted
npm install
npm run dev # http://localhost:5179，/api 与 /ws 由 vite 代理到 8081cd x-pan-mobile
flutter pub get
# 指向本地后端（默认指向公网生产地址 https://pan.zhangzhengyang.com，见 lib/core/config/app_config.dart）：
flutter run --dart-define=X_PAN_API_BASE_URL=http://127.0.0.1:8081
# Android 模拟器访问宿主机用 http://10.0.2.2:8081distribution/conf/db.sql 未内插账号数据；x-pan-parent/README.md 提到"默认账号 admin/admin（上线前修改）"，但当前 db.sql 为纯 DDL（⚠️ 待确认：该默认账号是否需手工 INSERT 或由注册接口创建）。
01-系统架构.md 理解 framework/server 分层、模块边界与数据流；02-页面设计.md，对接接口看 03-接口设计.md，改表看 04-数据模型.md；05-核心流程.md（上传/秒传/断点续传、登录鉴权、分享、离线下载）；06-部署运行.md。按角色取用的建议：做前端的读者 00 → 02 → 03（重点看上传协议与 WebSocket 约定），组件约定另见根 DEV_GUIDELINES.md；做后端的读者 00 → 01 → 04 → 05，07-模块详解可当模块字典；关心工程质量的读者可加读 09-测试与质量保障 与 13-技术债务与演进建议——后者与根目录 CODE_AUDIT_2026-09-06.md、CHANGELOG.md 一起，完整呈现"审计 → 修复 → 门禁"的质量加固路径。全文档集以源码为唯一事实来源，仓库处于持续演进中，发现文档与代码不一致时以代码为准。