快速开始指南

**本文档引用的文件** - [[README.md]](../file/readme.md) - [[bi-analysis/README.md]](../file/bi-analysis/readme.md) - [[ui-web/README.md]](../file/ui-web/readme.md) - [[bi-common/README.md]](../file/bi-common/readme.md) - [[bi-analysis/cmd/bi-analysis/main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-analysis/Makefile]](../file/bi-analysis/makefile) - [[bi-analysis/configs/application-dev.yaml]](../file/bi-analysis/configs/application-dev.yaml) - [[bi-chat/docker-compose.yml]](../file/bi-chat/docker-compose.yml) - [[bi-chat/.env.example]](../file/bi-chat/.env.example) - [[bi-common/go.mod]](../file/bi-common/go.mod) - [[ui-web/package.json]](../file/ui-web/package.json)

简介

BI分析平台是一个企业级商业智能(BI)分析平台，提供数据可视化、指标管理和深度分析功能。平台采用现代化技术栈构建，具备高性能、可扩展性和良好的用户体验。

技术架构概览

前端技术栈

框架: Next.js 16 (App Router)
语言: TypeScript
样式: Tailwind CSS
图表: ECharts 6.x
状态管理: Zustand
图标: Iconfont
构建工具: docker + k8s

后端技术栈

语言: Golang
框架: Kratos
API: gRPC + Protobuf
消息队列: Apache Kafka
实时计算: Apache Flink
数据库: StarRocks (OLAP)
网关: APISIX

AI组件

语言: Python
框架: AngentScope + FastAPI
API: Restful
AI模型: Qwen-Max
用途: 多智能体数据分析对话系统

项目结构

BI分析平台采用微服务架构，主要包含以下核心模块：

图表来源

[README.md]

开发环境准备

系统要求

操作系统: macOS 10.15+, Windows 10+, Linux Ubuntu 18.04+
内存: 至少 8GB RAM (建议 16GB+)
存储: 至少 20GB 可用空间

必需工具安装

1. Node.js 环境

bash

# 检查 Node.js 版本
node --version
npm --version

# 推荐使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18.17.0
nvm use 18.17.0

2. Go 环境

bash

# 下载并安装 Go 1.25.5
wget https://go.dev/dl/go1.25.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -xzf go1.25.5.linux-amd64.tar.gz -C /usr/local/

# 配置环境变量
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
source ~/.bashrc

# 验证安装
go version

3. Docker 环境

bash

# 安装 Docker Desktop
# macOS: 从官网下载 Docker Desktop
# Windows: 从官网下载 Docker Desktop
# Linux: 使用官方安装脚本

# 验证安装
docker --version
docker compose version

4. Git 工具

bash

# 安装 Git
git --version

# 配置 Git 用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

前端开发环境

项目启动步骤

1. 进入前端项目目录

bash

cd ui-web

2. 安装依赖包

bash

# 使用 npm 安装
npm install

# 或使用 yarn 安装
yarn install

# 或使用 pnpm 安装
pnpm install

# 或使用 bun 安装
bun install

3. 配置环境变量

bash

# 复制示例环境文件
cp .env.example .env.development

# 编辑环境变量文件
vim .env.development

前端支持多种构建模式：

bash

# 开发模式
npm run dev

# 测试环境
npm run dev:test

# 预发布环境
npm run dev:staging

# 生产环境构建
npm run build:prod

4. 启动开发服务器

bash

# 启动开发服务器
npm run dev

# 访问应用
open http://localhost:3000

前端项目结构

图表来源

[ui-web/package.json]

章节来源

后端开发环境

项目启动步骤

1. 进入后端项目目录

bash

cd bi-analysis

2. 初始化开发环境

bash

# 安装开发工具和依赖
make init

3. 配置 Nacos

在 Nacos 控制台创建以下配置：

Data ID: bi-common.yaml (通用配置)
Data ID: bi-analysis.yaml (项目配置，优先级更高)

4. 构建和运行

bash

# 构建项目
make build

# 开发环境运行
./bin/bi-analysis -env dev

# 测试环境运行
./bin/bi-analysis -env test

# 生产环境运行
./bin/bi-analysis -env prod

后端项目结构

图表来源

[bi-analysis/README.md]

关键配置文件

1. 应用配置文件

yaml

# 开发环境配置
nacos:
  server:
    addr: "nacos-hs.dev.svc.cluster.local"
    port: 8848
    context_path: "/"
  
  client:
    namespace_id: "dev"
    group: "DEFAULT_GROUP"
    timeout_ms: 10000
  
  config:
    data_ids:
      - "bi-common.yaml"
      - "bi-analysis.yaml"

2. 依赖管理

图表来源

[bi-common/go.mod]

