TOTP 服务核心功能设计

自建 TOTP 服务核心功能设计

1. 基础功能

• TOTP 生成与验证

  • 实现标准 TOTP 算法（HMAC-SHA1，RFC 6238）
  • 支持 6/8 位数字，30秒时间窗口
  • 提供验证 API（返回布尔值或JSON）

• 密钥管理

  • 安全生成随机密钥（建议 160-bit）
  • 加密存储密钥（AES-256-GCM）
  • 密钥备份功能

2. 用户管理

• 用户注册/绑定

  • 提供用户注册接口
  • 生成二维码（otpauth:// 格式）
  • 支持手动输入密钥（Base32）

• 设备管理

  • 用户可绑定多个设备
  • 设备名称标注
  • 设备解绑功能

3. 管理功能

• Web 管理界面

  • 用户列表查看
  • 用户添加/删除
  • 使用统计（可选）

• 命令行工具

  • 用户批量导入（CSV）
  • 密钥导出（加密格式）
  • 服务状态检查

4. API 设计

POST /api/register    # 注册用户
POST /api/verify      # 验证OTP
GET  /api/qrcode/{id} # 获取二维码
POST /api/backup      # 获取恢复码
DELETE /api/user/{id} # 删除用户

5. 安全功能

• 防暴力破解

  • 验证失败次数限制
  • IP 访问频率限制
  • 失败延迟响应

• 数据安全

  • 密钥加盐加密存储
  • 传输使用 HTTPS
  • 定期密钥备份

6. 可选功能

• 恢复机制

  • 生成一次性恢复码（10个）
  • 恢复码使用后失效

• 时间同步

  • NTP 时间校验
  • 时间偏移容错（±1-2个窗口）

• 日志记录

  • 验证成功/失败日志
  • 管理操作日志

7. 部署考虑

• 数据库

  • SQLite（小型部署）
  • PostgreSQL/MySQL（生产环境）

• 配置

  • 配置文件或环境变量
  • 服务端口、加密密钥设置

技术栈建议

后端：Go（轻量高效）或 Python（开发快）
数据库：SQLite/PostgreSQL
前端：简单HTML页面或使用现有库
部署：Docker容器化

简单架构示例

┌─────────┐    ┌─────────┐    ┌─────────┐
│  客户端  │───▶│  Web服务 │───▶│  数据库 │
│  (浏览器)│    │         │    │         │
└─────────┘    └─────────┘    └─────────┘
                       │
                  ┌─────────┐
                  │   密钥   │
                  │   存储   │
                  └─────────┘

注意事项

1. 密钥安全：永远不要明文存储或传输密钥
2. 备份策略：定期备份加密的密钥库
3. 容错设计：考虑服务重启后的状态恢复
4. 监控：基础的健康检查端点

最小可用版本（MVP）

1. 用户注册（生成密钥）
2. 二维码展示
3. OTP 验证接口
4. 密钥加密存储
5. 简单的Web界面

后续扩展

• 支持多租户（多个独立团队）
• 审计日志
• 双因素认证集成
• 移动应用支持

这种设计平衡了安全性和开发成本，适合中小规模自用场景。

整理符合自己的功能需求

根据 DeepSeek 的介绍，整理自己的功能需求点；

• Vue 管理后台：采用 vue3 + ts + Element Plus
• Go 服务端提供后台 API，给后台 vue-admin 对接
• Go 服务端提供开放 API，给其他项目对接

该项目需要为内部和外部多个项目提供安全、可靠的二步验证解决方案。系统采用微服务架构，提供完整的 API 接口和管理后台，支持多项目、多用户的集中式 TOTP 密钥管理。

主要功能

🛠️ 管理后台 用户管理：系统管理员可以创建和管理后台用户 项目管理：为每个用户创建独立项目，每个项目生成唯一的 API Key 和 Secret 监控仪表盘：实时查看 API 调用统计和系统状态

🔐 API 服务

提供项目方调用的开放 API 服务

• TOTP 用户创建：为项目创建二步验证用户，以 Project ID + Email 作为唯一标识
• 二维码生成：自动生成 TOTP 绑定二维码链接，支持 Auth App（如 Google Authenticator）
• 验证码验证：实时验证用户提供的 TOTP 验证码
• 用户管理：支持 TOTP 用户的查询、更新和禁用

提供管理后台调用的 API 服务

• 后台用户登录：项目初始化后，超级管理员登录；
• 系统用户管理
• 用户及项目管理
• 项目用户的信息管理
• 审计日志查看

🔗 集成特性

多项目支持：每个项目拥有独立的 API 凭证和配置 必填邮箱：Email 作为用户标识的必要组成部分 灵活集成：项目方自行决定何时触发二步验证 标准化协议：基于 RFC 6238 TOTP 标准

下一步准备创建 AI Agent 开发提示文档，让 Aagent 完成整个项目开发。