# kp-softvault **Repository Path**: jocundmo/kp-softvault ## Basic Information - **Project Name**: kp-softvault - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-16 - **Last Updated**: 2026-05-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SoftVault - 软件下载管理站 MVP ## 项目概述 SoftVault 是一个论坛风格的软件下载管理网站,用于管理个人收集的工具软件和下载资源。 **核心特性:** - 文件不动原则:文件保持在用户下载时的位置,数据库仅存储路径引用 - 快速录入:通过文件选择器浏览本地磁盘,自动解析文件名,快速录入软件信息 - 多源下载:支持本地文件、网盘链接、种子/磁力链接等多种下载方式 ## 技术栈 **后端:** - Python 3.14 + FastAPI - SQLAlchemy 2.0 + SQLite - JWT认证 **前端:** - React 18 + TypeScript 5 - Vite 5 + React Router 6 - Zustand 5(状态管理) - Axios(API调用) ## 项目结构 ``` kp-softvault/ ├── backend/ # 后端项目 │ ├── app/ │ │ ├── models/ # SQLAlchemy数据模型 │ │ ├── schemas/ # Pydantic请求/响应模型 │ │ ├── routers/ # API路由 │ │ ├── services/ # 业务逻辑 │ │ ├── utils/ # 工具函数 │ │ ├── config.py # 配置管理 │ │ ├── database.py # 数据库连接 │ │ └ main.py # FastAPI入口 │ ├── data/ # SQLite数据库文件 │ ├── uploads/ # 上传文件存储 │ ├── pyproject.toml # 项目配置 │ └ .env # 环境变量 │ ├── frontend/ # 前端项目 │ ├── src/ │ │ ├── components/ # 组件 │ │ ├── pages/ # 页面组件 │ │ ├── routers/ # 路由配置 │ │ ├── services/ # API服务层 │ │ ├── stores/ # Zustand状态管理 │ │ ├── styles/ # CSS样式 │ │ ├── types/ # TypeScript类型定义 │ │ ├── App.tsx # 根组件 │ │ └ main.tsx # 入口文件 │ ├── vite.config.ts # Vite配置 │ ├── package.json # 项目配置 │ ├── docs/ # 文档目录 │ └── archive/ # 归档的研究报告 │ └── configs/ # 配置文件 ├── resources_pool.json └── vaults.json ``` ## 快速启动 ### 后端启动 ```bash cd backend uv sync uv run uvicorn app.main:app --port 8085 --reload ``` 后端服务运行在 http://localhost:8085 ### 前端启动 ```bash cd frontend yarn yarn dev ``` 前端服务运行在 http://localhost:3000 ## 默认账号 管理员账号: - 用户名:admin - 密码:admin123 ## 核心功能 ### 1. 快速录入 后台快速录入页面提供: - 文件选择器:浏览本地磁盘,选择已下载的文件 - 文件名解析:自动从文件名提取软件名称和版本号 - 表单填写:补充分类、描述、标签等信息 - 一键保存:快速完成录入 ### 2. 文件选择器 核心特性: - 浏览本地目录树 - 显示文件大小、修改时间 - 支持文件类型过滤(exe、msi、zip等) - 路径安全检查(只允许访问白名单目录) ### 3. 软件列表 前台展示: - 卡片式软件列表 - 关键词搜索 - 分类筛选 - 分页浏览 ## API文档 后端启动后访问 http://localhost:8085/docs 查看完整API文档。 主要API: - `/api/v1/auth/login` - 登录 - `/api/v1/files/browse` - 浏览目录 - `/api/v1/files/parse` - 解析文件名 - `/api/v1/softwares` - 软件CRUD - `/api/v1/categories` - 分类管理 ## 下一步计划 当前已完成 MVP 版本(Phase 1-2),后续可扩展: - Phase 3:前台展示功能完善(详情页、下载功能) - Phase 4:后台管理完善(仪表盘、批量操作) - Phase 5:批量导入工具(CLI扫描工具) - Phase 6:优化完善(性能优化、错误处理) ## 开发注意事项 1. 文件选择器只允许访问配置的白名单目录(`.env` 中的 `ALLOWED_ROOT_DIRS`) 2. 数据库使用 SQLite,文件位于 `backend/data/softvault.db` 3. JWT Token 有效期为 7 天 4. 前端使用 Zustand 持久化存储用户状态 ## 参考项目 本项目参考了 `kp-forum`(Express + EJS + SQLite)的实现思路,采用了前后端分离架构和更现代的技术栈。