# pg_flight_simulator

**Repository Path**: shenyuflying/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**: 3
- **Forks**: 5
- **Created**: 2025-12-19
- **Last Updated**: 2026-01-26

## 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. 监控指标追踪
- 实时监控用户操作历史和命令执行情况
- 提供16个核心监控指标（CPU使用率、内存使用率、磁盘空间、网络流量、TPS、QPS、平均响应时间、活动会话数、当前连接数、空闲事务数、慢查询数、锁等待数、长事务数、WAL速率、复制延迟、缓存命中率）
- 支持查看详细的执行日志

### 5. Token使用统计
- 实时统计大模型API交互的token使用情况
- 记录prompt_tokens、completion_tokens、total_tokens等指标
- 支持查看详细的文本内容和请求次数
- 提供重置统计数据功能

### 6. 活跃会话监控
- 模拟PostgreSQL的pg_stat_activity视图
- 展示数据库活跃会话的详细信息（PID、用户名、状态、查询等）
- 支持会话数据的刷新和过滤
- 提供会话历史记录功能

### 7. 灵活的配置选项
- 支持自定义大模型 API 配置
- 可调整终端和上下文参数
- 支持多种大模型提供商
- 支持在Web界面动态配置模型名称

## 环境要求

- 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  # 服务端口
```

**注意：** 模型名称（MODEL_NAME）不再在配置文件中设置，而是通过Web界面动态输入，以支持灵活切换不同的大模型。

### 2. Web界面配置

应用启动后，用户可以在Web界面中配置以下参数：

- **API密钥：** 大模型服务的API密钥
- **API基础URL：** 大模型服务的API地址
- **模型名称：** 要使用的大模型名称（如 gpt-3.5-turbo、gpt-4 等）

这些配置会覆盖config.py中的默认值，并在会话中生效。

### 3. 场景配置

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

### 4. 自定义场景

您可以通过创建新的 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
监控管理器，记录和分析用户操作历史和演练数据，提供16个核心监控指标。

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

### 6. token_counter.py
Token计数器，用于统计大模型API交互过程中的token使用情况，包括prompt_tokens、completion_tokens、total_tokens等。

### 7. token_stats_api.py
Token统计API模块，提供RESTful API接口用于获取和重置token统计数据。

### 8. pg_stat_activity.py
PostgreSQL活跃会话管理模块，模拟pg_stat_activity视图功能，生成和管理数据库活跃会话数据。

### 9. blueprints/token_stats.py
Flask蓝图，用于注册token统计相关的API路由。

## 数据结构架构图

### 1. 整体数据流架构

```mermaid
graph TB
    subgraph "前端界面"
        A[用户界面]
    end
    
    subgraph "Flask应用层"
        B[app.py<br/>路由处理]
        C[token_stats_api.py<br/>Token统计API]
    end
    
    subgraph "业务逻辑层"
        D[ContextManager<br/>上下文管理]
        E[ScenarioManager<br/>场景管理]
        F[MonitoringManager<br/>监控管理]
        G[TerminalSimulator<br/>终端模拟]
    end
    
    subgraph "数据统计层"
        H[TokenCounter<br/>Token计数]
        I[PGStatActivity<br/>活跃会话]
    end
    
    subgraph "外部服务"
        J[大模型API]
    end
    
    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    
    D --> G
    D --> F
    E --> D
    F --> J
    G --> J
    G --> H
    F --> H
    C --> H
    
    I --> F
```

### 2. ContextManager数据结构

```mermaid
classDiagram
    class ContextManager {
        - dict user_contexts
        + get_user_context(user_id)
        + set_scenario(user_id, scenario_id, prompt, api_config)
        + set_scenarios(user_id, scenario_ids, prompts, api_config)
        + execute_command(user_id, command)
        + reset_context(user_id, api_config)
        + evaluate_drill(user_id)
        + get_hint(user_id)
    }
    
    class UserContext {
        + str scenario_id
        + str scenario_prompt
        + TerminalSimulator terminal
        + dict api_config
    }
    
    class TerminalSimulator {
        - OpenAI client
        - list context_history
        - str scenario_context
        - str model_name
        - bool api_config_valid
        + execute_command(command)
        + _build_context(command)
        + _update_context(command, output)
    }
    
    ContextManager "1" --> "*" UserContext : manages
    UserContext "1" --> "1" TerminalSimulator : contains
