当前位置：首页 > news >正文

基于SSE与Next.js的AI Agent实时监控面板架构与实现

news 2026/4/30 18:49:33

1. 项目概述：实时监控你的AI Agent团队

如果你正在使用Claude Code的Agent Teams功能，让多个Claude实例协同处理复杂的编码任务，那你一定遇到过这样的困惑：这些AI代理们到底在聊什么？任务分配得怎么样了？哪个卡住了？哪个已经完成了？以前，你只能通过零散的日志或者反复刷新界面来猜测进度，整个过程就像在“盲人摸象”。

今天要聊的这个开源项目——Agent Dashboard，就是为解决这个痛点而生的。它是一个专为Claude Code Agent Teams设计的实时监控面板，让你能在一个统一的界面上，像看“作战指挥中心”的大屏幕一样，清晰地看到所有AI代理的实时状态、任务流转和对话记录。简单来说，它把AI团队的“黑盒”变成了“玻璃盒”。

这个工具的核心价值在于提升开发者的掌控感和调试效率。当你的AI团队在处理一个大型重构、多模块开发或复杂bug修复时，实时监控能让你第一时间发现协作瓶颈、理解代理间的决策逻辑，甚至在必要时进行干预。它基于Next.js构建，直接读取Claude Code本地的SQLite数据库，通过Server-Sent Events（SSE）实现无刷新的实时推送，架构轻巧，部署简单。

接下来，我会带你从零开始，深入拆解这个工具的架构设计、核心实现、以及我在实际使用和二次开发中积累的一系列实战经验与避坑指南。

2. 核心架构与设计思路拆解

2.1 为什么选择这样的技术栈？

Agent Dashboard的技术选型非常“现代”且务实，每一层都针对实时监控场景做了优化。理解这个选型逻辑，对你后续定制或借鉴其设计至关重要。

前端框架：Next.js 16 (App Router)这是整个项目的基石。选择Next.js而非纯React，主要基于两点考量：

全栈能力：项目需要后端API路由来读取数据库和建立SSE连接。Next.js的App Router完美集成了前后端，允许在app/api/目录下直接编写服务端逻辑，省去了维护独立后端服务的复杂度，部署也极其简单。
开发体验与性能：App Router带来的服务端组件（RSC）、流式渲染等特性，虽然在本项目前端以客户端组件为主，但其构建优化、路由系统等为项目提供了良好的基础。对于一个小型但需要实时性的工具，Next.js是平衡开发效率和运行性能的最佳选择。

状态管理：Zustand你可能熟悉Redux或Context API，但Zustand在这里的优势非常明显：轻量且直接。监控面板的状态（如当前活动团队、任务列表、消息流）更新频繁且来源单一（SSE流）。Zustand的API极其简洁，避免了Redux的模板代码，也绕开了Context可能带来的不必要的重渲染。它就像一个全局的、可响应的变量存储，非常适合这种实时数据推送场景。

实时通信：Server-Sent Events (SSE)这是技术选型中最关键的一环。为什么不用更常见的WebSocket？SSE和WebSocket的核心区别在于通信模型：SSE是服务器向客户端的单向推送，而WebSocket是双向的。对于监控面板，数据流是单向的（服务器推送状态更新到前端），SSE正合适。它的好处是：

协议简单：基于HTTP，无需额外的握手协议，兼容性极好。
自动重连：浏览器原生支持在连接断开后自动重连。
轻量：对于这种主要“只读”的监控场景，SSE比维护一个全双工的WebSocket连接开销更小，实现也更简单。

数据库读取：better-sqlite3Claude Code将Agent Teams的数据存储在用户本地~/.claude/目录下的SQLite文件中。项目需要读取这个文件。better-sqlite3是一个Node.js的SQLite3驱动，其特点是同步API和高性能。在服务端API路由中，使用同步读取是安全的，并且能确保在响应SSE流或API请求时，直接获取到最新的数据库状态，没有异步回调的复杂度。

