tianma-if/edgeever · 上手攻略

  • 仓库：tianma-if/edgeever
  • 链接：https://github.com/tianma-if/edgeever
  • 分类：agent / skill（AI-native 知识库，Evernote 替代品，原生 MCP）
  • 作者：spark
  • 更新：2026-09-11

1. 这是什么

EdgeEver 是一个开源、面向 AI Agent 时代重做的个人/团队知识库。它致敬 Evernote 经典的三栏布局（笔记本树 + 笔记列表 + 大编辑器），同时用现代化的 Web 技术栈（Bun workspace + Vite/React + TipTap/ProseMirror + Tailwind/shadcn/ui + Dexie + PWA）把它重新实现，并把整套系统设计成能被 AI Agent 原生调用：暴露 REST API、MCP（Model Context Protocol）服务端点和 CLI，所以 Claude Code、Codex、Cursor、Antigravity 等工具可以直接读写、检索、重组你的笔记库。

项目的两个关键定位：

  1. "100% 自托管、零运行成本" —— 推荐部署目标是 Cloudflare 的免费配额（D1 + R2 + Workers & Pages），按官方估算可容纳约 15 万条短笔记和 5 万张图片；想要更多容量或本地隐私，Docker 一键装在 VPS / NAS / 家庭服务器上。
  2. "AI 原生、Evernote 友好" —— 把 AI 作为一等公民：编辑器内置「要点提炼 / 校对 / 翻译 / 续写」等动作（可挂 OpenAI / Anthropic / Gemini 兼容服务），同时整库通过 MCP 对外暴露，让 Agent 把知识库当可读写的长期记忆。

许可：AGPL-3.0。Stars 1.4k，最近一次提交 2026-09-10，活跃度仍在主版本节奏上（release 流水围绕 v1.63，Docker 历史路径保留 v1.62 兼容入口 ⚠️ 见后文踩坑）。

2. 解决什么问题

Evernote 老用户的痛点是：越来越臃肿、广告、付费墙、AI/MCP 要加钱、数据导出困难。Obsidian 走另一条路——文件开放但核心闭源、官方同步要订阅、第三方同步折腾、图片和附件跟着笔记一起塞 vault，移动端同步会越用越慢，且对小颗粒度「随手记」太重。Memos / flomo 类又太轻（社交时间线），偏离经典三栏工作流。

EdgeEver 想吃掉中间这块：开放数据（标准 SQLite + 完整 REST/MCP/CLI）、零成本部署（Cloudflare 免费层）、三栏布局的熟悉感、原生 AI/Agent 集成。它还顺手做了一些创作者向功能：一键富文本复制（粘到 Substack/Medium/WordPress/Newsletter 直接成型）、Markdown ⇄ 富文本双视图、Mermaid 渲染、可视化图文档（流程图/思维导图/架构图）、版本历史、公开笔记分享、微信公众号文章剪藏（移动端直接 share-to 保存为可编辑笔记）。

3. 快速安装

EdgeEver 走两条部署主线：Cloudflare 在线一键（推荐，零服务器）和 Docker 本地（NAS/VPS/家庭服务器）。

3.1 Cloudflare 部署（6 步，README 原文摘要）

  1. Fork 仓库到个人账号：https://github.com/tianma-if/edgeever
  2. 在 Cloudflare 控制台创建 D1 数据库 edgeever 和 R2 存储桶 edgeever-resources
  3. 在 Cloudflare Workers & Pages 里导入 Fork，main 作为生产分支（不要手动改 Fork 文件，部署命令会自己写绑定）
  4. 在 Worker Secrets 里加 EDGE_EVER_AUTH_PASSWORD，值用至少 32 位的强密码
  5. 触发首次构建，访问 /api/health 应返回 200，再用 admin + 上面的密码登录
  6. 在 Fork 的 Actions 标签页启用并手动跑一次 Update deployed EdgeEver workflow，这样 Fork 能自动同步上游新特性

⚠️ R2 必须先用信用卡/PayPal/Apple Pay/Google Pay 等激活付费方式（即便最终落在免费层），中国大陆地区卡可参考官方支持的支付方式说明。

3.2 Docker 部署（一行命令）

curl -fsSL https://edgeever.org/install.sh | bash

脚本会：拉取最新 GHCR 镜像、随机生成管理员密码、用 Docker Compose 启动、挂一个每日自动更新的 cron。

镜像源在 ghcr.io，中国大陆网络偶尔慢或超时——README 明确建议提前配好代理或可信镜像仓库（用户自负安全责任）。手动部署细节见 docs/deploy-docker.md。

3.3 移动端 & 客户端

  • Android：play.google.com/store/apps/details?id=org.edgeever.mobile
  • iOS：apps.apple.com/us/app/edgeever/id6792625631（⚠️ iOS 端需要中国大陆以外的 Apple ID）
  • 桌面：Windows / macOS / Linux x86_64 Preview 均在 GitHub Releases 页面下载
  • Web 剪藏扩展：Chrome / Edge / Firefox 商店，Edge 浏览器可直接装 Chrome Web Store 版

4. 核心用法

4.1 三栏工作流（编辑器核心动作）

笔记本树 → 笔记列表 → 大编辑器。支持：无限层级嵌套笔记本、拖拽重排、批量合并/移动、客户端 WebP 压缩图片（实测减重 50%–90%）、1 GiB 以内的分片上传与流式预览（PDF/Office/zip/音视频）、离线草稿与队列、Mermaid 渲染、思维导图/架构图的可视化编辑（Web + 桌面端可编辑，移动端只读语义视图）。

