Inkstone 手动构建部署教程

Inkstone 是一个部署在 Cloudflare Workers 上的自托管 Markdown 笔记应用。
本教程基于 shuaiplus/inkstone 版本（含 AI 语义搜索 + MCP/OAuth 功能）。
从零开始，跟着复制命令就行，全程约 15-20 分钟，无需编程基础。

---

一、需要准备的东西

检查环境

打开终端（Windows 用 PowerShell/CMD，Mac/Linux 用 Terminal）：

bash
node -v

显示类似 v24.18.0 即已安装 ✅

没装的话去官网下载：

• Windows：https://nodejs.org/zh-cn/download （LTS 版，一路下一步）
• Mac：https://nodejs.org/zh-cn/download （pkg 安装包）
• Linux：curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt install -y nodejs

💡 国内用户 npm 慢的话先切换镜像源：

bash
npm config set registry https://registry.npmmirror.com

---

二、获取项目代码

bash
git clone https://github.com/shuaiplus/inkstone.git
cd inkstone

（或到 GitHub 页面点 Code → Download ZIP 解压）

---

三、安装依赖

bash
npm install

看到 added xxx packages 即成功 ✅
（提示 allow-scripts 警告就执行 npm approve-scripts esbuild workerd 再装一次）

---

四、登录 Cloudflare

bash
npx wrangler login

浏览器弹出后：登录账号 → 点 Allow → 终端显示 Successfully logged in. ✅

⚠️ 报 invalid_scope 错误就先升级 wrangler：

bash
npm install -D wrangler@latest
npx wrangler login

4.登陆完wrangler还问要不要给 AI 编程工具自动安装 Cloudflare 开发技能包这个直接n或者回车即可。

text
√ Before you go, Wrangler detected AI coding agents that may not be best configured to work with Cloudflare: Claude Code, Codex. Would you like Wrangler to automatically install Cloudflare skills for the best experience?

---

五、创建数据库、存储桶和 KV 命名空间

1. 创建 D1 数据库（存笔记数据）

bash
npx wrangler d1 create inkstone-db

输出里有 database_id = "xxxx"，记下来。

2. 创建 R2 存储桶（存附件/图片）

bash
npx wrangler r2 bucket create inkstone-files

3. 创建 KV 命名空间（MCP/OAuth 登录功能用）

bash
npx wrangler kv namespace create OAUTH_KV

输出里有 id = "xxxx"，记下来。

---

六、把 ID 填进配置文件

打开项目根目录的 wrangler.toml，找到：

toml
[[d1_databases]]
binding = "DB"
database_name = "inkstone-db"

加一行（换成你自己的 database_id）：

toml
[[d1_databases]]
binding = "DB"
database_name = "inkstone-db"
database_id = "你的database_id"

再找到 KV 部分：

toml
[[kv_namespaces]]
binding = "OAUTH_KV"

加上 id：

toml
[[kv_namespaces]]
binding = "OAUTH_KV"
id = "你的KV_id"

保存文件。

---

七、构建并部署 🚀

bash
npm run deploy

看到类似输出即成功：

text
Uploaded inkstone (21.50 sec)
https://inkstone.xxxxxxxx.workers.dev

最后那行就是你的笔记应用地址！

---

八、开始使用

1. 浏览器打开你的 https://inkstone.xxx.workers.dev
2. 注册账号（新账号自动有中英文示例笔记）
3. 开始写！支持 Markdown、实时预览、全文/语义搜索、双链、版本历史

⚠️ 国内访问 workers.dev 可能慢，打不开就开代理或绑定自定义域名。

---

九、进阶：绑定自定义域名

1. 域名托管在 Cloudflare（或把 DNS 迁过去）
2. 控制台 → Workers & Pages → 点 inkstone Worker
3. Settings → Domains → Add → 输入子域名
4. 按提示完成绑定，等证书签发（几分钟）

---

写在最后

部署流程一句话：装 Node → 克隆 → 装依赖 → 登录 → 建 D1/R2/KV → 填 ID → 部署

遇到问题对照排查表，90% 都能解决。Happy Writing! 📝

📢 觉得教程有用？欢迎关注我的 TG 频道：https://t.me/lucklog_cc

日常分享自托管项目、服务器折腾心得、实用工具教程，喜欢折腾的朋友来一起交流！🚀