UI与样式：Tailwind CSS + shadcn/uiTailwind CSS的效用优先（Utility-First）理念，使得构建这种数据密集型的仪表盘界面速度飞快。配合shadcn/ui，直接复用了一套设计精美、可访问性良好的组件（如表格、卡片、按钮），避免了从零开始造轮子，让开发者能专注于监控逻辑本身。

实操心得：技术栈的“恰到好处”这个项目的技术栈没有盲目追求最新最炫，而是紧紧围绕“实时监控Claude本地数据”这个核心需求。Next.js处理全栈，Zustand管状态，SSE推数据，better-sqlite3读库，Tailwind快速出界面。每一环都扣得很准，没有过度设计。这在个人项目或小团队工具中是非常值得学习的思路——用最合适的工具快速解决问题，而不是堆砌技术。

2.2 核心工作原理与数据流

理解了技术栈，我们再来看看数据是如何流动的。这是整个系统的命脉。

Claude Code Agent Teams (运行时) ↓ (写入) ~/.claude/claude_code.db (SQLite数据库) ↓ (轮询读取) Agent Dashboard Next.js API 路由 ↓ (SSE 流) 前端React组件 (实时更新UI)

数据源：Claude Code在运行Agent Teams时，会将团队（Team）、代理（Agent）、任务（Task）、消息（Message）等实体的状态变化，实时写入用户本地的一个SQLite数据库文件中（通常位于~/.claude/claude_code.db）。
数据读取：Agent Dashboard启动后，其Next.js服务端（API路由）会以只读方式打开这个数据库文件。这里有一个关键点：它采用轮询（Polling）查询数据库，而不是监听数据库事件。因为SQLite本身不是一个支持事件通知的数据库，所以Dashboard通过定期（例如每秒）查询相关数据表的变化来感知更新。
数据推送：当API路由检测到数据变化（通过比较上次查询结果），它会通过已建立的SSE连接，将变化的数据以JSON格式主动推送到前端。
前端呈现：前端接收到SSE事件后，使用Zustand Store更新对应的全局状态。React组件订阅这些状态，界面便实现了实时更新。

注意事项：关于数据库路径与权限项目默认假设数据库路径是~/.claude/claude_code.db。但在不同操作系统或Claude Code自定义配置下，这个路径可能不同。如果启动后仪表盘没有数据，首先需要检查的就是这个路径是否正确。你可以在Claude Code的设置或日志中寻找确切的数据库位置，并在Dashboard的环境变量或配置文件中进行覆盖。此外，确保运行Dashboard的进程有读取该数据库文件的权限。

3. 核心功能模块深度解析与实操

3.1 实时团队监控视图的实现

这是仪表盘的核心页面（/live），它需要高频率、多维度地更新数据。我们拆解一下它的实现要点。

前端组件结构：

TeamOverview组件：展示团队整体状态，如团队ID、创建时间、状态（活跃/完成）。这里的数据通常更新频率较低。
AgentsTable组件：以表格形式列出所有代理。关键列包括：代理ID、名称、状态（空闲、思考、执行任务、等待输入）、当前任务ID、最后心跳时间。“状态”和“当前任务ID”是高频更新字段。
TasksBoard组件：通常采用看板（Kanban）形式，将任务按状态（Pending, In Progress, Completed, Failed）分组展示。每个任务卡片显示任务ID、简要描述、负责的代理、创建/更新时间。这里是拖拽更新的视觉焦点。
MessageFeed组件：一个实时滚动的消息列表，显示代理与领导（Lead）之间、代理与代理之间的对话。需要处理可能的高频消息流，并优化渲染性能。

状态管理与更新策略：

// 示例：Zustand Store 的简化结构 interface DashboardState { currentTeam: Team | null; agents: Agent[]; tasks: Task[]; messages: Message[]; // Actions setAgents: (agents: Agent[]) => void; appendMessage: (msg: Message) => void; updateTaskStatus: (taskId: string, newStatus: TaskStatus) => void; } // 在SSE事件监听器中更新状态 eventSource.onmessage = (event) => { const data = JSON.parse(event.data); switch (data.type) { case 'AGENT_UPDATE': useDashboardStore.getState().setAgents(data.payload); break; case 'NEW_MESSAGE': useDashboardStore.getState().appendMessage(data.payload); // 自动滚动到底部 break; case 'TASK_UPDATE': useDashboardStore.getState().updateTaskStatus(data.payload.taskId, data.payload.status); break; } };

