EdgeChat消息加密指南:AES-256-GCM服务端加密与密钥轮换完整解析

原创2026-10-16 23:55:562,188 阅读

EdgeChat消息加密指南:AES-256-GCM服务端加密与密钥轮换完整解析

EdgeChat(EdgeChat 消息加密)是一款完全运行在 Cloudflare Worker 上的现代团队聊天系统。它使用 AES-256-GCM 对消息正文和新上传的附件做服务端静态加密,并通过版本化密钥环(keyring)实现安全的密钥轮换,让历史密文在换钥后依然可读。本文带你从零看懂这套 EdgeChat 消息加密方案的原理与配置方法。

EdgeChat 现代聊天系统:实时通信、Telegram 桥接与消息加密


一、EdgeChat 消息加密整体架构:加密发生在哪一层?

先看一个关键结论:EdgeChat 是服务端加密,不是端到端加密(E2EE)。

  • 落库前加密:用户发送消息时,Worker 先通过会话权限校验,然后在把内容写入 Cloudflare D1 数据库之前完成 AES-GCM 加密。数据库里存的永远是密文信封,而不是明文。
  • 读取时解密:Worker 在确认请求方有权访问该会话后,用密文信封中携带的 key ID 找到对应密钥,在内存中解密后返回明文。
  • 密钥来自 Secrets:密钥不放在代码里,而是由部署流程注入为 Worker Secrets,密钥环支持多版本并存。

EdgeChat 聊天界面预览:加密消息在客户端正常展示

核心实现集中在后端加密模块 worker/src/encryption.js,消息读写路径在 worker/src/data/messages.js,测试覆盖见 worker/src/message-encryption.test.js。

💡 为什么后台"看不到消息"不等于绝对安全?Worker 在权限校验后会在运行环境中解密内容,因此 Cloudflare 运行环境和掌握密钥的部署方仍需被信任。管理员后台没有消息正文查看入口,但这是产品层面的约束,不是技术层面的隔离。


二、AES-256-GCM:为什么选它?

EdgeChat 使用 Web Crypto 标准的 AES-GCM 模式,每个密钥固定 32 字节(256 位)(见 encryption.js 中的 AES_KEY_BYTES = 32):

特性 说明
认证加密 GCM 模式同时提供机密性和完整性校验。密文被篡改哪怕 1 个字节,解密会直接失败并抛出 authentication failed,而不是解出乱码
随机 Nonce 每次加密都用 crypto.getRandomValues 生成 12 字节随机 IV。即使同一条消息加密两次,密文也完全不同
关联数据(AAD) 把密文"绑定"到特定上下文(如某个频道、某个文件下载地址),把密文挪到别处使用会认证失败
硬件级标准 AES-256 是目前业界最主流的高强度对称算法,Web Crypto 在浏览器和 Worker 中均有原生支持

简单说:防偷看靠 AES,防篡改和防挪位置靠 GCM。


三、密文信封格式:一条消息在数据库里长什么样?

1. 消息密文信封

