从零搭建本地 AI 平台：一次完整开发复盘

从对话界面到知识库检索，再到桌面端打包，一个本地 AI 平台看似只是把若干成熟组件组合起来，真正落地时却会遇到架构边界、原生模块兼容、密钥存储和流式中断等一连串工程问题。下面结合一次完整开发经历，梳理这些问题的处理方式及其背后的取舍。

从 0 到 1 做一个本地 AI 平台，我学到了什么

一个人、一台机器、一套代码，走完产品全流程的复盘。

这个项目是什么

一个私人 AI 助手：对话、知识库 RAG、自定义助手人设，Web 模式和桌面端（Electron）双交付。技术栈是 Next.js 14 全栈 + Electron + SQLite + pnpm Monorepo。

从零到能打包交付，踩了不少坑，也沉淀了一些方法论。

学到的 10 件事

1. 分层是一个人开发的护城河

Monorepo + 单向依赖 + 服务层，让改动有边界。改数据库不影响前端，换供应商不影响 UI。没有分层，一个人维护全栈就是噩梦。

2. 原生模块的 ABI 问题要提前想清楚

Electron + better-sqlite3，差点让我放弃桌面端。最终方案是 fork 真实 Node 子进程，原生模块跑在和编译时一致的运行时里。遇到 dlopen 报错，先查 NODE_MODULE_VERSION。

3. 密钥安全是底线，不是可选项

API Key 明文落库 = 把钥匙放在门口。加密落盘 + 永不返回明文 + 本地服务令牌守卫，三层防护缺一不可。用户把 Key 交给你，你要对得起这份信任。

4. 流式对话的中断语义要设计好

用户点停止，已生成的内容不能丢。abort 后写回已生成内容、消息置 stopped，是体验细节，也是工程素养。

5. 小体量数据别上重型组件

几百篇文档的知识库，SQLite + sqlite-vec 完全够。归一化向量后 L2 等价余弦，一个文件搞定。不要为了「技术先进」引入运维负担。

6. 统一 API 契约省掉一半联调时间

{ success, data } / { success, error: { code, message } } + 领域错误码，前端零猜测。前后端类型同源（Zod schema），改一处全链路生效。

7. 测试里绝不调真实 API

慢、贵、不稳定。100% mock 外部调用，测试验证的是你的代码逻辑，不是模型质量。依赖注入让 mock 变得简单。

8. 300 行规则是给「未来的自己」的礼物

超长文件 = 认知过载 = 改不动。设个数字红线，用脚本强制，逼自己拆。维护成本在写的时候就付了，后面都是收益。

9. 一个人也要有 CI

没人评审，CI 就是 reviewer。typecheck + lint + 行数 + 覆盖率，全绿才提交。不是为了好看，是为了改代码不害怕。

10. 文档不是交付后的事

架构文档、接口文档、模块设计，边写代码边更新。代码会忘，文档不会。三个月后回来，文档是你和过去自己的对话。

踩过的坑（避坑指南）

坑	症状	解法
Electron fork 子进程 ABI 不匹配	窗口 30s 不出现	打包内置真实 Node，fork 指定 execPath
fork 无 error	子进程崩溃无日志	加 error/exit ，转发 stdout/stderr
Smart App Control 拦截未签名 exe	打包产物无法启动	用官方签名 electron.exe 作为宿主加载 asar
SSE 半包解析失败	流式内容错乱	逐字符状态机 parser，不依赖完整行
密钥明文出参	安全漏洞	仓储层分脱敏视图和含密文行，服务层才可取密文
数据库写入非单一事务	崩溃后数据不一致	四步写库包进一个 db.transaction
未子进程端口回收	重启端口被占	will-quit 先 SIGTERM 再 SIGKILL

独立开发的心态

一个人做全栈产品，最大的挑战不是技术，是取舍：

• 什么该自己做，什么用现成的（SQLite 不自己写，UI 组件用 shadcn）
• 什么现在做，什么以后做（Ollama 适配器先预留，不实现）
• 什么是必须的，什么是锦上添花（密钥安全必须，主题切换锦上添花）

不要追求完美，追求能用、好维护、能迭代。

下一步

这个项目还能继续：

• Ollama 本地模型适配器（完全离线）
• 多模态（图片理解、文档解析增强）
• 对话导出 / 数据备份
• 插件系统（函数调用）

但核心闭环已经跑通：配置供应商 → 创建助手 → 对话 → 知识库 RAG → 桌面打包。

写在最后

从 0 到 1 做一个产品，技术只是其中一部分。架构决策、工程规范、测试体系、文档习惯，这些「非功能」的东西，决定了项目能不能活下去、能不能长大。

希望这个系列能给你一些启发。如果你也在做自己的 AI 应用，记住：先让它跑起来，再让它跑得好。