性能优化点：

虚拟滚动：对于MessageFeed和AgentsTable，如果数据量很大，必须实现虚拟滚动（例如使用@tanstack/react-virtual），仅渲染可视区域内的行，避免因高频更新导致页面卡顿。
更新粒度：SSE推送和状态更新应尽量保持细粒度。与其每次推送全量代理列表，不如只推送变化的代理对象。前端Store再根据ID进行合并更新，这样可以最小化React的重新渲染范围。
防抖与节流：虽然SSE由服务器控制推送频率，但前端在处理更新（如更新图表）时，对于连续快速的变化，可能仍需使用requestAnimationFrame或节流来避免过于频繁的UI重绘。

3.2 任务流与消息流的处理逻辑

任务和消息是监控的两个关键维度，它们的处理逻辑各有侧重。

任务状态机与看板同步： Claude Code内部的任务有一个生命周期。Dashboard需要准确映射这个状态机。通常状态包括：

pending：任务已创建，等待分配或执行。
in_progress：已有代理认领并正在执行。
completed：任务成功完成。
failed：任务执行失败。
cancelled：任务被取消。

前端看板（如使用@dnd-kit库实现拖拽）的UI状态需要与后端数据同步。这里要避免一个常见陷阱：不要用前端的拖拽操作直接反向修改Claude Code的数据库。这个仪表盘主要是“只读”监控。任务状态的改变应由Claude Code自身的逻辑驱动。拖拽动画可以增强用户体验，但数据源应以SSE推送来的状态为准。如果检测到前端看板状态与SSE推送状态不一致，应以SSE数据为准并重置UI位置。

消息流的处理与展示：消息流是理解AI团队“思考过程”的窗口。实现时要注意：

格式与高亮：消息内容可能包含代码块、JSON、自然语言。需要集成一个代码高亮库（如Prism.js或highlight.js）来美化展示，提升可读性。
会话线程：消息可能属于不同的会话（Session）或线程（Thread）。前端需要能按会话分组或过滤消息，避免所有消息混在一起。
自动滚动与暂停：消息流应默认自动滚动到最新消息。但当用户手动向上滚动查看历史时，应暂停自动滚动，直到用户再次滚动到底部。这是一个提升用户体验的关键细节。
性能：消息是追加式的，且可能很多。使用虚拟滚动是必须的。同时，对于过长的历史消息，可以考虑分页加载或懒加载，而不是一次性全部渲染。

3.3 历史会话回放功能

/history页面允许你回放已结束的Agent团队会话。这功能对于复盘、调试和分享成果非常有用。

实现原理：

数据获取：从数据库的sessions表（或类似表）中列出所有历史会话，包含会话ID、开始时间、结束时间、状态等元数据。
状态快照重建：回放的本质是按时间顺序，重新应用该会话过程中产生的所有状态变化（任务创建/更新、消息发送、代理状态变更）。这些数据通常关联存储在tasks、messages、agent_activities等表中，通过session_id关联。
前端播放器：前端需要实现一个“播放器”控件，包括进度条、播放/暂停、快进/快退、速度调节按钮。回放时，前端根据时间戳，逐步将历史数据注入到与实时监控相同的Zustand Store和UI组件中，从而“重演”整个过程。

技术挑战与解决方案：

