# faq errorcode dags

**Repository Path**: lainyu/faq-errorcode-dags

## Basic Information

- **Project Name**: faq errorcode dags
- **Description**: 该系统用于定时从阿里云数据库获取数据，并将数据按照特定格式上传到 Dify 知识库。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-05
- **Last Updated**: 2025-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FAQ与错误代码爬虫系统

## 项目概述

这是一个基于Apache Airflow的知识库爬虫系统，用于从阿里云数据库中提取FAQ、故障排除和错误代码数据，并将其上传到Dify知识库。

传送文件命令
- `scp -r ./faq-errorcode-crawler-dags/ agi@192.168.40.16:/home/agi/Documents/docker_param_files/airflow/dags`
- `scp -r .\faq-crawler-dags\ agi@192.168.40.16:/home/agi/Documents/docker_param_files/airflow/dags` 

## 当前架构状态

### ✅ 系统状态 - 稳定运行

经过系统重装和优化，之前的MySQL连接问题已得到解决。当前系统采用**混合模式**运行：

1. **统一爬虫** (`unified_crawler`) - 处理故障排除和错误代码数据
2. **FAQ爬虫** (`faq_crawler`) - 专门处理FAQ数据  
3. **文件检测器** (`file_checker`) - 智能检测文件变更 **（新增功能）**

这种架构的优势：
- 🚀 并行执行，提高效率
- 🔍 智能文件检测，只上传变更内容
- 📧 自动邮件通知，及时了解数据更新
- 🎯 增量上传，节省时间和资源

### 当前实现状态

#### 1. 连接管理 (`conn_manager.py`)
- ✅ 实现了统一的连接管理器
- ✅ 支持SSH隧道连接
- ✅ 提供两个独立的数据库连接:
  - `aliyun-database-faq` - FAQ数据库连接
  - `aliyun-database-ec-ts` - 故障排除和错误代码数据库连接
- ✅ 集中管理数据目录配置
- ✅ 新增Dify配置管理

#### 2. 统一爬虫 (`unified_crawler.py`)
- ✅ 实现了统一的数据获取逻辑
- ✅ 支持FAQ、故障排除和错误代码数据的区分处理
- ✅ 提供递归树状结构解析
- ✅ 包含错误代码过滤功能
- ⚠️ **存在MySQL连接问题，需要拆分为独立DAG**

#### 3. 当前DAG架构 (`faq_errorcode_crawler_dag.py`)
- ✅ 混合爬虫模式 (`unified_crawler` + `faq_crawler`)
- ✅ 实现了连接预热机制，连接问题已解决
- ✅ 智能文件检测和增量上传功能
- ✅ 包含完整的工作流程：
  1. 创建数据目录
  2. 并行运行爬虫（统一爬虫 + FAQ爬虫）
  3. 文本清理
  4. **文件变更检测** 🆕
  5. 智能上传到Dify（增量/跳过）

#### 4. 数据处理模块
- ✅ `faq_crawler.py` - FAQ数据专用爬虫
- ✅ `unified_crawler.py` - 统一爬虫（故障排除+错误代码）
- ✅ `replace_all_txt.py` - JSON字符清理
- ✅ `file_cheker.py` - 文件变更检测器 🆕
- ✅ `upload_to_dify.py` - Dify上传功能（支持增量上传）
- ✅ `dify_utils.py` - Dify工具函数

#### 5. 文件检测与邮件通知 🆕
- 🔍 **智能文件检测**: 自动对比文件结构变化
- 📧 **邮件通知功能**: 检测到变更时自动发送详细报告
- 📝 **变更记录**: 维护文件历史记录 (`faq-recorder.json`)
- 🎯 **增量上传**: 只上传新增或修改的文件，提高效率

### 智能工作流程

#### 🔄 当前执行流程

```
📁 创建数据目录
        ↓
🕷️ 并行运行爬虫
├── unified_crawler (故障排除+错误代码)
└── faq_crawler (FAQ数据)
        ↓
🧹 文本清理处理
        ↓
🔍 文件变更检测 🆕
├── 对比历史记录
├── 识别新增/更新/删除文件  
└── 📧 发送邮件通知（如有变更）
        ↓
🎯 智能上传决策
├── 有变更 → 增量上传变更文件
├── 无变更 → 跳过上传
└── 异常时 → 回退到全量上传
```

#### 📧 邮件通知功能
- **收件人**: 技术中心-AGI应用部团队
- **触发条件**: 检测到文件新增、更新或删除
- **邮件内容**: 
  - 📊 变更统计信息
  - 📄 详细文件列表  
  - 🔗 DAG执行链接
  - 😉 可爱小爬虫签名

## 技术架构

