mirror of
https://github.com/ZeroCatDev/ClassworksKV.git
synced 2025-10-22 18:33:11 +00:00
282 lines
7.4 KiB
Markdown
282 lines
7.4 KiB
Markdown
# KV 服务管理应用
|
||
|
||
一个基于 Vue 3 + JavaScript + shadcn-vue 的 KV 存储服务管理界面，支持多应用 Token 管理和本地设备码生成。
|
||
|
||
## 功能特性
|
||
|
||
- 🔑 **多 Token 管理**：管理多个应用的访问 Token
|
||
- 🔐 **本地设备码生成**：自动生成设备授权码，无需服务器
|
||
- 📊 **KV 空间信息**：实时显示当前 KV 空间的使用情况
|
||
- 💾 **数据管理**：浏览、创建、编辑和删除 KV 键值对
|
||
- 🔍 **搜索过滤**：支持键名搜索和多种排序方式
|
||
- 📱 **响应式设计**：适配桌面和移动设备
|
||
- 🎨 **现代 UI**：shadcn-vue 组件库，简洁清爽
|
||
- ⚡ **快速开发**：Vite 驱动，HMR 即时更新
|
||
- 🗂️ **约定式路由**：基于文件系统的自动路由
|
||
|
||
## 技术栈
|
||
|
||
- **框架**：Vue 3 + JavaScript
|
||
- **构建工具**：Vite
|
||
- **UI 组件**：shadcn-vue
|
||
- **样式**：Tailwind CSS v4
|
||
- **路由**：Vue Router + unplugin-vue-router (约定式路由)
|
||
- **图标**：Lucide Icons
|
||
- **状态管理**：LocalStorage (轻量级)
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制 `.env.example` 到 `.env` 并填写配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```env
|
||
VITE_API_BASE_URL=http://localhost:3000
|
||
VITE_SITE_KEY=your-site-key-here
|
||
```
|
||
|
||
### 3. 启动开发服务器
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
应用将在 http://localhost:5173 运行
|
||
|
||
### 4. 构建生产版本
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
构建产物将输出到 `dist` 目录。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
kv-admin/
|
||
├── src/
|
||
│ ├── components/
|
||
│ │ └── ui/ # shadcn-vue 组件
|
||
│ ├── pages/ # 约定式路由页面
|
||
│ │ ├── index.vue # Token 管理页面 (/)
|
||
│ │ └── dashboard.vue # KV 数据管理 (/dashboard)
|
||
│ ├── lib/
|
||
│ │ ├── api.js # API 客户端
|
||
│ │ ├── tokenStore.js # Token 存储管理
|
||
│ │ └── utils.js # 工具函数
|
||
│ ├── App.vue # 根组件
|
||
│ ├── main.js # 入口文件
|
||
│ └── style.css # 全局样式
|
||
├── .env.example # 环境变量模板
|
||
├── components.json # shadcn-vue 配置
|
||
├── jsconfig.json # JavaScript 配置
|
||
├── vite.config.js # Vite 配置
|
||
└── package.json
|
||
```
|
||
|
||
## 核心功能说明
|
||
|
||
### 1. Token 管理（首页）
|
||
|
||
- **添加应用 Token**：输入应用名称和 Token，系统自动生成设备码
|
||
- **设备码生成**：本地随机生成格式如 `XXXX-XXXX-XXXX-XXXX` 的设备码
|
||
- **多 Token 支持**：可以添加多个应用的 Token，方便切换
|
||
- **活跃 Token**：选择当前要使用的 Token
|
||
- **KV 空间信息**：显示当前活跃应用的 KV 数据统计
|
||
- **Token 可见性**：支持显示/隐藏 Token 值
|
||
- **复制功能**：一键复制设备码和 Token
|
||
|
||
### 2. 数据管理（Dashboard）
|
||
|
||
- **浏览数据**：查看当前应用的所有 KV 键值对
|
||
- **搜索**：通过键名快速查找
|
||
- **排序**：按键名、创建时间或更新时间排序
|
||
- **创建**：添加新的键值对（JSON 格式）
|
||
- **编辑**：修改现有键值对的内容
|
||
- **查看详情**：查看完整的键值对信息和元数据
|
||
- **删除**：删除不需要的键值对
|
||
- **分页**：支持大量数据的分页浏览
|
||
|
||
### 设备码说明
|
||
|
||
**什么是设备码？**
|
||
- 设备码是应用授权的密钥，相当于一个唯一标识符
|
||
- 格式：`XXXX-XXXX-XXXX-XXXX`（4段，每段4个字母/数字）
|
||
- **本地生成**：无需服务器接口，在浏览器端随机生成
|
||
- **用途**：用于标识和授权特定的应用或设备访问 KV 服务
|
||
|
||
**工作流程：**
|
||
1. 用户添加应用 Token 时，系统自动生成设备码
|
||
2. 设备码与 Token 绑定存储在本地
|
||
3. 应用可以使用设备码作为标识符进行授权验证
|
||
|
||
## API 端点
|
||
|
||
应用与以下 API 端点交互：
|
||
|
||
### KV 存储
|
||
- `GET /kv` - 获取键值对列表
|
||
- `GET /kv/_keys` - 获取键名列表
|
||
- `GET /kv/:key` - 获取指定键的值
|
||
- `GET /kv/:key/metadata` - 获取键的元数据
|
||
- `POST /kv/:key` - 创建或更新键值对
|
||
- `DELETE /kv/:key` - 删除键值对
|
||
- `POST /kv/_batchimport` - 批量导入
|
||
|
||
## 数据存储
|
||
|
||
应用使用 LocalStorage 存储以下数据：
|
||
|
||
- `kv_tokens` - Token 列表数据
|
||
```json
|
||
[
|
||
{
|
||
"id": "1234567890",
|
||
"token": "your-token-here",
|
||
"appName": "我的应用",
|
||
"deviceCode": "ABCD-1234-EFGH-5678",
|
||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||
"lastUsed": "2025-01-01T00:00:00.000Z"
|
||
}
|
||
]
|
||
```
|
||
- `kv_active_token` - 当前活跃的 Token ID
|
||
|
||
## 约定式路由
|
||
|
||
本项目使用 `unplugin-vue-router` 实现约定式路由，无需手动配置路由：
|
||
|
||
- `src/pages/index.vue` → `/` (Token 管理页面)
|
||
- `src/pages/dashboard.vue` → `/dashboard` (数据管理页面)
|
||
|
||
### 路由元信息
|
||
|
||
在页面组件中使用 `defineOptions` 设置路由元信息：
|
||
|
||
```vue
|
||
<script setup>
|
||
defineOptions({
|
||
meta: {
|
||
requiresAuth: true
|
||
}
|
||
})
|
||
</script>
|
||
```
|
||
|
||
### 导航守卫
|
||
|
||
路由守卫在 `src/main.js` 中配置，自动处理授权检查：
|
||
|
||
```javascript
|
||
router.beforeEach((to, _from, next) => {
|
||
const requiresAuth = to.meta?.requiresAuth
|
||
const activeToken = tokenStore.getActiveToken()
|
||
|
||
if (requiresAuth && !activeToken) {
|
||
next({ path: '/' })
|
||
} else {
|
||
next()
|
||
}
|
||
})
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 添加新页面
|
||
|
||
在 `src/pages/` 目录下创建新的 `.vue` 文件，路由会自动生成：
|
||
|
||
```
|
||
src/pages/
|
||
├── index.vue → /
|
||
├── dashboard.vue → /dashboard
|
||
└── settings.vue → /settings (自动添加)
|
||
```
|
||
|
||
### 添加新组件
|
||
|
||
使用 shadcn-vue CLI 添加组件：
|
||
|
||
```bash
|
||
pnpm dlx shadcn-vue@latest add [component-name]
|
||
```
|
||
|
||
## 部署
|
||
|
||
### Vercel / Netlify
|
||
|
||
这些平台会自动检测 Vite 项目并进行构建。只需连接 Git 仓库即可。
|
||
|
||
### 传统服务器
|
||
|
||
构建后将 `dist` 目录部署到您的 Web 服务器，确保配置 SPA 回退规则：
|
||
|
||
**Nginx 示例**：
|
||
```nginx
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
### 首次使用
|
||
|
||
1. 访问首页
|
||
2. 点击"添加应用"
|
||
3. 输入应用名称（可选）和访问 Token
|
||
4. 系统自动生成设备码并保存
|
||
5. 点击"管理数据"进入数据管理页面
|
||
|
||
### 切换应用
|
||
|
||
1. 在首页的应用列表中
|
||
2. 点击要切换的应用行的"选择"按钮
|
||
3. 该应用变为"活跃"状态
|
||
4. KV 空间信息自动更新
|
||
5. 点击"管理数据"查看该应用的数据
|
||
|
||
### 管理数据
|
||
|
||
1. 在数据管理页面可以进行 CRUD 操作
|
||
2. 使用搜索框快速查找键名
|
||
3. 使用排序和分页功能浏览大量数据
|
||
4. 点击左上角的"主页"图标返回 Token 管理页面
|
||
|
||
## 安全建议
|
||
|
||
1. 始终使用 HTTPS 部署生产环境
|
||
2. 定期更换访问 Token
|
||
3. 不要在前端代码中硬编码敏感信息
|
||
4. 使用环境变量管理配置
|
||
5. 实施适当的 CORS 策略
|
||
6. LocalStorage 数据在浏览器端存储，注意隐私保护
|
||
|
||
## 技术亮点
|
||
|
||
- ✅ **纯 JavaScript**：无 TypeScript 依赖，更简单轻量
|
||
- ✅ **约定式路由**：基于文件系统，自动生成路由
|
||
- ✅ **本地设备码**：客户端生成，无需服务器接口
|
||
- ✅ **多 Token 管理**：支持多应用切换
|
||
- ✅ **现代化工具链**：Vite + Vue 3 组合式 API
|
||
- ✅ **完整的 UI 组件**：44 个 shadcn-vue 组件
|
||
- ✅ **响应式设计**：Tailwind CSS v4
|
||
- ✅ **轻量级状态**：LocalStorage 管理，无需额外状态库
|
||
|
||
## 许可证
|
||
|
||
MIT
|