数据量大：一个长时间的会话可能产生数万条消息和状态变更。一次性加载所有数据到前端不可行。解决方案是按需加载。在用户选择某个会话后，先加载该会话的元数据和关键时间点快照。当用户拖动进度条到某个范围时，再向后台请求该时间段内的详细变更数据。
播放流畅性：如果按真实时间戳逐条应用变更，回放可能很慢。因此需要支持加速播放（例如2x, 5x, 10x）。实现上，可以计算每条记录与开始时间的相对偏移量，然后在播放时，用一个缩放因子（播放速度）来加速这个时间线的推进。
状态重置：开始回放新会话或跳转进度时，必须彻底清空前一个回放状态，从头或从指定点初始化Store。这需要Store提供resetToHistoricalSnapshot这样的Action。

避坑指南：SSE连接稳定性在实际部署或长时间运行时，SSE连接可能会因为网络波动、服务器重启、电脑休眠等原因中断。一个健壮的实现必须包含：
自动重连：利用EventSource原生的onerror事件监听，在连接断开后，等待几秒（并采用指数退避策略）后重新建立连接。
连接状态提示：在UI上（例如顶栏）清晰显示“实时连接中”、“连接断开，正在重试...”等状态，让用户心中有数。
重连后的数据同步：重连成功后，简单的做法是让服务器推送一次全量状态快照。更精细的做法是，前端在断开时记录最后收到的事件ID，重连后将该ID发送给服务器，服务器只推送该ID之后的变化（类似断点续传）。

4. 本地开发、部署与深度定制指南

4.1 从零开始的环境搭建与运行

虽然README提供了快速启动命令，但其中有些细节需要展开说明，以确保你能顺利跑起来。

步骤一：前置条件检查

Claude Code与Agent Teams：确保你安装的是支持Agent Teams实验性功能的Claude Code版本。你需要在其设置或通过环境变量CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1来启用该功能。没有活跃的Agent Teams，仪表盘将没有数据可显示。
Node.js/Bun：项目推荐使用Bun，因为它安装依赖和启动速度更快。但如果你习惯用Node.js，确保版本在20以上。我个人更推荐Bun，能避免很多Node版本和包管理器的兼容性问题。
数据库文件权限：这是最容易出错的一步。在类Unix系统（Mac, Linux）上，Claude Code的数据库文件可能位于~/.claude/，且默认权限可能只允许当前用户读写。你需要确保运行bun dev的用户（通常就是你自己的终端用户）有读取该目录和文件的权限。如果遇到SQLITE_CANTOPEN错误，请检查权限。

步骤二：克隆与依赖安装

git clone https://github.com/aiwithabidi/agent-dash.git cd agent-dash bun install

如果使用npm或yarn，理论上也可以，但package.json中的脚本（如bun dev）可能需要你手动改为npm run dev。建议遵循项目推荐，使用Bun。

步骤三：配置与运行

项目通常通过环境变量来配置数据库路径。查看项目根目录下是否有.env.example或config.ts文件。你可能需要复制一份.env.example到.env，并修改其中的DATABASE_PATH变量，指向你电脑上Claude Code数据库的真实路径。
运行开发服务器：bun dev。默认端口是3847，如果被占用，可以在package.json的dev脚本中修改。
打开浏览器访问http://localhost:3847。
关键验证：在另一个终端，启动Claude Code并创建一个包含Agent Teams的新会话或项目。如果一切正常，你应该能在Dashboard的/live页面看到实时出现的团队、代理和任务信息。

4.2 核心配置文件与关键API路由剖析

要定制这个项目，你需要熟悉几个核心部分。

数据库连接配置(src/lib/db.ts或类似文件)：

import Database from 'better-sqlite3'; import path from 'path'; import fs from 'fs'; // 动态获取数据库路径，优先级：环境变量 > 默认路径 const dbPath = process.env.DATABASE_PATH || path.join(os.homedir(), '.claude', 'claude_code.db'); // 检查文件是否存在且有读权限 if (!fs.existsSync(dbPath)) { console.error(`[ERROR] Database file not found at: ${dbPath}`); console.error('Please ensure Claude Code is running with Agent Teams enabled and set the correct DATABASE_PATH.'); // 可能创建一个空状态或抛出错误 } export const db = new Database(dbPath, { readonly: true }); // 以只读模式打开！

