「云衣花容晓梦迷蝶」

免费栈的七个硬限制：Cloudflare 知识库踩坑清单

2026-10-21T12:30:00.000Z

“不绑卡、不租服务器，把知识库跑起来”这句话是对的。但“跑起来”和“稳定跑”之间，隔着七个具体的数字限制。它们不会在写代码时提醒你，只会在批量任务跑到一半时给你一个 400。

下面每一条都是我在这个项目里真实撞上的，附上绕过方式和代价。

1. Workers AI 单请求 60000 token

嵌入模型不是按“条”计费，而是按 token。一次把 200 个 chunk 塞进去，最可能的结果是请求被拒，而不是排队。

我的做法是先算预算再分批：用 tokenizer 估算每段文本的 token 数，累加到接近 5 万就切一批，留出 20% 余量给模型自己的模板开销。批内再设一个条数上限，防止“200 条极短文本”这种边界情况。

代价是：请求数变多，总耗时线性增长，并且必须在失败时能定位到具体批次——所以每一批都带 batch_index 落日志，重试只重跑失败批次。

2. KV 单个 value 上限 25MiB

大产物（全量索引 JSON、图谱快照）写不进 KV。这个限制最初表现为 413，后来发现不是请求体太大，而是 value 太大。

绕法有两种：

拆成多个 key，用 manifest.json 记录分片顺序；
干脆不进 KV，把产物写进仓库，由 Pages 直接托管。

我选了后者：图谱和规范判定的结果本来就需要公开访问，放进 KV 反而多一次鉴权。

3. D1 单语句绑定参数约 100 个

WHERE id IN (?, ?, ...) 这种写法在 D1 上有绑定参数上限。超过之后不是慢，而是直接报错。图谱的邻域查询一次要查几十个节点、每个节点再查两边边，很容易超。

处理方式是把一批 ID 切成多个 IN 子句，分批执行再在内存里合并：

-- 每一批最多 90 个占位符，留一点余量
SELECT id, src, dst, rel, weight
FROM kg_edges
WHERE src IN (?, ?, ...) OR dst IN (?, ?, ...);

注意 src IN 和 dst IN 是两组占位符，所以实际单批只能放 45 个节点。这个数字要写在代码常量里，而不是散落在调用处。

4. 免费账户不支持子域名独立 Zone 路由

想让 api.example.com 指向 Worker，最直觉的做法是配一条 Zone Route。但免费套餐里，子域名的路由权限并不完整，配置会静默失效或直接拒绝。

