Loading... # Inkstone 自托管教程：在 Cloudflare Workers 上部署全能 Markdown 笔记 如果你想要一套**完全自托管**、笔记始终是纯 Markdown、又能在浏览器里流畅写作的知识库，[Inkstone](https://github.com/shuaiplus/inkstone) 很值得试一试。 它跑在 **Cloudflare Workers** 上，数据落在你自己的 D1 / R2（或 KV）里，支持双链、全文搜索、离线编辑、PWA、分享口令、WebDAV/S3 备份，甚至可选 Workers AI 语义搜索和远程 MCP。部署者掌控数据库、附件和运行环境。 - GitHub：<https://github.com/shuaiplus/inkstone> - 在线 Demo：<https://inkstone-demo.pages.dev/> - 当前版本：`v0.5.0`（2026-08-08） - 协议：LGPL-3.0-only - 社区讨论：[NodeSeek 原帖](https://www.nodeseek.com/post-849481-1) > 本文基于官方 README、Release 说明与 NodeSeek 社区介绍整理，适合第一次把 Inkstone 部署到 Cloudflare 的读者。 --- ## 一、它是什么，适合谁 Inkstone 的定位很清晰： > 一套用于写作、整理、同步和备份个人知识的自托管 Markdown 笔记应用。 和常见「纯前端笔记」不同，它是**完整后端 + 前端**的自托管方案： | 能力 | 说明 | | --- | --- | | 写作 | CodeMirror 6、可独立编辑标题、桌面双笔记窗格、编辑/分栏/预览、双向滚动、大纲、专注模式、打字机模式、自动保存、版本历史 | | Markdown | 表格、任务列表、脚注、定义列表、Callout、标签页、折叠块、数学公式、Mermaid、代码高亮、Front Matter、Pandoc 属性 | | 整理 | 多级文件夹（拖拽排序）、正文标签、收藏、置顶、归档、回收站、Wiki 双链、反向链接、块引用、笔记嵌入、关系图谱 | | 搜索 | D1 FTS5 全文搜索（含中文索引）、筛选、命令面板；可选 Workers AI 语义/混合搜索 | | MCP | 私有远程 MCP、OAuth 2.1 + PKCE、可撤销 `ink_...` API Key、`search`/`fetch`、版本安全写入 | | 可靠性 | 可安装 PWA、离线启动、本地缓存、离线写入队列、乐观并发、冲突副本、实时同步通知 | | 分享 | 公开链接，可设访问口令与有效期 | | 迁移/备份 | JSON / ZIP 导出、可读 Markdown、附件导出；手动或定时 WebDAV / S3 备份 | | 界面 | 桌面 + 移动布局、深浅主题、中英文、仅站长可见的版本更新提醒 | **适合：** - 想把笔记放在自己 Cloudflare 账号里，而不是第三方 SaaS - 习惯 Markdown / 双链 / 知识库，又希望浏览器即开即用 - 需要离线编辑、多设备同步、备份到 WebDAV/S3 - 想给 AI Agent 通过 MCP 安全读写自己的笔记库 **不太适合：** - 完全不想碰 Cloudflare / GitHub 的纯小白（部署仍有几步） - 需要重度团队协作文档（它更偏个人知识库） --- ## 二、架构与数据放哪 官方把存储拆得很清楚，部署前先建立心智模型： | 组件 | 用途 | | --- | --- | | **Cloudflare D1** | 账号、笔记、文件夹、标签、设置、版本、分享、关键词索引、AI 向量、后台索引队列 | | **R2 或 Workers KV** | 附件与头像二进制（`FILES` / `FILES_KV`） | | **Workers KV `OAUTH_KV`** | OAuth 客户端、授权码、令牌与授权记录（**不存笔记正文**） | | **Workers AI** | 可选语义搜索向量；未绑定时仍可用关键词搜索 | | **浏览器 IndexedDB** | 本地缓存与未同步的离线写入 | | **SyncHub Durable Object** | 在线客户端实时变更通知 | | **CredentialVault Durable Object** | 加密备份凭据的密钥隔离存储 | | **WebDAV / S3** | 用户自行配置的异地备份目标 | 代码结构也直观： ```text src/ ├── client/ React 界面、编辑器、预览、本地状态 ├── shared/ 共享类型、限制、语言资源、Markdown 工具 └── worker/ Hono API、认证、D1、同步、分享、备份 public/ 静态资源 scripts/ 检查与 e2e tests/ 回归测试 ``` 默认 `wrangler.toml` 会绑定： - D1：`inkstone-db` - R2：`inkstone-files` - KV：`OAUTH_KV` - Durable Objects：`SyncHub`、`CredentialVault` - AI binding（可选语义搜索） - 定时触发（备份/索引类 cron） --- ## 三、5 步部署到 Cloudflare（推荐 R2） 官方推荐路径非常短，核心就是 **Fork → Cloudflare 连接仓库 → 构建/部署**。 ### 1. Fork 仓库 打开： <https://github.com/shuaiplus/inkstone> 点击 **Fork**，把仓库拷到自己的 GitHub 账号。 ### 2. 在 Cloudflare 创建 Worker 1. 打开 [Cloudflare Workers & Pages 创建页](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) 2. 选择 **Continue with GitHub** 3. 授权并选中你 Fork 的 `inkstone` 仓库 ### 3. 填写构建与部署命令 **R2 模式（推荐，适合附件）：** - Build command：`npm run build` - Deploy command：`npm run deploy` **KV 模式（无 R2 / 想更轻量）：** - Build command：`npm run build`（或按仓库 KV 脚本） - Deploy command：`npm run deploy:kv` 对应本地/脚本含义大致是： ```bash # R2 npm run build npm run deploy # KV npm run deploy:kv ``` ### 4. 等部署完成 Cloudflare 会自动处理依赖安装、构建，以及 D1 / R2 / KV / DO 等资源绑定（具体以控制台向导与仓库配置为准）。现有数据库升级走**带版本号、可重复执行**的迁移，一般**不需要手写 SQL**。 ### 5. 打开 Workers 域名 部署成功后，进入生成的 `*.workers.dev` 或你绑定的自定义域名： 1. 注册/创建账号 2. 新账号会自动获得中英两篇起始笔记 3. 建议先写一篇测试笔记，确认保存、刷新、多标签页同步都正常 Demo 站：<https://inkstone-demo.pages.dev/> （纯前端体验版刷新会恢复起始笔记，方便试功能，不等于你的生产数据） --- ## 四、本地开发与命令速查 想先本地跑通，再上生产： ```bash git clone https://github.com/<你的账号>/inkstone.git cd inkstone npm install # 本地 Worker + 前端 npm run dev # 本地 KV 附件模式 npm run dev:kv # 纯前端 demo（刷新重置） npm run dev:demo # 类型检查 / 单测 / 构建 npm run typecheck npm run test:unit npm run build ``` 其他常用命令： | 命令 | 用途 | | --- | --- | | `npm run deploy` | 构建并按 R2 配置部署 | | `npm run deploy:kv` | 使用 `wrangler.kv.toml` 路径部署 | | `npm run deploy:demo` | 部署静态体验版 | | `npm run deploy:check` | dry-run 部署检查 | | `npm run i18n:check` | 中英文资源键一致性 | | `npm run test:e2e` | 对本地临时实例跑 API e2e（会写删数据，别对生产跑） | --- ## 五、上线后建议立刻做的 6 件事 ### 1. 创建站长账号并改默认习惯 - 设置深浅主题、强调色 - 确认中文界面 - 熟悉侧边栏：文件夹 / 标签 / 设置入口 ### 2. 试一下核心写作体验 - 分栏预览 + 双向滚动 - 专注模式 / 打字机模式 - 独立标题（不必和正文一级标题绑定） - 桌面双笔记窗格（并排改两篇） ### 3. 建立整理体系 - 多级文件夹 + 拖拽排序 - 标签（侧边栏可直接新建/改色/重命名） - Wiki 双链 `[[笔记名]]`、反向链接、关系图谱 - 收藏 / 置顶 / 归档 / 回收站 从 `v0.5.0` 起，文件夹、笔记、标签被整成更统一的组织系统：文件夹选择器支持嵌套路径、图标与颜色；删除文件夹会提升子目录、笔记挪到父级，避免整理体系被拆散。 ### 4. 打开搜索与命令面板 - 中文全文搜索依赖 D1 FTS5 - 有 Workers AI 时，可进一步开语义/混合搜索 - 命令面板适合快速跳笔记、执行动作 ### 5. 配置备份（强烈建议） 支持： - **JSON 导出**：结构化，可再导入 - **ZIP 导出**：结构化数据 + 可读 Markdown + 附件 + manifest - **WebDAV / S3 兼容存储**：可多目标，手动或定时 注意：登录密码、活动会话、分享口令、备份服务凭据**不会**进入导出文件。 自托管更新前，务必先留一份最新备份。 ### 6. 需要时再开高级能力 - **公开分享**：可设口令与过期时间 - **PWA**：可从「关于」安装，断网时外壳与本地会话快照仍可启动；离线写入队列保护未同步编辑 - **更新提醒**：仅站长可见，发现上游有新稳定版时提示 - **远程 MCP**：给 AI 工具受控访问笔记库（OAuth + 可撤销 API Key） --- ## 六、版本演进速览（社区贴 → 当前 0.5.0） NodeSeek 原帖较早介绍到 **0.2.0**，重点是： - 可安装、可离线启动的 PWA - 站长更新提醒 - 可独立编辑的自定义笔记标题 - 设置入口更容易找 之后官方继续快速迭代。到 **v0.5.0 - Better Organization and Safer Upgrades**，重点变成： 1. **更清晰安全的文件夹层级**（嵌套路径、图标颜色、防环/防重名、删除时提升子项） 2. **上下文感知的笔记整理**（单篇/批量移动共用层级选择器，列表显示完整路径） 3. **侧边栏内联标签管理**（新建、改色、重命名、删除，Front Matter 与正文 hashtag 同步） 4. **更安全的升级与按账号隔离的离线缓存** 5. **更可靠的 AI / 全文搜索队列** 6. **长时备份与大文件夹集合的稳定性增强** 另外还经历过： - **v0.3.0**：Remote MCP、AI Search、更快同步 - **v0.4.0**：可移植内容、双笔记工作区 升级建议： 1. 先备份（JSON/ZIP 或远程备份目标） 2. 从你的 Fork 同步上游 / 重新部署 3. 让自动 migration 跑完 4. 用站长账号验证登录、搜索、附件、分享与备份 --- ## 七、R2 还是 KV？怎么选 | 模式 | 优点 | 注意 | | --- | --- | --- | | **R2（推荐）** | 适合附件、头像、较大文件 | 需开通 R2 | | **KV** | 部署更轻、某些账号环境更好搭 | 附件场景能力/成本模型不同，适合轻量用法 | 实操建议： - 个人知识库 + 截图/附件较多 → **R2** - 先验证功能、附件很少 → 可先 **KV**，后续再迁 R2 --- ## 八、常见问题 ### Q1. 部署后是空的吗？ 不是。新账号会自动有中英两篇起始笔记，方便熟悉编辑器与双链。 ### Q2. 更新要不要手动改数据库？ 一般不需要。官方强调现有库通过幂等 migration 自动升级；但仍建议更新前备份。 ### Q3. 离线能用吗？ 可以到「应用外壳 + 本地会话快照 + 离线写入队列」这一层。网络恢复后会同步；冲突会以冲突副本等方式保护。 ### Q4. 能给 AI 用吗？ 可以。通过私有远程 MCP + OAuth/API Key，把搜索与受控读写暴露给兼容 MCP 的客户端；权限可撤销，回收站权限独立。 ### Q5. 和 Obsidian 什么关系？ Inkstone 不是 Obsidian 插件，而是浏览器里的自托管笔记应用；导出可读 Markdown / ZIP，方便迁移与备份。社区也有人希望未来和 Notion/Obsidian 生态有更深互通，但当前重点是 **Cloudflare 上一站式自托管**。 ### Q6. 自定义域名怎么做？ 在 Cloudflare 给对应 Worker 绑定自定义域即可（需域名已在 CF 或可 CNAME）。具体以你的账号网络/证书设置为准。 --- ## 九、最小验收清单 部署完成后，建议按这个清单点一遍： - [ ] 能注册/登录 - [ ] 新建笔记，刷新后还在 - [ ] 分栏预览、大纲、双链可用 - [ ] 文件夹移动 / 标签筛选正常 - [ ] 全文搜索能搜到中文内容 - [ ] 上传一张图（若用 R2/KV 附件） - [ ] 导出 JSON 或 ZIP 成功 - [ ]（可选）配置一个 WebDAV 或 S3 备份目标并手动跑一次 - [ ]（可选）安装 PWA，断网启动看本地缓存是否可用 --- ## 十、总结 Inkstone 把「Markdown 知识库」和「Cloudflare 边缘托管」拼在了一起： - **笔记仍是纯文本 Markdown**，可迁移性强 - **后端完整**：账号、同步、分享、备份、搜索、MCP 都在你自己的 Worker 里 - **部署路径短**：Fork + Cloudflare Git 集成 + `npm run build` / `npm run deploy` - **持续迭代快**：从社区贴里的 0.2.0 PWA，到如今 0.5.0 的组织体系与更安全升级 如果你已经有 Cloudflare 账号，一套 Inkstone 往往比自建一整套 VPS 笔记栈更省心；如果你本来就在用 Workers/D1/R2，它几乎是「原生居民」。 相关链接： - 项目仓库：<https://github.com/shuaiplus/inkstone> - 在线体验：<https://inkstone-demo.pages.dev/> - NodeSeek 讨论：<https://www.nodeseek.com/post-849481-1> --- *参考来源：Inkstone 官方 README / README_ZH、GitHub Releases（含 v0.5.0）、以及 NodeSeek 开源介绍帖。本文为整理重写的部署与使用教程，非原文搬运。* Last modification：August 9, 2026 © Allow specification reprint Like 如果觉得我的文章对你有用，请随意赞赏