Inkstone Cloudflare Workers 部署教程：零服务器，纯 Markdown 自托管笔记

Inkstone 是一个自托管的 Markdown 笔记应用，数据全部留在自己手里。它完全运行在 Cloudflare Workers 上：不需要服务器、不需要数据库、不需要运维，Fork 仓库、关联 GitHub、推送即部署，所有笔记以纯 Markdown 文本形式保存。

shuaiplus

inkstone

A self-hosted Markdown notebook that runs entirely on Cloudflare Workers.

—

NOASSERTION

TypeScript

项目简介#

层级	技术
运行时	Cloudflare Workers
前端	浏览器端 SPA（纯前端渲染）
数据存储	Cloudflare R2（对象存储）或 KV（键值存储）
笔记格式	纯 Markdown 文本
协议	LGPL-3.0-only

它能做的事情可以概括成一句话：一个浏览器就能打开的私有知识库，笔记永远是你自己的 Markdown 文件。

主要特性：

专注写作 + 实时预览
词汇搜索与可选语义搜索
双向链接（[[Wiki 链接]]）
离线编辑，重新联网后自动同步
多设备同步（基于 Cloudflare 存储）
私有 AI 接入（自行填 endpoint 与 API Key）
公开分享笔记
异地备份

存储模式选型：R2 还是 KV？#

Inkstone 提供两种存储后端，部署时需要二选一：

维度	R2 模式	KV 模式
构建命令	`npm run build`	`npm run build`
部署命令	`npm run deploy`	`npm run deploy:kv`
适用场景	附件较多、笔记体积较大	轻量纯文本笔记
免费额度	10 GB 存储 + 100 万 Class A 请求	1 GB 存储 + 10 万次读 / 1000 次写
单值大小	较大	25 MB

Tip

个人知识库通常以纯文本笔记为主，KV 模式免费额度已足够；如果你打算存放大量图片附件，建议选择 R2 模式。

部署前准备#

一个 GitHub 账号
一个 Cloudflare 账号，并开启 Workers & Pages 服务
（可选）一个用于绑定的自定义域名

部署方式一：Cloudflare 控制台关联 Git 仓库（推荐）#

这是最省事的路径，不需要装任何 CLI，也不需要本地构建。

1. Fork 仓库#

把 shuaiplus/inkstone Fork 到你自己的 GitHub 账号。

2. 从 Git 仓库导入项目#

登录 Cloudflare 控制台
进入 Workers & Pages → 创建应用 → 连接 Git
授权 GitHub，选择刚才 Fork 的 inkstone 仓库
项目类型选择 Cloudflare Workers
构建配置会自动读取仓库中的 wrangler.toml / package.json

3. 配置环境变量#

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

R2 模式示例：

1
R2_BUCKET_NAME=inkstone

KV 模式示例：

1
KV_NAMESPACE_ID=你的 KV 命名空间 ID

Warning

具体环境变量名请以仓库中的 wrangler.toml 或 .dev.vars.example 为准，不要泄露 API Token。

4. 部署并访问#

点击 部署应用，部署通常在 1～3 分钟内完成。打开 Cloudflare 分配的 *.workers.dev 或 *.pages.dev 域名。

初次打开时，Inkstone 会自动运行数据库迁移，无需手动初始化。

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

在 域名管理 → 添加自定义域名 中填入你的域名，按提示在 DNS 服务商处添加 CNAME 记录，Cloudflare 会自动签发免费 SSL 证书。

部署方式二：Wrangler CLI 本地部署#

想在本地调试后再部署，按这套流程走。

1. 安装 Wrangler 并登录#

1
npm install -g wrangler
2
wrangler --version
3
wrangler login   # 浏览器弹窗授权 Cloudflare 账号

2. 克隆并安装依赖#

1
git clone https://github.com/你的用户名/inkstone.git
2
cd inkstone
3
npm install

3. 配置本地环境变量#

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

编辑 .dev.vars，按注释填写对应的存储配置。

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

4. 启动本地开发服务#

1
wrangler dev

5. 推送部署#

1
# R2 模式
2
wrangler deploy
3

4
# KV 模式
5
npm run deploy:kv

Cloudflare 会自动构建、部署到边缘节点，并生成可访问的 URL。

环境变量速查#

Note

下表为常见变量，具体以仓库 wrangler.toml 定义为准。

变量	说明	必填	备注
`R2_BUCKET_NAME`	R2 桶名	R2 模式必填	如 `inkstone`
`KV_NAMESPACE_ID`	KV 命名空间 ID	KV 模式必填	在 Cloudflare 控制台创建
`AI_ENDPOINT`	私有 AI 接口地址	否	OpenAI 兼容
`AI_API_KEY`	AI 接口密钥	否	用于 AI 辅助功能

部署后的常用配置#

这些都在 Inkstone 前端设置里完成，不需要重新部署。

私有 AI 接入#

在设置中新增一个 OpenAI 兼容的自定义 API（endpoint + API Key），即可使用 AI 润色、摘要等功能。API Key 存在 Cloudflare 存储中，接口返回时会做脱敏。

多设备同步#

登录同一个 Inkstone 实例，不同设备上的笔记会自动通过 Cloudflare 存储同步，支持离线编辑，重新联网后合并更改。

公开分享#

可以将单篇笔记设为公开，生成可分享的链接，供他人阅读。

备份与迁移#

Inkstone 的笔记始终是纯 Markdown 文本，备份特别直白：把 Markdown 文件原样导出存好，恢复时再导入即可。Cloudflare R2/KV 数据也可通过控制台或 Wrangler CLI 导出。

Note

升级时，Inkstone 会通过版本化、幂等的自动迁移升级数据库。建议在更新前保留当前备份。

常见问题#

Q：一定要用 Cloudflare 吗？ A：是的，Inkstone 的设计目标就是完全运行在 Cloudflare Workers 上，不支持传统服务器部署。

Q：构建失败了怎么办？ A：先查看部署日志。常见原因是依赖没装全或 wrangler.toml 配置错误。R2 模式需确保 R2 桶已创建并绑定。

Q：页面打开后空白或 404？ A：检查环境变量是否配置正确，以及 Workers 路由是否命中。

Q：R2 和 KV 怎么选？ A：笔记为主选 KV，带大量附件选 R2。两者免费额度对个人使用通常绰绰有余。

小结#

Inkstone 的价值在于把部署成本压到了最低：不用买服务器，不用建数据库，不用初始化，Fork 仓库、关联 GitHub、填几个环境变量就能跑。笔记永远是纯 Markdown，数据掌握在自己手里，适合想要自主掌控数据、进行多设备云端同步与私有知识管理的场景。

项目开源，LGPL-3.0-only 协议，欢迎提 Issue 和 PR。

音乐

音乐

项目简介#

存储模式选型：R2 还是 KV？#

部署前准备#

部署方式一：Cloudflare 控制台关联 Git 仓库（推荐）#

1. Fork 仓库#

2. 从 Git 仓库导入项目#

3. 配置环境变量#

4. 部署并访问#

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

部署方式二：Wrangler CLI 本地部署#

1. 安装 Wrangler 并登录#

2. 克隆并安装依赖#

3. 配置本地环境变量#

4. 启动本地开发服务#

5. 推送部署#

环境变量速查#

部署后的常用配置#

私有 AI 接入#

多设备同步#

公开分享#

备份与迁移#

常见问题#

小结#

支持与分享

评论区