cloud-reporter

AWS Resource Scanner

一个全栈Web应用，用于扫描AWS账号中的资源信息，并按照Word模板生成专业的项目报告文档。系统支持多账号、多区域并行扫描，具有完整的用户权限管理、任务调度和报告管理功能。

✨ 功能特性

🔐 用户认证与权限管理

• JWT令牌认证 - 安全的用户会话管理
• 三级权限控制 - Admin、Power User、User角色
• 细粒度访问控制 - 基于角色的资源访问限制
• 用户管理 - 完整的用户生命周期管理

🔑 AWS凭证管理

• 多种认证方式 - 支持IAM Role和Access Key
• 智能Account ID检测 - Access Key类型自动获取账号ID
• Assume Role支持 - 跨账号安全访问
• 凭证加密存储 - 敏感信息安全保护
• 凭证分配管理 - 灵活的用户-凭证关联

🚀 资源扫描引擎

• 多账号并行扫描 - 同时扫描多个AWS账号
• 多区域支持 - 自定义区域选择，自动包含全局资源
• 全面资源覆盖 - 支持30+AWS服务类型
• 异步任务处理 - Celery驱动的后台任务队列

📊 智能报告生成

• Word模板引擎 - 基于专业模板自动生成报告
• 动态内容填充 - 自动替换模板占位符
• 资源分类展示 - 按服务类型组织资源信息
• 项目元数据集成 - 包含完整的项目信息

🎨 现代化Web界面

• 响应式设计 - 适配各种设备屏幕
• 实时状态更新 - 任务进度实时显示
• 直观操作界面 - 基于Ant Design的现代UI
• 数据可视化 - 清晰的数据展示和管理
• Worker监控 - 实时查看Celery Worker状态和任务队列

🏗️ 技术架构

前端技术栈

• React 18.3 + TypeScript 5.6 - 现代化前端框架
• Ant Design 5.21 - 企业级UI组件库
• Vite 5.4 - 快速构建工具
• React Router 6.28 - 单页应用路由
• Axios 1.7 - HTTP客户端

后端技术栈

• Python 3.8+ + Flask 3.0 - 轻量级Web框架
• SQLAlchemy 2.0 - ORM数据库操作
• Celery 5.3 + Redis - 异步任务队列
• boto3 - AWS SDK
• python-docx - Word文档处理
• PyJWT - JWT令牌认证

数据存储

• PostgreSQL (生产环境) - 关系型数据库
• SQLite3 (开发/测试) - 轻量级数据库
• Redis - 缓存和消息队列

🚀 快速开始

环境要求

• Python 3.8+
• Node.js 18+
• Redis (必需，用于Celery任务队列)

1. 克隆项目并准备模板

git clone https://git.iaun.cn/iaun/cloud-reporter.git
cd cloud-reporter

mkdir sample-reports

# 复制报告模板到 sample-reports 文件夹
copy "[Client Name]-[Project Name]-Project-Report-v1.0.docx" sample-reports/
# Unix/Linux/macOS:
# cp "[Client Name]-[Project Name]-Project-Report-v1.0.docx" sample-reports/

2. 后端设置

# 进入后端目录
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

# 启动后端服务
python run.py

3. 启动Celery Worker

# 新开终端，进入后端目录并激活虚拟环境
cd backend
activate_venv.bat  # Windows
# 或 source activate_venv.sh  # Unix/Linux

# 启动Celery Worker
celery -A celery_worker.celery_app worker --loglevel=info --pool=solo

4. 前端设置

# 新开终端，进入前端目录
cd frontend

# Windows用户
setup.bat

# Unix/Linux/macOS用户
chmod +x setup.sh && ./setup.sh

# 启动前端服务
yarn dev

5. 访问应用

• 前端界面: http://localhost:3000
• 后端API: http://localhost:5000
• 默认管理员: admin / admin123

📁 项目结构

