OpenRAG 加密实现剖析OAuth凭证安全存储的完整方案【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openragOpenRAG 是基于 Langflow、Docling 和 OpenSearch 构建的开源检索增强生成RAG平台。它内置了一套完整的OpenRAG 加密体系使用 AES-256-GCM 算法对 OAuth 凭证、模型 API Key、连接器令牌缓存等敏感数据进行加密存储让密钥和凭据在磁盘上以密文形式存在为新手也提供了企业级的安全存储方案。本文将带你读懂这套方案的完整实现。一、OpenRAG 加密体系全景 ️OpenRAG 将云盘文件Google Drive、OneDrive、SharePoint摄入知识库时需要保存大量凭证OAuth 令牌、客户端密钥、云存储 API Key 等。如果这些明文落盘任何能读取数据卷的人都可能窃取你的账号权限。OpenRAG 的解决方案是所有敏感字段统一走一个加密信封envelope落盘前加密、读取时解密并额外用租户 ID 做防篡改绑定。加密体系覆盖四大落点落点保护对象相关模块模型提供商配置OpenAI 等 API Keysrc/config/config_manager.py连接器连接凭证client_secret、云存储密钥src/connectors/base.pyOAuth 令牌缓存Google Drive / OneDrive / SharePoint 令牌文件src/connectors/sharepoint/oauth.py工作区 OAuth 覆盖配置管理员在 UI 中设置的客户端密钥src/services/connector_oauth_config_service.py二、主密钥从哪来OPENRAG_ENCRYPTION_KEY 一键生成 整套加密的根是一个环境级主密钥OPENRAG_ENCRYPTION_KEY由 src/utils/encryption.py 中的get_master_secret()读取并进程内缓存。自动生成运行 TUI 或 CLI 配置向导时会自动生成一个 32 字节 Base64 密钥新手无需手写任何密码学配置托管可选开启IBM_AUTH_ENABLED后可从 IBM Secrets Manager 拉取解密密钥失败时自动回退到本地OPENRAG_ENCRYPTION_KEY强制校验设置OPENRAG_ENFORCE_PREREQUISITEStrue后若主密钥缺失应用会拒绝以未加密模式启动见 src/utils/encryption.py。⚠️ 注意主密钥一旦丢失或轮换已加密的凭证将无法解密官方文档在 docs/docs/reference/configuration.mdx 中明确提醒了这一点。三、核心算法AES-256-GCM PBKDF2 密钥派生 核心实现集中在 src/utils/encryption.py流程非常清晰密钥派生用PBKDF2HMAC-SHA256从主密钥派生出 32 字节 AES 密钥盐值每次加密随机生成16 字节迭代 10 万次抗暴力破解加密使用AES-256-GCM认证加密随机 12 字节 nonce 保证同一明文每次密文不同租户绑定将tenant_id作为 GCM 的附加认证数据AAD绑定进密文解密密文时必须租户匹配否则认证失败——这就是加密信封的防篡改能力信封格式密文与元数据一起打包成 JSON 字典落盘字段如下字段作用algorithm固定为AES-256-GCM解密时先校验kdfPBKDF2HMAC-SHA256派生方式标识tenant_id租户绑定参与 AAD 构造salt/nonceBase64 编码的随机盐与随机数ciphertextBase64 编码的 GCM 密文含认证标签单元测试 tests/unit/test_encryption.py 专门验证了一个细节伪造租户 ID 去解密会被 AES-GCM 认证标签直接拒绝从机制上杜绝了跨租户窃取密文的可能。四、四大加密落点是怎么工作的 4.1 模型提供商 API KeyConfigManager 保存 YAML 配置前会自动把 providers 下的api_key及各提供商凭证字段调用encrypt_secret()加密见 src/config/config_manager.py。磁盘上的 YAML 里只剩加密信封读回时透明解密对上层代码完全无感。4.2 连接器连接凭证每个连接器通过SECRET_CONFIG_KEYS声明哪些配置键需要加密。保存连接如 Google Drive 的client_secret、S3 的secret_key时ConnectionManager 只对这些键加密非敏感字段原样保存。测试文件 tests/unit/test_encryption.py 展示了加密后的connections.json结构只有密钥字段变成了AES-256-GCM信封。4.3 OAuth 令牌缓存文件重点这是 OAuth 凭证安全存储的核心场景。以 SharePoint 为例写入save_cache() 把 MSAL 令牌缓存序列化后统一交给 write_encrypted_file() 加密落盘读取load_credentials() 通过 read_encrypted_file() 读取自动识别密文信封并解密再用OPENRAG_TENANT_ID作为期望租户校验 AADGoogle Drive、OneDrive 走同样的路径见 tests/unit/test_oauth_encryption.py。4.4 工作区级 OAuth 客户端凭证管理员可以在 UI 中为各 OAuth 连接器覆盖client_id / client_secret。set_oauth_config() 会把client_secret加密后存入工作区配置表查询状态接口则永远不返回解密后的密钥只提示密钥来源是覆盖值还是环境变量兼顾了安全与可观测性。五、向后兼容与自动升级 OpenRAG 的加密设计非常照顾存量用户未设置主密钥时encrypt_secret()返回明文系统保持旧行为不会因升级而瘫痪自动升级read_encrypted_file() 返回needs_upgrade标志——当检测到明文旧文件且主密钥已就绪读取后的首次保存会顺手把文件加密test_auto_upgrade_features用例验证了此行为旧格式兼容解密端同时支持早期32 字节原始 Base64 密钥的历史格式见 src/utils/encryption.py。六、总结 ✅OpenRAG 的加密实现可以用一句话概括一把主密钥、一个加密信封、四个落点、租户绑定防篡改。对新手TUI 向导一键生成OPENRAG_ENCRYPTION_KEY即获得全套保护无需理解任何密码学细节对进阶用户AES-256-GCM PBKDF210 万轮的组合、每次随机的盐/nonce、AAD 租户绑定、明文降级与自动升级策略构成了一个既严谨又务实的生产级方案。想深入了解推荐阅读源码 src/utils/encryption.py 与官方配置文档 docs/docs/reference/configuration.mdx。【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考