这里强调只读模式至关重要。Dashboard不应该、也绝不要去修改Claude Code的运营数据库，否则可能导致数据损坏或Claude Code运行异常。

SSE流API路由(src/app/api/stream/route.ts)：这是实时性的心脏。它的大致逻辑如下：

export async function GET(request: Request) { // 1. 设置SSE响应头 const headers = new Headers({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', }); const stream = new ReadableStream({ async start(controller) { // 2. 发送初始连接确认 controller.enqueue(`data: ${JSON.stringify({ type: 'CONNECTED' })}\n\n`); // 3. 轮询循环 let lastCheckTime = Date.now(); const pollInterval = 1000; // 1秒轮询一次 const intervalId = setInterval(async () => { try { // 4. 查询数据库，比较自上次检查以来的变化 const changes = await pollDatabaseForChanges(lastCheckTime); lastCheckTime = Date.now(); if (changes.agents.length > 0) { controller.enqueue(`data: ${JSON.stringify({ type: 'AGENTS_UPDATE', payload: changes.agents })}\n\n`); } if (changes.tasks.length > 0) { controller.enqueue(`data: ${JSON.stringify({ type: 'TASKS_UPDATE', payload: changes.tasks })}\n\n`); } // ... 处理消息等 } catch (error) { console.error('Polling error:', error); controller.enqueue(`data: ${JSON.stringify({ type: 'ERROR', payload: error.message })}\n\n`); } }, pollInterval); // 5. 客户端断开连接时清理 request.signal.addEventListener('abort', () => { clearInterval(intervalId); controller.close(); }); }, }); return new Response(stream, { headers }); }

这个模式是典型的SSE服务端实现：建立长连接，在一个循环中定期检查数据源，并将变化推送给客户端。

4.3 如何进行功能定制与扩展

开源项目的魅力在于可以按需修改。以下是几个常见的定制方向：

1. 修改UI主题或布局：项目使用Tailwind CSS和shadcn/ui，修改非常方便。

主题：修改tailwind.config.js中的颜色配置，或直接覆盖src/app/globals.css中的CSS变量。
布局：主要布局文件在src/components/layout/目录下。你可以调整侧边栏宽度、主面板布局（如将任务看板和消息流上下排列改为左右排列）。

2. 增加新的监控维度：假设你想监控每个Agent的“资源消耗”（虚构指标，Claude Code可能不提供）。

后端：首先，你需要确认Claude Code的数据库中是否有相关数据表或字段。如果没有，此扩展无法进行。如果有，在pollDatabaseForChanges函数中增加对新表的查询逻辑，并在SSE流中定义新的消息类型（如AGENT_RESOURCES_UPDATE）。
前端：在Zustand Store中增加对应的状态（如agentResources）和更新Action。然后创建新的React组件（如ResourceMonitorPanel）来展示这些数据，并将其集成到主界面中。

3. 集成外部通知（如Slack, Discord）：你想在关键任务失败或所有任务完成时收到通知。

后端：在Next.js的API路由中（可以新建一个/api/webhook），接收前端或SSE逻辑触发的事件。然后调用外部服务的Webhook API（如Slack Incoming Webhook）。
安全考虑：Webhook URL等敏感信息应存储在环境变量中，不要硬编码在代码里。

4. 数据持久化与导出： Dashboard默认只显示实时数据。你可以增加历史数据导出功能。

后端：新增API路由/api/sessions/:id/export，接收会话ID，查询所有相关数据，组装成JSON或CSV格式。
前端：在历史会话列表页面，为每个会话增加一个“导出”按钮，点击后调用上述API，并使用Blob对象触发浏览器下载。

深度定制建议：从Fork到PR如果你打算进行深度、个性化的定制，最好的流程是：
Fork原仓库：在GitHub上Fork该项目到你的账户下。
在本地分支开发：为你的新功能创建一个清晰的分支（如feat/custom-notifications）。
保持核心逻辑清晰：修改时，尽量将你的定制代码模块化，通过配置文件、环境变量或特性开关（Feature Flag）来控制，避免把原项目代码改得面目全非。
考虑向上游贡献：如果你的功能具有通用性（比如一个更好的历史会话过滤器、一个更稳定的SSE重连逻辑），在开发完成后，可以向原项目发起Pull Request（PR）。在PR描述中清晰说明你的改动解决了什么问题，以及如何测试。

5. 常见问题排查与实战经验实录

即使按照指南操作，在实际使用中你仍可能遇到各种问题。下面是我在部署和使用过程中遇到的一些典型问题及解决方法。

5.1 启动与连接类问题

问题一：启动bun dev后，访问页面空白或报错“Failed to fetch”。

排查步骤：
1. 检查终端日志：首先看运行bun dev的终端是否有错误输出。常见错误是数据库文件找不到或无法读取。根据错误信息修正路径或权限。
2. 检查端口占用：默认端口3847可能被其他程序占用。尝试修改package.json中dev脚本，加上-p 3848指定另一个端口。
3. 检查依赖：删除node_modules和bun.lockb（或package-lock.json），重新运行bun install。
4. 检查Claude Code是否运行：确保Claude Code正在运行，并且已经创建了一个启用了Agent Teams的会话。Dashboard需要从活跃的Claude进程中读取数据。

问题二：页面能打开，但一直显示“等待数据...”或“无活跃团队”。

排查步骤：
1. 确认Agent Teams已启用：在Claude Code中，检查设置或项目配置，确保CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1这个环境变量已生效。有时需要重启Claude Code。
2. 验证数据库内容：你可以使用一个SQLite浏览器（如DB Browser for SQLite）直接打开~/.claude/claude_code.db文件。查看是否存在teams、agents、tasks等表，并且表里有数据（确保你有一个正在运行的Agent团队）。这能最快确定问题是出在Claude Code没写数据，还是Dashboard读不到。
3. 检查SSE连接：打开浏览器开发者工具（F12），切换到“网络”（Network）标签页，过滤“事件流”（EventStream）或查看所有请求，找到对/api/stream的请求。检查其状态是否为200，并且是否在持续接收数据。如果连接失败，查看控制台（Console）是否有CORS或其它错误。

问题三：SSE连接频繁断开重连。

可能原因与解决：
1. 开发服务器热重载：在开发模式下，Next.js的热重载（Hot Reload）可能会导致API路由重启，从而断开SSE连接。这是正常现象，生产环境不会发生。可以暂时忍受，或调整开发服务器的监控配置（但较复杂）。
2. 代理或防火墙：如果你在公司网络或使用了网络代理，可能会干扰长连接。尝试在无代理环境下运行。
3. 浏览器限制：某些浏览器扩展或省电模式可能会限制后台页面的连接。尝试在无痕模式下运行。
4. 服务器端超时：检查Next.js部署环境（如Vercel）是否有函数执行超时限制。Vercel的Serverless函数默认有10秒超时，而SSE连接是持久的，这会导致问题。这是将此类SSE应用部署到Serverless环境的主要挑战。解决方案是：a) 部署到支持长时间运行的Node.js服务器环境（如Railway, Fly.io, 你自己的VPS）；b) 使用Vercel的Pro计划并配置更高的超时时间；c) 考虑改用支持WebSocket的托管服务。

