Memos on EdgeOne 部署教程：零数据库，纯 Blob 存储

1. KV 需要申请开通，Blob 不用#

KV 存储的开通流程是：控制台顶部导航栏 → KV Storage → Apply now，然后填写申请理由、提交申请表、等待工作人员审核。也就是说，想用 KV 的部署者要先卡在一个人工审批环节，审核结果和时长不可控。

而 Blob 是零配置的：代码里第一次 getStore("memos") 调用时，平台会自动为当前项目创建同名命名空间，后续调用直接复用。既不用申请，也不用在控制台点”创建命名空间”再”绑定变量名”。

对于一个”点几下就能用起来”的部署教程，把申请审核写进前置条件是体验最差的一环。

2. KV 当前仅在 Edge Functions 运行时可用#

官方存储对比文档里写得很清楚：KV 的运行时环境是 Edge Functions only，而 Blob 支持 Edge Functions / Cloud Functions。

memos-on-edgeone 的后端是 Node.js Cloud Functions（依赖 @edgeone/pages-blob 这个 Node.js SDK，edgeone.json 里也配置了 cloudFunctions.maxDuration 与 externalNodeModules）。即使申请到了 KV 命名空间，也无法在这个运行时里直接访问——最后还是要绕回 Blob。

3. 一致性模型：用户和配置需要读后立即一致#

KV 只有最终一致性，没有”读最新值”的选项。用户表、实例设置这类权威数据必须读到刚写入的内容——比如注册后立刻登录、刚改完设置就刷新页面——不能容忍最长 60 秒的延迟。

Blob 则可以在每次读取时指定 { consistency: "strong" } 绕过边缘缓存直读主存储。本项目正是这么做的：所有对 JSON 表的读取都强制强一致（worker/src/storage/index.ts 中的 EdgeOneBlobProvider 每次 get 都带 consistency: 'strong'），保证读后写成立。

顺带一提：以后想换回 KV 也不难#

Blob 里是纯粹的 key → JSON 文档，db/user.json 这类 key 天然可以一对一映射成 KV 的 key。也就是说，如果哪天 KV 申请下来了，把 worker/src/db/blob-database.ts 里的存储实现换成 KV 后端即可，业务层 SQL 和表结构都不用动。这也是这个项目坚持把存储收敛到一层抽象接口的原因。

1. Fork 仓库#

把 memos-on-edgeone Fork 到你自己的 GitHub 账号。

2. 从 Git 仓库导入项目#

1. 登录 EdgeOne 国内版控制台 | EdgeOne 国际版控制台
2. 进入 边缘应用 → Pages（Makers）→ 创建项目
3. 选择 从 Git 仓库导入
4. 授权 GitHub，选择刚才 Fork 的仓库
5. 构建配置会自动读取仓库根目录的 edgeone.json，一般不需要手改

edgeone.json 里的关键配置如下：

1
{
2
  "buildCommand": "npm run build:web",
3
  "installCommand": "npm install && cd web && npm install",
4
  "outputDirectory": "./web/dist",
5
  "nodeVersion": "22.11.0",
6
  "cloudFunctions": {
7
    "maxDuration": 120,
8
    "externalNodeModules": ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"]
9
  },
10
  "rewrites": [{ "source": "/*", "destination": "/index.html" }]
11
}

注意 rewrites：前端是 SPA，所有未知路径都要回退到 index.html，/u/<username> 这类页面靠它才能正常打开。

3. 配置环境变量#

在 项目设置 → 环境变量 中添加：

1
JWT_SECRET=<你的密钥>
2
INSTANCE_NAME=memos-on-edgeone
3
APP_VERSION=1.0.0
4
BLOB_STORE_NAME=memos

JWT_SECRET 是唯一必填项，用来签发登录态。生成一个足够随机的值：

1
# macOS / Linux
2
openssl rand -base64 32
3

