用 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 接口,因此敏感词、封禁、刷屏、工作时间等校验只有一份实现。
text
┌──────────────────────────────┐
浏览器 ──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})
┌──────────▼───────────────────┐
│ 全站广播(只发事件标识) │
│ 客户端收到后按需重新拉取数据 │
└──────────────────────────────┘
实时层刻意做得很薄。服务端广播的事件体只有几十字节:
ts
// 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 天。
ts
// 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 条)检查;
- 写库 → 机器人回复 → 成长值 → 广播。
ts
// 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 三级,用等长 * 替换敏感词,保留句子可读性;同时提供前后文例外(如「你妈妈」不该被「你妈」误伤),用零宽断言实现:
ts
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 排除纯色截图,避免误伤:
ts
// 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 名里随机选,既不容易走进死路又保留变化。
ts
// 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 修复,比人肉点页面再口头描述高效得多。
ts
// .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. 本地运行与部署
bash
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