vitepress-template

Appearance

开发环境搭建 ​

**本文引用的文件** - [[bi-analysis/cmd/bi-analysis/main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-analysis/Dockerfile]](../file/bi-analysis/dockerfile) - [[bi-analysis/go.mod]](../file/bi-analysis/go.mod) - [[bi-analysis/configs/application-local.yaml]](../file/bi-analysis/configs/application-local.yaml) - [[bi-analysis/k8s/deployment.yaml]](../file/bi-analysis/k8s/deployment.yaml) - [[bi-common/mq/kafkax/config.go]](../file/bi-common/mq/kafkax/config.go) - [[bi-common/cache/redisx/config.go]](../file/bi-common/cache/redisx/config.go) - [[bi-common/database/gormx/config.go]](../file/bi-common/database/gormx/config.go) - [[bi-common/registry/nacos/nacos-default.yaml]](../file/bi-common/registry/nacos/nacos-default.yaml) - [[bi-chat/docker-compose.yml]](../file/bi-chat/docker-compose.yml) - [[bi-chat/.env.example]](../file/bi-chat/.env.example)

目录 ​

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

简介 ​

本指南面向新加入 BI 分析平台项目的开发者，目标是帮助你在本地与容器/Kubernetes 环境中快速搭建完整的开发环境。内容覆盖：

  • 前置条件与工具链要求（Go、Node.js、Python、Docker、Kubernetes）
  • 各组件安装与配置（数据库、缓存、消息队列、配置中心）
  • IDE 配置建议（VSCode、GoLand、WebStorm）
  • 本地 Docker Compose 与 Kubernetes 集群部署
  • 环境变量与密钥管理
  • 常见问题排查与解决方案

项目结构 ​

