为什么第一个工具是 Chat

选型时想过文档问答、文案助手，最后选了最"朴素"的对话：它是验证整条链路（页面 → 大模型 API → 流式渲染）最短路径的工具。后面所有工具——无论文案、问答还是智能体——底层都是这一条链路，先把水管铺通，以后接什么都方便。

关键决策：BYOK（Bring Your Own Key）

第一个要回答的问题：API Key 从哪来？

方案 A 是我在服务端放一个 Key 大家共用——但本站是纯静态站，没有服务端；要加就得引入后端和计费，违背"从零手写、无数据库"的初衷，而且等于提前做了一遍 API 中转生意（那是路线图的后续项）。

所以选了方案 B：BYOK——访客填自己的 OpenAI 兼容端点 + Key，浏览器直连。好处很直接：

• 零服务器成本，纯静态托管扛得住任意流量；
• Key 只存访客自己的 localStorage，不经过任何第三方（包括我）；
• 合规简单：没有代充值、没有账号体系。

代价是访问门槛：用户得有一个 API Key。对目标读者（折腾 AI 的开发者）来说，这门槛约等于零。

技术点一：流式输出

对话体验的生命线是流式。OpenAI 兼容接口的流式响应是 SSE 格式，浏览器端用 fetch + ReadableStream 手动解析：

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = "";
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  const lines = buf.split("\n");
  buf = lines.pop() || ""; // 半行留到下一轮
  for (const line of lines) {
    if (!line.startsWith("data:")) continue;
    const payload = line.slice(5).trim();
    if (payload === "[DONE]") continue;
    const delta = JSON.parse(payload)?.choices?.[0]?.delta?.content;
    if (delta) appendToLastMessage(delta);
  }
}

三个细节：buf.pop() 处理跨 chunk 的半行；[DONE] 是结束标记；解析失败的行直接跳过（有的网关会夹带注释行）。另外做了降级：如果响应不是 text/event-stream，按普通 JSON 处理，兼容不支持流式的端点。

技术点二：混合内容的坑

上线前自测差点翻车：HTTPS 页面调用 HTTP 接口会被浏览器直接拦截（混合内容），报错还长得像 CORS，容易误诊。

规则记一下：

• https:// 页面 → http:// 接口：拦截；
• 例外只有 localhost / 127.0.0.1（浏览器视为安全上下文）。

所以我在本机填 http://localhost:20128/v1（自建网关）一切正常，局域网其他电脑填 http://10.1.74.64:20128/v1 就会被拦。想让局域网机器也能连，得给网关套一层 HTTPS（Caddy 两行配置的事，之后单开一篇）。对公网访客则完全无感——主流模型服务商都是 HTTPS 端点。

技术点三：被"聪明"坑到的 details 组件

配置面板我用了原生 <details>，第一版偷懒写了 open={!ready}（没配好就展开）——结果填完 Key 的瞬间面板"啪"地自动收起，其他字段还没填完。受控组件会忠实执行你给的每个状态，哪怕这个状态并不符合用户意图。改成用户手动控制展开收起，问题消失。

教训：UI 的"自动化体贴"要克制，用户操作到一半的界面不要自作主张。

效果

• 页面：itzhouq.cn/tools/chat，支持流式输出、多轮对话、系统提示词、Ctrl+Enter 发送、停止生成；
• 配置持久化在 localStorage，第二次打开即用；
• 全部代码在本仓库 app/tools/chat/，共一个页面文件，没有新增任何依赖。

下一步

路线图更新：工具矩阵的管子通了。接下来是变现主线——API 中转商店（new-api 底座 + 自建网关做上游），到时候继续公开数据。

为什么是现在

过去我习惯闷头做事：学一个技术、写一个脚本、搭一个服务，做完就完了，没有沉淀，也没有反馈。结果就是：

• 同样的坑踩了两遍，因为上一次的笔记随手丢在了聊天记录里；
• 做出来的东西没人知道，也就没人用、没人提意见；
• 没有外部压力，很多"想做"的事情最后都变成了"想过的"事情。

公开，是这三个问题的共同解法。

我打算公开什么

