加密与明文存储

Kaiwu 的架构以端到端加密（E2EE）为核心：客户端在本地加密会话内容，服务器仅存储密文。

在某些自托管或企业部署场景中，你可能希望放弃使用存储端到端加密，以便服务器能够以明文形式存储会话内容（例如用于后续实现服务端索引与搜索）。

本页将面向服务器运维人员说明相关配置，并介绍其对最终用户的具体影响。

启用明文存储后会有哪些变化？

• E2EE 存储（默认）：服务器无法读取会话记录（仅存储加密数据块）。
• 明文存储：服务器可以读取并处理以明文存储的新会话内容。

重要提示：明文存储是一种存储模式，而非认证模式。

• 第一阶段的明文存储仍沿用 Kaiwu 常规的登录模型（基于设备密钥的账户）。
• 仅当服务器策略允许时，用户才能为新会话选择明文模式。

存储策略（服务器全局）

可配置以下三种存储策略之一：

• required_e2ee（默认）：仅限加密；拒绝明文写入。
• optional：视账户或会话模式而定，同时允许加密或明文。
• plaintext_only：仅限明文；拒绝加密写入。

环境变量：

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=required_e2ee|optional|plaintext_only

推荐配置

默认 E2EE 服务器：

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=required_e2ee

允许明文存储（按账户自选启用）：

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=optional
KAIWU_FEATURE_ENCRYPTION__ALLOW_ACCOUNT_OPTOUT=1

强制仅限明文（适用于“优先使用服务端功能”的部署场景）：

KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY=plaintext_only

账户加密模式（最终用户开关）

当服务器策略设为 optional 且允许账户自选关闭加密时，界面可向用户提供账户级开关：

• e2ee：新会话默认采用加密存储
• plain：新会话默认采用明文存储

环境变量：

KAIWU_FEATURE_ENCRYPTION__ALLOW_ACCOUNT_OPTOUT=0|1
KAIWU_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE=e2ee|plain

说明：

• 切换账户模式仅对变更后创建的新会话生效。
• 现有会话不会被迁移（不支持追溯解密或重新加密）。
• 切换账户模式是一次基于迁移的原子状态转换（客户端调用 POST /v1/account/encryption/migrate）。

明文账户与账户级作用域数据

为了让明文账户在各设备间正常工作（包括无密钥登录），客户端不得对账户级作用域的数据块预设“设备密钥密文”。

• 明文账户使用 settings v2（GET/POST /v2/account/settings），并将设置项存储为明文封装包。
• 传统的设置路由（/v1/account/settings）会对明文账户拒绝访问，并返回 400 { error: "plain_account_requires_settings_v2" }。

明文静态加密封装（推荐）

从定义上看，明文账户的内容对服务器是可读的；但你仍可以使用服务器主密钥对敏感的账户级作用域数据块进行静态加密封装，从而降低磁盘或备份泄露带来的风险。

环境变量：

# Defaults are server_sealed
KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_SETTINGS_AT_REST=none|server_sealed
KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_CREDENTIALS_AT_REST=none|server_sealed

说明：

• 该配置仅影响数据库存储。对于明文账户，传输中的网络负载依然是明文封装包。
• 对于已连接的服务，v3 明文凭据端点会将凭据存储为明文封装包；若配置了静态封装，则会在落盘时予以密封。

单会话加密模式

每个会话在创建时都会选定一个固定的 encryptionMode（e2ee 或 plain）。

这既避免了单个会话内出现“混合模式”内容，也让客户端的行为更加可预测（同时便于后续引入服务端功能）。

分享行为

• 加密（E2EE）会话：分享时需向接收方分发会话数据密钥（仍保持 E2EE）。
• 明文会话：分享纯粹依赖服务端授权（无需加密数据密钥）。

公开分享链接同样适用于明文会话（服务器将返回明文封装包）。

客户端兼容性

• 仅支持加密写入的旧版客户端在以下情况下仍可正常工作：
  • 策略为 required_e2ee，或
  • 策略为 optional，且客户端创建的是加密会话。
• 在 plaintext_only 策略下，由于服务器拒绝加密写入，旧版客户端将无法正常工作。

客户端如何获取策略信息

客户端使用 GET /v1/features 获取相关配置：

• 特性开关：features.encryption.plaintextStorage.enabled、features.encryption.accountOptOut.enabled
• 详细信息：capabilities.encryption.storagePolicy、capabilities.encryption.defaultAccountMode

安全检查清单（明文模式）

如果选择在服务器上存储明文会话内容，请将其视作敏感业务数据妥善保护：

• 全程强制使用 HTTPS/TLS 端到端传输（包括代理服务器与应用服务器之间）。
• 对磁盘和备份实施静态加密。
• 严格限制数据库访问权限，并尽可能开启审计日志。
• 制定符合你所在组织规范的数据留存与清理策略。