# GCP 账单数据工具

本目录包含 GCP 账单数据的导出和分析工具，用于从 BigQuery 导出账单数据并进行异常检测。

## 🚀 快速开始

### 1. 安装依赖
```bash
pip install google-cloud-bigquery requests pandas
```

### 2. 配置环境
```bash
# 设置 Google Cloud 认证
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

# 创建配置文件
cp config.json.example config.json
# 编辑 config.json，设置云级 webhook（cloud_webhook_url）及项目分类（环境不再单独配置 webhook）
```

### 3. 导出数据
```bash
# 导出最近一周数据
python -m gcp.main_export --last-week

# 导出特定环境数据
python -m gcp.main_export --env prod --days 30
```

### 4. 分析数据
```bash
# 分析并发送告警（默认分析前天数据）
python -m gcp.main_analyze --config gcp/config.json

# 测试模式（不发送通知）
python -m gcp.main_analyze --dry-run
```

## 📁 工具说明

### main_export.py - 数据导出工具
从 BigQuery 导出 GCP 账单数据到 CSV 文件，按环境分类存储。

**主要功能：**
- 自动发现所有活跃的 GCP 项目
- 支持并发查询提高效率
- 智能缓存减少重复查询
- 按项目和月份分别保存文件

**常用命令：**
```bash
# 导出最近 7 天
python -m gcp.main_export --days 7

# 导出指定日期范围
python -m gcp.main_export --start-date 2025-08-01 --end-date 2025-08-15

# 导出特定环境
python -m gcp.main_export --env prod --days 30

# 使用更多并发线程
python -m gcp.main_export --last-week --max-workers 10

# 强制刷新缓存
python -m gcp.main_export --last-week --refresh-cache
```

### main_analyze.py - 异常分析工具
分析导出的账单数据，检测异常并发送飞书告警。支持环境分类分析。
统一告警通过 `cloud_webhook_url` 发送到同一 GCP 话题群，已移除环境维度的独立 webhook。

**主要功能：**
- 项目维度费用异常检测
- 服务维度费用异常检测
- 新服务和停用服务检测
- 支持生产/非生产环境分别配置

**常用命令：**
```bash
# 分析指定日期（自动从prod和nonprod目录加载）
python -m gcp.main_analyze --date 2025-08-15 --config gcp/config.json

# 分析特定项目
python -m gcp.main_analyze --project-id tidbcloud-prod-000

# 测试模式（不发送通知）
python -m gcp.main_analyze --dry-run

# 指定配置文件
python -m gcp.main_analyze --config gcp/config.json
```

### MySQL 首次数据同步
将历史 CSV 导入 MySQL 以便门户与报表消费。

**前置准备：**
- 在 `gcp/config.json` 中填写正确的 `mysqlConfig` 凭证，并新增 `"accountDetailsFile": "gcp_account_details.csv"` 字段指向活跃项目清单。
- 确认 `gcp/gcp_billing_exports/<env>/` 已包含导出的 CSV 文件。
- 推荐先创建虚拟环境并安装依赖：
  ```bash
  python3 -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt
  ```

**执行步骤：**
1. 预览将要同步的文件：
   ```bash
   python -m gcp.scripts.backfill_mysql \
     --config gcp/config.json \
     --exports-root gcp/gcp_billing_exports \
     --dry-run
   ```
2. 无误后去掉 `--dry-run` 执行正式同步：
   ```bash
   python -m gcp.scripts.backfill_mysql \
     --config gcp/config.json \
     --exports-root gcp/gcp_billing_exports
   ```
   *仅对 `gcp_account_details.csv` 中标记为活跃的项目写入数据；若需导入已归档的项目，可追加 `--include-inactive`。*

**常用参数：**
- `--env prod` / `--env nonprod`：仅同步指定环境目录。
- `--project <project_id>`：只导入单个项目，参数可重复。
- `--limit 5`：限制本次处理的文件数量。

**验证：**
- 查看脚本输出的 “已同步/已跳过” 总结。
- 在 MySQL 中检查 `billing_accounts`、`billing_daily_costs` 表确认新数据与活跃标记。
- 访问门户 API（如 `/api/accounts`、`/api/costs/monthly?provider=gcp`）确认前端只展示活跃账户。