4
# Windows PowerShell
5
[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

4. 访问并注册管理员#

部署成功后（通常 2～5 分钟），打开 EdgeOne 分配的默认域名。

第一个完成注册的用户会自动成为管理员（ADMIN），之后的注册才是普通用户。所以部署完成后请立刻完成管理员注册，再到「设置 → 实例设置」里打开「禁止用户注册」，避免被别人抢先注册成管理员。

5. 绑定自定义域名（可选）#

在 项目 → 域名管理 → 添加自定义域名 中填入你的域名，按提示在 DNS 服务商处添加对应的 CNAME 记录，证书可在控制台申请免费证书或使用托管证书。

1. 安装 EdgeOne CLI 并登录#

1
npm install -g edgeone
2
edgeone -v          # 确认安装成功
3
edgeone login       # 浏览器弹窗授权；命令行会询问站点，选 China 或 Global
4
edgeone whoami      # 查看当前账号

2. 克隆并安装依赖#

1
git clone https://github.com/你的用户名/memos-on-edgeone.git
2
cd memos-on-edgeone
3
npm install
4
cd web && npm install && cd ..

根目录和 web 是两个独立的 npm 工程，EdgeOne 的安装命令也正是分两步安装的。

3. 配置本地环境变量#

1
cp .dev.vars.example .dev.vars    # Windows: copy .dev.vars.example .dev.vars

编辑 .dev.vars，至少填入 JWT_SECRET：

1
BLOB_STORE_NAME=memos
2
JWT_SECRET=your-super-secret-jwt-key-here
3
INSTANCE_NAME=memos-on-edgeone
4
APP_VERSION=1.0.0

.dev.vars 已在 .gitignore 中，不要把它提交到仓库。

4. 启动本地开发服务#

需要两个终端：

1
# 终端 1：后端 Cloud Functions
2
npm run dev
3

4
# 终端 2：前端 Vite 开发服务器
5
npm run dev:web

edgeone makers dev 默认在 8088 端口同时提供前端页面与 Functions 服务。如果想把控制台已配置的环境变量同步到本地，可以执行 edgeone makers link 关联项目，或者用 edgeone makers env pull 拉取环境变量。

5. 推送触发自动部署#

1
git push origin main

EdgeOne 检测到推送后会自动安装依赖、执行 npm run build:web、把前端部署到 CDN、把 Functions 部署到边缘节点，并更新域名指向。

附件存储#

默认附件也存在 Blob 里（key 为 attachments/<uid>/<filename>）。需要注意 Cloud Functions 对请求体超过 6 MB 会直接拒绝，所以大附件走的是预签名 URL 直传：函数只签发一个短期令牌，浏览器把文件字节直接 PUT 到存储，再回调 POST /api/v1/attachments/complete 落库，绕开了函数体积限制。

想把附件搬到自己的 S3 兼容存储，可以在 设置 → 存储 里选择 S3 并填写 endpoint、region、bucket、Access Key / Secret Key。切换后新旧附件都能正常读取：每条附件记录都会写入 storage_type 标记（BLOB 或 S3），读写时据此解析到对应后端。

如果连数据库也要一起搬到 S3，那就在环境变量里设置 STORAGE_TYPE=s3 加上一组 S3_* 变量，此时 Blob 不再承担任何数据：

1
STORAGE_TYPE=s3
2
S3_ENDPOINT=https://s3.your-provider.com
3
S3_REGION=auto
4
S3_BUCKET=your-bucket-name
5
S3_ACCESS_KEY_ID=your-access-key
6
S3_SECRET_ACCESS_KEY=your-secret-key
7
S3_FORCE_PATH_STYLE=true   # MinIO 等需要路径风格的服务保持 true

AI 语音转写#

在 设置 → AI 里新增一个 OpenAI 兼容的自定义 API（endpoint + API Key），指定为转写模型（如 whisper-1），录音文件就能直接转成文字写进备忘录。API Key 存在 Blob 的 instance/settings/AI 里，接口返回时会做脱敏。

关闭注册#

设置 → 实例设置 中打开「禁止用户注册」和「禁止密码登录」（如需配合 OAuth 登录）。