cloud-reporter/
├── backend/                    # Python Flask后端
│   ├── app/                   # 应用核心代码
│   │   ├── api/              # REST API路由
│   │   ├── models/           # 数据模型
│   │   ├── services/         # 业务逻辑服务
│   │   ├── scanners/         # AWS扫描器模块
│   │   │   ├── services/    # 各服务扫描器实现
│   │   │   └── DEVELOPMENT_GUIDE.md  # 扫描器开发指南
│   │   ├── tasks/            # Celery异步任务
│   │   └── utils/            # 工具函数
│   ├── config/               # 配置文件
│   ├── migrations/           # 数据库迁移
│   ├── tests/                # 测试文件
│   ├── instance/             # 实例数据(数据库等)
│   ├── uploads/              # 上传文件存储
│   ├── reports/              # 生成的报告文件
│   └── requirements.txt      # Python依赖
├── frontend/                  # React前端
│   ├── src/                  # 源代码
│   │   ├── components/       # React组件
│   │   ├── pages/           # 页面组件
│   │   ├── services/        # API服务
│   │   ├── contexts/        # React Context
│   │   └── utils/           # 工具函数
│   ├── public/              # 静态资源
│   └── package.json         # 项目配置
├── sample-reports/           # 示例报告模板
├── .gitignore               # Git忽略文件
└── README.md                # 项目说明

🔧 配置说明

后端环境变量 (.env)

# Flask配置
FLASK_ENV=development
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here

# 数据库配置
DATABASE_URL=sqlite:///dev.db
# 生产环境使用PostgreSQL:
# DATABASE_URL=postgresql://user:password@localhost/dbname

# Celery配置
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1

# 加密密钥
ENCRYPTION_KEY=your-encryption-key-here

# 文件存储
UPLOAD_FOLDER=uploads
REPORTS_FOLDER=reports

前端环境变量 (.env.local)

# API配置
VITE_API_BASE_URL=http://localhost:5000

# 应用配置
VITE_APP_TITLE=AWS Resource Scanner
VITE_DEBUG=true

📋 支持的AWS服务

网络服务

• VPC: VPCs, Subnets, Route Tables, Internet Gateways, NAT Gateways
• 安全: Security Groups, VPC Endpoints, VPC Peering Connections
• VPN: Customer Gateways, Virtual Private Gateways, VPN Connections

计算服务

• EC2: Instances (含EBS卷、AMI信息), Elastic IPs
• Auto Scaling: Auto Scaling Groups (含Launch Templates)
• EKS: Kubernetes集群

负载均衡

• ELB: Application/Network/Classic Load Balancers, Target Groups

数据库服务

• RDS: 数据库实例
• ElastiCache: 缓存集群

存储服务

• S3: 存储桶, S3事件通知

无服务器

• Lambda: 函数

全局服务

• CloudFront: 分发 (全局)
• Route 53: 托管区域 (全局)
• ACM: SSL证书 (全局，当未选择us-east-1时自动在us-east-1扫描)
• WAF: Web应用防火墙 (全局)

监控和日志

• CloudWatch: 日志组
• EventBridge: 事件规则
• CloudTrail: 审计跟踪
• Config: 配置记录器

消息服务

• SNS: 主题和订阅

🔐 权限模型

角色定义

角色	权限范围
Admin	系统全部权限：用户管理、凭证管理、所有报告、Worker管理
Power User	使用所有凭证、查看所有报告、创建扫描任务
User	仅使用分配的凭证、查看自己的报告、创建扫描任务

访问控制

• 用户认证: JWT令牌机制，支持令牌刷新
• 权限验证: 基于角色的访问控制(RBAC)
• 数据隔离: 用户只能访问授权的资源
• API保护: 所有API端点都有权限验证

🛠️ 开发指南

扫描器开发

添加新的AWS服务扫描器时，请参考 扫描器开发指南，其中包含：

• 架构概述和目录结构
• 添加新服务扫描器的完整步骤
• 代码规范和命名约定
• 错误处理和重试机制
• 测试要求和检查清单

后端开发

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  # 创建示例数据

# 启动Celery Worker (必需，用于任务处理)
celery -A celery_worker.celery_app worker --loglevel=info --pool=solo

前端开发

cd frontend

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build

# 运行测试
yarn test

# 代码检查
yarn lint

# 类型检查
npx tsc --noEmit

API文档

认证接口

• POST /api/auth/login - 用户登录
• POST /api/auth/refresh - 刷新令牌
• POST /api/auth/logout - 用户登出
• GET /api/auth/me - 获取当前用户信息

用户管理 (Admin)

• GET /api/users - 获取用户列表
• POST /api/users/create - 创建用户
• POST /api/users/update - 更新用户
• POST /api/users/delete - 删除用户

凭证管理

• GET /api/credentials - 获取凭证列表
• POST /api/credentials/create - 创建凭证
• POST /api/credentials/update - 更新凭证
• POST /api/credentials/delete - 删除凭证

