mirror of
https://github.com/ZeroCatDev/ClassworksKV.git
synced 2025-10-22 02:03:11 +00:00
7.4 KiB
7.4 KiB
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. 安装依赖
pnpm install
2. 配置环境变量
复制 .env.example
到 .env
并填写配置:
cp .env.example .env
编辑 .env
文件:
VITE_API_BASE_URL=http://localhost:3000
VITE_SITE_KEY=your-site-key-here
3. 启动开发服务器
pnpm dev
应用将在 http://localhost:5173 运行
4. 构建生产版本
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 服务
工作流程:
- 用户添加应用 Token 时,系统自动生成设备码
- 设备码与 Token 绑定存储在本地
- 应用可以使用设备码作为标识符进行授权验证
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 列表数据[ { "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
设置路由元信息:
<script setup>
defineOptions({
meta: {
requiresAuth: true
}
})
</script>
导航守卫
路由守卫在 src/main.js
中配置,自动处理授权检查:
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 添加组件:
pnpm dlx shadcn-vue@latest add [component-name]
部署
Vercel / Netlify
这些平台会自动检测 Vite 项目并进行构建。只需连接 Git 仓库即可。
传统服务器
构建后将 dist
目录部署到您的 Web 服务器,确保配置 SPA 回退规则:
Nginx 示例:
location / {
try_files $uri $uri/ /index.html;
}
使用流程
首次使用
- 访问首页
- 点击"添加应用"
- 输入应用名称(可选)和访问 Token
- 系统自动生成设备码并保存
- 点击"管理数据"进入数据管理页面
切换应用
- 在首页的应用列表中
- 点击要切换的应用行的"选择"按钮
- 该应用变为"活跃"状态
- KV 空间信息自动更新
- 点击"管理数据"查看该应用的数据
管理数据
- 在数据管理页面可以进行 CRUD 操作
- 使用搜索框快速查找键名
- 使用排序和分页功能浏览大量数据
- 点击左上角的"主页"图标返回 Token 管理页面
安全建议
- 始终使用 HTTPS 部署生产环境
- 定期更换访问 Token
- 不要在前端代码中硬编码敏感信息
- 使用环境变量管理配置
- 实施适当的 CORS 策略
- LocalStorage 数据在浏览器端存储,注意隐私保护
技术亮点
- ✅ 纯 JavaScript:无 TypeScript 依赖,更简单轻量
- ✅ 约定式路由:基于文件系统,自动生成路由
- ✅ 本地设备码:客户端生成,无需服务器接口
- ✅ 多 Token 管理:支持多应用切换
- ✅ 现代化工具链:Vite + Vue 3 组合式 API
- ✅ 完整的 UI 组件:44 个 shadcn-vue 组件
- ✅ 响应式设计:Tailwind CSS v4
- ✅ 轻量级状态:LocalStorage 管理,无需额外状态库
许可证
MIT