用 AI 从零搭一个全栈聊天应用:萤火虫 Firefly 的架构、落地与踩坑
用 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 消息发送管线:所有校验只有一份#
消息接口是这个项目最值得看的文件。一次发送会依次经过:
- IP 封禁检查、账号封禁检查;
- 工作时间闸门(非工作日或 8:30–17:30 之外直接 403);
- 图片路径白名单:
/^\/uploads\/[\w.-]+$/,杜绝外链注入; - 内置三级词库 + 后台自定义词打码;
- 色情/敏感链接命中则永久封禁账号与关联 IP;
- 涉政表态正则拦截,当天累计 3 次封禁 3 天;
- 成员权限与连续刷屏(同内容连续 3 条)检查;
- 写库 → 机器人回复 → 成长值 → 广播。
// 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
- 打开链接,点「点亮萤火 · 游客进入」即可零注册试聊;
- 在群里试试
签到、@萤火虫小助手 介绍一下功能;- 注册账号后解锁积分头衔、私聊、匿名速聊和反馈举报——游客身份下次打开就换了,注册才能留住你的聊天记录。
技术栈:Next.js 16 · React 19 · Tailwind CSS 4 · TypeScript 5 · Prisma 5 · SQLite · WebSocket · jose · bcryptjs · sharp · Playwright
评论