OpenViking加密配置实战ov.conf里encryption字段该怎么填3种Provider完整指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking是一个面向 AI Agent 的自进化上下文数据库统一管理 Agent 记忆、知识 RAG 与技能。它的ov.conf中的encryption 字段负责开启静态数据加密开启后所有写入的数据会在存储层自动加密API 完全不变旧数据也能兼容读取。本文手把手讲清楚 encryption 字段每个参数该怎么填以及 3 种密钥提供程序Local、Vault、火山引擎 KMS的选择与配置方法。为什么需要开启 OpenViking 加密在多租户部署中不同账户的资源文件、记忆和技能都存储在同一个 AGFS 实例里。OpenViking 采用**信封加密Envelope Encryption**三层密钥架构层级名称说明Layer 1Root Key根密钥全局唯一存放在本地文件或 KMSLayer 2Account Key账户密钥每个账户独立运行时用 HKDF 派生不落地存储Layer 3File Key文件密钥每次写操作随机生成加密文件内容它的核心好处是✅透明加密API 无变化应用层无感知✅多租户隔离账户 A 的密钥无法解密账户 B 的文件✅向后兼容未加密的旧文件仍可正常读取加密后你在 Web Studio 中的操作体验完全一样数据在底层已受保护encryption 字段速查表encryption段只有三个顶层参数全部字段定义见 configuration 指南完整示例可直接参考 ov.conf.example{ encryption: { enabled: true, provider: local, api_key_hashing: { enabled: false } } }参数类型说明默认值enabledbool是否启用文件级静态加密AES-GCMfalseproviderstr密钥提供程序local/vault/volcengine_kms-api_key_hashing.enabledboolAPI key 字段 Argon2id 单向哈希与文件级enabled独立控制false三种 provider 怎么选一张表说清提供程序适用场景优点缺点Local开发环境、单节点部署最简单无需外部服务密钥在本地安全性较低Vault生产环境、多云部署企业级密钥管理需部署并维护 VaultVolcengine KMS火山引擎云部署云原生密钥服务仅限火山引擎环境Local 模式3 步完成最简单的加密配置Local 是最常用的起步方案只需一个根密钥文件。第 1 步生成根密钥ov system crypto init-key --output-file ~/.openviking/master.key该命令会在本地生成 32 字节 root key权限自动设为 0600。第 2 步填写 ov.conf{ encryption: { enabled: true, provider: local, local: { key_file: ~/.openviking/master.key } } }local.key_file默认为~/.openviking/master.key可以省略。⚠️ 注意两点密钥文件权限必须是600仅所有者可读写权限过开会校验失败千万不要把密钥文件提交到版本控制系统。第 3 步备份密钥文件master.key丢了就再也解不开数据建议立即做离线备份。生产环境Vault 与 Volcengine KMS 怎么填Vault 模式需已部署 HashiCorp Vault 并启用 Transit 引擎{ encryption: { enabled: true, provider: vault, vault: { address: https://vault.example.com:8200, token: hvs.your-vault-token, mount_point: transit, kv_mount_point: secret, kv_version: 1, root_key_name: openviking-root-key, encrypted_root_key_key: openviking-encrypted-root-key } } }其中address和token是必填项其余参数都有默认值。火山引擎 KMS 模式需已创建 AES_256 对称密钥{ encryption: { enabled: true, provider: volcengine_kms, volcengine_kms: { key_id: d926aa0d-xxxx-xxxx-xxxx-xxxxxxxxxxxx, region: cn-beijing, access_key: AKLTxxxxxxxx, secret_key: Tmpxxxxxxxx, endpoint: null, key_file: ~/.openviking/openviking-volcengine-root-key.enc } } }四个必填项key_id、region、access_key、secret_key。升级必看api_key_hashing 行为变更 ⚠️这是一个容易踩坑的 Breaking Changev0.3.12 之后以前encryption.enabled true会隐式启用 API key 的 Argon2id 哈希现在必须显式配置encryption.api_key_hashing.enabled否则默认falseAPI key 以明文存在 AES-GCM 加密的文件内如果升级后启动日志出现API key hashing is disabled while file encryption is enabled...警告说明行为已变更。想要最高级别保护就显式开启api_key_hashing: { enabled: true }开启后 API key 单向哈希存储无法还原明文ov admin list-users只会显示 key 前缀。验证加密是否生效方法一检查文件头魔术数。加密文件以OVE1OpenViking Encryption v1开头hexdump -C ./data/agfs/your-file | head -1 # 加密文件 4f 56 45 31 ... 即 OVE1 # 明文文件 7b 22 63 6f ... 即 {co...方法二跑一次健康检查。配置校验、密钥初始化、加解密测试全通过后ov doctor会给出全绿结果加密模块的初始化与校验逻辑位于 crypto/config.py密钥提供程序实现见 crypto/providers.py。常见配置错误排查报错/现象原因解决办法Key file not found密钥文件路径错误或未生成确认ov system crypto init-key已执行路径用~会自动展开Key file permissions too open密钥文件权限不是 0600执行chmod 600 ~/.openviking/master.keyUnsupported providerprovider 值写错只能是local/vault/volcengine_kmsVault 连接失败服务未启动或 Token 过期检查address、网络与 Token 有效性KMS 认证失败AK/SK 或区域错误核对 Access Key、Secret Key 与 region跨 provider 解密失败KeyMismatchError这是正常的安全行为不同 provider 密钥互相不可解无需处理⚠️ 特别提醒从明文切换到加密不会自动改写已有文件旧文件仍按明文兼容读取新写入的数据才会加密。如需把存量数据也加密应通过 OVPack 备份-恢复流程迁移到全新的加密存储环境详见 加密指南的迁移说明。参考资料加密完整指南docs/zh/guides/08-encryption.md加密概念与三层密钥架构docs/zh/concepts/10-encryption.md全量配置参考含 encryption 段docs/zh/guides/01-configuration.md配置示例文件examples/ov.conf.example【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考