LLLike27/One-Time-Link

一次性链接功能设计文档

📋 项目概述

一次性链接（One-Time Link）是一种安全的链接分享机制，链接在被访问指定次数后自动失效，常用于敏感信息分享、身份验证、临时授权等场景。

技术栈
- 前端: Vue 3 + TypeScript + Vite + Ant Design Vue
- 后端: ThinkPHP 6
- 数据库: MySQL 5.7+

🎯 核心功能

1. 主要用途

1.1 安全分享
- 分享密码、API密钥等敏感内容
- 阅读后链接自动失效
- 防止信息泄露和传播

1.2 邮箱验证
- 用户注册时确认邮箱地址的有效性
- 一次性验证链接，防止重复使用
- 可设置过期时间

1.3 密码重置
- 发送重置密码的临时链接
- 使用后立即失效，防止被他人利用
- 时效性保护

1.4 免密登录（魔法链接）
- 无需输入密码，点击即可登录
- 一次性 Token 验证
- 提升用户体验

1.5 临时访问授权
- 授权用户一次性访问某个受限资源
- 文件下载、内容查看等场景
- 可控的访问权限管理

1.6 二维码扫码验证
- PC端登录时的移动端扫码确认
- 设备授权验证
- 安全的跨设备认证

⚙️ 工作原理

流程图

┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
│ 生成链接 │ ───> │ 发送用户 │ ───> │ 用户访问 │ ───> │ Token验证│
└─────────┘      └─────────┘      └─────────┘      └─────────┘
│
▼
┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
│ 访问拒绝 │ <─── │ Token失效│ <─── │ 销毁Token│ <─── │ 执行操作 │
└─────────┘      └─────────┘      └─────────┘      └─────────┘

详细步骤

1. 生成阶段
- 服务器生成唯一的 Token（UUID/随机字符串）
- 将 Token 与业务数据关联存储到数据库
- 设置访问次数限制（默认1次）
- 设置过期时间（可选）

2. 发送阶段
- 构造完整的访问链接：https://domain.com/verify/{token}
- 通过邮件、短信或其他方式发送给用户

3. 访问与验证
- 用户点击链接，服务器接收请求
- 提取 URL 中的 Token 参数
- 验证 Token 的有效性（存在性、过期时间、访问次数）

4. 执行与销毁
- Token 有效：执行业务逻辑（展示内容、验证邮箱、重置密码等）
- 访问次数 -1，若达到限制则标记为已使用
- 记录访问日志（IP、时间、User-Agent等）

5. 失效处理
- 再次访问时检测到 Token 已失效
- 返回友好的错误提示
- 引导用户重新申请（如需要）

🔐 安全特性

1. Token 生成策略
- 使用 UUID v4 或加密安全的随机字符串
- Token 长度建议 32-64 字符
- 不可预测性，防止暴力破解

2. 访问控制
- 次数限制: 可配置访问次数（默认1次）
- 时间限制: 可设置过期时间（如15分钟、24小时）
- IP绑定: 可选，绑定首次访问的IP地址
- 设备指纹: 可选，验证设备一致性

3. 防护机制
- 防重放攻击: Token 使用后立即失效
- 防暴力破解: Token 长度足够长且随机
- 访问日志: 记录所有访问尝试，便于审计
- 速率限制: 限制同一 IP 的请求频率

4. 数据安全
- 敏感内容加密存储
- 传输使用 HTTPS
- Token 不包含业务敏感信息

📦 常见应用形式

1. 魔法链接（Magic Links）
https://example.com/auth/magic?token=abc123...
用于无密码登录，点击即完成认证。

2. 邮箱验证链接
https://example.com/verify/email?token=xyz789...
用户注册后验证邮箱地址。

3. 密码重置链接
https://example.com/reset-password?token=def456...
用户忘记密码时的重置链接。

4. 安全分享服务
https://example.com/secret/view?token=ghi012...
类似 Onetime Secret，查看密文后自动销毁。

5. 临时短链接
https://example.com/s/abc123
通过短链接服务创建，可限制访问次数和时效。

6. 文件下载链接
https://example.com/download?token=jkl345...
临时文件下载授权，下载后失效。

🎨 功能扩展

1. 可配置访问次数
- 默认1次，可设置为多次（如3次、5次）
- 适用于需要多次查看但有限制的场景

2. 访问统计
- 记录每次访问的详细信息
- IP地址、时间、User-Agent、地理位置
- 生成访问报告

3. 通知机制
- Token 被访问时发送通知（邮件/短信/推送）
- Token 过期前提醒
- 异常访问告警

4. 链接预览
- 访问前展示链接基本信息（非敏感部分）
- 确认页面，防止误点击
- 显示剩余访问次数和过期时间

5. 二维码支持
- 生成 Token 对应的二维码
- 方便移动端扫码访问
- 适用于跨设备场景

6. 批量管理
- 批量生成一次性链接
- 批量撤销/延期
- 链接管理后台

📊 核心参数配置

| 参数名称 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| token | string | - | 唯一标识符，UUID格式 |
| max_visits | int | 1 | 最大访问次数 |
| expire_time | int | 86400 | 过期时间（秒），0表示永不过期 |
| bind_ip | bool | false | 是否绑定IP |
| content_type | string | - | 业务类型：email/password/secret/file等 |
| content_data | text | - | 业务数据（加密存储） |
| notify_on_visit | bool | false | 访问时是否通知 |

🚀 实施建议

1. 安全优先
- 所有敏感操作使用一次性链接
- 合理设置过期时间，避免时间窗口过长
- 重要操作启用多因素验证

2. 用户体验
- 提供清晰的错误提示
- 链接失效后给出重新申请的入口
- 移动端适配良好

3. 性能优化
- Token 验证使用缓存（Redis）
- 定期清理过期 Token 数据
- 数据库索引优化

4. 监控与审计
- 记录所有 Token 生成和访问日志
- 异常访问告警
- 定期审计安全日志

📝 相关文档

- 前端开发计划 - Vue3 前端实现计划
- 后端开发计划 - ThinkPHP6 后端实现计划
- 数据库设计 - MySQL 数据库表结构设计

🔄 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2025-12-25 | 初始版本，完成核心功能设计 |

👥 贡献指南

欢迎提出改进建议和功能需求，请通过 Issue 或 Pull Request 参与贡献。

📄 许可证

本项目采用 MIT 许可证。