1. 技术踩坑实录：比如怎么把聚合了全网免费额度的大模型网关跑起来、怎么开放给局域网的其他电脑用，这类文章对同路人是真有用的。
2. 产品构建过程：我会在本站陆续挂上自己的小工具，从选型、写代码到上线的数据，全部记录。
3. 变现尝试：包括但不限于 API 服务、工具订阅、返利合作。赚到多少、亏掉多少，都摊开说。

这个网站的路线图

• ✅ 个人博客网站（你正在看的这个）
• 🚧 每周一篇 build in public 记录
• 🚧 第一个挂载的小工具
• 🚧 大模型 API 服务上线

写在最后

Build in public 最大的好处不是涨粉，而是倒逼自己把事情做完。当一周的进展要在下周公之于众时，拖延就变得很昂贵。

如果你也在做类似的事，欢迎通过 GitHub 或 RSS 订阅找到我，我们一起把事情做完。

免费额度的几种来源

按获取门槛从低到高，大致分四类：

需要特别提醒：第三类（订阅附带）往往在 ToS 里写了"仅限其 CLI/IDE 内使用"，绕过限制拿去开 API 属于灰色操作，风险自担。

聚合的核心：统一网关

思路很简单——在所有通道前面加一层自建网关：

1. 每个通道作为一个 provider 接入网关，填上各自的凭证；
2. 网关对外只暴露一个 OpenAI 兼容接口（/v1/chat/completions）；
3. 请求进来后由网关做路由：按模型能力、速率、剩余额度挑一个可用通道；
4. 单个通道撞了限制（402/403/429）自动 fallback 到下一个。

对上层应用（编码工具、聊天客户端、你自己的产品）来说，它看到的只是一个"永远有额度的模型"，模型名甚至可以只填一个 auto。

真实产出

我把 5 个免注册通道接进自建网关跑了一周日常任务，粗算下来：

• ~16 亿 tokens/月 的名义额度池（各家宣传额度加总）；
• 日常编码、问答、翻译类任务完全覆盖，一周只遇到 2 次限流，重试即恢复；
• 编码场景建议固定走 best-coding 路由组，比 auto 稳定。

下一步

网关只是底座。接下来我会把它接到自己的产品上：小工具用它的 API，中转服务拿它当上游。到时候继续在这里公开数据和代码。

一句话总结：免费额度是零成本的原料，网关是厨房，产品才是菜。

部署主流程

git clone <omniroute> && cd OmniRoute
cp .env.example .env          # 生成 JWT_SECRET / API_KEY_SECRET
npm install
npm run build                 # 务必生产模式
PORT=20128 npm start

接入免注册 provider 通过 Dashboard 完成，然后就能用标准 OpenAI SDK 调用了：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://10.1.74.64:20128/v1",
  apiKey: "sk-xxx", // 网关生成的 key
});

const res = await client.chat.completions.create({
  model: "auto", // 网关自动路由
  messages: [{ role: "user", content: "ping" }],
});

坑一：dev 模式下局域网访问无限转圈

现象：本机 localhost:20128 一切正常，局域网其他电脑打开页面——登录页能出，但点任何东西都转圈。

排查：浏览器 DevTools 看到大量 /_next/hmr 请求被 CORS 拦截。根因是 Next.js dev 模式的热更新（HMR）WebSocket 只认 localhost，即使 .env 里配了 HOSTS 白名单也不够。

解法：局域网使用必须走生产模式：

npm run build
PORT=20128 npm start

同时在 next.config.mjs 的 allowedDevOrigins 里加入本机局域网 IP 兜底（仅影响 dev 模式）。

坑二：npm 11 会静默跳过原生模块

构建报 better-sqlite3 相关错误。原因：npm 11 对带原生编译的依赖处理有变化，某些情况下 npm install 没有真正编译它。

解法：显式补装并看到编译日志：

npm install better-sqlite3 --no-save --foreground-scripts

--foreground-scripts 让 node-gyp 的输出直接打到终端，方便确认编译成功。

坑三：Windows 防火墙默认拦入站