5.2 数据展示与性能类问题

问题四：消息流滚动卡顿，页面响应慢。

原因：消息数量过多，React渲染压力大。
解决方案：
1. 实施虚拟滚动：这是根本解决方案。将MessageFeed组件改用虚拟滚动列表库。
2. 限制历史消息：在前端Store中，只保留最近N条（例如1000条）消息。旧的可以丢弃或存档。
3. 优化组件：使用React.memo包裹消息列表项组件，避免因父组件状态更新导致所有子项重渲染。确保传递给子组件的props是稳定的（使用useMemo,useCallback）。
4. 分页加载：对于历史会话回放，不要一次性加载所有消息，实现按需分页加载。

问题五：任务状态在UI上看板中更新有延迟，或与Claude Code界面不同步。

原因：SSE轮询存在固有延迟（例如1秒一次）。Claude Code内部状态变化到写入数据库，再到Dashboard轮询读取，有一个时间差。
理解与缓解：
- 这是最终一致性模型，不是强一致性。对于监控目的，1-2秒的延迟通常是可接受的。
- 可以尝试缩短轮询间隔（如500ms），但这会增加数据库和服务器负载，需权衡。
- 确保数据库轮询逻辑是高效的，只查询自上次检查后可能变化的记录（利用updated_at时间戳字段），而不是全表扫描。

