# 🚀 AWS Resource Scanner - 快速启动指南

## 项目概述

AWS Resource Scanner 是一个用于扫描和报告AWS资源的Web应用程序，包含：
- **Backend**: Python Flask API服务
- **Frontend**: React + TypeScript Web界面

## 环境要求

### Backend
- Python 3.8+
- pip (Python包管理器)
- Redis (推荐，用于任务队列)

### Frontend  
- Node.js 18+
- npm/yarn (包管理器)

**注意**: Redis是可选的。如果没有安装Redis，应用会自动使用Mock模式，可以进行基本功能测试。

## 快速启动

### 1. 启动Backend

```bash
# 进入backend目录
cd backend

# Windows: 运行设置脚本
setup.bat

# Unix/Linux/macOS: 运行设置脚本
chmod +x setup.sh
./setup.sh

# 激活虚拟环境
# Windows:
activate_venv.bat

# Unix/Linux/macOS:
source activate_venv.sh

# 初始化数据库
python init_db.py

# 检查Redis连接 (可选)
python test_redis.py

# 启动Flask应用 (自动检测Redis)
python start_with_redis_check.py

# 或者直接启动 (如果确定Redis已配置)
python run.py
```

**注意**: 如果没有安装Redis，应用会自动切换到Mock模式，功能受限但可以进行基本测试。

Backend将运行在: http://localhost:5000

### 2. 启动Frontend

```bash
# 新开一个终端，进入frontend目录
cd frontend

# Windows: 运行设置脚本
setup.bat

# Unix/Linux/macOS: 运行设置脚本
chmod +x setup.sh
./setup.sh

# 启动开发服务器
yarn dev
```

Frontend将运行在: http://localhost:3000

### 3. 访问应用

- **Web界面**: http://localhost:3000
- **API文档**: http://localhost:5000/api
- **默认管理员**: `admin` / `admin123`

## 项目结构

```
cloud-reporter/
├── backend/                    # Python Flask后端
│   ├── app/                   # 应用代码
│   ├── config/                # 配置文件
│   ├── migrations/            # 数据库迁移
│   ├── tests/                 # 测试文件
│   ├── venv/                  # Python虚拟环境
│   ├── requirements.txt       # Python依赖
│   ├── setup_venv.py         # 环境设置脚本
│   ├── init_db.py            # 数据库初始化
│   └── run.py                # 应用入口
├── frontend/                   # React前端
│   ├── src/                   # 源代码
│   ├── node_modules/          # Node.js依赖
│   ├── package.json           # 项目配置
│   ├── vite.config.ts         # 构建配置
│   └── setup.bat/sh           # 环境设置脚本
└── sample-reports/            # 示例报告文件
```

## 开发工作流

### Backend开发

```bash
cd backend

# 激活虚拟环境
activate_venv.bat  # Windows
source activate_venv.sh  # Unix/Linux

# 启动开发服务器
python run.py

# 运行测试
pytest

# 数据库操作
python init_db.py --reset      # 重置数据库
python init_db.py --with-demo  # 创建示例数据
```

### Frontend开发

```bash
cd frontend

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build

# 运行测试
yarn test

# 代码检查
yarn lint
```

## 功能特性

### 已实现功能
- ✅ 用户认证和授权
- ✅ AWS凭证管理
- ✅ 资源扫描任务
- ✅ 报告生成和下载
- ✅ 任务日志和监控
- ✅ 响应式Web界面

### 核心模块
- **认证系统**: JWT令牌认证
- **凭证管理**: AWS访问密钥和角色管理
- **扫描引擎**: 多服务AWS资源扫描
- **报告生成**: Word文档报告生成
- **任务队列**: Celery异步任务处理

## API接口

### 认证接口
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/refresh` - 刷新令牌
- `POST /api/auth/logout` - 用户登出

### 用户管理
- `GET /api/users` - 获取用户列表
- `POST /api/users` - 创建用户
- `PUT /api/users/{id}` - 更新用户
- `DELETE /api/users/{id}` - 删除用户

### 凭证管理
- `GET /api/credentials` - 获取凭证列表
- `POST /api/credentials` - 创建凭证
- `PUT /api/credentials/{id}` - 更新凭证
- `DELETE /api/credentials/{id}` - 删除凭证

### 任务管理
- `GET /api/tasks` - 获取任务列表
- `POST /api/tasks` - 创建扫描任务
- `GET /api/tasks/{id}` - 获取任务详情
- `DELETE /api/tasks/{id}` - 删除任务

### 报告管理
- `GET /api/reports` - 获取报告列表
- `GET /api/reports/download?id={id}` - 下载报告

## 环境配置

### Backend环境变量 (.env)
```env
FLASK_ENV=development
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret-key
DATABASE_URL=sqlite:///dev.db
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
ENCRYPTION_KEY=your-encryption-key
```

### Frontend环境变量 (.env.local)
```env
VITE_API_BASE_URL=http://localhost:5000
VITE_APP_TITLE=AWS Resource Scanner
VITE_DEBUG=true
```

## 故障排除

### Backend问题

1. **虚拟环境问题**
```bash
# 重新创建虚拟环境
python setup_venv.py --clean
```

2. **数据库问题**
```bash
# 重置数据库
python init_db.py --reset
```

3. **依赖问题**
```bash
# 升级依赖
python setup_venv.py --upgrade
```

### Frontend问题

1. **依赖安装失败**
```bash
# 清理并重新安装
yarn cache clean
rm -rf node_modules yarn.lock
yarn install
```

2. **端口冲突**
```bash
# 使用不同端口
yarn dev --port 3001
```

3. **构建失败**
```bash
# 检查TypeScript错误
npx tsc --noEmit
```

## 验证安装

### Backend验证
```bash
cd backend
python verify_setup.py
```

### Frontend验证
```bash
cd frontend
node verify_setup.js
```

## 生产部署

### Backend部署
1. 设置生产环境变量
2. 使用PostgreSQL数据库
3. 配置Redis服务
4. 使用Gunicorn + Nginx

### Frontend部署
1. 构建生产版本: `yarn build`
2. 部署dist目录到静态服务器
3. 配置API代理

## 获取帮助

- 查看详细文档: `backend/README_VENV.md`, `frontend/README_SETUP.md`
- 运行验证脚本检查环境
- 检查日志文件排查问题

---

🎉 **环境设置完成，开始开发吧！**