← Back to home@LLLike27

One-Time-Link

agent

Stars
1
Language
PHP
Created
Dec 27, 2025
Updated
Jan 3, 2026
Auth
GitHub repo

Introduction

一次性链接功能设计文档

📋 项目概述

一次性链接（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. 批量管理

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

📊 核心参数配置

参数名称类型默认值说明
tokenstring-唯一标识符，UUID格式
max_visitsint1最大访问次数
expire_timeint86400过期时间（秒），0表示永不过期
bind_ipboolfalse是否绑定IP
content_typestring-业务类型：email/password/secret/file等
content_datatext-业务数据（加密存储）
notify_on_visitboolfalse访问时是否通知

🚀 实施建议

1. 安全优先

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

2. 用户体验

  • 提供清晰的错误提示
  • 链接失效后给出重新申请的入口
  • 移动端适配良好

3. 性能优化

  • Token 验证使用缓存（Redis）
  • 定期清理过期 Token 数据
  • 数据库索引优化

4. 监控与审计

  • 记录所有 Token 生成和访问日志
  • 异常访问告警
  • 定期审计安全日志

📝 相关文档

🔄 版本历史

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

👥 贡献指南

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

📄 许可证

本项目采用 MIT 许可证。