# pg_flight_simulator

**Repository Path**: social-net/pg_flight_simulator

## Basic Information

- **Project Name**: pg_flight_simulator
- **Description**: postgresql flight simulator
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-12-20
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PostgreSQL 飞行模拟器

## 项目概述

PostgreSQL 飞行模拟器是一个基于 Flask 的交互式 Web 应用程序，旨在帮助用户通过模拟真实的 PostgreSQL 数据库环境，学习和实践数据库故障诊断、性能优化和日常运维技能。该模拟器提供了多种预定义场景，模拟数据库常见问题（如配置不匹配、连接限制、缺少索引、表膨胀等），用户可以在安全的环境中练习故障排查和解决方法。


![演示图1](pictures/case1-1.png)
![演示图2](pictures/case1-2.png)
![演示图3](pictures/case1-3.png)
![演示图4](pictures/case1-4.png)

## 核心功能

### 1. 交互式终端模拟
- 提供逼真的 PostgreSQL 命令行界面
- 支持常用的 psql 命令（如 SELECT、EXPLAIN、VACUUM 等）
- 模拟数据库响应和错误信息

### 2. 多场景支持
- 预定义多种数据库故障和性能问题场景
- 支持动态切换和重置场景
- 可扩展的场景配置系统

### 3. 智能评估系统
- 对用户的操作和解决方案进行实时评估
- 提供详细的评分和反馈
- 支持获取提示和建议

### 4. 监控指标追踪
- 实时监控用户操作历史和命令执行情况
- 提供演练过程的统计数据
- 支持查看详细的执行日志

### 5. 灵活的配置选项
- 支持自定义大模型 API 配置
- 可调整终端和上下文参数
- 支持多种大模型提供商

## 环境要求

- Python 3.7 及以上版本
- pip 包管理器
- 网络连接（用于访问大模型 API）

## 安装步骤

### 1. 克隆项目

```bash
git clone <项目仓库地址>
cd pg_flight_simulator2
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动应用

```bash
python app.py
```

应用将在 `http://localhost:5000` 上启动。

## 详细使用指南

### 1. 访问应用

在浏览器中打开 `http://localhost:5000`，您将看到应用的主界面。

### 2. 选择场景

1. 配置大模型API参数
2. 在界面左侧的场景列表中选择一个场景
3. 点击"开始演练"按钮

### 3. 执行命令

在终端模拟器中输入PostgreSQL命令，例如：

```sql
SELECT * FROM employees WHERE department_id = 10;
EXPLAIN ANALYZE SELECT * FROM orders WHERE order_date > '2023-01-01';
VACUUM ANALYZE customers;
```

### 4. 获取提示

如果您遇到困难，可以点击"获取提示"按钮，系统会提供相关的解决建议。

### 5. 评估演练

完成故障排查后，点击"评估演练"按钮，系统会对您的表现进行评分并提供详细反馈。

### 6. 重置场景

点击"重置场景"按钮可以重新开始当前场景或切换到其他场景。

## 配置说明

### 1. 主要配置文件

项目的主要配置文件是 `config.py`，包含以下配置项：

```python
# SiliconFlow大模型API配置
OPENAI_API_KEY = "your-siliconflow-api-key-here"  # 大模型API密钥
OPENAI_BASE_URL = "https://api.siliconflow.cn/v1"  # 大模型API基础URL

# 终端模拟器配置
TERMINAL_PROMPT = "$ "  # 终端提示符
DEFAULT_CONTEXT_SIZE = 100  # 默认上下文保留的命令数

# 项目配置
DEBUG = True  # 调试模式
PORT = 5000  # 服务端口
```

### 2. 场景配置

场景文件位于 `scenarios/` 目录下，每个场景是一个 Markdown 文件。

### 3. 自定义场景

您可以通过创建新的 Markdown 文件来自定义场景：