最后的方案是同源转发：在 Pages 项目里放一个 Function，把 /api/* 转发到 Worker。好处不止是绕开权限：

门户和 API 同源，Access 的登录凭据可以直接带上，不会反复弹验证码；
前端不用处理跨域和预检；
Cookie、CORS、鉴权都少一层心智负担。

代价是多了一跳转发，Worker 里拿到的客户端 IP 需要从转发头里取，而不是直接信任 CF-Connecting-IP。

5. 配了 ACCESS_AUD 之后，所有请求都 401

这是最容易踩、也最容易被误判为“鉴权失败”的一条。

Cloudflare Access 校验 JWT 时，需要 ACCESS_AUD。一旦你把它当成唯一凭据，那些走 Bearer Token 的机器调用（CI、脚本、MCP）就全部被拒。正确做法是双通道：

有 Cf-Access-Jwt-Assertion 头就校验 JWT；
没有就回退校验 Authorization: Bearer ；
两者都没有才 401。

关键是第 1 步失败时要明确区分“没带 JWT”和“JWT 无效”：前者应该继续走第 2 步，后者应该直接拒绝。

6. Workers 域会被边缘拦截

在 Worker 内部回调 Pages 的接口时，用 *.workers.dev 域名有时会被边缘拦掉，返回 403 或直接超时。原因不在代码，在路由层。

解决办法是回调一律走 Pages 项目自己的域名。这条经验没有文档，只有日志：同一个请求换域名就通了。

顺带一提，本机访问 Cloudflare API 也存在“部分 IP 不可达”的情况，表现是单个请求卡两分钟才超时。我的处理是启动时并行探测多个可用 IP，之后复用连接，避免每个请求都重新握手。

7. 枢纽节点会让邻域查询爆炸

图谱里总有那么几个节点，连向所有文档：device、ios、tools。从它们出发做 2 跳邻域，结果会瞬间上千条，前端渲染卡死，查询也超时。

三条约束必须同时存在：

节点总数上限（例如 200）；
每层扩展数上限（例如 50）；
禁止穿透枢纽节点：邻居数超过阈值的节点只返回自身，不再向下展开。

前两条控制结果规模，第三条控制深度。只做前两条的话，查询还是会先算完再截断，CPU 时间照烧。

还有一条：把重计算放到离线管线

规范判定曾经跑在请求里，结果经常因为单请求 CPU 时间限制失败。后来把它整体移到离线管线：构建时算好、写进产物、请求只读结果。

这是架构层面的取舍：牺牲了“实时性”，换来了稳定性和可预测的延迟。对一个个人知识库来说，这个交换非常划算。

总结

免费额度不是“没有成本”，而是把成本从账单转移到了工程细节：

限制	触发表现	绕法
60000 token	嵌入请求 400	预算分批 + 批次重试
25MiB / value	KV 413	分片或改走 Pages
~100 绑定参数	D1 绑定报错	拆批 IN 查询
Zone 路由权限	配置无声失效	Pages Function 同源转发
ACCESS_AUD	机器调用全 401	JWT + Bearer 双通道
Workers 域	回调 403	走 Pages 域名
枢纽节点	邻域爆炸	限节点 + 禁穿透

这七条都不难，难的是它们只会在你忘了的时候出现。现在它们被写进了项目的约束清单，下次换项目还能直接复用。

知识图谱：从 3 条边到 15955 条边

2026-10-21T02:00:00.000Z

起点：一个装饰性图谱

我的知识库门户里一直有个”图谱”页面：力导向布局、节点按来源着色、能拖拽缩放。
看起来很像回事。

直到我看了一眼数据：

nodes=1104  links=3

1104 个节点，3 条边。 边全部来自正文里的 [[双链]]，而我几乎不写双链。
这个页面唯一的用途是截图好看。

为什么不直接用 LLM 抽

2026 年这个方向最热的是 GraphRAG（微软）和 LightRAG（港大），
它们的做法都是：用 LLM 从文本里抽实体和关系。

我想过，但算了三笔账：

额度：免费 10,000 neurons/天。用 LLM 抽 1187 篇文档，一次就可能吃掉大半，
而且抽取质量不稳定，重跑一次结果就变；
可复现：规范判定要求”同输入同输出”。LLM 抽出来的图，今天和明天不一样，
基于它做的判定就没法解释；
可维护：词表写错了，我能定位到具体词条；模型抽错了，我只能”再抽一次看看”。

所以我选了确定性路线：结构化事实优先，LLM 留到以后按需补充。

三层抽取

层	来源	产出	覆盖率
L0 结构事实	路径、front-matter	文档→目录/来源/设备/标签	100%
L1 显式链接	`[[双链]]`、Markdown 相对链接	文档→文档	约 1250 条
L2 词典实体	内置词表 + 正则	文档→实体	约 540 条

L0 是覆盖率的关键：每篇文档都”属于”某个目录、来自某个工具、在某台设备上。
这些关系不需要”理解”，只需要解析。先把确定的东西全拿到，再谈语义。

最终：

nodes=1649  edges=15955
belongs_to 9875  tagged 1907  mdlink 1248
from_source 1187  on_device 1187  mentions 539

三个必须处理的坑

坑 1：枢纽节点会毁掉可视化

device 和 source 这两个节点几乎连到所有文档。从任意文档出发走两跳：

文档 → 设备 → 另外 295 篇文档

图上一秒变毛线球。解法是展示但不穿透：枢纽类节点画出来，但不再从它继续扩展；
再加单层 60 个节点的上限。

坑 2：伪双链

正文里的 Markdown 示例会被误当成真链接：

比如可以写 [[{ "tag": "md", "text": "..." }]]

原来的 31 条”断链”里，有 24 条是这种噪声。加了一条过滤规则
（长度、非法字符、协议前缀）后剩 7 条真实断链。

坑 3：中文分词

FTS5 用 unicode61，会把一整串中文当成一个 token。
所以「索引管线怎么分批嵌入」这种整句查询，MATCH 命中是 0，LIKE 兜底也难。
短期靠”查两个关键词”，中期要接 jieba 预分词。

规范判定：让规则可写、可复现

规则放在内容仓的 policy/rules/*.yaml，和笔记一起版本化：

- id: fm.required
  name: front-matter 必填字段
  kind: front_matter
  severity: error
  params:
    required: ["title", "source"]

关键设计是 kind 是封闭枚举，YAML 只传参数、不写 SQL。
内容仓是可写的（笔记软件、网页、客户端都能改），如果规则里能塞 SQL，
等于给内容仓开了一个注入面。

结果

1187 篇 × 13 条规则 → 2068 条判定记录
违规 881 条：warn 125 + info 756，error 0
按规则：doc.orphan 756 / title.dup 107 / naming.no_space 11 / 断链 7

error = 0 说明敏感信息扫描（私钥、API Key）在内容仓里零命中——这是我最想看到的结果。

至于那 756 条”孤立文档”：它们全是机器导入的会话记录，本来就没有入链。
规则的意义不是消灭数字，而是让数字可解释。

还没做的

传递闭包目前只到 10 轮，复杂层级还没压测；
图谱的社区聚类（Leiden）没做——要做也打算用纯 TS，不调 LLM；
增量判定：现在每次全量重算，规模再大就得改。

下一步如果做，我会先做增量，而不是做更花哨的图算法。
因为真实使用中，”改一篇笔记后多久能看到判定更新”比”图好看不好看”重要得多。

用 Cloudflare 免费额度搭一套私有知识库

2026-10-20T02:00:00.000Z

架构一览

Markdown 仓库（私有）
   │ git push
   ▼
GitHub Actions  ── 抽取/切分/嵌入/判定 ──▶ Cloudflare
                                            ├─ D1（文档、切片、三元组、判定）
                                            ├─ Workers KV（索引产物）
                                            ├─ Vectorize（语义向量）
                                            └─ Worker（查询 API）
                                                   ▲
                                     Pages + Access（只给自己看）

选这套的原因很朴素：没有一个组件需要常驻服务器。
Neo4j、OpenSPG 这类图数据库确实更强，但要一台机器一直开着，就不符合”零成本”。

四个撞过的硬限制

1. 嵌入请求有 6 万 token 的总上限

第一次跑索引，第一批就 400：

AiError: Max context reached 99392 tokens but model supports only 60000

原因是按固定 64 条一批，而中文分片每片接近 900 token，64 × 900 直接顶破。
改成按估算 token 预算动态分批，并对单条做字符上限保护；仍失败就二分重试。

2. KV 的单键上限是 25 MiB

索引产物里有一份 embeddings.jsonl，88 MB，PUT 直接 413：

content size of 87905171 bytes exceeds maximum allowed size of 27MiB

后来发现这个键运行时根本没人读——向量在 Vectorize 里，Worker 只读
docs.json 和 meta.json。删掉即可。先查清楚谁在读，再决定怎么存。

3. D1 单条语句的绑定参数有上限

想在一条 SQL 里从 300 个节点取边：

WHERE e.src IN (?,?,...) OR e.dst IN (?,?,...)   -- 600 个参数

直接 500。官方文档没写这个数，实测大约 100。改成拆两条 SQL、每批 50 个 id，
再用 id 去重合并。

4. 免费神经元额度是 10,000/天

全量重建一次约 3000 neurons（4290 片 × 约 700 token），
所以一天最多重建三次。这直接决定了：增量索引不是”优化”，是”必需”。

一个反直觉的设计：判定放在离线

一开始我想把规则引擎放进 Worker，请求时现算。算了一下：1187 篇 × 13 条规则 ≈ 1.5 万条判定，
而 Workers 免费档单请求 CPU 只有 10 ms——跑不完，也写不完。

于是把判定挪到管线里离线跑（一次约 3 秒），Worker 只做”读”。
副产品是：判定结果成了可查看的历史快照，而不是每次请求都变的临时值。

代价与收益

项	结果
月成本	0 元
全量索引耗时	约 4 分钟（Actions）
查询延迟	毫秒级（D1 / KV 命中）
规模上限	Vectorize 5M 维度，当前已用 87.8%

最后一行是唯一的隐患：知识库再涨约 14%，语义检索就会超限。
到那天的退路已经想好了——降级成纯关键词检索，功能不崩，只是没那么”聪明”。

小结

免费额度的真正价值不是”省钱”，而是逼你把架构想清楚：
不能堆组件，就得想清楚每一层到底在解决什么问题。
这套系统里，真正不可替代的只有两件事——分片策略和规则。
其余的，都是可以替换的实现细节。

为什么我要做一个自己的知识库

2026-10-18T02:00:00.000Z

起因

我的笔记散在四个地方：Obsidian 里一部分、几个 AI 工具的会话记录里一部分、浏览器书签里一部分、
还有一部分在「等我有空再整理」的文件夹里。

结果是：收藏越多，越找不到。

真正让我下决心的是一个很具体的问题——我想找半年前写过的一段
「Cloudflare Workers 怎么复用连接」的笔记，翻了三个 App 都没找到。
那一刻我意识到，我缺的不是存储，是检索和结构。

我想要的到底是什么

我把需求写成了四条，后来整个系统都是围绕这四条长出来的：

一个地方：所有笔记最终汇到一个仓库，不管原来在哪；
搜得到：关键词能搜，语义也能搜；
看得见关系：这篇笔记和哪些文档有关，为什么有关；
判得准：我的知识库有没有违反自己定的规范（缺元数据、断链、过期、含密钥）。

第 4 条听起来最玄，其实是最后落地时最有用的一条——见下面。

为什么不用现成的

我试过几个方向：

云笔记 + 全平台同步：同步没问题，但检索只有关键词，没有关系；
现成的 RAG 工具：能问答，但索引是黑盒，我改不了它的分片策略；
笔记软件自带的图谱：好看，但只是”双链的可视化”，不是可计算的图。

共同的问题是：它们不让我碰索引。

而知识库的价值恰恰在索引层——分片怎么切、实体怎么抽、规则怎么判。
所以我决定自己写一个，只在索引层花功夫，其他都尽量简单。

最后的形态

存储：Markdown 仓库（GitHub 私有仓），跨设备靠 git 同步；
索引：GitHub Actions 里跑，产出切片、向量、三元组、判定结果；
查询：Cloudflare Worker + D1 + Vectorize，全部落在免费额度内；
入口：一个网页门户 + 一个桌面客户端 + 一套 MCP 工具。

关键取舍是：不绑卡。所以没有用 R2，索引产物直接写 Workers KV，
原文由 Worker 通过 GitHub API 直读。

第 4 条需求意外地有用

我原本以为”规范判定”是个锦上添花的功能，直到它第一次跑出结果：

warn  标题重复    knowledge/memory/dsh/profiles/desktop/cordis.yml
      与 1 篇文档同名，容易混淆
warn  双链断链    31 处 → 过滤掉代码示例里的伪链接后剩 7 处
info  孤立文档    756 篇没有入链

756 这个数字很刺眼，但它是对的：那批文档是机器导入的会话记录，本来就没有入链。
规则的价值不是”发现问题”，而是”让问题可度量”。有了度量，才知道先修什么。

下一步

语义检索和关系图谱已经能用了，但我还想加两件：

中文分词后再进全文索引（现在 unicode61 会把整句中文当成一个 token）；
增量索引（现在每次全量重建都吃一次嵌入额度）。

这两件事都不难，难的是别把系统搞复杂。这个博客大概会记录它们。

「云衣花容 晓梦迷蝶」