4.2 让 AI 进编辑器（BYO Model）

在实例里挂 OpenAI / Anthropic / Gemini 兼容服务或第三方中转 API。可用动作：全文或选区总结、要点抽取、校对、翻译、续写。⚠️ 上游凭据会以加密形式写入数据卷；首次部署若环境变量丢失，需在「添加服务」面板里重新填写 API Key。

4.3 让 AI Agent 进整库（MCP）

这是 EdgeEver 相对 Evernote/Obsidian 最大的差异化。任意支持 MCP 的 Agent（Claude Code、Codex、Cursor、Antigravity 等）通过 MCP 端点读取、检索、重组、总结你的笔记库，还能把库挂到 Notion / 飞书 Bitable 这类外部工作流。

仓库里提供了一个「直接给 Agent 用的部署 prompt 模板」，可整段贴进 Codex / Claude / Cursor / workbuddy / Antigravity / OpenClaw / Hermes Agent，由 Agent 代为 Fork、配 D1/R2、配 Worker Secret、跑部署。模板本质是 README 的 6 步中文摘要（带权限提示语）——调用前请人工审阅请求的 GitHub/Cloudflare 权限范围。

4.4 备份与迁移

一键无损 ZIP 导出：包含 Markdown + Front Matter + 嵌套文件夹 + 相对路径附件链接 + 版本历史，可还原到任意兼容环境。单篇笔记也能导出为 Markdown / HTML / PDF。

5. 典型适用场景

  • 个人长期记忆库：替代 Evernote，自托管在 Cloudflare 免费层，零月费；通过 MCP 让 Claude Code 把你的笔记当长期记忆。
  • 研究员 / 写作者：三栏布局 + Markdown ⇄ 富文本 + 一键富文本复制到 Newsletter，搭配微信公众号剪藏，做"读到 → 整理 → 写作 → 发布"全链路。
  • 小团队共享知识底座：单实例多租户（账户间严格隔离），管理员在「Profile → User accounts」里创建/禁用/重置成员账号，每个成员拥有完全隔离的笔记本、附件、回收站、MCP token。
  • NAS / 家庭服务器玩家：Docker 部署，容量按需扩展，百万级笔记 + 大图库都不在话下。
  • AI Agent 工作流的"上游记忆"：把 EdgeEver 作为 Notion / 飞书之外的本地优先选择，用 MCP 与外部 Agent 解耦。

6. 坑与注意

  1. iOS 端需要海外 Apple ID（README 明确）。
  2. Cloudflare R2 必须先激活付费方式才能用，即便最终落在免费层——纯零卡账号直接卡在 R2 启用这一步。
  3. Docker 镜像源在 GHCR，中国大陆网络可能慢/超时，要提前准备代理或可信镜像；自行评估第三方镜像安全风险。
  4. v1.63 → v1.62 兼容入口：若你用 NAS/GUI 之类第三方启动脚本调用了 scripts/self-hosted-server.mjs，升级 v1.63 后要确认镜像仍保留该路径（README 提到本次特意保住了启动路径，⚠️ 后续版本是否继续保留需观察 release notes）。
  5. 桌面端自动重启节奏会跟实例拉齐：当桌面端连的实例还没追上 GitHub latest 时，应用内自动重启会被暂缓，避免客户端比实例新导致状态不一致；手动下载不受影响。
  6. 加密根密钥：AI 与对象存储凭据的加密根密钥写在数据卷里，若 Docker/NAS 升级丢环境变量，加密可能不可用，表现为「添加服务」按钮灰掉——已存的密钥无法解密时只能重填 API Key。
  7. AGPL-3.0：自托管对外提供服务时需注意传染条款；个人/团队内部使用没问题，商用 SaaS 改造需评估。
  8. 公开 demo：https://demo.edgeever.org 每天凌晨 3:00 CST 重置回示例笔记，不要存任何私密内容。
  9. 贡献者守约：若你的 Fork 同时用来部署，请保持 main 分支纯净只用于部署；开发/PR/同步上游都另开分支，避免 Sync fork 把部署分支污染。

7. 与同类对比

维度 EdgeEver Evernote Obsidian Memos / flomo
数据所有权 自托管 + SQLite 开放 闭源/导出繁琐 文件开放、核心闭源 自托管（按实现）
部署成本 0（Cloudflare 免费层）/ Docker 月费 + 设备数限制 本地免费、同步要订阅 0
经典三栏 ✅ ✅ ❌（自定义视图） ❌（时间线）
AI 原生 / MCP ✅（核心卖点） 付费订阅 插件生态非原生 部分插件
离线 + 多端 ✅ 全端 ✅ ✅ 受限
适合人群 自托管党 + Agent 重度用户 小白/商业用户 本地优先 + 插件党 随手记轻量党

一句话：如果你既嫌 Evernote 贵且封闭、又嫌 Obsidian 同步折腾、又嫌 Memos 太轻——EdgeEver 是这个三角地带里目前少见的「零成本 + AI 原生 + 三栏」三件套齐全的选项。

8. 一句话推荐结论

想给 AI Agent 配一个长期记忆、又要 Evernote 那种三栏熟悉感、还不想付订阅费？——把 EdgeEver Fork 到 Cloudflare 免费层 10 分钟搭好，再用 MCP 把 Claude Code 接进去，是当前少有的"零成本 + 真正 AI 原生"组合。唯一前置：R2 要先激活付费方式（即便最终落在免费层）。