【免费下载链接】Edgechat完全运行于 Cloudflare Worker的现代聊天系统实时通信、Telegram 双向桥接、消息与文件加密 A modern, self-hosted team chat built on Cloudflare — realtime messaging, Telegram bridge, encrypted messages files, and WebMCP. |项目地址https://gitcode.com/gh_mirrors/ed/Edgechat点击查看免费下载EdgeChatEdgeChat 消息加密是一款完全运行在 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-L212edgechat:enc:v1:keyId:Base64(12字节nonce):Base64(密文)字段作用前缀edgechat:enc:v1:/v2:标记这是密文并区分本地用户v1与外部来源用户v2keyId该条消息使用的密钥版本 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 Dataencryption.js#L147-L165数据类型绑定内容防住什么攻击消息频道 ID 发送者 ID防止把 A 频道的密文挪到 B 频道的记录里通过认证外部桥接消息频道 ID 外部用户上下文同上适配 v2 信封附件R2 对象键下载地址路径防止同一份密文被替换到其他文件的下载地址敏感配置明确用途标识如 bot-token防止 Bot Token 与 Webhook Secret 的密文互换后仍能被解密测试用例明确验证了这一点把消息改到错误频道解密、把附件换成另一个 objectKey 解密都会抛出authentication failedencryption.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 还支持由部署工作流自动管理的版本化 SecretEDGECHAT_ENCRYPTION_KEY_1、EDGECHAT_ENCRYPTION_KEY_2… 会被自动映射为auto-v1、auto-v2… 这样的 key IDencryption.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: 新密钥 } │ └────────────────────────────────────────────┘ ↑ ↑ 旧消息信封 keyIdv1 新消息信封 keyIdv2 用 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 中隐私与加密章节。赞分享【免费下载链接】Edgechat完全运行于 Cloudflare Worker的现代聊天系统实时通信、Telegram 双向桥接、消息与文件加密 A modern, self-hosted team chat built on Cloudflare — realtime messaging, Telegram bridge, encrypted messages files, and WebMCP. |项目地址https://gitcode.com/gh_mirrors/ed/Edgechat点击查看免费下载相关推荐Serf 安全模型深度解析AES-256-GCM 对称加密、消息格式、威胁模型与密钥轮换机制Serf 安全模型深度解析AES 256 GCM 对称加密、消息格式、威胁模型与密钥轮换机制 Serf 集群采用对称密钥共享密钥密码系统为节点间的全部网服务注册发现云原生集群管理Apache Pulsar 端到端加密PIP-4实战指南基于 ECDSA/RSA 与 AES-256-GCM 的消息加解密实现Apache Pulsar 端到端加密PIP 4实战指南基于 ECDSA/RSA 与 AES 256 GCM 的消息加解密实现 本文以 Apache Pu消息队列流处理后端微服务消息路由如何快速创建专业级Arcaea谱面开源编辑器的完整指南如何快速创建专业级Arcaea谱面开源编辑器的完整指南 你是否梦想创作属于自己的Arcaea谱面却苦于找不到合适的工具Arcade plus正是你需要的解游戏开发开发工具桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考