### 数据库连接
- **SSH隧道**: 通过`product-cloud-app`连接
- **FAQ数据库**: `aliyun-database-faq`
- **故障排除数据库**: `aliyun-database-ec-ts`

### 数据目录结构
```
data/
├── faq/          # FAQ数据文件
└── errorcode/    # 故障排除和错误代码数据文件
```

### Dify集成
- 支持本地和AWS Dify环境
- 通过Airflow Variables配置:
  - `local_dify` - 本地Dify配置
  - `aws_dify` - AWS Dify配置

## 部署配置

### Airflow Connections
需要配置以下连接：

1. **product-cloud-app** (SSH隧道)
   - Host: SSH服务器地址
   - Port: SSH端口 (默认22)
   - Login: SSH用户名
   - Password: SSH密码

2. **aliyun-database-faq** (FAQ数据库)
   - Host: 数据库地址
   - Port: 数据库端口 (默认3306)
   - Login: 数据库用户名
   - Password: 数据库密码
   - Schema: 数据库名称

3. **aliyun-database-ec-ts** (故障排除数据库)
   - Host: 数据库地址
   - Port: 数据库端口 (默认3306)
   - Login: 数据库用户名
   - Password: 数据库密码
   - Schema: 数据库名称

### Airflow Variables
需要设置以下变量：

1. **local_dify** - 本地Dify配置JSON
2. **aws_dify** - AWS Dify配置JSON

## 运行说明

### 当前状态
- 使用混合DAG：`unified_crawler` 🆕
- 调度：每周六凌晨2点运行
- 标签：`spider`, `knowledge_base`, `dify`, `file_checker` 🆕
- 新增功能：
  - 🔍 智能文件检测
  - 📧 自动邮件通知
  - 🎯 增量上传优化
  - 🚀 并行爬虫执行

### 增量上传机制 🆕
- **检测原理**: 基于文件大小对比历史记录
- **上传策略**: 
  ```
  export_all=True  → 全量上传所有文件
  export_all=False → 只上传变更文件 (新增+更新)
  ```
- **文件分类**: 自动识别FAQ文件和错误代码文件
- **知识库映射**: 
  - FAQ文件 → 按产品分组到对应知识库
  - 错误代码文件 → 统一上传到Bluetti-ErrorCode知识库

## 故障排除

### MySQL连接问题 ✅ 已解决
~~之前的连接问题已通过系统重装得到解决~~

如果遇到MySQL连接问题：
1. 检查SSH隧道连接是否正常
2. 验证数据库连接配置
3. 查看Airflow日志中的详细错误信息
4. 使用连接预热机制

### 文件检测问题 🆕
如果文件检测异常：
1. 检查数据目录权限：`/opt/airflow/dags/faq-errorcode-crawler-dags/data`
2. 验证 `faq-recorder.json` 文件格式
3. 确认邮件配置正确 (`conn_manager.py` 中的 `EMAIL_CONFIG`)
4. 查看文件检测日志中的详细信息

### 数据目录问题
如果数据文件未正确保存：
1. 检查数据目录权限
2. 验证路径配置是否正确
3. 查看文件系统空间是否充足

## 开发历史

### 主要里程碑
1. ✅ 实现基础FAQ和故障排除爬虫
2. ✅ 创建统一连接管理器
3. ✅ 建立Airflow DAG工作流
4. ✅ 集成Dify知识库上传
5. ✅ 解决MySQL连接问题（系统重装）
6. ✅ 实现智能文件检测功能 🆕
7. ✅ 集成邮件通知系统 🆕
8. ✅ 支持增量上传优化 🆕

### 技术改进
- 从相对路径改为绝对路径
- 实现contextmanager连接管理
- 添加comprehensive logging
- 建立错误处理机制
- 支持多环境Dify配置
- **智能文件变更检测** 🆕
- **增量上传机制** 🆕
- **自动邮件通知** 🆕
- **并行爬虫执行** 🆕

## 文件检测记录格式 🆕

```json
{
  "last_update_time": "2025-06-13 04:00:00",
  "file_structure": {
    "faq": [
      {
        "file_name": "AC200MAX-faq.txt",
        "file_path": "/opt/airflow/dags/.../data/faq/AC200MAX-faq.txt",
        "file_size": 4096
      }
    ],
    "errorcode": [
      {
        "file_name": "error-codes.txt", 
        "file_path": "/opt/airflow/dags/.../data/errorcode/error-codes.txt",
        "file_size": 2048
      }
    ]
  }
}
```

## 下一步计划

1. **优化**: 改进文件检测精度（MD5校验）
2. **监控**: 添加文件检测性能指标
3. **扩展**: 支持更多文件类型检测
4. **集成**: 与其他系统的数据同步

---

*最后更新：2025年06月 - 实现智能文件检测和增量上传功能* 🚀