# insight

**Repository Path**: marcus_3/insight

## Basic Information

- **Project Name**: insight
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Insight 元数据管理系统

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/insight/metadata-management)
[![Java Version](https://img.shields.io/badge/Java-21-blue)](https://adoptium.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.0-green)](https://spring.io/projects/spring-boot)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

企业级多数据源元数据管理系统,支持自动采集、版本管理、数据字典生成和全文检索。

## 核心特性

### 🔄 多数据源支持
- **Oracle**: 11g, 12c, 19c, 21c
- **MySQL**: 5.7, 8.0+
- **PostgreSQL**: 12, 13, 14, 15+
- **SQL Server**: 2016, 2017, 2019, 2022
- **TiDB**: 5.x, 6.x, 7.x
- **达梦数据库**: DM8

### 📊 元数据采集
- ✅ 表结构自动采集 (表名、字段、类型、注释)
- ✅ 索引信息采集 (主键、外键、普通索引)
- ✅ 表关系分析 (外键关系、依赖关系)
- ✅ 统计信息采集 (行数、数据大小)
- ✅ Java 21 Virtual Threads 并发采集 (1000张表<10分钟)

### 📝 版本管理
- 🔍 SHA-256 结构哈希自动检测变更
- 📈 版本历史追踪 (最多保留30个版本)
- 🔄 版本对比与差异分析
- 📊 相似度计算 (Jaccard算法)

### 📄 数据字典生成
- **Excel**: 多sheet分组导出
- **PDF**: 中文字体支持,专业排版
- **Word**: 基于模板生成
- **Markdown**: GitHub风格文档
- 🎨 自定义模板支持 (Thymeleaf)

### 🔍 全文检索
- 基于 **ParadeDB pg_search** 扩展
- BM25 算法全文索引
- 中文分词支持 (jieba兼容)
- 表名、字段名、注释全文搜索

### 📊 可视化分析
- 表关系图谱生成 (GraphViz)
- 依赖关系分析
- 数据血缘追踪

## 技术架构

### 核心技术栈
- **Java 21**: Virtual Threads, Records, Pattern Matching
- **Spring Boot 3.2.0**: Web, JPA, Cache, Validation
- **ParadeDB**: PostgreSQL 15 + pg_search 全文检索扩展
- **Redis 7.x**: 二级缓存、分布式锁
- **Kafka 3.6.0**: 元数据变更事件流
- **MinIO**: 数据字典文件对象存储

### 性能优化
- ✅ HikariCP 连接池优化
- ✅ Hibernate 二级缓存 (Redis)
- ✅ JPA 批量插入/更新
- ✅ Virtual Threads 并发采集
- ✅ 异步操作日志

### 可观测性
- 📈 Prometheus metrics 导出
- 🏥 Spring Boot Actuator 健康检查
- 📋 Logback 结构化日志 (JSON)
- 🔍 操作审计日志

## 快速开始

### 前置条件
- Java 21+ (推荐 Amazon Corretto 21)
- Docker & Docker Compose
- Maven 3.8+

### 1. 启动依赖服务

```bash
docker-compose up -d
```

这将启动:
- ParadeDB (PostgreSQL 15 + pg_search): `localhost:31432`
- Redis 7.x: `localhost:31379`
- Kafka 3.6.0: `localhost:30092`
- Schema Registry: `localhost:8081`
- MinIO: `localhost:30900`

### 2. 编译项目

```bash
mvn clean compile
```

### 3. 运行应用

```bash
mvn spring-boot:run
```

应用启动后访问:
- **API 文档**: http://localhost:8080/swagger-ui.html
- **健康检查**: http://localhost:8080/actuator/health
- **Prometheus metrics**: http://localhost:8080/actuator/prometheus

### 4. 配置数据源

```bash
curl -X POST http://localhost:8080/api/datasources \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "生产MySQL",
    "dbType": "MYSQL",
    "host": "mysql.example.com",
    "port": 3306,
    "databaseName": "production",
    "username": "metadata_user",
    "password": "your_password"
  }'
```

### 5. 启动元数据采集

```bash
curl -X POST http://localhost:8080/api/collection/tasks \\
  -H "Content-Type: application/json" \\
  -d '{
    "datasourceId": 1,
    "taskType": "FULL"
  }'
```

详细使用说明请参考 [QUICKSTART.md](./QUICKSTART.md)

## API 文档

启动应用后访问 Swagger UI: http://localhost:8080/swagger-ui.html

主要 API 端点:

### 数据源管理
- `POST /api/datasources` - 创建数据源
- `GET /api/datasources` - 查询数据源列表
- `GET /api/datasources/{id}` - 查询数据源详情
- `PUT /api/datasources/{id}` - 更新数据源
- `DELETE /api/datasources/{id}` - 删除数据源
- `POST /api/datasources/test-connection` - 测试数据库连接

### 元数据采集
- `POST /api/collection/tasks` - 创建采集任务
- `GET /api/collection/tasks` - 查询任务列表
- `GET /api/collection/tasks/{id}` - 查询任务详情
- `POST /api/collection/tasks/{id}/cancel` - 取消任务

### 元数据查询
- `GET /api/metadata/tables` - 查询表列表
- `GET /api/metadata/tables/{id}` - 查询表详情
- `GET /api/metadata/tables/{id}/columns` - 查询表字段
- `GET /api/metadata/search` - 全文检索

### 版本管理
- `GET /api/metadata/tables/{id}/versions` - 查询版本历史
- `GET /api/metadata/versions/{id}` - 查询版本详情
- `POST /api/metadata/versions/compare` - 版本对比

### 数据字典导出
- `POST /api/dictionary/export` - 创建导出任务
- `GET /api/dictionary/exports/{id}` - 查询导出任务
- `GET /api/dictionary/exports/{id}/download` - 下载数据字典

### 表关系分析
- `GET /api/relationships/datasource/{id}/graph` - 数据源关系图
- `GET /api/relationships/table/{id}/graph` - 表关系图

## 配置说明

### application.yml 核心配置

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:31432/insight
    username: dgp_user
    password: dgp_password

    hikari:
      maximum-pool-size: 20
      minimum-idle: 10

insight:
  collection:
    max-concurrent-tasks: 10
    enable-virtual-threads: true

  version:
    max-versions-per-table: 30
    similarity-threshold: 0.80

  search:
    enable-chinese-tokenizer: true
```

### 生产环境配置

使用 `application-prod.yml` 配置生产环境:

```bash
java -jar insight.jar --spring.profiles.active=prod
```

支持环境变量:
- `DB_URL`: 数据库连接地址
- `DB_USERNAME`: 数据库用户名
- `DB_PASSWORD`: 数据库密码
- `REDIS_HOST`: Redis 主机地址
- `REDIS_PASSWORD`: Redis 密码
- `KAFKA_BROKERS`: Kafka broker 地址
- `MINIO_ENDPOINT`: MinIO 端点

## 开发指南

### 项目结构

```
src/
├── main/
│   ├── java/com/insight/
│   │   ├── controller/      # REST API 控制器
│   │   ├── service/         # 业务服务层
│   │   ├── repository/      # 数据访问层
│   │   ├── entity/          # JPA 实体
│   │   ├── dto/             # 数据传输对象
│   │   ├── mapper/          # MapStruct 映射器
│   │   ├── collector/       # 元数据采集器
│   │   ├── export/          # 数据字典导出
│   │   ├── config/          # 配置类
│   │   ├── common/          # 通用工具
│   │   └── aop/             # AOP 切面
│   └── resources/
│       ├── application.yml
│       ├── application-prod.yml
│       ├── db/schema.sql
│       └── logback-spring.xml
└── test/
    ├── java/com/insight/
    │   ├── controller/      # 控制器测试
    │   ├── service/         # 服务测试
    │   ├── entity/          # 实体测试
    │   ├── acceptance/      # 验收测试
    │   └── benchmark/       # 性能测试 (JMH)
    └── resources/
        └── application-test.yml
```

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=DataSourceControllerTest

# 运行性能基准测试
mvn test -Dtest=LargeScaleCollectionBenchmark
```

### 代码质量

项目强制执行 80% 代码覆盖率:

```bash
mvn clean test jacoco:report jacoco:check
```

查看覆盖率报告: `target/site/jacoco/index.html`

## 部署指南

### Docker 部署

```bash
# 构建镜像
docker build -t insight-metadata:1.0.0 .

# 运行容器
docker run -d \\
  -p 8080:8080 \\
  -e DB_URL=jdbc:postgresql://paradedb:5432/insight \\
  -e DB_PASSWORD=your_password \\
  -e REDIS_PASSWORD=your_redis_password \\
  --name insight-metadata \\
  insight-metadata:1.0.0
```

### Kubernetes 部署

```bash
# 应用 Kubernetes 配置
kubectl apply -f k8s/

# 查看部署状态
kubectl get pods -l app=insight-metadata

# 查看健康检查
kubectl get pods -l app=insight-metadata -o jsonpath='{.items[*].status.conditions[?(@.type=="Ready")].status}'
```

Kubernetes 探针配置:
- **Liveness probe**: `/actuator/health/liveness`
- **Readiness probe**: `/actuator/health/readiness`

## 监控告警

### Prometheus 监控指标

- `http_server_requests_*`: HTTP 请求指标
- `jvm_*`: JVM 内存、线程、GC 指标
- `hikaricp_*`: 数据库连接池指标
- `cache_*`: 缓存命中率指标
- `collection_tasks_*`: 采集任务指标

### Grafana 仪表板

导入预配置仪表板: `monitoring/grafana-dashboard.json`

## 常见问题

### Q: 如何配置多个数据源?
A: 通过 REST API 动态添加数据源,无需重启应用:
```bash
POST /api/datasources
```

### Q: 采集1000张表需要多久?
A: 开启 Virtual Threads 后,通常 <10 分钟 (视网络和数据库性能)

### Q: 如何自定义数据字典模板?
A: 在 `templates/` 目录创建 Thymeleaf 模板文件,支持HTML/Markdown格式

### Q: 支持哪些中文分词器?
A: 使用 ParadeDB 内置的 `chinese_compatible` 分词器,兼容 jieba

### Q: 如何开启生产环境 API 文档?
A: 设置环境变量:
```bash
export API_DOCS_ENABLED=true
export SWAGGER_UI_ENABLED=true
```

## 贡献指南

欢迎提交 Issue 和 Pull Request!

### 开发流程
1. Fork 本仓库
2. 创建特性分支: `git checkout -b feature/your-feature`
3. 提交代码: `git commit -m 'Add your feature'`
4. 推送分支: `git push origin feature/your-feature`
5. 提交 Pull Request

### 代码规范
- 遵循 Java 编码规范
- 使用 MapStruct 进行对象映射
- 使用 Lombok 减少样板代码
- 编写单元测试,确保覆盖率 ≥80%
- 使用有意义的变量和方法命名

## 许可证

本项目采用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可证。

## 联系方式

- **项目主页**: https://github.com/insight/metadata-management
- **问题反馈**: https://github.com/insight/metadata-management/issues
- **邮箱**: insight@example.com

---

**Made with ❤️ by Insight Team**