技术2026年11月20日· 约 19 分钟

用 AI 从零搭一个全栈聊天应用:萤火虫 Firefly 的架构、落地与踩坑

#全栈开发#聊天应用#AI辅助#Next.js
Twitter 微博

用 AI 从零搭一个全栈聊天应用:萤火虫 Firefly 的架构、落地与踩坑

用 AI 从零搭一个全栈聊天应用:萤火虫 Firefly 的架构、落地与踩坑

在线体验地址:https://www.testauto.cn/chat

游客身份无需注册,点开即进;注册后解锁群机器人、积分头衔、私聊、匿名速聊与反馈举报。

本文是一份可复用的工程复盘:一个内部聊天工具是如何用 AI 辅助完成从数据模型、后端接口、实时通信到后台管理的完整闭环,以及哪些地方必须由人把住方向盘。


1. 项目背景与设计目标#

萤火虫(Firefly)是一个面向团队内部的轻量聊天工具,产品约束只有一句话:工作时间提灯聊天,下班后自动归林。围绕这句话衍生出几个真实需求:

  • 降低进入门槛:游客零注册进入,但要把用户留下来必须给注册足够的理由;
  • 团队场景的治理能力:群聊、私聊、拉黑、举报、敏感内容拦截、管理员处置;
  • 让工具「有人气」:机器人、签到、积分、成语接龙、天气、节日倒计时等轻游戏化能力;
  • 运维成本要低:单进程、单数据库、一条命令启动,不引入消息队列和独立缓存服务。

最终实现是一个 Next.js 16 + React 19 + TypeScript 的全栈应用,数据库用 SQLite / Prisma,实时通信用自建 WebSocket 服务,全文约 1.5 万行 TypeScript(含词库与数据文件),15 个数据库模型,40 余个 API Route。

萤火虫首页:夜林萤火主题

图 1:默认「夜林萤火」深色主题,右上角可切换白昼主题,偏好写入 localStorage。


2. 技术栈与整体架构#

层次 选型 说明
前端 Next.js 16 App Router + React 19 + Tailwind CSS 4 服务端组件与客户端组件混用,样式原子化
后端 Next.js Route Handlers 40+ 个 REST 接口,业务逻辑集中在 src/lib
实时 自定义 server.js + ws 同一进程提供 HTTP、HTTPS 与 /ws 长连接
数据 SQLite + Prisma 5 prisma db push 同步结构,无 migrations 目录
认证 jose (JWT HS256) + bcryptjs HttpOnly Cookie,注册用户 7 天,游客会话级
安全 三层敏感词 + 正则规则 + sharp 图片初筛 命中即打码、拦截或封禁,见 3.3 节
运维 scripts/server.sh 启动前自动 db push / generate / build

架构上最关键的一个决定是:不让 WebSocket 直接写数据库。自定义服务器只负责长连接与身份校验,消息的发送仍然以用户 Cookie 回调站内 REST 接口,因此敏感词、封禁、刷屏、工作时间等校验只有一份实现。

                       ┌──────────────────────────────┐
   浏览器 ──HTTP───────▶│ Next.js Route Handlers       │
   浏览器 ──/ws────────▶│ server.js (WebSocketServer)  │
                       │  · 校验 firefly-session JWT   │
                       │  · 心跳 25s,半开连接自动清理 │
                       └──────────┬───────────────────┘
                                  │ send 消息时带 Cookie
                                  ▼
                       ┌──────────────────────────────┐
                       │ POST /api/conversations/:id/  │
                       │          messages             │
                       │  时间窗 → IP → 封禁 → 审核     │
                       │  → 刷屏 → 写库 → 机器人       │
                       └──────────┬───────────────────┘
                                  │ publish({type:'message', conversationId})
                       ┌──────────▼───────────────────┐
                       │ 全站广播(只发事件标识)      │
                       │ 客户端收到后按需重新拉取数据  │
                       └──────────────────────────────┘

实时层刻意做得很薄。服务端广播的事件体只有几十字节:

// src/lib/realtime.ts
export type RealtimeEvent =
  | { type: 'connected' }
  | { type: 'message'; conversationId: string }
  | { type: 'conversation' }
  | { type: 'pending' };