问题六：在历史回放时，跳转到某个时间点后状态显示混乱。

原因：回放逻辑没有正确重置状态。跳转不是从初始状态快照开始按时间线重放，而是直接应用了目标时间点的状态，但中间可能有关联状态缺失。
解决方案：实现一个可靠的“状态快照”机制。在回放开始时，加载会话的完整初始快照（所有任务、代理的初始状态）。当用户跳转进度时，需要计算从初始状态到目标时间点之间所有状态变更事件的累积效果，并以此为基础更新UI。这比直接应用目标点的“当前状态”更准确，但实现也更复杂。一个简化方案是，只允许从会话开始处播放，不支持随机跳转。

5.3 部署与生产环境问题

问题七：部署到Vercel后，实时功能失效。

根本原因：如问题三所述，Vercel的Serverless函数有执行时长限制（Hobby计划10秒，Pro计划15秒或更长），不适合运行持续的SSE连接。
解决方案：
1. 更换部署平台：选择支持长时间运行进程的PaaS平台，如：
  - Railway.app：对Node.js应用友好，支持WebSocket/SSE。
  - Fly.io：可部署为长期运行的VM。
  - 你自己的云服务器（VPS）：使用PM2或Docker管理进程。
2. 改造架构（高级）：将SSE服务拆分成一个独立的、可长时间运行的后端服务（例如用Express.js编写），部署在支持长连接的平台上。Next.js前端则只负责静态页面和调用这个独立的后端服务。这增加了架构复杂度，但更灵活。

问题八：多用户同时访问时，数据库文件被锁或读取冲突。

原因：SQLite在写入时会对数据库文件加锁。如果Claude Code正在密集写入，而Dashboard同时尝试读取，可能会遇到SQLITE_BUSY错误。
解决方案：
1. 只读模式与重试：Dashboard连接数据库时已经使用了{ readonly: true }，这有助于减少冲突，但不能完全避免。在数据库查询逻辑中，可以加入简单的重试机制。
2. 轮询间隔避让：适当增加Dashboard的轮询间隔（如2秒），减少读取频率。
3. 使用WAL模式（高级）：如果Claude Code的数据库启用了WAL（Write-Ahead Logging）日志模式，读和写可以更好地并发。但修改Claude Code的数据库配置非Dashboard可控。
4. 理解并接受：对于个人本地使用的工具，轻微的读取冲突和重试是可以接受的。如果频繁出错，可能是Claude Code写入过于频繁，或者磁盘I/O性能瓶颈。

我的实战经验：从本地工具到团队共享最初，我只在本地使用Agent Dashboard。后来我想让团队其他成员也能看到某个复杂AI任务的进展。直接让每个人都在本地运行Dashboard不现实。我的做法是：
在一台内网开发服务器上部署了Agent Dashboard。
在这台服务器上，以“无头”（headless）模式运行Claude Code（这需要Claude Code支持命令行或API模式，目前可能还是实验性的）。
将Claude Code的数据库文件放在一个共享位置，并确保Dashboard容器有权限读取。
通过内网IP和端口，团队成员就能在浏览器中实时查看同一个AI团队的进展了。
这个方案的缺点是，这台服务器成了单点，且需要管理Claude Code进程。但它验证了将监控工具“服务化”的可行性，对于小团队内部协作很有价值。未来如果Claude Code提供更完善的远程API，这种集成会更容易。

查看全文

http://www.jsqmd.com/news/726908/