apps-key-guard

@apps-admin/key-guard

一个基于密钥验证的 React 访问控制组件，支持本地缓存和自动验证。

功能特性

• 基于密钥的访问控制
• 本地存储密钥，自动验证
• 支持密钥等级检查（排除 none 等级）
• 支持密钥过期检查
• 完全可自定义样式
• TypeScript 支持
• 悬浮窗显示用户信息（应用名称、密钥、等级、过期时间）
• 密钥显示/隐藏切换（小眼睛图标）
• 一键退出登录功能
• 自动安全防护（关闭面板时隐藏密钥）

安装

npm install @apps-admin/key-guard

或者

yarn add @apps-admin/key-guard

使用方法

基础用法

import { KeyGuard } from '@apps-admin/key-guard';

function App() {
  return (
    <KeyGuard appName="my-app" apiBaseUrl="http://localhost:8080">
      <div>
        <h1>受保护的内容</h1>
        <p>只有通过密钥验证的用户才能看到这里的内容</p>
      </div>
    </KeyGuard>
  );
}

高级用法

import { KeyGuard } from '@apps-admin/key-guard';

function App() {
  const handleValidated = (level: string) => {
    console.log('用户验证成功，等级:', level);
    // 可以根据等级做不同的处理
  };

  return (
    <KeyGuard
      appName="my-app"
      apiBaseUrl="https://api.example.com"
      title="请输入访问密钥"
      placeholder="输入您的密钥"
      buttonText="提交验证"
      onValidated={handleValidated}
      customStyle={{
        backgroundColor: '#f0f0f0',
      }}
    >
      <div>
        <h1>受保护的内容</h1>
        <p>只有通过密钥验证的用户才能看到这里的内容</p>
      </div>
    </KeyGuard>
  );
}

API 参数

参数	类型	必填	默认值	说明
appName	string	是	-	应用名称，用于标识应用
apiBaseUrl	string	否	http://localhost:8080	API 基础 URL
children	ReactNode	是	-	验证成功后要渲染的子组件
onValidated	(level: Level) => void	否	-	验证成功后的回调函数，返回密钥等级
customStyle	CSSProperties	否	-	自定义容器样式
title	string	否	访问验证	标题文本
placeholder	string	否	请输入访问密钥	输入框占位符
buttonText	string	否	验证	按钮文本
showFloatingButton	boolean	否	true	是否显示悬浮按钮

工作原理

• 组件首次加载时，会检查 localStorage 中是否存在该应用的密钥
• 如果存在，自动使用该密钥进行验证
• 验证成功且密钥等级不为 none 时，渲染子组件
• 验证失败时，显示密钥输入表单
• 用户输入密钥后，调用后端 API 进行验证
• 验证成功后，将密钥存储到 localStorage，并渲染子组件
• 验证成功后，右下角显示悬浮按钮，点击可查看密钥信息
• 用户可以通过悬浮窗中的"退出登录"按钮清除本地密钥

悬浮窗功能

验证成功后，页面右下角会显示一个悬浮按钮。点击按钮可以打开信息面板，显示：

• 应用名称: 当前访问的应用
• 密钥: 默认隐藏显示（用 • 符号遮蔽），点击小眼睛图标可切换显示/隐藏
• 等级: 密钥等级（游客/VIP/高级 VIP）
• 过期时间: 密钥的过期时间或"永久有效"
• 退出登录: 清除本地存储的密钥并返回验证页面

安全性：关闭面板时会自动重置密钥显示状态为隐藏，保护用户隐私。

可以通过 showFloatingButton={false} 禁用悬浮窗功能。

后端 API 要求

组件需要后端提供一个密钥验证接口：

POST /api/public/keys/verify

请求体：

{
  "app_name": "my-app",
  "key_value": "user-input-key"
}

响应格式：

{
  "code": 200,
  "message": "验证成功",
  "data": {
    "valid": true,
    "level": "vip",
    "expires_at": "2024-12-31T23:59:59Z",
    "message": "密钥有效"
  }
}

密钥等级

• none: 无权限（验证会失败）
• guest: 游客
• vip: VIP 用户
• super_vip: 高级 VIP 用户

开发

本地开发和测试

使用 Vite 开发服务器快速测试组件：

# 安装依赖
npm install

# 启动开发服务器（自动打开浏览器）
npm run dev

开发服务器会在 http://localhost:3000 启动，并提供多个示例供测试：

• 基础示例: 最简单的使用方式
• 自定义示例: 展示自定义配置选项
• 多应用示例: 展示如何处理多个应用

测试前准备：

• 确保后端服务已启动（默认 http://localhost:8080）
• 在数据库中创建测试应用：

  # 使用后端 API 创建应用
  POST /api/apps
  {
    "name": "my-app",
    "remark": "测试应用"
  }
  

• 为应用创建密钥（等级不能为 none）：

  POST /api/keys
  {
    "app_id": 1,
    "key_value": "test-key-123",
    "level": "vip"
  }
  

构建

# 构建用于发布的包（监听模式）
npm run build:watch

# 构建用于发布的包
npm run build

# 预览构建结果
npm run preview

License

MIT