加密后的消息正文是一个带前缀的字符串(encryption.js#L182-L212):

edgechat:enc:v1:<keyId>:<Base64(12字节nonce)>:<Base64(密文)>
字段 作用
前缀 edgechat:enc:v1: / v2: 标记"这是密文",并区分本地用户(v1)与外部来源用户(v2)
<keyId> 该条消息使用的密钥版本 ID。这是密钥轮换能生效的关键——旧消息带着旧 key ID,换钥后照旧可解
nonce + 密文 AES-GCM 标准输出,Base64 编码后落库

同一个密钥、同一段文字加密两次,会产生两条完全不同的密文(随机 nonce 保证),这一点在 encryption.test.js 中有专门测试验证。

2. 文件附件信封

附件走二进制信封(encryption.js#L355-L382),结构为:

魔数 EDGE01\0 + keyId长度 + keyId + 12字节nonce + 密文
  • 8 字节魔数 EDGE01 用于识别"这是加密附件";没有魔数的旧附件按原始字节直接返回,保证历史文件仍可正常下载。
  • 上传链路在 worker/src/api/upload.js 中调用 encryptAttachment 写入 R2,下载时在 worker/src/api/upload.js 调用 decryptAttachment 还原。

3. 敏感配置信封

Telegram Bot Token、Webhook Secret 等敏感配置同样被加密存入数据库(worker/src/data/telegram.js),前缀为 edgechat:secret:v1:,解密入口是 encryption.js#L282-L313 的 decryptSecretValue。


四、关联数据(AAD):把密文"钉"在正确的位置

这是 EdgeChat 加密方案中最容易被忽略、但价值很高的一环。加密时,每类数据都会附加一段关联认证数据(Additional Authenticated Data)(encryption.js#L147-L165):

数据类型 绑定内容 防住什么攻击
消息 频道 ID + 发送者 ID 防止把 A 频道的密文挪到 B 频道的记录里通过认证
外部桥接消息 频道 ID + 外部用户上下文 同上,适配 v2 信封
附件 R2 对象键(下载地址路径) 防止同一份密文被替换到其他文件的下载地址
敏感配置 明确用途标识(如 bot-token) 防止 Bot Token 与 Webhook Secret 的密文互换后仍能被解密

测试用例明确验证了这一点:把消息改到错误频道解密、把附件换成另一个 objectKey 解密,都会抛出 authentication failed(encryption.test.js#L49-L62、encryption.test.js#L99-L102)。


五、密钥环(Keyring)配置:多版本密钥如何共存

1. JSON 密钥环格式

密钥环是一个 JSON 结构,activeKeyId 指向当前用于新加密的密钥,keys 里保留所有仍被历史密文引用的旧密钥(每项为 Base64 编码的 32 字节密钥):

{"activeKeyId":"v1","keys":{"v1":"BASE64_ENCODED_32_BYTE_KEY"}}

配置通过名为 EDGECHAT_ENCRYPTION_KEYRING 的 Secret 注入。加载与校验逻辑在 encryption.js#L107-L137 的 loadEncryptionKeyring 中:密钥长度不是 32 字节、key ID 格式非法、active key 不在 keys 中,都会直接报错拒绝启动。

2. 自动版本化密钥(Worker Secrets 轮换)

除了 JSON 密钥环,EdgeChat 还支持由部署工作流自动管理的版本化 Secret:EDGECHAT_ENCRYPTION_KEY_1、EDGECHAT_ENCRYPTION_KEY_2… 会被自动映射为 auto-v1、auto-v2… 这样的 key ID(encryption.js#L49-L64)。首次部署若目标 Worker 尚无加密 Secret,工作流会随机生成 32 字节 AES 密钥并记录 active key ID;之后的普通部署只检查 Secret 是否存在,不会重新生成或覆盖。


六、密钥轮换原理:为什么旧消息换钥后仍可读?

这是本方案最优雅的设计。轮换不是重新加密所有历史数据,而是:

  1. 新增一个版本化密钥 Secret,把 active key ID 切换到新版本;
  2. 所有旧 Secret 与旧 JSON 密钥环原样保留;
  3. 新消息用新密钥加密(信封里写入新 key ID);
  4. 旧密文解密时,程序读取信封中自带的 key ID,从密钥环里找到旧密钥继续解密。
┌────────────── 密钥环 Keyring ──────────────┐
│  activeKeyId: v2   ← 新消息用 v2 加密      │
│  keys: { v1: 旧密钥, v2: 新密钥 }          │
└────────────────────────────────────────────┘
        ↑                        ↑
  旧消息信封 keyId=v1        新消息信封 keyId=v2
  用 v1 解密(仍然成功)     用 v2 解密

对应测试 encryption.test.js#L64-L85 完整覆盖了"轮换后旧数据可解 + 增量新增密钥不破坏旧密钥环"两个场景。

两种轮换操作方式

方式 操作 特点
自动增量轮换 手动运行 Deploy Worker 并勾选 rotate_encryption_key 只新增一个版本化密钥 Secret 并切换 active key ID,旧 Secret 全部保留,推荐方式
手动覆盖密钥环 使用 apply_encryption_keyring,在 Repository Secret 中提供完整 JSON 密钥环 备用入口。keys 必须保留所有仍被历史密文引用的旧 key ID,再新增 key 并更新 activeKeyId

⚠️ 两条红线:

  1. 删除旧 key 会导致对应历史密文永久无法读取——轮换时切记保留旧密钥。
  2. apply_encryption_keyring 与 rotate_encryption_key 不能在同一次部署运行中同时启用。

七、历史明文兼容:不回填、不迁移

EdgeChat 对部署前已存在的明文数据采取"原样保留"策略:

  • 读取时发现内容不带密文前缀,就按明文直接返回(encryption.js#L214-L223),既不回写数据库,也不触发后台批量加密任务;
  • 只有新写入的消息和新上传的附件才被加密(encryption.js#L384-L389)。

这样做的好处是:升级零风险、不产生大规模数据迁移负载;代价是历史数据仍是明文存储,新数据才是密文。测试用例见 encryption.test.js#L45-L47。


八、快速上手清单

  • [ ] 确认部署时 EDGECHAT_ENCRYPTION_KEYRING 等加密 Secret 已存在(首次部署自动生成,无需手动准备)
  • [ ] 需要手动指定密钥时,创建合法 JSON 密钥环:{"activeKeyId":"v1","keys":{"v1":"<Base64 32字节密钥>"}}
  • [ ] 轮换密钥:运行 Deploy Worker 并勾选 rotate_encryption_key
  • [ ] 切勿在轮换后删除旧 key ID
  • [ ] 记住边界:这是服务端加密;开启 Telegram 桥接后,被转发的消息还会进入对应 Telegram 会话

总结

EdgeChat 的消息加密方案可以浓缩成一句话:用 AES-256-GCM 把每条消息和每个附件加密成自带 key ID 的信封,用关联数据把密文钉死在原始上下文,再用多版本密钥环实现"只加不改"的平滑轮换。对新手而言,你只需要记住三件事:

  1. 数据库和 R2 里存的是密文,密钥在 Secrets 里;
  2. 每条密文自带 key ID,所以换钥不丢历史消息;
  3. 轮换时永远保留旧密钥,删了旧 key = 历史密文永久不可读。

更多实现细节可参考 worker/src/encryption.js 源码、worker/src/encryption.test.js 测试,以及主文档 README.md 中"隐私与加密"章节。

登录后查看全文
Edgechat