技术栈概览

**本文引用的文件** - [[ui-web/package.json]](../file/ui-web/package.json) - [[bi-chat/bi-chat-web/package.json]](../file/bi-chat/bi-chat-web/package.json) - [[bi-chat/bi-chat-web/next.config.ts]](../file/bi-chat/bi-chat-web/next.config.ts) - [[bi-chat/bi_chat/main.py]](../file/bi-chat/bi-chat/main.py) - [[bi-chat/requirements.txt]](../file/bi-chat/requirements.txt) - [[bi-analysis/go.mod]](../file/bi-analysis/go.mod) - [[bi-analysis/cmd/bi-analysis/main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-analysis/README.md]](../file/bi-analysis/readme.md) - [[bi-common/go.mod]](../file/bi-common/go.mod) - [[bi-common/README.md]](../file/bi-common/readme.md)

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

引言

本文件面向 BI 分析平台的综合技术栈概览，围绕前端（Next.js 16、TypeScript、Tailwind CSS、ECharts）、后端（Go 语言、Kratos 框架、gRPC、Protobuf）、AI 组件（AgentScope、FastAPI、Qwen-Max）展开，解释技术选型理由、协作关系与集成方式，并提供最佳实践建议。内容兼顾初学者友好与资深工程师的深度细节。

项目结构

该仓库采用多模块、多语言混合架构：

• 前端侧包含多个 Next.js 应用（如 ui-web、bi-chat-web），统一使用 TypeScript 与 Tailwind CSS，部分页面使用 ECharts 进行可视化。
• 后端侧以 Go 语言为主，基于 Kratos 框架构建微服务（如 bi-analysis），通过 gRPC/HTTP 提供 API，并使用 Protobuf 定义接口契约。
• AI 侧采用 Python 与 FastAPI 搭建服务（bi_chat），集成 AgentScope 与 DashScope/Qwen 等大模型能力，提供聊天与多智能体协作能力。
• 公共基础库 bi-common 为 Go 微服务提供统一的配置、日志、数据库、缓存、消息队列等基础设施。

图示来源

• [ui-web/package.json]
• [bi-chat/bi-chat-web/package.json]
• [bi-analysis/go.mod]
• [bi-common/go.mod]

章节来源

• [bi-analysis/README.md]

核心组件

• 前端技术栈
  • Next.js 16：SSR/ISR、App Router、TypeScript 支持，提供高性能与良好的 SEO。
  • TypeScript：强类型保障，提升开发效率与可维护性。
  • Tailwind CSS：实用优先的样式框架，快速构建一致的 UI。
  • ECharts：丰富的图表库，用于仪表盘与趋势分析。
• 后端技术栈
  • Go + Kratos：微服务框架，提供服务治理、配置中心、日志、监控等能力。
  • gRPC + Protobuf：高性能 RPC 通信与接口契约定义，配合 OpenAPI 文档生成。
  • bi-common：统一基础设施（Nacos、日志、数据库、Redis、Kafka、StarRocks 等）。
• AI 组件
  • FastAPI：异步高性能 API 框架，便于构建流式响应与多 Agent 协作。
  • AgentScope：多 Agent 编排与运行时，支持共享模型与工具。
  • Qwen-Max/DashScope：大模型推理与联网搜索能力，结合 enable_search 实现实时信息检索。

章节来源

• [ui-web/package.json]
• [bi-chat/bi-chat-web/package.json]
• [bi-chat/bi_chat/main.py]
• [bi-chat/requirements.txt]
• [bi-analysis/go.mod]
• [bi-common/README.md]

架构总览

整体架构由“前端应用 + 后端服务 + AI 服务 + 公共基础设施”构成，前后端通过 HTTP/gRPC 交互，AI 服务独立部署并通过内部网络与后端协同。

图示来源

• [bi-analysis/cmd/bi-analysis/main.go]
• [bi-common/README.md]
• [bi-chat/bi_chat/main.py]

详细组件分析

前端组件分析（Next.js 16 + TypeScript + Tailwind CSS + ECharts）

• 技术要点
  • 使用 Next.js 16 的 App Router 与 SSR，提升首屏性能与 SEO。
  • TypeScript 提供类型安全；Tailwind CSS 实现原子化样式。
  • ECharts 用于趋势、占比等可视化图表，组件化封装并在页面中按需渲染。
• 图表组件与可视化
  • 通过 ChartComponent.tsx 封装折线、柱状、饼图等常见图表，统一配置与响应式处理。
  • TrafficTrendChart.tsx 展示销售与访客趋势，使用渐变填充与平滑曲线增强视觉效果。
• 集成方式
  • 在页面中引入 ECharts 并传入数据，组件内部设置 option 并监听窗口 resize 事件，保证图表自适应。

图示来源

• [ui-web/src/components/ChartComponent.tsx]
• [ui-web/src/components/dashboard/analysis/TrafficTrendChart.tsx]

章节来源

• [ui-web/package.json]

后端组件分析（Go + Kratos + gRPC + Protobuf）

