AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
AI Agent 在线部署 EdgeEver 约定
本文档为 AI Agent(以及自动化部署工具)在 Cloudflare 上在线部署 EdgeEver 的标准操作规范与约定。
💡 核心原则:纯 Serverless 架构部署,基于 Cloudflare 免费配额运行,无需购买 VPS 或配置 Docker/SSL 证书。
自动化部署标准步骤
Fork 仓库
- Fork
tianma-if/edgeever到目标 GitHub 账户。
- Fork
创建 Cloudflare 资源
- 创建名称严格为
edgeever的 D1 数据库。 - 创建名称严格为
edgeever-resources的 R2 存储桶。
- 创建名称严格为
创建 Worker
- 在 Workers & Pages → Create application → Start with Hello World! 中创建并部署名称严格为
edgeever的 Worker。 - 此时只是占位服务,不代表 EdgeEver 已部署。已有 EdgeEver 实例应复用其 Worker 和认证 Secret,不得替换为 Hello World 或重置密码。
- 在 Workers & Pages → Create application → Start with Hello World! 中创建并部署名称严格为
连接 Fork 前配置运行时 Secret
- 在该 Worker 的 Settings → Variables and Secrets 中添加 Secret 类型的
EDGE_EVER_AUTH_PASSWORD,值为初始管理员登录密码(建议至少 32 个字符),并点击 Deploy。 - 确认 Secret 名称已出现在列表中,再连接仓库。密码只保存为 Worker 运行时 Secret,不得写入 Workers Builds 构建变量或 Fork 文件。
- 在该 Worker 的 Settings → Variables and Secrets 中添加 Secret 类型的
连接 Fork
- 在这个已有 Worker 的 Settings → Builds → Connect 中授权 GitHub 访问并选择 Fork 的
main分支。参考 Cloudflare 连接已有 Worker 的步骤。不要使用 Deploy to Cloudflare 模板入口,也不要创建 Pages 应用。 - 使用仓库根目录与默认部署命令
npx wrangler deploy,由 Cloudflare 在线执行并接入 EdgeEver 的受验证部署流程。已有部署可保留显式的bun run build:cloudflare与bun run deploy:cloudflare-builds命令。 - 不要修改
wrangler.toml或重复添加 binding。部署根据edgeever自动查询 D1 UUID,并生成临时DB与RESOURCESbinding。其他数据库名称通过EDGE_EVER_D1_DATABASE_NAME设置;仅无法查询 UUID 时使用EDGE_EVER_D1_DATABASE_ID。非敏感实例参数放入 Workers Builds 构建变量。 - 已有部署默认沿用线上
RESOURCESbinding 与管理员用户名,不要求用户重命名或重新配置自定义 R2 存储桶。受版本控制的配置保持不变,确保 Fork 默认作为部署镜像。
- 在这个已有 Worker 的 Settings → Builds → Connect 中授权 GitHub 访问并选择 Fork 的
配置部署权限
- 在 Settings → Builds → API token 中选择或创建 Workers Builds 部署应用使用的 Cloudflare API Token。选择 Create new token 会自动生成 Token,但默认权限可能不含 D1;到个人资料 → API Tokens 为其补充目标账户的 D1 读取和编辑权限,并保留原有部署权限。在该 Worker 的 Settings → Builds → API token 中选用该 Token 并保存构建设置。后续 Cloudflare Workers Builds 会使用它执行数据库迁移和 Worker 部署。
启动首次构建与服务验证
用户名默认使用
admin;仅用户要求自定义时,在启动首次构建前设置EDGE_EVER_AUTH_USERNAME。在 Fork 的 GitHub 仓库中进入 Actions → Update deployed EdgeEver,按提示启用工作流,选择
main分支并点击 Run workflow。该工作流会重新发布所选上游版本,即使 Fork 已对齐也会触发新的部署事件。返回 Cloudflare 的 Deployments 查看对应构建。缺少认证配置是需要修正的部署错误,不是预期的首次构建失败。保持认证与部署校验开启。
在 Cloudflare 确认对应构建成功、部署完成后,验证
/api/health返回 HTTP200及{"ok": true},/api/openapi.json可访问且 JSON 含"ok": true,并使用管理员用户名及密码验证登录 API。Hello World 响应不能通过验收。后续由该工作流自动同步正式版本,持续获得功能更新和问题修复。
上游更新通道说明
- 普通 Fork 默认作为部署镜像,无需配置任何更新变量:工作流会把所选上游 Release 的产品代码快照应用到
main,再触发 Cloudflare。 - 更新器会把 Fork 自己的完整
.github/workflows/**目录及两个更新辅助脚本作为稳定的本地引导层保留。官方打包、签名、测试与 Release 工作流继续通过tianma-if/edgeever仓库门禁限制执行,也不会被下游产品更新改写。 - 只有明确维护了应用代码修改的 Fork,才应创建 Actions 仓库变量
EDGE_EVER_PRESERVE_FORK_CHANGES=true。启用后改为 merge,并由仓库所有者处理未来冲突;普通部署无需设置。 - 打开 Job Summary,确认 Fork mode 为
mirror,并显示上游目标(stable Release 或 edgemain),以及「已发布更新」或明确的「已对齐」结果。 - 若发生了 push,确认 Cloudflare Deployments 构建的是对应的
maincommit。 - 普通部署 Fork 不应修改部署文件,日常升级也不要依赖 GitHub Sync fork;本工作流就是唯一需要的同步路径。只有旧 Fork 必须取得新版更新工作流本身时,才使用一次 Sync fork,之后继续使用 Update deployed EdgeEver。
可选:自定义初始管理员用户名
普通部署直接使用默认用户名 admin,不要主动询问用户是否需要修改。仅当用户明确要求自定义管理员用户名时,才在启动首次构建前通过 Workers Builds 构建变量设置 EDGE_EVER_AUTH_USERNAME,并在登录验证时使用该用户名。管理员账号已创建后,仅修改该变量不会重命名现有账号。