EdgeEver源码架构剖析一套代码如何在Cloudflare Serverless与Docker之间自由切换【免费下载链接】edgeeverOpen-source, AI-native knowledge base Evernote alternative with native MCP. Zero-cost on Cloudflare or Docker.项目地址: https://gitcode.com/gh_mirrors/ed/edgeeverEdgeEver 是一个开源的 AI 原生知识库与 Evernote 替代方案原生支持 MCP最大亮点是同一套代码既能零成本部署在 Cloudflare Serverless 上也能一键跑在自己的 Docker 容器里。本文带你剖析它是如何通过存储契约抽象层抹平两套基础设施差异的帮助自托管用户理解其架构精髓。为什么值得读一套代码两种部署 很多开源笔记项目要么只支持 Cloudflare省事但数据不在自己手里要么只提供 Docker灵活但需要自己维护数据库。EdgeEver 选择了更难的路业务代码只写一遍运行时在两个入口分别注入不同的基础设施适配器。官方文档 self-hosting-architecture.md 开宗明义Cloudflare 和 Docker 执行的是同一个 Hono 应用二者只在薄薄的运行时与基础设施适配器接缝处不同。这意味着你在 Docker 里自建实例和部署在 Cloudflare 上的实例功能、路由、API 完全一致——不存在二等公民版本。核心设计存储契约抽象层 整个架构的钥匙在 storage-contract.ts 中。它只定义了 API 层真正需要的三个能力不暴露任何厂商 SDK 类型DatabaseAdapterSQL 语句准备prepare与批量执行batch对应 D1 或 SQLiteBlobStoreAdapter附件的get/put/delete以及分片上传对应 R2、本地文件系统或 S3StorageAdapter把上面两者打包并附带诊断信息如当前数据库是d1还是sqlite。API 路由与业务服务 │ 只依赖 StorageAdapter ┌───────┴────────┐ Cloudflare 适配器 自托管适配器 D1 R2 SQLite 文件系统 / S3文件头注释写得很直白运行时适配器把 D1、SQLite、R2、文件系统或 S3 的原语翻译成这些形状而不把厂商 SDK 类型泄漏进路由和服务。两个入口注入不同实现入口适配器数据库对象存储Cloudflare Workercloudflare-storage-adapter.tsD1R2Docker / 本地自托管self-hosted-storage-adapter.tsSQLitebun:sqlite本地文件系统或 S3 兼容存储Cloudflare 侧的适配器只有 27 行——它只是把 Worker 原生绑定的DB和RESOURCES包成StorageAdapter并标记诊断为d1/r2。而自托管侧则由 self-hosted-server.mjs 创建 SQLite 连接开启 WAL 模式、创建数据目录再按配置选择本地文件系统或 s3-compatible-storage-adapter.ts。值得注意的是wrangler.toml 中声明了[[d1_databases]]绑定DB和[[r2_buckets]]绑定RESOURCES并在 package.json 的cloudflare.bindings里用中文写明了每个绑定的用途——这对自托管用户理解数据到底存在哪非常友好。Cloudflare 侧D1 R2 Worker 装配 ☁️在 Cloudflare 上部署物是一个 Worker 静态资源组合Worker执行业务逻辑/api/*、/mcp、/__scheduled均走 Worker 优先处理见wrangler.toml的run_worker_firstAssets直接托管前端产物apps/web/dist未匹配路由回落到单页应用入口D1存储笔记本、笔记、全文搜索索引、修订记录与审计事件R2存储笔记内图片与附件D1 只保留元数据。迁移文件统一放在 migrations/ 目录0001_initial.sql到0065D1 通过wrangler d1 migrations apply应用。这也是零成本的关键D1 与 R2 在免费额度内即可支撑个人知识库的日常读写。Docker 侧一个容器 一个 /data 卷 Dockerfile 采用多阶段构建安装依赖 → 构建前端与自托管服务端 → 最终以极简的oven/bun:1.3.14-alpine运行只拷贝编译后的self-hosted-server.js、前端产物、migrations/和 LICENSE。数据布局刻意保持极简整个实例只需要持久化一个卷EdgeEver 容器 ├── SQLite 数据库 - /data/edgeever.sqlite ├── 凭据密钥 - /data/edgeever-secrets.json └── 附件存储 - /data/resources附件在数据库里以resources.object_key的同一套不透明对象键寻址因此运行时支持两种对象后端本地文件系统默认或 S3 兼容存储设置EDGE_EVER_STORAGE_BACKENDs3底层使用 AWS SDK且不会在 Cloudflare 入口加载该 SDK。NAS 用户尤其受益备份只需备份/data一个卷。镜像还内置健康检查/api/health每 30 秒探测一次并暴露 8787 端口compose.yaml 里给出了no-new-privileges、cap_drop: ALL等安全加固默认值。数据迁移双端共用的 append-only 迁移很多双平台项目会为容器单独分叉一套 schemaEdgeEver 明确禁止这种做法migrations/*.sql 是append-only的单一事实来源。Cloudflare 侧由 D1 迁移机制管理d1_migrations表SQLite 侧由自托管入口在启动时逐个应用并记录在_edgeever_migrations表中见 self-hosted-server.mjs 中的迁移循环。PostgreSQL 则被预留为第二个关系型后端——storage-contract.ts 中已定义了驱动中立的RelationalDatabaseAdapter契约但刻意暂未实现SQLite 仍是自托管默认数据库。对自托管用户的实际意义 理解了这套架构你作为普通用户能直接得到三件事平滑迁移Cloudflare 实例与 Docker 实例的 API、数据模型一致配合内置的备份导出/导入Evernote、Notion、Memos 等迁移见 migration-guide搬家只是导一次数据备份简单Docker 用户只需要备份/data卷SQLite 附件全部在内可选 S3附件量大时可切到 MinIO 等 S3 兼容存储数据库依然留在本地。EdgeEver 的AI 原生能力AI 图表、信息图、数据库视图等也完整保留在自托管版本中例如 AI 生成的架构图快速上手Docker Compose 一键部署 准备好密码后即可启动export EDGE_EVER_AUTH_PASSWORDstrong-password docker compose up -d容器启动后访问http://主机:8787登录。更多操作细节密钥管理、HTTPS、NAS 权限、升级流程请参考官方文档架构说明self-hosting-architecture.mdDocker 部署deploy-docker.mdCloudflare 部署agent-deploy-cloudflare.md总结EdgeEver 的架构哲学可以浓缩为一句话业务逻辑只写一遍差异全部收敛到存储契约这一层。storage-contract.ts 定义了API 需要什么样的持久化能力cloudflare-storage-adapter.ts 和 self-hosted-storage-adapter.ts 各自回答D1R2与SQLite文件/S3两种具体答案。路由、鉴权、AI、MCP 等上层代码对此毫无感知。如果你想在 Cloudflare 上零成本托管又想在 NAS/VPS 上完全自主可控EdgeEver 这套一套代码、双端自由切换的设计正是为这类需求而生。【免费下载链接】edgeeverOpen-source, AI-native knowledge base Evernote alternative with native MCP. Zero-cost on Cloudflare or Docker.项目地址: https://gitcode.com/gh_mirrors/ed/edgeever创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考