任务管理

• GET /api/tasks - 获取任务列表
• POST /api/tasks/create - 创建扫描任务
• GET /api/tasks/detail - 获取任务详情
• POST /api/tasks/delete - 删除任务

报告管理

• GET /api/reports - 获取报告列表
• GET /api/reports/download - 下载报告
• POST /api/reports/delete - 删除报告

Worker管理 (Admin)

• GET /api/workers - 获取Worker列表和状态
• GET /api/workers/stats - 获取Worker统计信息
• POST /api/workers/purge - 清空任务队列
• POST /api/workers/revoke - 取消指定任务

🧪 测试

运行测试

# 后端测试
cd backend
pytest

# 前端测试
cd frontend
yarn test

# 覆盖率测试
pytest --cov=app
yarn test --coverage

测试类型

• 单元测试: 组件功能测试
• 集成测试: API端点测试
• 属性测试: 基于Hypothesis的属性验证
• 端到端测试: 完整流程测试

📦 部署

生产环境部署

后端部署

1. 环境准备

   # 安装PostgreSQL和Redis
   sudo apt-get install postgresql redis-server
   
   # 创建数据库
   sudo -u postgres createdb aws_scanner
   

2. 应用部署

   # 设置生产环境变量
   export FLASK_ENV=production
   export DATABASE_URL=postgresql://user:pass@localhost/aws_scanner
   
   # 安装依赖
   pip install -r requirements.txt
   
   # 数据库迁移
   flask db upgrade
   
   # 使用Gunicorn启动
   gunicorn -w 4 -b 0.0.0.0:5000 run:app
   

3. Celery Worker

   # 启动Celery Worker
   celery -A celery_worker worker --loglevel=info --concurrency=4
   

前端部署

# 构建生产版本
yarn build

# 部署到Nginx
sudo cp -r dist/* /var/www/html/

Docker部署

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

🔍 故障排除

CloudShell Scanner (独立扫描工具)

除了完整的Web应用外，项目还提供了一个独立的CloudShell扫描脚本 cloudshell_scanner.py，可以直接在AWS CloudShell环境中运行，无需配置Access Key。

功能特点

• 单文件脚本 - 仅依赖boto3和Python标准库
• 自动使用CloudShell IAM凭证 - 无需配置Access Key
• 多区域扫描 - 支持指定区域或扫描所有可用区域
• 进度显示 - 实时显示扫描进度
• 错误处理 - 自动重试和错误记录

使用方法

# 在AWS CloudShell中运行

# 扫描所有区域
python cloudshell_scanner.py

# 扫描指定区域
python cloudshell_scanner.py --regions us-east-1,ap-northeast-1

# 指定输出文件
python cloudshell_scanner.py --output my_scan.json

# 扫描指定服务
python cloudshell_scanner.py --services ec2,vpc,rds

支持的服务

与Web应用支持相同的30+AWS服务类型，包括VPC、EC2、RDS、S3、Lambda、EKS等。

输出格式

扫描结果以JSON格式输出，可直接上传到Web应用生成报告。

常见问题

后端问题

1. 虚拟环境问题

   # 重新创建虚拟环境
   python setup_venv.py --clean
   

2. 数据库连接失败

   # 检查数据库配置
   python verify_setup.py
   

3. Celery Worker无法启动

   # 检查Redis连接
   redis-cli ping
   
   # 确保使用正确的启动命令
   celery -A celery_worker.celery_app worker --loglevel=info --pool=solo
   

前端问题

1. 依赖安装失败

   # 清理并重新安装
   yarn cache clean
   rm -rf node_modules yarn.lock
   yarn install
   

2. 构建失败

   # 检查TypeScript错误
   npx tsc --noEmit
   

日志查看

# 后端日志
tail -f backend/logs/app.log

# Celery日志
tail -f backend/logs/celery.log

# 前端开发日志
# 在浏览器开发者工具中查看

🤝 贡献指南

1. Fork项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建Pull Request

代码规范

• Python: 遵循PEP 8规范
• TypeScript: 使用ESLint和Prettier
• 提交信息: 使用约定式提交格式

📄 许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Flask - Web框架
• React - 前端框架
• Ant Design - UI组件库
• boto3 - AWS SDK
• Celery - 分布式任务队列

📞 支持

如果您遇到问题或有疑问，请：

查看故障排除部分

---

AWS Resource Scanner - 让AWS资源管理变得简单高效 🚀