# bond_analysis

**Repository Path**: istop/bond_analysis

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flask + 本地线程 + MySQL 异步任务系统 - 部署指南

## 环境要求

- Python 3.12+
- MySQL 8.0+

> 说明：已移除 Celery / Redis 依赖，异步任务改为进程内线程池执行（见 `service_api/thread_tasks.py`）。

## 1. 安装依赖包

```bash
cd d:\dlh_ccdc\GreenBondAnalysis_API
pip install -r requirements.txt
```

## 2. 配置文件检查

检查 `service_api/config.py`：
- MySQL 配置（从 `utils/const.py` 自动读取）
- 线程任务配置：`THREAD_MAX_WORKERS`（线程池并发数，默认 4）、`THREAD_SOFT_TIME_LIMIT`（软超时，默认 3600 秒）

## 3. 初始化数据库

```bash
cd d:\dlh_ccdc\GreenBondAnalysis_API\service_api
python init_db.py
```

预期输出：
```
🚀 开始初始化数据库...
✅ 数据库表创建成功！
✅ 数据库初始化完成！
```

## 4. 启动服务

> **无需单独启动 Worker 和队列进程**：
> - 异步任务由 Flask 进程内的线程池（`THREAD_MAX_WORKERS` 控制并发）执行。
> - 队列消费线程（原 `queue.py`）已整合至 Flask，首次收到请求时自动启动，无需单独运行 `python queue.py`。

### 4.1 开发环境（Flask 内置服务器）

**方式一：双击脚本**
```
直接双击项目根目录下的 start_flask.bat
```

**方式二：命令行**

```bash
cd d:\dlh_ccdc\GreenBondAnalysis_API\service_api
python app.py
```

### 4.2 生产环境（Gunicorn）

**方式一：Shell 脚本**

```bash
cd d:\dlh_ccdc\GreenBondAnalysis_API
./start_gunicorn.sh
```

**方式二：直接运行**

```bash
cd d:\dlh_ccdc\GreenBondAnalysis_API
gunicorn -c gunicorn_config.py service_api.app:app
```

Gunicorn 配置项可通过环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `GUNICORN_PORT` | `15000` | 监听端口 |
| `GUNICORN_WORKERS` | `2*CPU+1` | Worker 进程数 |
| `GUNICORN_LOG_LEVEL` | `info` | 日志级别 |

预期输出：
```
 * Serving Flask app 'app'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://192.168.x.x:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
```

## 5. 测试接口

### 5.1 健康检查

```bash
curl http://localhost:5000/api/v1/health/
```

预期响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "now_time": "2026.01.26 16:00:00"
  }
}
```

### 5.2 上传文件（异步任务）

使用 Postman 或 curl：

```bash
curl -X POST http://localhost:5000/api/v1/file/upload/ \
  -F "file=@D:\test.pdf"
```

预期响应：
```json
{
  "code": 200,
  "msg": "任务已提交",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "filename": "1737876000.123-test.pdf",
    "status": "pending"
  }
}
```

### 5.3 查询任务状态

```bash
curl http://localhost:5000/api/v1/task/abc123-def456-ghi789/
```

**处理中：**
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "filename": "1737876000.123-test.pdf",
    "status": "processing",
    "progress": 30,
    "result": null,
    "created_at": "2026-01-26 16:00:00"
  }
}
```

**已完成：**
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "filename": "1737876000.123-test.pdf",
    "status": "completed",
    "progress": 100,
    "result": {
      "success": true,
      "start_page": 9,
      "end_page": 15,
      "data": {
        "answer": "大模型回答内容...",
        "filename": "test.pdf"
      }
    },
    "completed_at": "2026-01-26 16:05:00"
  }
}
```

### 5.4 查询任务列表

```bash
# 查询所有任务
curl http://localhost:5000/api/v1/tasks/

# 查询指定状态的任务
curl "http://localhost:5000/api/v1/tasks/?status=completed"

# 分页查询
curl "http://localhost:5000/api/v1/tasks/?limit=10&offset=0"
```

### 5.5 监控仪表盘（首页）

启动服务后，浏览器访问根路径即可查看实时监控面板：

```bash
# 监控首页（HTML）
http://localhost:5000/dashboard
# 或根路径
http://localhost:5000/

# 监控数据（JSON，供前端轮询）
curl http://localhost:5000/api/v1/dashboard/

# 自定义刷新间隔（秒）
http://localhost:5000/dashboard?interval=10
```

面板包含四个维度：
- **服务器状态**：主机名、CPU/内存/磁盘使用率、进程 PID、运行时长、线程池并发与活跃任务数
- **任务队列**：`t_file_recog_task_queue` 按状态（待处理/处理中/已完成/失败）统计，及最近 20 条明细
- **处理情况**：`greenbond_tasks` 按状态统计与进度，及最近 20 条明细
- **Redis 数据**：若已配置 `REDIS_URL` 且可达，展示 key 总数、内存占用、采样 key；否则显示「不可用」原因

> 说明：本项目已移除 Celery/Redis 作为任务存储，Redis 面板仅作可选监控；需先 `pip install redis`（已加入 `requirements.txt`）才会尝试连接。

## 6. 常见问题

### Q1: MySQL 连接失败
**错误信息：** `Can't connect to MySQL server`

**解决方案：**
1. 确认 MySQL 服务已启动
2. 检查 `utils/const.py` 中的数据库配置
3. 运行 `python init_db.py` 初始化表

### Q2: 任务一直 pending / 无执行
**可能原因：**
1. Flask 进程未正常运行
2. 线程池任务抛出异常（查看 Flask 日志）

**检查方法：**
- 查看 Flask 终端输出
- 通过 `/api/v1/task/<task_id>/` 查询任务状态

## 7. 生产环境部署建议

1. **使用 Supervisor 或 systemd 管理进程**
2. **使用 Nginx + Gunicorn 替代 Flask 开发服务器**
3. **并发度由 `THREAD_MAX_WORKERS` 控制，按需调整**
4. **定期清理过期任务**（数据库）
5. **配置日志系统**
6. **使用环境变量管理敏感配置**

## 8. 目录结构

```
GreenBondAnalysis_API/
├── requirements.txt            # 统一依赖清单
├── service_api/
│   ├── app.py                 # Flask 主应用
│   ├── config.py              # 配置文件
│   ├── database.py            # 数据库连接
│   ├── models.py              # 数据库模型
│   ├── thread_tasks.py        # 本地线程池调度器
│   ├── tasks.py               # 异步任务
│   ├── init_db.py             # 数据库初始化脚本
│   └── local_file_storage/    # 上传文件目录
├── data_extraction/
│   ├── corporate_credit_bonds.py        # PDF 处理逻辑
│   └── local_pdf_storage/     # 处理后的 PDF 文件
└── utils/
    └── const.py               # 常量配置
```