GitHub 当笔记盘：开源 Web 笔记 BatNoter 选型与自托管边界

源微信标题写成「最好的 Web 笔记管理工具」，核对 sn=bda54a8c15ab5879 后，真实产品是 batnoter/batnoter（MIT）。前端约 2.4k Star，配套后端 batnoter/batnoter-api 用 Go 暴露 REST；官方演示站是 batnoter.com。源文吹的是「1.6K Star、React + MUI」——方向没错，但少写了两件对选型更关键的事：笔记文件落在用户自己的 GitHub 仓库里，以及上游最后一次有效推送停在 2022 年 10 月。

本地已经写过 NoteGen（内置 RAG 的本地 AI 笔记本）和 Obsidian 技能包路线。它们回答的是「笔记应用本身」或「CLI 如何改写旧页」。本文换一层：如果你的痛点是「想用浏览器写 Markdown，又不想再买一套云笔记盘」，BatNoter 的交易条件是什么、什么时候别上。

一、它到底在卖什么：浏览器 + GitHub OAuth + 你的仓库

BatNoter 不是又一个「本地文件夹双链 PKM」，也不是 Notion 式数据库工作区。官方一句话很短：Create and store notes to your git repository。

拆开看，链路是固定的：

1. 浏览器打开 Web App（官方托管或你自建前端）。

2. 用 GitHub 登录（OAuth）。

3. 选中（或创建）一个用于存笔记的 GitHub 仓库。

4. 之后每一次创建 / 编辑 / 删除，都通过 BatNoter API 写回该仓库里的 Markdown 文件；前端用缓存减少重复 GitHub API 调用。

技术栈也干净：前端 React + TypeScript + Redux Toolkit + MUI；后端 Go，当前官方说明里只支持 GitHub 仓库作为存储后端，本地开发要起 Postgres（Docker）再 migrateup / serve。

这意味着你拿到的不是「私有二进制格式」，而是可被任意编辑器打开的 .md 树——迁走成本接近 git clone。

二、功能清单：够用，但边界清晰

对照官方 README 与源文功能表，可核对的能力如下：

它没有（至少官方文档没承诺）：实时多人编辑、块级双链图谱、内置 RAG、移动端原生 App、GitLab / Gitee / 裸 Git 远端。若你要这些，应去看 Outline、AFFiNE、思源、Memos 等另一类产品，而不是硬拧 BatNoter。

三、本地跑通：前端与 API 是两套工程

前端（batnoter）

官方要求 Node.js 18+：

git clone https://github.com/batnoter/batnoter.git
cd batnoter
npm install
npm start

开发模式默认打开 http://localhost:3000。测试：

npm test

后端（batnoter-api）

官方要求 Go 1.18+ 与 Docker Desktop，先起 Postgres：

make network
make postgres
make createdb
cp config.yaml .config.yaml
# 把 .config.yaml 里的占位符改成真实 GitHub OAuth Client ID/Secret、JWT 密钥等
go run main.go migrateup
go run main.go serve

生产侧还有 Helm 仓库 batnoter/batnoter-charts，适合已经在跑 Kubernetes 的团队；个人试用通常官方演示站或 Docker Compose（社区自拼）更轻。

排坑：只起前端不起 API，或 OAuth Redirect URL 与 GitHub App 配置不一致，会卡在「能打开页面、登不进仓库」。先确认 .config.yaml 的 Redirect 与 GitHub OAuth App 回调完全一致，再查浏览器 Network 里 /api/v1/oauth2 相关请求。

四、和 NoteGen / Obsidian / Notion 替代品怎么站队

选型口诀：

• 要「浏览器写、版本历史交给 Git、文件永远可搬」→ BatNoter 逻辑自洽。
• 要「随手乱记再 AI 重整」→ NoteGen，别硬套 BatNoter。
• 要「第二大脑 + Agent 改写旧页」→ Obsidian 技能路线，不是这个仓库。
• 要「团队 Wiki / 白板 / 多维表」→ Outline / AFFiNE / AppFlowy。

五、必须写进决策单的三条边界

1. 上游活跃度。 GitHub 显示主仓 pushed_at 约在 2022-10-01。功能能跑，但你要默认：安全补丁、GitHub API 变更、Node/Go 大版本，多半要自己接。生产使用前评估是否 fork 自维。

2. 存储绑定 GitHub。 API README 写明 currently only supports github repository。公司禁用 GitHub、或笔记不能出内网，这条链路直接否决。

3. OAuth 与仓库权限。 登录后应用需要读写你指定的笔记仓库。最小权限原则：单独建一个 notes 私有仓，不要授权到含密钥的业务仓；定期审计 GitHub OAuth App 授权列表。

源文是项目安利体，几乎不谈停更与权限面。作为工程选型，这三条比「界面干不干净」更决定能不能上。

六、什么人值得今晚就 clone

适合：个人知识库想 100% Markdown、已经生活在 GitHub、接受「Web 壳 + Git 盘」、能自己维护 OAuth 与偶发 API 变更。

不适合：要团队实时共编、要本地离线优先、要 AI 检索、要非 GitHub 远端、要「五年不用碰代码」的托管笔记。

仓库：前端 https://github.com/batnoter/batnoter，后端 https://github.com/batnoter/batnoter-api，图表 https://github.com/batnoter/batnoter-charts。演示：https://batnoter.com。协议均为 MIT（以仓库 LICENSE 为准）。

源微信页曾被验证码拦截；正文以搜狗签名链抓取到的原文要点、官方 README 与 GitHub API 元数据为准，不臆造未公开能力。