export function publish(event: RealtimeEvent) { (globalThis as any).__fireflyWsBroadcast?.(event); }

AI 协作提示:让 AI 实现实时功能时,它很容易把整条消息塞进 WebSocket payload,然后前后端各维护一份「消息已读/撤回」状态,最终两边对不上。把「事件只传 ID,数据从 REST 拉」写成架构约束,能省掉大量状态同步 bug。


3. 核心模块实现#

3.1 身份体系:游客零摩擦,注册给足理由#

游客进入时不弹表单,而是由 getCurrentUser() 自动创建身份:从「修饰词 × 名词」组合里挑一个自然昵称(如「温柔海风」「贪吃小猫」),避开 30 天内已用过的名字,同时按 IP + User-Agent 复用原有游客账号,避免刷新一次就换人。注册用户则使用手机号 + 真实姓名,密码 bcrypt 哈希,JWT 写入 HttpOnly Cookie,有效期 7 天。

// src/lib/auth.ts(节选)
const token = await new SignJWT({ uid: userId })
  .setProtectedHeader({ alg: 'HS256' })
  .setExpirationTime('7d')
  .sign(getAuthSecret());

cookieStore.set('firefly-session', token, { httpOnly: true, sameSite: 'lax', path: '/', ...(remember ? { maxAge: 60 * 60 * 24 * 7 } : {}), // 游客为会话级 Cookie });

游客能看群聊、发消息;注册后才开放私聊、匿名速聊、积分头衔、反馈举报和图片上传。这条边界既是产品策略,也是数据治理需要——举报要能找到责任人,积分要挂在稳定账号上。

注册页:手机号 + 真实姓名 + 昵称 + 密码

图 2:注册页把「真实姓名用于找回密码」写在表单说明里,注册后立刻登录态直达聊天。

3.2 消息发送管线:所有校验只有一份#

消息接口是这个项目最值得看的文件。一次发送会依次经过:

  1. IP 封禁检查、账号封禁检查;
  2. 工作时间闸门(非工作日或 8:30–17:30 之外直接 403);
  3. 图片路径白名单:/^\/uploads\/[\w.-]+$/,杜绝外链注入;
  4. 内置三级词库 + 后台自定义词打码;
  5. 色情/敏感链接命中则永久封禁账号与关联 IP;
  6. 涉政表态正则拦截,当天累计 3 次封禁 3 天;
  7. 成员权限与连续刷屏(同内容连续 3 条)检查;
  8. 写库 → 机器人回复 → 成长值 → 广播。
// src/app/api/conversations/[id]/messages/route.ts(节选)
if (!isWorkingHours()) {
  return NextResponse.json({ error: '下班了,萤火虫已归林 🕯️' }, { status: 403 });
}
const moderated = moderateText(text, customWords);
const finalContent = moderated.text || (image ? '[图片]' : '');

// 只接受本站上传路径 const image = typeof imageUrl === 'string' && /^/uploads/[\w.-]+$/.test(imageUrl) ? imageUrl : null;

这套顺序不是随意排的:便宜的检查放前面,写库放最后。被封 IP 的请求不会触发任何数据库查询;命中违规内容的请求不会产生一条「成功发送」的消息。

聊天主界面:消息引用、机器人回复、头衔与输入框

图 3:桌面端聊天页。机器人回复带「AI 机器人」标识,用户输入框支持 @ 提及、表情、图片与粘贴。

3.3 内容安全:规则、正则与轻量图像初筛#

文本侧把风险分成 normal / danger / extreme 三级,用等长 * 替换敏感词,保留句子可读性;同时提供前后文例外(如「你妈妈」不该被「你妈」误伤),用零宽断言实现:

const prefix = safePrev ? `(?<!${safePrev.map(escapeRegExp).join('|')})` : '';
const suffix = safeNext ? `(?!${safeNext.map(escapeRegExp).join('|')})` : '';
const re = new RegExp(prefix + escapeRegExp(word) + suffix, 'gi');

此外还有两类「不留情面」的规则:色情网站关键词与链接命中直接永久封禁;涉政表态用正向/反向两套正则匹配「动作词 + 称谓」,当天第 3 次触发封禁。这些规则在代码里都是具名常量(POLITICAL_BAN_THRESHOLD、SPAM_REPEAT_LIMIT),便于人工审计策略,而不是散落在 if 里的魔法数字。

图片侧没有引入重型模型,而是用 sharp 把图片缩到 72×72,转 YCbCr 计算肤色占比,阈值默认 0.62;再用亮度标准差 ≥ 10 排除纯色截图,避免误伤:

// src/lib/image-moderation.ts(节选)
const cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b;
const cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b;
if (y > 50 && cb >= 77 && cb <= 132 && cr >= 133 && cr <= 178) skin++;
return { flagged: score >= threshold && stdLuma >= MIN_LUMA_STD, score };

这是启发式初筛,不是 NSFW 模型。它的价值在于用几乎零成本挡住最明显的违规图片,并明确标注了局限——AI 生成这类代码时常常把「启发式」写成「已实现内容安全」,需要人在注释和文档里把边界说清楚。

3.4 群机器人:规则引擎比想象中复杂#

「萤火虫小助手」不是调用大模型,而是一个确定性规则引擎,好处是离线可用、响应稳定、零调用成本。能力包括签到、积分、打劫、成语接龙、脑筋急转弯、天气、节日倒计时、今日运势、群活跃度、入群欢迎和每日提示,后台有 13 个独立开关。

萤火虫小助手设置

成语接龙看似简单,但要避免 AI 生成出「一局就死」的实现。这里的做法是:词库按首字建立 Map 索引;开局只从 600 条高频成语中挑「尾字还有下文」的;跟牌时按「剩余可接数量」打分,从前 5 名里随机选,既不容易走进死路又保留变化。

// src/lib/bot.ts(节选)
const scored = candidates
  .map((idiom) => ({
    idiom,
    score: (IDIOM_BY_FIRST.get(idiom.slice(-1)) ?? [])
      .filter((next) => next !== idiom && !state.used.has(next)).length,
  }))
  .filter((item) => item.score > 0)
  .sort((a, b) => b.score - a.score)
  .slice(0, 5);

笑话/脑筋急转弯维护「最近 200 条不重复」的滑动窗口,接龙状态 2 小时过期、谜题 30 分钟过期,轮询时用 dailyCache、membershipCache 避免反复查库。这些细节是 AI 第一版通常不会写的,需要人用真实交互把它「磨」出来。

3.5 时间闸门与匿名速聊#

工作时间由环境变量驱动(WORK_START_HOUR=8.5、WORK_END_HOUR=17.5、WORK_DAYS=1,2,3,4,5),前端展示下班倒计时,后端在同一个 isWorkingHours() 上做拦截,前后端口径一致。

匿名速聊只允许注册用户使用:点击按钮后优先匹配当天登录过的伙伴,匹配不到则由机器人兜底陪聊;会话标记为 anonymous 且 expiresAt 当天有效,读取消息时对对方昵称和头像做匿名化,不暴露真实身份。


4. AI 协作开发的真实工作流#

这个项目大量使用 AI 生成代码,但真正让交付可控的不是「提示词写得妙」,而是下面几个工程习惯。

4.1 规格先行:README 就是长期提示词#

在写任何业务代码之前,先把技术栈、目录结构、环境变量、功能边界写进 README。后续每次让 AI 加功能,不需要重新解释「我们用 Prisma / SQLite / App Router」,也不会出现 AI 自作主张引入 Redux 或新 ORM 的情况。文档在这里不是交付物,而是约束 AI 的上下文。

4.2 数据模型先于界面#

先定 schema.prisma,再让 AI 根据模型生成 API 和页面。用户 ID 从字符串 cuid 改成数字自增、匿名会话加 expiresAt、机器人开关收敛到 BotConfig 单行配置,这些决策都在模型层完成,改动只影响一处。反面教材是边写页面边加字段,最后前端 types、API 校验、数据库三处对不上。

4.3 用可执行脚本做验收#

项目里保留了一个 Playwright 端到端脚本,覆盖注册、匿名速聊、机器人兜底、消息发送与会话销毁等关键路径。AI 改完代码后跑一遍,失败信息直接反馈给 AI 修复,比人肉点页面再口头描述高效得多。

// .tmp-ui-full-test.mjs(节选)
check('兜底匹配提示', await waitText(a, '小助手先陪你聊聊'));
check('匿名会话不显示拉黑按钮',
  (await a.locator('button[title="拉黑对方"]').count()) === 0);
check('机器人消息带 AI 机器人标识',
  (await a.getByText('AI 机器人', { exact: false }).count()) > 0);

4.4 人机分工#

环节 AI 承担 人承担
需求拆解 把一句话扩展成功能清单与验收点 砍掉伪需求,确定产品边界
样板代码 CRUD 接口、表单页面、类型定义 定义数据模型与命名规范
UI 主题、响应式布局、动效、空状态 审美取舍、可用性审查
安全 按规则生成校验代码 设计风险分级、封禁策略、审计日志
性能 基础实现 加索引、缓存、TTL、边界保护
测试与文档 生成测试脚本、README、中英双语 跑验收、核对事实、决定上线

4.5 踩坑记录#

现象 根因 修法
游客刷新即换身份 每次都创建新 User 按 IP + UA 复用游客账号,主动「换个身份」才新建
WebSocket 推送后状态错乱 payload 带完整消息,多处各自维护状态 事件只带 conversationId,客户端重新拉取
成语接龙快速死局 随机选词不看尾字可接性 打分排序 + 前 5 随机,状态 2 小时过期
纯色截图被判违规图片 只看肤色占比 加亮度标准差门槛,纯色图跳过判定
并发注册返回 500 唯一索引竞态 捕获 Prisma P2002 转成 409
管理员后台被撞库 仅密码校验 一次性图形验证码 + 同 IP 失败 5 次锁 15 分钟
被封用户换号回来 只封账号 注册与发言入口都校验 IP 封禁表

5. 本地运行与部署#

npm install
# .env 中至少配置 DATABASE_URL / AUTH_SECRET / ADMIN_PASSWORD
npx prisma db push && npx prisma generate
npm run dev:http        # HTTP 3000

生产环境用 npm run start:daemon,脚本会在每次启动前自动同步表结构、生成 Prisma Client 并构建。server.js 同时监听 HTTP 与 HTTPS(证书在 ssl/),并在 /ws 提供长连接;默认绑定 0.0.0.0,局域网可访问。数据库升级用 db push,破坏性变更会安全报错并中止启动,避免误删数据。

移动端采用单列布局:会话列表全屏,点进会话后隐藏侧栏;输入区适配 iOS 安全区。图 4、图 5 是同一账号在 390px 宽度下的真实界面。

移动端会话列表

图 4:移动端会话列表,未读、未加入状态和底部四栏导航。

移动端聊天详情与机器人签到回复

图 5:移动端聊天详情,机器人签到回复带积分、成长值与头衔变化。


6. 小结与体验入口#

Firefly 的价值不在于「AI 写了很多代码」,而在于把不确定的 AI 产出收敛进确定的工程边界:先定模型、再写接口、规则集中、事件最小化、验收脚本化。AI 负责把想法快速变成可运行的四面墙,人负责决定哪面墙不能拆。

如果你想直接看效果:

🚀 现在体验萤火虫#

地址:https://www.testauto.cn/chat

  1. 打开链接,点「点亮萤火 · 游客进入」即可零注册试聊;
  2. 在群里试试 签到、@萤火虫小助手 介绍一下功能;
  3. 注册账号后解锁积分头衔、私聊、匿名速聊和反馈举报——游客身份下次打开就换了,注册才能留住你的聊天记录。

技术栈:Next.js 16 · React 19 · Tailwind CSS 4 · TypeScript 5 · Prisma 5 · SQLite · WebSocket · jose · bcryptjs · sharp · Playwright


原文链接:https://www.cnblogs.com/tynam/p/23727636

评论

© 2026 松岛川树