# isolo-authenticator

**Repository Path**: MengNingBin/isolo-authenticator

## Basic Information

- **Project Name**: isolo-authenticator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iSOLO Authenticator - 情报令

> 赛博朋克风格的多平台 TOTP 双因素认证器

**情报令** 是一款赛博朋克主题的 TOTP（基于时间的一次性密码）双因素认证应用，配有 Go 后端服务。提供沉浸式特工操作体验，融合未来科技美学与实用安全功能。

![Platform](https://img.shields.io/badge/platform-Android%20%7C%20iOS%20%7C%20Web%20%7C%20Desktop%20%7C%20HarmonyOS-blue)
![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go)
![Flutter](https://img.shields.io/badge/Flutter-3.x-02569B?logo=flutter)
![Vue](https://img.shields.io/badge/Vue.js-3.x-4FC08D?logo=vue.js)
![License](https://img.shields.io/badge/license-MIT-green)

---

## 📋 目录

- [系统架构](#-系统架构)
- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [项目结构](#-项目结构)
- [快速开始](#-快速开始)
- [API 文档](#-api-文档)
- [配置说明](#-配置说明)
- [安全特性](#-安全特性)
- [主题系统](#-主题系统)
- [开发说明](#-开发说明)
- [许可证](#-许可证)

---

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    客户端层 (Client)                      │
│  ┌─────────┐  ┌──────────┐  ┌────────────┐             │
│  │ Flutter  │  │  Vue 3   │  │ HarmonyOS  │             │
│  │ (Mobile  │  │   (Web)  │  │  (ArkTS)   │             │
│  │ Desktop) │  │          │  │            │             │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘             │
│       │             │              │                    │
└───────┼─────────────┼──────────────┼────────────────────┘
        │             │              │
        │     HTTP API (REST)        │
        └─────────────┼──────────────┘
                      │
┌─────────────────────┼──────────────────────────────────┐
│              后端层 (Backend)                           │
│  ┌──────────────────────────────────────────────────┐  │
│  │              Gin Web Framework                   │  │
│  │  ┌─────────┐ ┌──────────┐ ┌──────────────────┐   │  │
│  │  │ Handler │ │ Service  │ │   Middleware      │   │  │
│  │  │  (路由)  │ │  (业务)   │ │  (认证/CORS/权限) │   │  │
│  │  └────┬────┘ └────┬─────┘ └────────┬─────────┘   │  │
│  └───────┼───────────┼────────────────┼──────────────┘  │
│          │           │                │                  │
│  ┌───────┴───────────┴────────────────┴──────────────┐  │
│  │                    Ent ORM                        │  │
│  │        (PostgreSQL + 自动迁移 / Redis 缓存)        │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │              Casbin (RBAC 权限控制)                │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 数据流

```
用户操作 → 客户端(GUI) → HTTP/REST → Gin Router → Middleware(认证)
    → Handler(参数校验) → Service(业务逻辑) → Ent ORM → PostgreSQL
                                                        → Redis(会话/缓存)
    → JSON 响应 → 客户端渲染
```

---

## 🌟 功能特性

### 核心功能
- ✅ **TOTP 验证码生成** — 基于 RFC 6238 标准，Base32 密钥 + HMAC-SHA1，30 秒滚动刷新
- ✅ **二维码扫描** — 快速添加令牌，支持 HUD 风格扫描界面
- ✅ **多令牌管理** — 搜索过滤、分类展示、详情查看
- ✅ **生物识别锁** — 指纹/面部识别保护敏感数据
- ✅ **数据加密存储** — 使用安全存储方案保护密钥

### 后端服务
- ✅ **用户注册/登录** — JWT 令牌认证（Redis 会话管理）
- ✅ **令牌云端同步** — 跨设备同步 2FA 令牌
- ✅ **验证记录** — 完整的验证历史追溯
- ✅ **成就系统** — 特工等级、XP 经验值、成就徽章
- ✅ **权限控制** — Casbin RBAC 精细权限管理
- ✅ **密码找回** — SMTP 邮件验证码发送

### 特色系统
- 🎨 **多主题切换**
  - `NEON HUD` — 暗色霓虹赛博朋克（默认）
  - `METAL GEAR` — 暗色工业机械风
  - `PASTEL DREAM` — 亮色粉彩可爱风
- 🌍 **中英双语本地化** — 完整的简体中文与英文界面支持
- 🎮 **特工档案系统** — 代号 / 等级 / 权限管理、XP 经验值 & 连续签到、成就徽章收集
- ⚙️ **个性化设置** — 自动锁定与安全策略、通知与剪贴板自动清除、背景网格自定义

---

## 🛠️ 技术栈

### 后端 (Go)

| 组件 | 技术 | 用途 |
|------|------|------|
| Web 框架 | [Gin](https://github.com/gin-gonic/gin) | HTTP 路由与中间件 |
| ORM | [Ent](https://entgo.io/) | PostgreSQL 数据库操作与自动迁移 |
| 缓存 | [Redis](https://github.com/redis/go-redis) | 会话管理与缓存 |
| 权限 | [Casbin](https://casbin.org/) | RBAC 权限控制 |
| 邮件 | [email](https://github.com/jordan-wright/email) | SMTP 密码找回 |
| ID 生成 | [ULID](https://github.com/oklog/ulid) | 分布式唯一 ID |

### Flutter 前端

| 组件 | 技术 | 用途 |
|------|------|------|
| 框架 | Flutter 3.x (Material 3) | 跨平台 UI |
| 状态管理 | Riverpod | 响应式状态管理 |
| 路由 | GoRouter | 声明式导航 |
| 扫码 | mobile_scanner | 二维码扫描 |
| 安全存储 | flutter_secure_storage | 密钥加密存储 |
| 生物识别 | local_auth | 指纹/面部识别 |
| 国际化 | Flutter i18n | 中英双语 |
| 加密 | crypto (HMAC-SHA1) | TOTP 算法 |

### Web 前端

| 组件 | 技术 |
|------|------|
| 框架 | Vue 3 (Composition API) |
| 语言 | TypeScript |
| 构建 | Vite |

### HarmonyOS 前端

| 组件 | 技术 |
|------|------|
| 框架 | ArkTS + ArkUI |
| SDK | HarmonyOS SDK |

---

## 📂 项目结构

```
isolo-authentictor/
│
├── cmd/server/                  # Go 后端入口
│   └── main.go                  # 服务启动、数据库迁移、种子数据
│
├── internal/                    # 后端内部包
│   ├── config/                  # 配置加载
│   │   └── config.go
│   ├── handler/                 # HTTP 处理器（路由 => 参数校验 => 响应）
│   │   ├── auth.go              #   注册 / 登录 / 密码找回
│   │   ├── token.go             #   令牌 CRUD
│   │   ├── otp.go               #   TOTP 验证码生成
│   │   ├── profile.go           #   用户档案
│   │   ├── settings.go          #   用户设置
│   │   ├── verification.go      #   验证记录
│   │   └── handler.go           #   Handler 聚合
│   ├── service/                 # 业务逻辑层
│   │   ├── auth.go              #   认证业务
│   │   ├── token.go             #   令牌业务
│   │   ├── otp.go               #   TOTP 业务
│   │   ├── profile.go           #   档案业务
│   │   ├── settings.go          #   设置业务
│   │   ├── verification.go      #   验证业务
│   │   └── email.go             #   邮件发送
│   ├── middleware/              # HTTP 中间件
│   │   ├── auth.go              #   JWT 认证
│   │   └── cors.go              #   跨域配置
│   └── router/                  # 路由注册
│       └── router.go
│
├── ent/                         # Ent ORM 生成代码
│   ├── user.go                  #   用户模型
│   ├── token.go                 #   令牌模型
│   ├── achievement.go           #   成就模型
│   ├── userachievement.go       #   用户-成就关联
│   ├── usersettings.go          #   用户设置模型
│   ├── verificationlog.go       #   验证日志模型
│   ├── passwordreset.go         #   密码重置模型
│   ├── client.go                #   ORM 客户端
│   └── ...
│
├── flutter/                     # Flutter 跨平台应用
│   ├── lib/
│   │   ├── main.dart            #   应用入口
│   │   ├── l10n/                #   国际化资源
│   │   ├── models/              #   数据模型
│   │   ├── pages/               #   页面组件
│   │   │   ├── token_list_page.dart
│   │   │   ├── token_detail_page.dart
│   │   │   ├── scan_page.dart
│   │   │   ├── settings_page.dart
│   │   │   ├── lock_screen_page.dart
│   │   │   └── profile_page.dart
│   │   ├── providers/           #   Riverpod 状态管理
│   │   ├── router/              #   GoRouter 导航
│   │   ├── services/            #   业务服务
│   │   ├── theme/               #   主题系统
│   │   ├── utils/               #   工具函数
│   │   └── widgets/             #   通用组件
│   ├── android/                 #   Android 原生
│   ├── ios/                     #   iOS 原生
│   ├── web/                     #   Web 构建配置
│   ├── linux/                   #   Linux 桌面
│   ├── macos/                   #   macOS 桌面
│   ├── windows/                 #   Windows 桌面
│   └── pubspec.yaml             #   Flutter 依赖
│
├── web/                         # Vue 3 Web 独立版本
│   ├── src/
│   │   ├── components/
│   │   ├── composables/
│   │   ├── router/
│   │   ├── types/
│   │   ├── views/
│   │   └── App.vue
│   └── package.json
│
├── harmony/                     # HarmonyOS 原生版本
│   ├── common/                  #   公共模块
│   ├── features/                #   特性模块
│   │   ├── adaptiveLayout/
│   │   └── responsiveLayout/
│   ├── products/default/        #   产品配置
│   └── AppScope/                #   应用配置
│
├── design/                      # UI 设计稿与原型
│   └── pages/                   #   HTML 原型页面
│
├── config.yaml                  # 后端配置文件
├── casbin_model.conf            # Casbin 权限模型
├── casbin_policy.csv            # Casbin 权限策略
├── go.mod                       # Go 模块定义
├── go.sum                       # Go 依赖锁
├── .gitignore                   # Git 忽略规则
└── README.md                    # 本文档
```

---

## 🚀 快速开始

### 环境要求

| 组件 | 版本要求 |
|------|----------|
| [Go](https://go.dev/dl/) | >= 1.26 |
| [PostgreSQL](https://www.postgresql.org/download/) | >= 14 |
| [Redis](https://redis.io/download/) | >= 6.x |
| [Flutter SDK](https://docs.flutter.dev/get-started/install) | >= 3.12 |
| [Node.js](https://nodejs.org/) | >= 18 (Web 前端) |

### 1️⃣ 启动后端服务

```bash
# 克隆项目
git clone https://gitee.com/MengNingBin/isolo-authenticator.git
cd isolo-authenticator

# 配置数据库连接
# 编辑 config.yaml，修改 database.dsn 为你的 PostgreSQL 连接串

# 启动服务（自动完成数据库迁移和种子数据初始化）
go run cmd/server/main.go
```

后端服务默认启动在 `http://localhost:8080`。

### 2️⃣ 启动 Flutter 客户端

```bash
cd flutter

# 获取依赖
flutter pub get

# 运行应用（连接本地后端需修改 API 地址）
flutter run

# 指定平台
flutter run -d chrome    # Web 调试
flutter run -d windows   # Windows 桌面
flutter run -d android   # Android
flutter run -d ios       # iOS

# 构建发布版本
flutter build apk --release          # Android
flutter build ios --release          # iOS
flutter build web --release          # Web
flutter build windows --release      # Windows
```

### 3️⃣ 启动 Web 前端

```bash
cd web

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build
```

### 4️⃣ HarmonyOS 版本

1. 使用 DevEco Studio 打开 `harmony/` 目录
2. 同步依赖并连接设备/模拟器
3. 点击运行按钮部署应用

---

## 📡 API 文档

### 认证接口（无需令牌）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/auth/register` | 用户注册 |
| POST | `/api/v1/auth/login` | 用户登录（返回 JWT） |
| POST | `/api/v1/auth/forgot-password` | 发送密码找回邮件 |
| POST | `/api/v1/auth/reset-password` | 重置密码 |

### 需认证接口（需在 Header 携带 `Authorization: Bearer <token>`）

#### 用户档案

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/profile` | 获取当前用户档案 |
| PUT | `/api/v1/profile` | 更新用户档案 |
| GET | `/api/v1/profile/stats` | 获取用户统计信息 |

#### 令牌管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tokens` | 获取令牌列表 |
| POST | `/api/v1/tokens` | 创建新令牌 |
| POST | `/api/v1/tokens/import` | 批量导入令牌 |
| GET | `/api/v1/tokens/:id` | 获取令牌详情 |
| PUT | `/api/v1/tokens/:id` | 更新令牌 |
| DELETE | `/api/v1/tokens/:id` | 删除令牌 |

#### TOTP 验证

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/otp/code` | 获取 TOTP 验证码 |
| GET | `/api/v1/otp/remaining` | 获取剩余有效时间 |

#### 成就系统

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/achievements` | 获取所有成就 |
| GET | `/api/v1/achievements/user` | 获取用户已解锁成就 |
| POST | `/api/v1/achievements/:id/unlock` | 解锁成就 |

#### 验证记录

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/verifications` | 获取验证历史 |
| POST | `/api/v1/verifications` | 创建验证记录 |

#### 用户设置

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/settings` | 获取用户设置 |
| PUT | `/api/v1/settings` | 更新用户设置 |

---

## ⚙️ 配置说明

后端配置通过 `config.yaml` 文件管理：

```yaml
server:
  port: 8080                  # 服务端口

database:
  dsn: "host=localhost port=5432 user=postgres password=isolo dbname=isolo_authenticator sslmode=disable"

redis:
  addr: "localhost:6379"      # Redis 地址
  password: ""                # Redis 密码
  db: 0                       # Redis 数据库编号

smtp:
  host: "smtp.qq.com"         # SMTP 服务器
  port: 587                   # SMTP 端口
  username: "your@email.com"  # 邮箱账号
  password: "your_password"   # SMTP 授权码
  from: "your@email.com"     # 发件人地址

casbin:
  model_path: "./casbin_model.conf"   # 权限模型路径
  policy_path: "./casbin_policy.csv"  # 权限策略路径
```

> **注意**：`config.yaml` 已加入 `.gitignore`，请复制模板并根据环境修改。

---

## 🔐 安全特性

- ✅ **密钥加密存储** — flutter_secure_storage / 服务端 PostgreSQL 加密
- ✅ **JWT 令牌认证** — 基于 Redis 的会话管理
- ✅ **生物识别认证** — 指纹/面部识别（Flutter 客户端）
- ✅ **Casbin 权限控制** — RBAC 模型精细管理
- ✅ **自动锁定机制** — 应用进入后台即锁定
- ✅ **剪贴板自动清理** — 防止验证码泄露
- ✅ **密码找回** — 邮箱验证码 + 安全重置
- ✅ **无网络请求** — 核心 OTP 计算在本地完成
- ✅ **符合 TOTP RFC 6238 标准**

---

## 🎨 主题系统

| 主题 | 主色 | 强调色 | 风格特点 |
|------|------|--------|----------|
| **NEON HUD** | `#00F0FF` 青色 | `#FF2D95` 品红 | 赛博朋克霓虹灯效 |
| **METAL GEAR** | `#F0A030` 琥珀 | `#4ECDC4` 青绿 | 工业机械硬朗风 |
| **PASTEL DREAM** | `#FF6B9D` 粉红 | `#A78BFA` 淡紫 | 柔和粉彩可爱风 |

---

## 🛠️ 开发说明

### 代码规范

- **Go**: 遵循 [Go 官方编码规范](https://go.dev/doc/effective_go)，使用 `gofmt` 格式化
- **Flutter**: 遵循 [Effective Dart](https://dart.dev/guides/language/effective-dart) 风格指南
- **Web**: 遵循 Vue 3 官方推荐组合式 API 规范
- **HarmonyOS**: 遵循 ArkTS 编码规范

### 数据库迁移

项目使用 Ent ORM 的自动迁移功能，启动时自动执行：

```go
// 在 main.go 中
if err := db.Schema.Create(ctx); err != nil {
    log.Fatalf("数据库迁移失败: %v", err)
}
```

如需手动管理迁移，可使用 Ent 的 `atlas` 工具：

```bash
go run -mod=mod entgo.io/ent/cmd/ent new <SchemaName>
```

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: 添加某个特性'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 待办事项

- [ ] Flutter 客户端对接后端 API
- [ ] Web 版本对接后端 API
- [ ] 云端同步备份（可选）
- [ ] 导出/导入令牌功能
- [ ] 小组件支持（桌面快捷查看）
- [ ] 更多主题定制选项
- [ ] 单元测试覆盖
- [ ] CI/CD 流水线

---

## 📄 许可证

本项目仅供学习交流使用。采用 **MIT 许可证** 开源。

---

## 🙏 致谢

- 灵感来源于赛博朋克美学与特工文化
- 感谢 Go、Flutter、Vue、HarmonyOS 社区的优质资源
- UI 设计参考多款科幻游戏界面元素

---

<div align="center">
  <strong>🔮 Made with 💜 for the Future 🔮</strong>
</div>