ClassworksKV/kv-admin

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 服务

工作流程：

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 列表数据

  [
    {
      "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;
}

使用流程

首次使用

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