章节来源

AI聊天组件

环境准备

1. 启动依赖服务

bash

cd bi-chat
docker compose up -d

2. 配置环境变量

bash

# 复制示例配置
cp .env.example .env

# 编辑配置文件
vim .env

3. 主要服务配置

yaml

# LLM 配置
DASHSCOPE_API_KEY=your_api_key_here
MODEL_CONFIG_NAME=qwen-max-latest

# StarRocks 配置
STARROCKS_HOST=localhost
STARROCKS_PORT=9030
STARROCKS_USER=root
STARROCKS_PASSWORD=
STARROCKS_DB=xcbi

# 基础设施配置
POSTGRES_URL=postgresql://bi_user:bi_password@localhost:5432/bi_chat
MILVUS_HOST=localhost
MILVUS_PORT=19530
REDIS_HOST=localhost
REDIS_PORT=6379

服务架构

图表来源

[bi-chat/docker-compose.yml]

章节来源

完整启动流程

环境准备

前端启动流程

后端启动流程

AI组件启动流程

图表来源

[bi-chat/docker-compose.yml]

常见问题解决

前端开发问题

1. 端口占用问题

bash

# 检查端口占用
lsof -i :3000

# 杀死占用进程
kill -9 $(lsof -t -i :3000)

# 或者修改端口
echo "PORT=3001" >> .env.development

2. 依赖安装失败

bash

# 清理缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

# 或使用其他包管理器
yarn install
# 或
pnpm install

3. TypeScript 类型错误

bash

# 更新类型定义
npm install @types/node @types/react --save-dev

# 清理 TypeScript 缓存
rm -rf .next/.cache

后端开发问题

1. Protobuf 编译错误

bash

# 检查 protoc 版本
protoc --version

# 重新安装开发工具
make init

# 生成代码
make api
make generate

2. Nacos 连接失败

bash

# 检查 Nacos 服务状态
curl -I http://localhost:8848/nacos

# 配置正确的 Nacos 地址
# 在 application-dev.yaml 中修改
nacos:
  server:
    addr: "nacos-hs.dev.svc.cluster.local"

3. 数据库连接问题

bash

# 检查数据库服务
docker ps | grep mysql

# 配置数据库连接
# 在 .env 文件中设置
export DATABASE_URL="mysql://user:password@localhost:3306/dbname"

AI组件问题

1. Docker 服务启动失败

bash

# 检查 Docker 状态
docker system info

# 重启 Docker 服务
sudo systemctl restart docker

# 检查磁盘空间
df -h

# 清理无用镜像
docker system prune -a

2. 向量数据库连接问题

bash

# 检查 Milvus 状态
docker logs bi-chat_milvus-standalone_1

# 重置 Milvus 数据
docker volume prune
docker compose up -d --force-recreate

3. LLM API 密钥问题

bash

# 验证 API 密钥
curl -X GET "https://dashscope.aliyuncs.com/api/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-DashScope-SSE: enable"

# 更新 .env 文件中的密钥
DASHSCOPE_API_KEY=your_valid_api_key

调试技巧

前端调试

1. 开发工具使用

bash

# 启用 React DevTools
# 在浏览器中安装 React Developer Tools 扩展

# 使用 Next.js 调试模式
npm run dev -- -d

# 启用详细日志
NEXT_PUBLIC_DEBUG=true npm run dev

2. 网络请求调试

javascript

// 在浏览器开发者工具中启用网络面板
// 查看 API 请求和响应
// 检查 CORS 设置
// 监控 WebSocket 连接

3. 状态管理调试

typescript

// 使用 Zustand DevTools
import { create } from 'zustand/devtools'

const useStore = create(
  (set) => ({
    // store state
  })
  // 开发模式下启用调试
  // devtools: process.env.NODE_ENV === 'development'
)

后端调试

1. 日志调试

// 在代码中添加调试日志
log.Infof("Debug info: %+v", variable)

// 启用详细日志级别
export LOG_LEVEL=debug

// 检查日志输出
tail -f logs/app.log

2. 性能分析

bash

# 启用 pprof 分析
go build -tags=pgo -o server
./server -env dev

# 访问性能分析页面
go tool pprof http://localhost:6060/debug/pprof/profile

3. API 调试

bash

# 使用 curl 测试 API
curl -X GET http://localhost:8080/api/v1/users

# 使用 Postman 或 Insomnia
# 配置环境变量和认证头

AI组件调试

1. 向量数据库调试

bash

# 检查 Milvus 连接
from pymilvus import connections
connections.connect(alias="default", host="localhost", port="19530")

# 查询集合状态
from pymilvus import utility
utility.list_collections()

# 检查向量维度
collection = Collection("your_collection")
print(collection.schema)

