kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
64fbaac7b5
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0008-datai-salesforce-auth-immediate-fixes.md
Kris 469c78cf29 feat: REQ-010-1 完成数据库表结构设计和创建，REQ-010-2 完成基础实体类和Mapper创建需求定义和架构决策 
REQ-010-1 完成内容：
- 创建 6 个数据库表设计（datai_meta_org_config、datai_meta_task、datai_meta_job_execution、datai_meta_component、datai_meta_deploy_history、datai_meta_job_log）
- 设计了合理的索引策略
- 对敏感字段进行了加密存储设计
- 表名前缀统一为 datai_meta_
- 所有表包含标准基础字段

REQ-010-2 完成内容：
- 补充用户故事和细化验收标准
- 创建架构决策记录（MyBatis Plus 注解 + XML 映射文件混合方案）
- 对比了 3 种备选方案
- 分析了决策对系统架构、开发流程、运维管理的影响
- 识别了技术风险、业务风险和实施风险
- 定义了回滚策略和验收标准

文档更新：
- 创建 0010-database-table-design.md 架构决策记录
- 创建 0011-entity-mapper-create.md 架构决策记录
- 创建 0020-database-table-design-create.md 变更记录
- 创建 20260117-database-table-design-create.md 会话记录
- 创建 20260117-database-table-design-create-retro.md 复盘报告
- 创建 011-database-table-design-create.md 提示词文档
- 更新 REQ-010-2.md 需求文档
- 更新 docs/index.md 和 CHANGELOG.md
2026-01-18 19:44:13 +08:00

9.3 KiB
Raw Blame History

name description
0008-datai-salesforce-auth-immediate-fixes datai-salesforce-auth 模块立即修复事项架构决策

架构决策记录: datai-salesforce-auth 模块立即修复事项

背景

经过对 datai-salesforce-auth 模块的详细扫描和分析，发现了以下影响系统编译、安全性和稳定性的问题：

  1. 语法错误: DataiSfLoginHistoryController 和 DataiSfLoginSessionController 中存在多余的右括号，导致代码无法编译
  2. 密码加密不安全: 使用对称加密存储密码，可以解密还原明文，存在数据泄露风险
  3. 敏感信息日志泄露: 日志中记录了 Session ID、用户名等敏感信息，存在日志泄露风险
  4. 缺少请求频率限制: 登录接口没有请求频率限制，可能遭受暴力破解攻击

这些问题需要立即修复，以确保系统的正常运行和数据安全。

决策

针对上述问题，我们做出以下架构决策：

决策 1: 语法错误修复

方案: 直接修复语法错误，移除多余的右括号 理由: 语法错误导致代码无法编译，必须立即修复 实施:

  • 在 DataiSfLoginHistoryController.java:82 移除多余的右括号
  • 在 DataiSfLoginSessionController.java:82 移除多余的右括号

决策 2: 密码加密方式调整

方案: 使用不可逆的哈希算法（BCrypt）替代对称加密 理由:

  • 对称加密可以解密还原明文，存在数据泄露风险
  • BCrypt 是业界标准的密码哈希算法，具有抗彩虹表攻击能力
  • BCrypt 自动处理盐值，提高安全性

实施:

  • 修改数据库表结构，将 password_encrypted 字段改为 password_hash
  • 修改 SalesforceLoginServiceImpl.java 中的密码存储逻辑
  • 使用 BCrypt.hashpw() 方法对密码进行哈希
  • 使用 BCrypt.checkpw() 方法验证密码

决策 3: 敏感信息日志脱敏

方案: 对敏感信息进行脱敏处理后再记录日志 理由:

  • 防止日志泄露导致敏感信息泄露
  • 满足安全合规要求（如 GDPR、等保三级）
  • 保留足够的调试信息（如 Session ID 前 8 位）

实施:

  • 创建脱敏工具类 SensitiveInfoMasker
  • 实现 maskSensitiveInfo(String info) 方法
  • 在 SalesforceLoginServiceImpl.java 中所有日志记录处使用脱敏方法
  • 脱敏规则：Session ID 只显示前 8 位，用户 ID 只显示前 4 位

决策 4: 请求频率限制

方案: 使用 Spring Security 或 Redis 实现请求频率限制 理由:

  • 防止暴力破解攻击
  • 保护系统资源不被滥用
  • 符合安全最佳实践

实施:

  • 使用 Spring Security 的 @RateLimiter 注解
  • 配置每分钟最多 5 次登录尝试
  • 超过限制时返回明确的错误信息（HTTP 429）
  • 使用 Redis 存储请求计数

备选方案

决策 1: 语法错误修复

无备选方案: 语法错误必须直接修复，无其他方案

决策 2: 密码加密方式调整

方案 A: BCrypt（已选择）

优点:

  • 业界标准，广泛使用
  • 自动处理盐值
  • 抗彩虹表攻击
  • 内置成本因子，可调整计算复杂度

缺点:

  • 计算较慢（但这是优点，防止暴力破解）
  • 需要修改数据库表结构

方案 B: PBKDF2

优点:

  • NIST 推荐算法
  • 可配置迭代次数
  • 安全性高

缺点:

  • 不如 BCrypt 常用
  • 需要手动处理盐值

方案 C: Argon2

优点:

  • 密码哈希竞赛冠军
  • 抗 GPU/ASIC 攻击
  • 可配置内存和计算成本