## ⚙️ 配置说明

### config.json 结构
```json
{
  "cloud_webhook_url": "https://open.feishu.cn/...",  // 云级飞书 webhook（唯一通道）
  "environments": {
    "prod": {
      "name": "生产环境",
      "projects": ["tidbcloud-prod-000", "dbaas-prod"],
      "thresholds": {
        "project_warning": 1.5,
        "project_critical": 2.0,
        "service_warning": 2.0,
        "service_critical": 3.0,
        "min_cost_threshold": 10.0,
        "new_service_threshold": 15.0
      }
    },
    "nonprod": {
      "name": "开发测试环境",
      "projects": [],
      "thresholds": {
        "project_warning": 2.0,
        "project_critical": 3.0,
        "service_warning": 2.5,
        "service_critical": 4.0,
        "min_cost_threshold": 5.0,
        "new_service_threshold": 10.0
      }
    }
  }
}
```

## 📊 数据结构

### BigQuery 数据源
- **Dataset**: `gcp-digital-bi.gcp_billing_v2`
- **当前表**: `gcp_billing_export_v1_01D088_8F9CF2_8AF1C6`（2025-11-20 当日 + 2025-11-21 及以后，迁移日数据与旧表分流）
- **主表 (旧版本)**: `gcp_billing_export_v1_01A169_D3D9BF_FB82A2`（2023-04-20 ~ 2025-11-20，其中 2025-11-20 当日与新表分流）
- **历史表**: `gcp_billing_export_v1_*`（2023-04-19 之前）

### CSV 文件格式
```csv
date,project_id,project_name,product,cost
2025-08-15,tidbcloud-prod-000,TiDB Cloud Production,Compute Engine,1234.56
```

### 输出目录结构
```
gcp/gcp_billing_exports/
├── gcp_projects_cache.json     # 项目缓存文件
├── prod/                        # 生产环境数据
│   └── gcp_{project_id}_{YYYY-MM}.csv
└── nonprod/                     # 非生产环境数据
    └── gcp_{project_id}_{YYYY-MM}.csv
```

## 🔄 定时任务配置

### Crontab 配置
```bash
# 每天早上 8 点导出前一天数据
0 8 * * * cd /path/to/project && python -m gcp.main_export --days 1

# 每天早上 9 点分析并发送告警
0 9 * * * cd /path/to/project && python -m gcp.main_analyze --config gcp/config.json

# 每周一导出上周数据
0 8 * * 1 cd /path/to/project && python -m gcp.main_export --last-week
```

## 🔍 故障排查

### 常见问题

1. **BigQuery 权限错误**
   ```bash
   # 检查服务账号权限
   gcloud projects get-iam-policy PROJECT_ID
   # 需要 BigQuery Data Viewer 权限
   ```

2. **找不到数据文件**
   ```bash
   # 确认数据已导出
   ls -la gcp/gcp_billing_exports/
   # 检查文件命名格式
   ```

3. **飞书通知失败**
   ```bash
   # 测试 webhook
   curl -X POST $cloud_webhook_url -H "Content-Type: application/json" \
     -d '{"msg_type":"text","content":{"text":"test"}}'
   ```

## 📈 最佳实践

1. **导出频率**：建议每日导出，避免数据积压
2. **分析时机**：在导出完成后 1 小时进行分析
3. **阈值调整**：根据实际情况调整异常检测阈值
4. **监控告警**：设置脚本执行失败的监控告警
5. **数据备份**：定期备份导出的 CSV 文件

## 🧪 测试验证

```bash
# 测试导出（仅导出 1 天数据）
python -m gcp.main_export --days 1

# 测试分析（dry-run 模式）
python -m gcp.main_analyze --dry-run

# 测试环境分类功能
python -m gcp.main_export --env prod --days 1
python -m gcp.main_export --env nonprod --days 1
```

## 📝 详细文档

更多详细信息请参考：
- [数据导出详细说明](GCP_BILLING_README.md)
- [异常分析详细说明](GCP_DAILY_BILLING_ANALYZER_README.md)
- [环境分类功能说明](环境分类功能更新说明.md)