⏺ 木雷短网址 v2.10.0 版本更新说明
版本概览
本次更新涵盖 v2.7.0 至 v2.10.0 的所有变更，共 4 个版本，主要包含登录安全加固、API 鉴权方式升级、短码安全性增强和删除操作优化四大核心改进。
一、登录安全加固
登录速率限制
新增速率限制服务，有效防止暴力破解攻击：
- 双层防护机制
- IP 级别限制：15 分钟内最多 10 次尝试，超出锁定 15 分钟
- 用户名级别限制：15 分钟内最多 5 次尝试，超出锁定 15 分钟
- 优雅降级设计
- 当缓存服务不可用时自动跳过速率限制检查
- 确保服务可用性优先
- 详细错误响应
- 返回限制类型（IP / 用户名）
- 返回剩余尝试次数
- 返回锁定剩余时间
代码结构优化
- 新增独立的 AuthService，从 UserService 中分离认证逻辑
- 新增 AuthController 处理认证相关请求
- 新增 RateLimiterService 速率限制服务（211 行）
二、API 鉴权方式升级
HMAC-SHA256 签名认证
新增更安全的 API 签名认证方式：
- 签名认证流程
| 请求头 | 说明 |
|---|---|
| X-App-Id | 应用 ID |
| X-Signature | HMAC-SHA256 签名 |
| X-Timestamp | 请求时间戳 |
| X-Nonce | 随机数（防重放攻击） |
- 双模式认证 a. 优先检测签名认证头（X-App-Id 等） b. 回退到 Bearer Token 认证 c. 无认证信息时返回 401
- Token 模型扩展
- 新增 token_type 字段：bearer 或 signature
- 签名认证使用 app_id + app_secret
- Bearer Token 使用传统 token 字符串
完整 API 文档
- API_BEARER_AUTH.md - Bearer Token 认证文档
- API_SIGNATURE_AUTH.md - 签名认证文档
- API_REFERENCE.md - 完整 API 参考文档
新增错误码
| 错误码 | 说明 |
|---|---|
| 40101 | 缺少认证信息 |
| 40102 | 时间戳无效 |
| 40103 | 签名验证失败 |
| 40104 | 无效的 AppID |
| 40105 | Token 已禁用 |
| 40106 | 用户已被禁用 |
三、短码安全性增强
XOR 混淆功能
新增 XOR 混淆功能，防止短码被顺序推测：
- Domain 配置扩展
- enable_xor_obfuscation: 是否启用 XOR 混淆
- xor_secret: XOR 密钥（后端自动生成）
- xor_rot: 旋转位数（后端自动生成）
- 混淆算法
- 使用 XOR + 位旋转混淆 ID
- 保持 base62 编码长度与原 ID 一致
- 密钥和旋转位数由服务层随机生成
域名默认开始数字配置
- Domain 新增 default_start_number 字段
- 支持设置短码 ID 生成的起始值
- 本地和 Redis ID 生成器支持初始化
- 域名创建后禁止修改，确保短码连续性
四、删除操作优化
硬删除机制
- 短网址和域名删除改为硬删除（彻底删除数据）
- 删除前必须先禁用 is_active 状态
- 未禁用就删除返回 403 状态码
新增接口
- PUT /api/v1/short-links/:id/status - 更新短网址状态
五、代码统计
| 版本 | 主要内容 |
|---|---|
| v2.8.0 | 登录速率限制、认证服务重构 |
| v2.9.0 | API 签名认证、双模式认证 |
| v2.10.0 | XOR 混淆、硬删除、默认开始数字 |
| 合计 | 四大核心功能更新 |
六、升级注意事项
1. 数据库迁移
- 新增字段需要执行数据库迁移
- user_token 表新增 token_type、app_id、app_secret 字段
- domain 表新增 enable_xor_obfuscation、xor_secret、xor_rot、default_start_number 字段
2. 兼容性
- Bearer Token 认证完全兼容，无需修改
- 签名认证为新增功能，可按需启用
3. 配置变更
- 建议生产环境启用登录速率限制
- 建议生产环境启用 Redis 缓存以获得最佳性能
发布日期： 2025年12月25日 代码仓库： cnb.cool/mliev/open/dwz-server