1. 在 `scenarios/` 目录下创建新的 `.md` 文件
2. 模仿missing_index.md的内容编写场景内容
3. 重启应用后，新场景将自动加载到场景列表中

您也可以使用大模型+提示词来定义新场景，可以参考如下提示词：

1. 以missing_index.md作为标准模板进行创建，确保格式和所要包含的内容结构保持一致
2. 故障场景难度设定为简单级别，定位步骤控制在3步以内，恢复步骤控制在2步以内，故障原理需简洁易懂，可通过基础数据库知识解释
3. 每个故障场景必须能够通过已支持的16个监控指标清晰反映出故障定位前后的变化，需明确指出关键指标及其变化趋势
4. 所有场景仅包含数据库侧的定位方法和恢复措施，不得涉及任何业务侧的调整或恢复操作，符合纯数据库演练的性质
5. 确保场景具备可重复性和可操作性，能够在标准测试环境中稳定复现

## 核心模块说明

### 1. app.py
主应用程序入口，负责处理 HTTP 请求和路由管理。

### 2. scenario_manager.py
场景管理器，负责加载、解析和管理所有预定义场景。

### 3. context_manager.py
上下文管理器，维护用户会话状态和命令执行上下文。

### 4. monitoring_manager.py
监控管理器，记录和分析用户操作历史和演练数据。

### 5. terminal_simulator.py
终端模拟器，模拟 PostgreSQL 命令行环境和响应。


## 预定义场景

项目提供了以下预定义场景：

### 1. 配置不匹配 (configuration_mismatch)
模拟数据库配置参数不匹配导致的性能问题。

### 2. 连接限制 (connection_limit)
模拟数据库连接数达到上限导致的连接失败问题。

### 3. 缺少索引 (missing_index)
模拟因缺少适当索引导致的查询性能低下问题。

### 4. 表膨胀 (table_bloat)
模拟表和索引膨胀导致的存储空间浪费和性能下降问题。


## 常见问题解答 (FAQ)

### 1. 应用启动失败，提示缺少模块

**问题：** 启动应用时出现 `ModuleNotFoundError: No module named 'flask'` 或类似错误。

**解决方法：** 确保已正确安装所有依赖：

```bash
pip install -r requirements.txt
```

### 2. 执行命令无响应

**问题：** 在终端输入命令后没有响应。

**解决方法：**
- 检查大模型 API 密钥是否正确配置
- 确保网络连接正常
- 检查浏览器控制台是否有错误信息

### 4. 如何添加自定义场景？

**解决方法：**
- 在 `scenarios/` 目录下创建新的 Markdown 文件
- 按照预定义场景的格式编写内容
- 重启应用后，新场景将自动加载

### 5. 支持哪些大模型提供商？

**答案：** 理论上支持所有兼容 OpenAI API 格式的大模型提供商，包括但不限于：
- SiliconFlow
- OpenAI

## 开发说明

### 代码结构

```
pg_flight_simulator2/
├── scenarios/           # 场景配置文件目录
├── static/              # 静态资源文件
├── templates/           # HTML 模板文件
├── app.py              # 主应用程序
├── config.py           # 配置文件
├── context_manager.py  # 上下文管理
├── monitoring_manager.py # 监控管理
├── scenario_manager.py # 场景管理
├── terminal_simulator.py # 终端模拟
├── requirements.txt    # 依赖列表
└── README.md           # 项目文档
```


## 贡献指南

我们欢迎社区贡献，包括但不限于：

1. 修复 bug 和优化性能
2. 添加新的场景和功能
3. 改进文档和用户界面
4. 提供使用案例和教程

### 贡献步骤

1. Fork 项目仓库
2. 创建新的特性分支
3. 提交代码变更
4. 运行测试确保没有问题
5. 创建 Pull Request



---

感谢您使用 PostgreSQL 飞行模拟器！通过不断练习，您将成为一名更出色的 PostgreSQL 数据库管理员。