本仓库采用多模块/多应用的组织方式，核心服务与公共组件分离，便于独立开发与部署。以下为与开发环境相关的关键目录与文件：

  • 服务入口与配置：bi-analysis/cmd/bi-analysis/main.go、configs/*.yaml
  • 构建与打包：bi-analysis/Dockerfile、go.mod
  • 公共能力：bi-common 下的数据库、缓存、消息队列、配置中心等
  • 本地基础设施：bi-chat/docker-compose.yml、.env.example
  • 部署模板：bi-analysis/k8s/deployment.yaml

图表来源

章节来源

核心组件 ​

  • Go 运行时与构建
    • 服务基于 Kratos 框架，使用 Google Wire 进行依赖注入，通过 Nacos 加载配置。
    • 构建镜像使用 Alpine Linux，包含时区与必要工具，支持私有仓库拉取。
  • 配置中心（Nacos）
    • 支持本地与远程配置源，按环境加载 application-*.yaml。
  • 数据库（MySQL/StarRocks）
    • 通过 GORM 配置连接参数、连接池、慢查询日志与 TLS。
  • 缓存（Redis）
    • 支持单机、哨兵、集群模式，可配置连接池、超时、TLS。
  • 消息队列（Kafka）
    • 支持生产者/消费者配置、批处理、压缩、分区策略与安全认证。
  • 本地基础设施（bi-chat）
    • 使用 Docker Compose 提供 PostgreSQL、Milvus、Etcd、MinIO、Redis。

章节来源

架构总览 ​

下图展示服务启动流程与外部依赖关系：

图表来源

章节来源

详细组件分析 ​

1) 前置条件与工具链 ​

  • Go 版本
    • 服务模块使用 Go 1.25.5；建议本地开发使用相同或兼容版本。
  • Node.js 与前端
    • 前端工程位于 ui-web、ui-web-admin 等目录，使用 Next.js 生态；建议安装 Node.js 18+。
  • Python 与后端
    • bi-chat 与 mcp-server-starrocks 使用 Python；建议安装 Python 3.9+。
  • Docker 与 Kubernetes
    • 服务提供 Dockerfile 与 K8s 部署模板；建议本地安装 Docker Desktop 与 kind/k3d/minikube 或远程集群。
  • 其他
    • Git、Make、YAML 编辑器、终端工具。

章节来源

2) IDE 配置与插件推荐 ​

  • VSCode
    • Go 扩展（gopls）、YAML、Docker、Kubernetes、ESLint（前端）、Python。
    • 推荐设置：启用 gofmt/goimports、保存时格式化、启用 gopls 诊断。
  • GoLand
    • 使用内置 Go 插件，启用代码格式化、测试运行、Wire 依赖注入支持。
  • WebStorm/Next.js
    • 启用 TypeScript/JavaScript、ESLint、Prettier、Tailwind CSS 支持。
  • Python
    • 在 PyCharm/VSCode 中启用 Python 扩展，安装依赖（requirements.txt）。

章节来源

3) 数据库与缓存配置 ​

MySQL/StarRocks（GORM） ​

  • 关键配置项
    • 驱动类型、主机、端口、数据库名、用户名、密码、字符集、连接池、日志级别、TLS。
  • 默认行为
    • 默认驱动为 mysql；当启用 StarRocks 优化或驱动为 starrocks 时，连接池参数会自动优化。
  • DSN 生成
    • 自动拼接 DSN，并根据 TLS 配置附加参数。

图表来源

章节来源

Redis（单机/哨兵/集群） ​

  • 关键配置项
    • 连接模式、地址列表、认证、DB、协议、重试、哨兵主名、集群路由策略、连接池、超时、TLS。
  • 默认行为
    • 默认单机模式，地址为 127.0.0.1:6379；可按需切换模式。

图表来源

章节来源

4) 消息队列（Kafka） ​

  • 关键配置项
    • 生产者：Broker 列表、Topic、Batch、可靠性、压缩、Balancer、超时、SASL/TLS。
    • 消费者：Broker、Topic、GroupID、分区、最小/最大字节、提交间隔、心跳/会话/再均衡超时、隔离级别、SASL/TLS。
  • 默认行为
    • 默认本地 Broker 地址；消费者组模式优先，支持分区变化监控。

图表来源

章节来源

5) 本地基础设施（Docker Compose） ​

  • 组件
    • PostgreSQL、Milvus（含 Etcd/MinIO）、Redis。
  • 端口映射
    • PostgreSQL: 5432 → 5432；Milvus: 19530 → 19530；Redis: 6379 → 6379。
  • 环境变量
    • 参考 bi-chat/.env.example 中的数据库、缓存、向量库等配置示例。

图表来源

章节来源

6) 配置中心（Nacos） ​

  • 本地配置
    • application-local.yaml 指定 Nacos 服务器地址、认证、命名空间、分组与配置 DataID。
  • 默认模板
    • nacos-default.yaml 提供默认字段与说明，便于理解配置项含义。
  • 服务加载
    • main.go 通过 -env 选择配置文件，动态加载并注入到服务。

图表来源

章节来源

7) 构建与部署 ​

  • 本地构建
    • 使用 bi-analysis/Dockerfile 构建二进制并打包到精简镜像，暴露 HTTP/gRPC 端口。
  • Kubernetes 部署
    • deployment.yaml 使用 ConfigMap/Secret 注入环境变量与认证信息，命令行传入 -env。

图表来源

章节来源

依赖关系分析 ​

  • 服务依赖
    • Kratos 框架、Wire 依赖注入、Nacos 配置中心、GORM/MySQL、Redis、Kafka。
  • 构建依赖
    • Go 模块替换指向本地 bi-common 与 bi-proto，便于联调。
  • 运行时依赖
    • 外部基础设施：Nacos、数据库、缓存、消息队列、本地 Compose 组件。

图表来源

章节来源

性能考虑 ​

  • 连接池优化
    • StarRocks 场景下自动优化连接池参数，减少连接频繁创建/销毁。
  • 日志与慢查询
    • GORM 日志级别与慢查询阈值可调，建议在开发环境适度放宽，生产环境收紧。
  • 缓存与队列
    • Redis 连接池大小、超时与 TLS 配置影响吞吐与稳定性；Kafka 批处理与压缩策略影响带宽与延迟。
  • 资源限制
    • K8s 部署模板提供 CPU/Memory 的 requests/limits，建议结合压测结果调整。

章节来源

故障排查指南 ​

  • 无法连接数据库
    • 检查 DSN 生成与 TLS 配置；确认主机、端口、账号、密码正确；如为 StarRocks，确认优化参数已生效。
  • Redis 连接失败
    • 核对模式（单机/哨兵/集群）、地址列表、认证与 DB；检查连接池大小与超时。
  • Kafka 消费无数据
    • 确认 Topic/GroupID/分区配置；开启分区变化监控；检查 SASL/TLS 是否启用且参数正确。
  • Nacos 配置加载失败
    • 校验 application-*.yaml 的 DataID 与命名空间；检查认证信息与网络连通性。
  • 本地 Compose 组件异常
    • 查看容器日志；确认端口未被占用；检查卷权限与初始化脚本。
  • Kubernetes 部署失败
    • 检查镜像拉取密钥、ConfigMap/Secret 注入、资源配额与节点亲和性。

章节来源

结论 ​

通过本指南，你可以完成从工具链安装、组件配置、本地 Compose 启动到 Kubernetes 部署的全流程准备。建议先在本地验证数据库/缓存/消息队列连通性，再启动服务并接入 Nacos 配置中心，最后使用 K8s 模板进行部署验证。遇到问题时，优先检查配置文件与日志输出，逐步定位依赖与网络问题。

附录 ​

A. 环境变量与密钥管理 ​

  • Nacos 认证
    • 通过 Secret 注入 NACOS_AUTH_USERNAME/PASSWORD；在 application-*.yaml 中配置认证信息。
  • 本地示例
    • 参考 bi-chat/.env.example 中的数据库、缓存、向量库等示例变量。
  • 安全建议
    • 生产环境避免将明文密钥写入代码；使用 K8s Secret、Vault 或云托管密钥服务。

章节来源