局域网其他电脑连不上，但本机 telnet 正常——典型的 Windows 防火墙入站拦截。给两个端口开规则（限制来源网段，别全放）：

New-NetFirewallRule -DisplayName "OmniRoute Dashboard" -Direction Inbound `
  -Protocol TCP -LocalPort 20128 -RemoteAddress 10.1.0.0/16 -Action Allow

• 20128：Dashboard + API（需要开放）
• 20132：Live WebSocket（需要开放）
• 20131：仅本机使用的服务（不要开放）

效果

完成后，局域网里任何一台电脑都能：

• 打开 http://10.1.74.64:20128/dashboard 管理通道；
• 用 OpenAI 兼容客户端把 base URL 指到 http://10.1.74.64:20128/v1，模型填 auto，白嫖聚合额度。

两个小提醒

1. 局域网 IP 是 DHCP 分配的，一旦变了要同步更新 .env 白名单和防火墙规则——建议给这台机器配静态 IP 或 DHCP 保留。
2. auto 路由偶尔会先撞到某个免费层的限制返回 402/403，重发一次就会换通道；嫌烦可以在 Dashboard 停用不稳定的 provider。

整个过程中最值得记的一句话：本机能跑 ≠ 局域网能用，dev 模式 ≠ 生产模式。

技术选型

• Next.js 16 + React 19 + TypeScript：生态成熟，SEO 开箱即用，以后加小工具/商城都是同一个框架；
• Tailwind CSS v4：原子类 + CSS 变量做主题，深浅色切换只需一个 dark class；
• unified/remark/rehype 管线渲染 Markdown，不引入 MDX、不引入 CMS——内容就是 content/posts/*.md，git 即后台。

依赖刻意保持在个位数，博客的核心是内容和排版，不是技术堆砌。

Markdown 管线

一篇文章从 .md 到 HTML 的流水线：

const processor = unified()
  .use(remarkParse)              // 解析为 AST
  .use(remarkGfm)                // 表格/任务列表/删除线
  .use(remarkRehype)             // 转 HTML 树
  .use(rehypeSlug)               // 标题加 id
  .use(rehypeAutolinkHeadings)   // 标题可点击锚点
  .use(rehypeHighlight)          // 代码高亮
  .use(rehypeStringify);         // 输出 HTML 字符串

有个细节：文章页右侧的目录（TOC）需要标题的 id。我单独用 remark-parse 遍历 AST 提取 h2/h3，再用 github-slugger 生成 slug——它和 rehype-slug 内部用的是同一个库，保证目录锚点能对上。

内容层

frontmatter 用 gray-matter 解析，字段极简：

---
title: 文章标题
date: 2026-10-03
tags: [Next.js, 建站]
summary: 一句话摘要，会出现在列表页和 SEO 描述里
---

draft: true 的文章在开发模式可见、生产构建自动剔除，方便写一半的东西先躺仓库里。中文阅读时长按 CJK 字符数（380 字/分钟）+ 英文词数（200 词/分钟）估算。

主题与配色

设计走"纸感编辑风"：米白纸底 + 墨色正文 + 朱砂红做点缀色（链接 hover、选中高亮、标签）。所有颜色收敛为 6 个 CSS 变量，深色模式只是换了一组变量值：

:root { --accent: #c73e3a; --bg: #faf8f5; /* ... */ }
.dark { --accent: #f08080; --bg: #0f0d0c; /* ... */ }

防闪白的关键是在 <head> 里塞一段同步脚本，首帧渲染前就把 dark class 挂到 <html> 上。

站点功能清单

这些全部是标准 Next.js 能力，没用第三方服务：

为什么不直接用模板

模板（比如 tailwind-nextjs-starter-blog）很好，但我想得到三样东西：

1. 对每一行代码的理解——以后要做分发的、要挂工具的、要接支付的，都得自己改；
2. 恰好需要的功能——没有后台、没有数据库、没有用户系统，也就没有攻击面；
3. 可迁移的判断力——亲手写一遍 unifed 管线，下次遇到任何渲染需求都不虚。

全部代码就在这个仓库里，欢迎 fork 自用。下一篇我会写怎么在这套底座上挂第一个小工具。