inkstone

shuaiplus活跃维护

跑在 Cloudflare Workers 上的自托管 Markdown 笔记本,用 D1、KV、R2 和 Durable Objects 存数据,支持双向链接和 CodeMirror 编辑,适合搭建个人知识库。

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

v0.8.0发布于 2026-09-14 07:50 UTC1,163star1,073fork同步于 2026-11-07 07:33 UTC

怎么上手

由 README 提炼,执行前请确认
npm run dev
硬件要求按 README 说明

README 未说明本地硬件要求;运行时依赖 Cloudflare Workers、D1、R2 或 Workers KV,语义搜索需 Workers AI 绑定,未启用时退回词法搜索

下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

跑在 Cloudflare Workers 上的自托管 Markdown 笔记本,用来写作、整理、同步和备份个人知识

跑在 Cloudflare Workers 上的自托管 Markdown 笔记本,用 D1、KV、R2 和 Durable Objects 存数据,支持双向链接和 CodeMirror 编辑,适合搭建个人知识库。

核心能力

  • 用 CodeMirror 6 编辑器,支持双笔记编辑组与专注、打字机模式
  • 支持 GFM、WikiLinks、数学公式、Mermaid 图表与 Front Matter
  • 用 D1 FTS5 做全文搜索,可选 Workers AI 语义与混合搜索
  • 提供离线写入队列与乐观并发控制,冲突时生成副本
  • 支持 WebDAV/S3 手动或定时异地备份,可导出 JSON 与 ZIP

容易踩的坑