2. RAG 系统调试

python

# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 测试检索功能
retriever = YourRetriever()
results = retriever.search(query, k=5)
print(results)

3. LLM 对话调试

python

# 测试模型调用
from dashscope import Generation
response = Generation.call(
    model='qwen-max',
    prompt='你好',
    api_key='your_api_key'
)
print(response)

总结

通过本指南，您应该能够：

成功搭建开发环境 - 安装并配置 Node.js、Go、Docker 等必需工具
启动前端应用 - 完成依赖安装和开发服务器启动
启动后端服务 - 配置 Nacos 并运行分析服务
启动 AI 组件 - 使用 Docker Compose 启动依赖服务
解决问题和调试 - 掌握常见问题的解决方案和调试技巧

下一步建议

学习项目架构 - 深入了解各个模块的功能和交互关系
查看 API 文档 - 通过 OpenAPI 文档了解接口规范
参与代码审查 - 学习团队的代码规范和最佳实践
贡献代码 - 从简单的 issue 开始，逐步深入项目

支持资源

官方文档: [项目 README]
API 文档: [bi-analysis 文档]
前端指南: [ui-web 文档]
社区支持: 项目维护者联系方式

祝您开发顺利！如有任何问题，请随时联系项目维护团队。

快速开始指南 ​

目录 ​

简介 ​

技术架构概览 ​

项目结构 ​

开发环境准备 ​

系统要求 ​

必需工具安装 ​

1. Node.js 环境 ​

2. Go 环境 ​

3. Docker 环境 ​

4. Git 工具 ​

前端开发环境 ​

项目启动步骤 ​

1. 进入前端项目目录 ​

2. 安装依赖包 ​

3. 配置环境变量 ​

4. 启动开发服务器 ​

前端项目结构 ​

后端开发环境 ​

项目启动步骤 ​

1. 进入后端项目目录 ​

2. 初始化开发环境 ​

3. 配置 Nacos ​

4. 构建和运行 ​

后端项目结构 ​

关键配置文件 ​

1. 应用配置文件 ​

2. 依赖管理 ​

AI聊天组件 ​

环境准备 ​

1. 启动依赖服务 ​

2. 配置环境变量 ​

3. 主要服务配置 ​

服务架构 ​

完整启动流程 ​

环境准备 ​

前端启动流程 ​

后端启动流程 ​

AI组件启动流程 ​

常见问题解决 ​

前端开发问题 ​

1. 端口占用问题 ​

2. 依赖安装失败 ​

3. TypeScript 类型错误 ​

后端开发问题 ​

1. Protobuf 编译错误 ​

2. Nacos 连接失败 ​

3. 数据库连接问题 ​

AI组件问题 ​

1. Docker 服务启动失败 ​

2. 向量数据库连接问题 ​

3. LLM API 密钥问题 ​

调试技巧 ​

前端调试 ​

1. 开发工具使用 ​

2. 网络请求调试 ​

3. 状态管理调试 ​

后端调试 ​

1. 日志调试 ​

2. 性能分析 ​

3. API 调试 ​

AI组件调试 ​

1. 向量数据库调试 ​

2. RAG 系统调试 ​

3. LLM 对话调试 ​

总结 ​

下一步建议 ​

支持资源 ​

快速开始指南

目录

简介

技术架构概览

项目结构

开发环境准备

系统要求

必需工具安装

1. Node.js 环境

2. Go 环境

3. Docker 环境

4. Git 工具

前端开发环境

项目启动步骤

1. 进入前端项目目录

2. 安装依赖包

3. 配置环境变量

4. 启动开发服务器

前端项目结构

后端开发环境

项目启动步骤

1. 进入后端项目目录

2. 初始化开发环境

3. 配置 Nacos

4. 构建和运行

后端项目结构

关键配置文件

1. 应用配置文件

2. 依赖管理

AI聊天组件

环境准备

1. 启动依赖服务

2. 配置环境变量

3. 主要服务配置

服务架构

完整启动流程

环境准备

前端启动流程

后端启动流程

AI组件启动流程

常见问题解决

前端开发问题

1. 端口占用问题

2. 依赖安装失败

3. TypeScript 类型错误

后端开发问题

1. Protobuf 编译错误

2. Nacos 连接失败

3. 数据库连接问题

AI组件问题

1. Docker 服务启动失败

2. 向量数据库连接问题

3. LLM API 密钥问题

调试技巧

前端调试

1. 开发工具使用

2. 网络请求调试

3. 状态管理调试

后端调试

1. 日志调试

2. 性能分析

3. API 调试

AI组件调试

1. 向量数据库调试

2. RAG 系统调试

3. LLM 对话调试

总结

下一步建议

支持资源