缺点:

  • 相对较新，兼容性可能有问题
  • 需要额外的依赖

选择理由: BCrypt 是业界标准，成熟稳定，安全性足够，易于实施。

决策 3: 敏感信息日志脱敏

方案 A: 自定义脱敏工具类（已选择）

优点:

  • 灵活，可定制脱敏规则
  • 不依赖外部库
  • 易于维护

缺点:

  • 需要自己实现

方案 B: 使用 Logback Masking 插件

优点:

  • 配置简单
  • 自动脱敏

缺点:

  • 灵活性差
  • 需要额外配置

方案 C: 使用第三方库（如 logback-mask）

优点:

  • 开箱即用
  • 功能丰富

缺点:

  • 增加依赖
  • 可能不满足定制需求

选择理由: 自定义脱敏工具类更灵活，易于维护，不增加外部依赖。

决策 4: 请求频率限制

方案 A: Spring Security @RateLimiter（已选择）

优点:

  • 与 Spring Security 集成良好
  • 使用注解，易于使用
  • 支持 Redis 分布式部署

缺点:

  • 需要 Redis 依赖

方案 B: 自定义拦截器

优点:

  • 不依赖外部库
  • 灵活可定制

缺点:

  • 需要自己实现
  • 不支持分布式部署

方案 C: 使用 Guava RateLimiter

优点:

  • 轻量级
  • 性能好

缺点:

  • 单机限流，不支持分布式
  • 需要手动集成

选择理由: Spring Security @RateLimiter 与现有架构集成良好，支持分布式部署。

影响

系统架构影响

  1. 密码加密方式变更: 需要修改数据库表结构，影响现有登录历史数据
  2. 日志脱敏: 需要修改所有日志记录处，影响调试体验
  3. 请求频率限制: 需要添加 Redis 依赖，影响部署架构

开发流程影响

  1. 语法错误修复: 立即修复，不影响开发流程
  2. 密码加密方式变更: 需要数据迁移脚本，影响开发流程
  3. 日志脱敏: 需要修改所有日志记录处，影响开发流程
  4. 请求频率限制: 需要添加 Redis 配置，影响开发流程

运维管理影响

  1. 密码加密方式变更: 需要执行数据迁移脚本，影响运维
  2. 日志脱敏: 不影响运维，反而提高安全性
  3. 请求频率限制: 需要部署 Redis，影响运维

用户体验影响

  1. 密码加密方式变更: 不影响用户体验
  2. 日志脱敏: 不影响用户体验
  3. 请求频率限制: 可能影响用户体验（频繁登录时会被限制）

风险

技术风险

  1. 密码加密方式变更风险:

    • 风险: 现有登录历史数据无法使用
    • 概率: 高
    • 缓解措施: 提供数据迁移脚本，保留旧数据作为备份

  2. 日志脱敏风险:

    • 风险: 调试困难，无法看到完整信息
    • 概率: 中
    • 缓解措施: 提供调试模式开关，调试时可关闭脱敏

  3. 请求频率限制风险:

    • 风险: 误伤正常用户
    • 概率: 低
    • 缓解措施: 提供清晰的错误信息，用户知道被限制的原因

业务风险

  1. 密码加密方式变更风险:

    • 风险: 用户需要重新登录
    • 概率: 高
    • 缓解措施: 提前通知用户，说明变更原因

  2. 请求频率限制风险:

    • 风险: 自动登录可能被限制
    • 概率: 低
    • 缓解措施: 自动登录不受频率限制限制

实施风险

  1. 数据库表结构变更风险:
    • 风险: 表结构变更失败
    • 概率: 低
    • 缓解措施: 在测试环境充分测试，准备回滚脚本

回滚策略

决策 1: 语法错误修复

回滚策略: 使用 Git 回滚到修复前的版本

决策 2: 密码加密方式变更

回滚策略:

  1. 恢复数据库表结构（添加 password_encrypted 字段）
  2. 恢复代码（使用对称加密）
  3. 从备份恢复数据

决策 3: 敏感信息日志脱敏

回滚策略: 移除脱敏逻辑，恢复原始日志记录

决策 4: 请求频率限制

回滚策略: 移除 @RateLimiter 注解，移除 Redis 配置

验收标准

决策 1: 语法错误修复

  • AC1: 项目能够正常编译，无编译错误
  • AC2: 登录功能正常工作
  • AC3: 自动登录功能正常工作

决策 2: 密码加密方式变更

  • AC1: 数据库表结构已更新（password_hash 字段已添加）
  • AC2: 密码使用 BCrypt 哈希存储
  • AC3: 密码验证使用 BCrypt.checkpw() 方法
  • AC4: 现有登录历史数据已迁移
  • AC5: 登录功能正常工作

决策 3: 敏感信息日志脱敏

  • AC1: 日志中 Session ID 只显示前 8 位
  • AC2: 日志中用户 ID 只显示前 4 位
  • AC3: 所有日志记录处都使用了脱敏方法
  • AC4: 调试模式开关正常工作

决策 4: 请求频率限制

  • AC1: 每分钟最多 5 次登录尝试
  • AC2: 超过限制时返回 HTTP 429 错误
  • AC3: 错误信息清晰明确
  • AC4: 自动登录不受频率限制限制
  • AC5: Redis 存储请求计数正常工作

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源。