部署前需在 Cloudflare 选择 R2 或 KV 模式,KV 模式要把部署命令改为 npm run deploy:kv;语义搜索依赖 Workers AI 绑定,未配置时只能用词法搜索;端到端测试会改动 http://localhost:7712 的数据,只能对专用本地实例运行

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v0.8.0
  1. v0.8.0v0.8.0 - Live Preview and a Mobile-First Workspace最新正式版2026-09-14 · 2026-09-14 07:50 UTC

    v0.8.0 - Live Preview and a Mobile-First Workspace

    Inkstone 0.8.0 introduces a Typora-style live-preview editor while retaining split view and a dedicated reading mode, rebuilds the mobile library and account experience, and makes settings, note opening, search, and database queries more responsive. Existing notes, folders, tags, attachments, shares, backups, sessions, offline edits, and account settings remain compatible. An automatic, idempotent schema migration adds and updates indexes for existing D1 databases; no manual database command or destructive rebuild is required. Keeping a current backup before deploying any self-hosted update is still recommended.

    Added

    1. Live Markdown preview while editing. The new default live mode keeps Markdown as the source while rendering supported inline and block syntax around the cursor, including sanitized rich Markdown output. Split view and the dedicated reading mode remain available, existing layout preferences migrate safely, and the command palette and editor toolbar expose all three modes consistently. Commit: 391c83a.

    2. A mobile-first library and account experience. Phones now have dedicated library filters for note views, folders, and tags; a focused account hub for settings and the knowledge graph; clearer list grouping and note actions; and a four-tab bottom navigation for notes, editing, reading, and account access. Subsequent refinements compact the library header, align search, sorting, and note creation, and bring account settings closer to the desktop layout. Commits: e96fa27, 772e666, 93f319d.

    Improved

    1. Faster, more resilient settings. Settings sections now load on demand, warm likely destinations in the background, reuse bounded resource caches, retain already visited panels, and show stable loading and recoverable error states. Profile and settings updates also avoid unnecessary session reloads while keeping synchronized account state current. Commit: dfebd89.

    2. More responsive note opening and editor mounting. CodeMirror is deferred until its workspace is visible, reducing hidden-editor work in multi-pane and mobile layouts. Note opening now separates immediate navigation feedback from content loading, guards stale requests, records inline load failures, and more carefully restores durable offline edits without allowing an older response to replace newer state. Commit: 966f43c.

    3. Consistent search access at every breakpoint. The former floating search control has been replaced with a shared search entry in the expanded and collapsed desktop sidebar, the tablet header, and mobile navigation, while preserving the command-search shortcut and accessible labels. Commit: bd96b14.

    4. Lower database work across common operations. Schema migration v12 adds targeted note, tag, version, and backup-run indexes and makes FTS note identifiers searchable. Search, graph degree calculation, statistics, version retention, orphan-tag cleanup, backup retention, synchronization, AI-index cleanup, API-key activity, and metadata writes now use more selective or aggregated queries and avoid redundant updates. Commit: 03714dc.

    5. A faster default local-development path with an explicit AI mode. Normal development no longer waits for a remote Workers AI binding and uses keyword search locally; npm run dev:ai keeps the real Workers AI path available when Cloudflare authentication and network access are present. Production AI bindings are unchanged. Commit: [bdc69d7](https://github.com/shuaiplus/inks

  2. v0.7.0v0.7.0 - Broader MCP, Better Markdown, and Faster Large Notebooks2026-08-31 · 2026-08-31 16:32 UTC
    查看更新说明

    v0.7.0 - Broader MCP, Better Markdown, and Faster Large Notebooks

    Inkstone 0.7.0 expands the private MCP server into a broader knowledge-work interface, improves Markdown preview and long-code reading, and makes startup and navigation more responsive for large notebooks and installed PWAs. This release does not add a database migration: existing notes, folders, tags, attachments, shares, backups, sessions, offline data, and account settings remain compatible. Keeping a current backup before deploying any self-hosted update is still recommended.

    Added

    1. Broader, bounded MCP knowledge operations. Authorized AI clients can now work with note history, folders, tags, bulk organization, link graphs, backup runs, attachments, typed Front Matter properties, lightweight property queries, and public-note shares in addition to the existing note search and editing tools. Reads remain bounded, writes use idempotency and revision guards, destructive changes have explicit scopes or preview steps, and permanent purge, account management, authentication management, and backup credentials are not exposed. Commit: 82be6bb.

    2. Collapsible long code blocks. Preview and public-share pages can collapse code blocks above a configurable line threshold, preserve the reader's expanded state while the preview refreshes, and expose accessible expand and collapse controls. Commit: 41509b1.

    Improved

    1. Responsive loading for large notebooks. Note lists now render an initial window and add more entries near the viewport instead of mounting every row at once; keyboard navigation and direct opening still reveal an off-screen active note. The workspace and locales load on demand, while the PWA precaches the modules required to open the app offline. Commit: 76b486b, eb1dc54.

    2. Leaner, clearer Markdown support. The documented and rendered syntax is now centered on GFM and the supported Obsidian-style features, preview code highlighting uses PrismJS with lazy language loading, and unused editor-language and Markdown extension packages have been removed. Commits: 5720acd, b45cabc.

    3. More resilient and responsive interface behavior. Top-level and inline error boundaries provide a recoverable fallback, editor setting changes no longer recreate the whole CodeMirror instance, loading states use stable skeletons, and folder and note interactions have clearer motion feedback. Text tokens and crawler guidance were also refined, and WebAssembly support dependencies were refreshed. Commits: e4b0a18, 09e6339, 7a26772, bb659e8.

    Fixed

    1. Complete offline availability without foreground contention. After the core shell is ready, the service worker now completes the optional offline cache quietly, one resource at a time with short yields, so features that have not yet been opened remain available offline without competing aggressively with foreground requests. Commit: ec42b77.

    2. Stable mobile PWA viewport sizing. Installed and mobile layouts now follow the visual viewport, safe areas, keyboard resizing, and overlay positioning more reliably instead of leaving clipped or unusable panes. Commit: 059298e.

    3. Compatible MCP OAuth authorization responses. OAuth responses now include the requested resource audience so compatible clients can complete authorization a

  3. v0.6.0v0.6.0 - Portable Backups and Two-Factor Security2026-08-10 · 2026-08-10 10:20 UTC
    查看更新说明

    v0.6.0 - Portable Backups and Two-Factor Security

    Inkstone 0.6.0 adds restorable portable backups, TOTP two-factor authentication, a much more capable knowledge graph, tag-aware editing, and selectable background palettes. It also hardens synchronization, offline state, MCP authorization, attachments, imports, exports, sharing, and scheduled maintenance for larger and longer-running installations. Existing 0.5.0 databases are upgraded automatically through the next versioned schema migration; no manual database command or destructive rebuild is required, and existing notes, folders, tags, attachments, backup targets, sessions, shares, MCP grants, and browser data remain compatible. Keeping a current backup before deploying any self-hosted update is still recommended.

    Added

    1. TOTP two-factor authentication with recovery codes. Account settings can now enable authenticator-app verification through a QR code or manual secret, download one-time recovery codes, regenerate them, and disable the factor after confirming the current password and a valid code. Login challenges are bounded and replay-safe, sensitive TOTP material uses the credential vault, and enabling, regenerating, or disabling the factor revokes other sessions. Existing accounts remain signed in and two-factor authentication stays off until each user explicitly enables it. Commit: 53eb340.

    2. Portable, verifiable backup archives and direct restore. Scheduled WebDAV and S3 backups now produce streamed ZIP archives containing readable Markdown, referenced attachments, a manifest, and a completion marker. Inkstone can restore a selected backup folder in bounded batches, choose the newest complete snapshot, verify file sizes and SHA-256 checksums, preserve active, archived, and trashed note states, and retain compatibility with the previous backup manifest layout. Only attachments referenced by backed-up notes are loaded and transferred. Commits: 5c1549b, 19785b4.

    3. A filterable local and global knowledge graph. The graph can now focus on the current note or the whole notebook, control traversal depth, search nodes, filter by folder or tag, include or hide orphan and unresolved notes, group nodes, toggle labels and arrows, and tune layout forces and node scale. Preferences persist safely, superseded requests are cancelled, and graph queries are validated and bounded on the server. Commits: 9405e3c, 753d4ba, 3caca05, c41e393, 0e9abbf.

    4. Tag-aware editing and discovery. Typing # in the editor now offers tag completion, while tag extraction and search recognize body occurrences more accurately without confusing Markdown structure or code for tags. Case-only renames, organizer filters, optimistic refreshes, and serialized color changes now remain consistent across the editor, sidebar, search, and API. Commits: 5233bd7, c2c6e1b, feab9f4, 2be4d35, 6f1f438.

    5. Selectable background palettes. Appearance settings now include synchronized background choices that work with the existing light and dark themes, apply during the initial page paint, and follow the account across tabs and devices. Commit: bbff680.

    Improved

    1. **Faster PWA startup and more consistent interface
  4. v0.5.0v0.5.0 - Better Organization and Safer Upgrades2026-08-08 · 2026-08-08 10:48 UTC
    查看更新说明

    v0.5.0 - Better Organization and Safer Upgrades

    Inkstone 0.5.0 makes folders, notes, and tags work as one coherent organization system while strengthening upgrades, search, backups, sharing, uploads, and session security. Existing databases and legacy browser caches are migrated automatically through compatibility-preserving paths; no manual database command is required, and existing notes, folders, tags, attachments, sessions, and offline data are retained. As with every self-hosted update, keeping a current backup before deployment is recommended.

    Added

    1. A clearer, safer folder hierarchy. Folder pickers now show searchable nested paths, folder icons, and colors. New notes can inherit the current folder, folders can be created in context and reordered by drag and drop, and moves reject cycles, excessive depth, invalid sibling targets, and duplicate names. Deleting a folder promotes its children in place and moves direct notes to the parent without losing organization. Commit: ec15d12.

    2. Context-aware note organization. Single-note and bulk move actions share the same hierarchical folder picker, recent and trash views retain their intended chronological order, and note lists and workspaces show full folder paths where the leaf name alone would be ambiguous. New notes preserve the folder context from which they were created. Commit: 95ea569.

    3. Tag management directly in the sidebar. The separate tag-management page has been replaced by an inline New button and per-tag context menus for rename, color, and delete. Tag changes update immediately with rollback on failure, preserve unused tags, follow the active tag view safely, merge case-insensitive duplicates with confirmation, and update YAML Front Matter and body hashtags together while skipping code. Existing custom #RRGGBB tag colors remain compatible. Commits: 9b106db, 5e302ba, a9961ec.

    4. A realistic MCP settings preview in Demo mode. The Demo now exposes the complete MCP settings surface as display-only content, with matching English and Chinese guidance and write operations still blocked. Commit: 6957c32.

    Improved

    1. Safer upgrades and account-local offline caches. Browser data is isolated by user so one account cannot inherit another account's cached shell state. Legacy cache layouts are migrated with fallbacks, and existing D1 databases converge through idempotent schema migrations instead of destructive rebuilds. Commits: 073e249, f14c70b, 03032fb.

    2. More reliable AI and full-text search queues. Disabling semantic search is now honored consistently; queue completion uses conditional guards so concurrent edits are not lost; deleting or purging notes also cleans their vectors; and normal search schedules FTS draining outside the request path while retaining a correct lexical fallback during pending work. Commits: d05c9aa, 4a04b4b, 5b8e92d, e3d26e3, 846df98.

    3. Long-running backups and large folder sets. Backup leases renew while work is active and allow longer destination operations, preventing valid long backups from losing their lock. Folder position normalization is chunked so large collections stay within D1 batch limits. Commits: [4b00f45](htt

  5. v0.4.0v0.4.0 - Portable Content and Two-Note Workspaces2026-08-06 · 2026-08-06 12:16 UTC
    查看更新说明

    v0.4.0 - Portable Content and Two-Note Workspaces

    Inkstone 0.4.0 makes it easier to bring content in, manage it, take it back out, and work across two notes at once. The release adds clipboard-image optimization, dedicated tag and attachment management, per-note Markdown/HTML/PDF export, Obsidian vault import, and a focused side-by-side workspace. It also refreshes onboarding and fixes local-development stability. This release does not change the database schema and requires no migration; existing notes, settings, attachments, and offline data remain compatible. Keeping a current backup before deployment is still recommended.

    Added

    1. Clipboard image paste with browser-side optimization. Screenshots copied as clipboard image data can now be pasted directly into the editor even when the clipboard does not expose them as files. Oversized images are downscaled and compressed in the browser before upload, reducing transfer time and R2/KV storage use while preserving normal uploads when optimization is unnecessary or unsupported. Commit: c3a5539.

    2. Dedicated tag management. A new panel from the sidebar can search tags, rename them across note bodies, change or clear their colors, and delete them. The manager uses the existing interface color tokens consistently. Commits: 5a07aa1, 6790c61.

    3. Attachment management and cleanup. Settings → Data now opens an attachment manager that can browse and filter files, show how many notes reference each attachment, delete individual files, and clean up unreferenced attachments. Commit: 12bf7dd.

    4. Per-note Markdown, HTML, and PDF export. Export the current note from the workspace or any note from its list context menu. Markdown exports include title Front Matter; HTML exports are self-contained and inline private images; PDF export renders the note and opens the browser print workflow. Commits: 0d2d601, 053b073.

    5. Obsidian vault ZIP import. Markdown imports now recognize referenced images and PDFs from ordinary Markdown paths and Obsidian wiki embeds, upload those files as private Inkstone attachments, and rewrite the references to managed URLs. Obsidian %% comments become hidden HTML comments, and array or nested Front Matter tags remain supported. Commit: 6b959f6.

    6. Two-note editor groups on desktop. Open another note beside the current note from the list action, context menu, or by holding Alt while clicking. Each group independently supports edit, split, or preview mode; the note divider is resizable, and open notes, active group, layouts, and divider position survive reloads. Commit: 9edabba.


    v0.4.0 - 内容导入导出与双笔记工作区

    Inkstone 0.4.0 让内容的导入、整理、导出以及双笔记协作更加完整。本版本新增剪贴板图片优化、独立的标签与附件管理、单篇笔记 Markdown/HTML/PDF 导出、Obsidian 仓库导入,以及专注的双笔记工作区;同时更新新手引导并修复本地开发稳定性。本版本不修改数据库结构,无需执行迁移;已有笔记、设置、附件和离线数据保持兼容。与所有自托管更新一样,部署前仍建议保留一份最新备份。

    新增

    1. 剪贴板图片粘贴与浏览器端优化。 即使剪贴板没有把截图暴露为普通文件,也可以直接把其中的图片数据粘贴到编辑器。尺寸过大的图片会在上传前由浏览器缩放和压缩,减少传输时间与 R2/KV 存储占用;无需优化或浏览器不支持时仍保持普通上传。提交:c3a5539。

    2. 独立的标签管理。 现在可以从侧边栏打开标签管理面板,搜索标签、在笔记正文中统一重命名、修改或清除颜色,并删除标签。管理器同时统一使用现有界面颜色变量。提交:5a07aa1、6790c61。

    3. 附件管理与清理。 “设置 → 数据”新增附件管理器,可以浏览和筛选文件、查看每个附件被多少篇笔记引用、单独删除附件,并清理未被引用的文件。提交:12bf7dd。

    4. 单篇笔记 Markdown、HTML 与 PDF 导出。 可以从工作区导出当前笔记,也可以从笔记列表右键菜单导出任意笔记。Markdown 包含标题 Front Matter;HTML 是可独立打开的完整

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    About

    Inkstone is a browser-based notebook that runs on Cloudflare Workers. Notes always remain plain Markdown text; on top of that foundation, the application provides focused writing, live preview, lexical and optional semantic search, bidirectional links, offline editing, multi-device synchronization, private AI access, public sharing, and off-site backups.

    It is a complete self-hosted application. The deployer retains control of the database, attachments, and runtime environment.

    Every new account automatically receives two standard starter notes, one in Chinese and one in English. The browser-only demo reuses the same note content; refreshing the page restores these two starter notes instead of loading a separate set of demo data.

    Features

    AreaIncluded
    WritingCodeMirror 6 editor, independently editable note titles, two-note editor groups, per-group editor/split/preview layouts, synchronized scrolling, outline, focus mode, typewriter mode, autosave, and version history
    MarkdownGFM tables and task lists, footnotes, Obsidian-style comments, WikiLinks, embeds, block IDs, callouts, details blocks, tabs, math, Mermaid diagrams, PrismJS syntax highlighting, and Front Matter
    OrganizationNested folders with drag-and-drop ordering, inline tags, favorites, pinning, archive, trash, wiki links, backlinks, block references, note embeds, and a relationship graph
    SearchD1 FTS5 full-text search with Chinese indexing, filters, recent notes, command-palette navigation, and optional private semantic/hybrid search powered by Workers AI
    MCPPrivate remote MCP, OAuth 2.1 with PKCE, revocable ink_... API keys, standard search/fetch, bounded reads, revision-safe writes, separate trash permission, and per-account grant management
    ReliabilityInstallable PWA, offline app launch, browser-side cache, offline write queue and optimistic concurrency control, immediate local mutations with rollback, stale-sync protection, conflict copies, realtime notifications, and elected-tab polling fallback
    SharingPublic note links with optional access passwords and expiration dates
    PortabilityJSON and ZIP exports, directly readable Markdown, attachment export, and manual or scheduled WebDAV/S3 backups
    InterfaceDesktop and mobile layouts, dark/light themes, accent colors, Simplified Chinese, English, and owner-only update notifications

    Data storage

    ComponentPurpose
    Cloudflare D1Accounts, notes, folders, tags, settings, versions, shares, lexical indexes, per-account AI embeddings, and background indexing queues
    Cloudflare R2 or Workers KVAttachment and uploaded-avatar binaries through the FILES or FILES_KV binding
    Workers KV OAUTH_KVOAuth client registrations, authorization codes, access and refresh tokens, and grants; note bodies are not stored here
    Workers AI AI bindingOptional embedding generation for semantic search; unavailable deployments continue to use lexical search
    Browser IndexedDBLocal cache and pending offline writes
    SyncHub Durable ObjectRealtime change notifications between active clients
    CredentialVault Durable ObjectIsolated storage for the key used to encrypt backup credentials
    WebDAV or S3 storageUser-configured off-site backups

    Deployment

    1. Fork the Inkstone repository to your GitHub account.
    2. Open Cloudflare Workers & Pages.
    3. Select Continue with GitHub, then choose your forked repository.
    4. For R2 mode, set the build command to npm run build and the deploy command to npm run deploy.
      • To use KV mode, change the deploy command to npm run deploy:kv.
    5. After deployment completes, open the generated Workers URL.

    Existing databases are upgraded automatically through versioned, idempotent migrations. Keep a current backup before updating any self-hosted deployment. When a newer stable Inkstone release is available, the owner receives a focused reminder without interrupting regular members.

    Exports and backups

    • JSON export preserves legacy structured notebook data for re-import.
    • ZIP export and remote backups use the same verified Markdown snapshot format, including readable notes, archived and trashed notes, attachments, and a completion marker.
    • Remote backup targets support WebDAV and S3-compatible storage, with duplicate attachment content stored only once inside each snapshot.
    • Large backups can be restored by selecting the backup folder, without loading one complete archive into memory.
    • Multiple targets can be configured and run manually or on a schedule.
    • Login passwords, active sessions, share passwords, and backup-service credentials are not included in exports.

    Development and verification

    CommandPurpose
    npm run devStart the local Worker and client
    npm run dev:kvStart locally with the KV attachment configuration
    npm run dev:demoStart the reset-on-refresh browser-only demo
    npm run typecheckRun TypeScript project checks
    npm run test:unitRun the Vitest unit test suite
    npm run i18n:checkVerify parity between the English and Chinese locale resources
    npm run comments:checkEnforce the source-comment policy
    npm run buildType-check and create a production build
    npm run deploy:kvBuild and deploy with wrangler.kv.toml
    npm run deploy:demoBuild and deploy the static browser-only demo
    npm run test:e2eExercise the API against a running disposable local instance

    The end-to-end script creates, changes, and deletes data at http://localhost:7712. Run it only against a fresh local state dedicated to testing.

    Repository layout

    src/
    ├── client/   React interface, editor, preview, and local state
    ├── shared/   Shared types, limits, locale resources, and Markdown utilities
    └── worker/   Hono API, authentication, D1 access, sync, sharing, and backups
    public/       Static assets
    scripts/      Repository checks and end-to-end verification scripts
    tests/        Cross-module regression tests
    

    Security and contributions

    Read SECURITY.md before reporting a vulnerability. Development setup and contribution requirements are documented in CONTRIBUTING.md.

    License

    Inkstone is distributed under the GNU Lesser General Public License v3.0 only, using the SPDX identifier LGPL-3.0-only.