EdgeChat消息加密指南:AES-256-GCM服务端加密与密钥轮换完整解析
EdgeChat消息加密指南:AES-256-GCM服务端加密与密钥轮换完整解析
EdgeChat(EdgeChat 消息加密)是一款完全运行在 Cloudflare Worker 上的现代团队聊天系统。它使用 AES-256-GCM 对消息正文和新上传的附件做服务端静态加密,并通过版本化密钥环(keyring)实现安全的密钥轮换,让历史密文在换钥后依然可读。本文带你从零看懂这套 EdgeChat 消息加密方案的原理与配置方法。
一、EdgeChat 消息加密整体架构:加密发生在哪一层?
先看一个关键结论:EdgeChat 是服务端加密,不是端到端加密(E2EE)。
- 落库前加密:用户发送消息时,Worker 先通过会话权限校验,然后在把内容写入 Cloudflare D1 数据库之前完成 AES-GCM 加密。数据库里存的永远是密文信封,而不是明文。
- 读取时解密:Worker 在确认请求方有权访问该会话后,用密文信封中携带的 key ID 找到对应密钥,在内存中解密后返回明文。
- 密钥来自 Secrets:密钥不放在代码里,而是由部署流程注入为 Worker Secrets,密钥环支持多版本并存。
核心实现集中在后端加密模块 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 是否存在,不会重新生成或覆盖。
六、密钥轮换原理:为什么旧消息换钥后仍可读?
这是本方案最优雅的设计。轮换不是重新加密所有历史数据,而是:
- 新增一个版本化密钥 Secret,把 active key ID 切换到新版本;
- 所有旧 Secret 与旧 JSON 密钥环原样保留;
- 新消息用新密钥加密(信封里写入新 key ID);
- 旧密文解密时,程序读取信封中自带的 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 |
⚠️ 两条红线:
- 删除旧 key 会导致对应历史密文永久无法读取——轮换时切记保留旧密钥。
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 的信封,用关联数据把密文钉死在原始上下文,再用多版本密钥环实现"只加不改"的平滑轮换。对新手而言,你只需要记住三件事:
- 数据库和 R2 里存的是密文,密钥在 Secrets 里;
- 每条密文自带 key ID,所以换钥不丢历史消息;
- 轮换时永远保留旧密钥,删了旧 key = 历史密文永久不可读。
更多实现细节可参考 worker/src/encryption.js 源码、worker/src/encryption.test.js 测试,以及主文档 README.md 中"隐私与加密"章节。