• 技术要点
  • 基于 Kratos 框架，统一服务注册、配置中心、日志、指标与健康检查。
  • 使用 gRPC + Protobuf 定义接口契约，结合 grpc-gateway 自动生成 OpenAPI 文档。
  • 通过 bi-common 统一接入数据库（GORM）、缓存（Redis）、消息队列（Kafka）、服务发现（Nacos）。
• 启动流程
  • 解析环境参数，加载 Nacos 配置源，初始化日志与雪花算法，创建 Kratos 应用并启动。
  • 通过 wire 生成依赖注入代码，确保服务生命周期与资源清理可控。

图示来源

• [bi-analysis/cmd/bi-analysis/main.go]

章节来源

• [bi-analysis/go.mod]
• [bi-analysis/README.md]
• [bi-common/README.md]

AI 组件分析（FastAPI + AgentScope + Qwen-Max）

• 技术要点
  • FastAPI 提供异步高性能 API，支持 SSE 流式响应与多 Agent 协作。
  • AgentScope 作为多 Agent 编排引擎，支持共享模型与工具，降低重复初始化成本。
  • DashScope/Qwen-Max 提供强大的语言理解与联网搜索能力，结合 enable_search 实现实时信息检索。
• 生命周期与路由
  • 应用启动时初始化数据库、共享模型与工具，定时清理超时会话。
  • 注册健康检查、聊天（v1/v2）、会话、用户等路由，满足不同交互模式需求。

图示来源

• [bi-chat/bi-chat-web/next.config.ts]
• [bi-chat/bi_chat/main.py]
• [bi-chat/requirements.txt]

章节来源

• [bi-chat/bi-chat-web/package.json]
• [bi-chat/bi_chat/main.py]
• [bi-chat/requirements.txt]

依赖关系分析

• 前端依赖
  • ui-web 与 bi-chat-web 均依赖 Next.js 16、TypeScript、Tailwind CSS；ui-web 引入 ECharts，bi-chat-web 引入 Recharts。
• 后端依赖
  • bi-analysis 依赖 Kratos、gRPC、grpc-gateway、Protobuf、bi-common、bi-proto 等；bi-common 提供统一基础设施。
• AI 依赖
  • bi_chat 依赖 FastAPI、Uvicorn、AgentScope、DashScope/Qwen、Pydantic、SQLAlchemy、Redis、Neo4j、Milvus 等。

图示来源

• [ui-web/package.json]
• [bi-chat/bi-chat-web/package.json]
• [bi-analysis/go.mod]
• [bi-common/go.mod]
• [bi-chat/requirements.txt]

章节来源

• [bi-analysis/go.mod]
• [bi-common/go.mod]

性能考量

• 前端
  • 使用 Next.js 16 的 App Router 与 SSR，结合 Tailwind CSS 的原子类减少打包体积；ECharts 图表按需渲染，避免一次性加载过多数据。
• 后端
  • Kratos 提供内置指标与日志，结合 Nacos 配置中心实现动态调优；gRPC 降低序列化开销，适合高并发场景。
• AI 服务
  • FastAPI 异步模型与 SSE 流式输出，优化长耗时任务体验；AgentScope 共享模型与工具减少冷启动成本。

故障排查指南

• 配置与注册
  • 若服务无法启动或配置异常，检查 Nacos 配置源是否正确加载 application-{env}.yaml，确认 data_id 与命名空间配置。
• 日志与追踪
  • 使用 bi-common 的日志组件，确保日志级别、格式与输出目标（文件/阿里云 SLS）正确配置。
• gRPC/OpenAPI
  • 如接口文档不更新，执行 make api 与 make api-sync，确保 Protobuf 与 OpenAPI 生成流程正常。
• AI 服务
  • 若流式响应异常，检查 Next.js 重写规则与代理超时配置；确认 DashScope/Qwen 的鉴权与网络连通性。

章节来源

• [bi-analysis/cmd/bi-analysis/main.go]
• [bi-analysis/README.md]
• [bi-common/README.md]

结论

该技术栈以 Next.js 16 + TypeScript + Tailwind CSS + ECharts 构建现代化前端，以 Go + Kratos + gRPC + Protobuf 实现高性能后端，以 FastAPI + AgentScope + Qwen-Max 提供智能化 AI 能力。通过 bi-common 统一基础设施，形成高内聚、低耦合的微服务体系。建议在团队内明确模块边界与接口契约，持续完善可观测性与自动化测试，以支撑业务长期演进。

附录

• 最佳实践建议
  • 前端：组件化与主题化设计，统一 ECharts 配置；按需懒加载与骨架屏优化首屏。
  • 后端：严格遵循 Protobuf 接口规范，使用 OpenAPI 文档驱动联调；合理拆分微服务，避免循环依赖。
  • AI：统一 Agent 生命周期管理与资源池化；对流式响应进行超时与重试策略设计。
  • 部署：容器化与 Helm/Manifest 管理，结合 Nacos 与 Prometheus/Grafana 实现可观测性。