```

### 3. MonitoringManager数据结构

```mermaid
classDiagram
    class MonitoringManager {
        - str api_key
        - str base_url
        - str model_name
        - OpenAI client
        - dict user_contexts
        - dict current_metrics
        + set_model_api_config(api_key, base_url, model_name)
        + set_scenario_context(user_id, scenario_info)
        + add_command_history(user_id, command, response)
        + get_monitoring_metrics(user_id)
        + _fetch_metrics_from_model(scenario_info, command_history)
    }
    
    class UserContext {
        - dict scenario_info
        - list command_history
        - float last_updated
    }
    
    class CommandHistory {
        - str command
        - str response
        - float timestamp
    }
    
    class Metrics {
        - float cpuUsage
        - float memoryUsage
        - float diskSpace
        - float networkTraffic
        - float tps
        - float qps
        - float avgResponseTime
        - int activeSessions
        - int currentConnections
        - int idleTransactions
        - int slowQueries
        - int lockWaits
        - int longTransactions
        - float walRate
        - float replicationDelay
        - float cacheHitRatio
    }
    
    MonitoringManager "1" --> "*" UserContext : manages
    UserContext "1" --> "*" CommandHistory : contains
    MonitoringManager "1" --> "1" Metrics : tracks
```

### 4. TokenCounter数据结构

```mermaid
classDiagram
    class TokenCounter {
        - int prompt_tokens
        - int completion_tokens
        - int total_tokens
        - int request_count
        - list prompt_texts
        - list completion_texts
        - list total_texts
        + reset_counts()
        + update_counts(response, prompt_text, completion_text)
        + get_stats()
        + get_summary()
        + get_texts(type)
    }
    
    class TextPair {
        - str prompt
        - str completion
    }
    
    class TokenStats {
        - int prompt_tokens
        - int completion_tokens
        - int total_tokens
        - int request_count
    }
    
    TokenCounter "1" --> "*" TextPair : stores
    TokenCounter "1" --> "1" TokenStats : provides
```

### 5. PGStatActivity数据结构

```mermaid
classDiagram
    class PGStatActivity {
        - list sessions
        - list session_history
        + generate_random_session(session_id)
        + generate_sample_sessions(count)
        + get_sessions(filter_by)
        + refresh_sessions()
        + to_json(sessions)
    }
    
    class Session {
        - int pid
        - str usename
        - str application_name
        - str client_addr
        - str xact_start
        - str query_start
        - float elapsed
        - str wait_event_type
        - str wait_event
        - str state
        - str query
        - str backend_type
    }
    
    PGStatActivity "1" --> "*" Session : manages
```

### 6. ScenarioManager数据结构

```mermaid
classDiagram
    class ScenarioManager {
        - str scenarios_dir
        - list scenarios
        + _load_scenarios()
        + _parse_scenario_file(file_path)
        + get_all_scenarios()
        + get_scenario_by_id(scenario_id)
        + reload_scenarios()
    }
    
    class Scenario {
        - str id
        - str name
        - str description
        - str prompt_template
        - str file_path
    }
    
    ScenarioManager "1" --> "*" Scenario : manages
```

### 7. 模块间交互关系

```mermaid
graph LR
    subgraph "用户请求"
        A[HTTP请求]
    end
    
    subgraph "路由层"
        B[app.py]
    end
    
    subgraph "业务层"
        C[ContextManager]
        D[MonitoringManager]
        E[ScenarioManager]
    end
    
    subgraph "工具层"
        F[TerminalSimulator]
        G[TokenCounter]
        H[PGStatActivity]
    end
    
    subgraph "外部API"
        I[大模型API]
    end
    
    A --> B
    B --> C
    B --> D
    B --> E
    
    C --> E
    C --> F
    D --> G
    D --> H
    
    F --> I
    D --> I
    
    F -.-> G
    D -.-> G
```

## 预定义场景

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

### 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/
├── blueprints/          # Flask蓝图目录
│   └── token_stats.py  # Token统计API蓝图
├── scenarios/          # 场景配置文件目录
│   ├── configuration_mismatch.md
│   ├── connection_limit.md
│   ├── missing_index.md
│   └── table_bloat.md
├── static/             # 静态资源文件
│   ├── css/            # CSS样式文件
│   │   ├── base.css
│   │   ├── buttons.css
│   │   ├── forms.css
│   │   ├── header.css
│   │   ├── layout.css
│   │   ├── monitoring.css
│   │   ├── panel.css
│   │   ├── responsive.css
│   │   ├── scenarios.css
│   │   ├── sessions.css
│   │   ├── terminal.css
│   │   └── variables.css
│   └── js/             # JavaScript文件
│       ├── apiConfig.js
│       ├── buttons.js
│       ├── command.js
│       ├── config.js
│       ├── drill.js
│       ├── monitoring.js
│       ├── pg_stat_activity.js
│       ├── scenarios.js
│       ├── test_api_connection.js
│       ├── tokenStats.js
│       └── utils.js
├── templates/          # HTML模板文件
│   └── index.html
├── app.py              # 主应用程序
├── config.py           # 配置文件
├── context_manager.py  # 上下文管理
├── monitoring_manager.py # 监控管理
├── scenario_manager.py # 场景管理
├── terminal_simulator.py # 终端模拟
├── token_counter.py    # Token计数器
├── token_stats_api.py  # Token统计API
├── pg_stat_activity.py # 活跃会话管理
├── requirements.txt    # 依赖列表
├── README.md           # 项目文档
└── TODO.md             # 待办事项
```


## 贡献指南

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

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

### 贡献步骤

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



---

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