# FOAMFlask-Native

**Repository Path**: qj9901/FOAMFlask-Native

## Basic Information

- **Project Name**: FOAMFlask-Native
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FOAMFlask 中文文档

**FOAMFlask** 是一个轻量级 Web 界面，用于管理、运行和可视化 **OpenFOAM** 仿真案例。无需编写命令行，用户直接在浏览器中完成从案例选择、网格生成、求解运行到后处理的全流程。

---

## 📋 当前状态

本项目经过多轮调试修错，**核心功能现已可用**：

| 功能 | 状态 | 说明 |
|------|------|------|
| 教程加载（Load Tutorial） | ✅ 可用 | 从 `$FOAM_TUTORIALS` 复制案例 |
| 网格生成（blockMesh 等） | ✅ 可用 | 支持 Docker / WSL / Native 三种后端 |
| 仿真运行（simpleFoam 等） | ✅ 可用 | 实时日志流输出到前端 |
| 实时绘图（Realtime Plots） | ✅ 可用 | 残差、速度剖面、压力系数等 |
| 3D 等值面可视化（Isosurface） | ✅ 可用 | Trame + PyVista 交互视图 |
| 静态等值面导出 | ✅ 可用 | subprocess 生成 HTML |
| 网格质量检查 | ✅ 可用 | checkMesh 分析结果展示 |

> **已知限制**：
> - 目前仅支持加载和运行 OpenFOAM 官方教程目录（`$FOAM_TUTORIALS`）中的案例
> - 自定义案例创建功能尚未实现

---

## 🐍 Python 环境配置

### 版本要求

**Python 3.11+**（推荐 3.11 / 3.12）

> ⚠️ Python 3.8/3.9/3.10 虽然可能运行，但部分依赖（如 `trame`）的较新版本需要 3.11+。建议优先使用 Python 3.11 或更高版本以获得最佳兼容性。

### 方式一：使用项目自带的 venv（推荐，已有全部依赖）

```bash
# 如果已有 venv，直接使用
/home/flash/OpenFOAM/flash-v2312/run/.venv/bin/python -m app

# 或激活后运行
source /home/flash/OpenFOAM/flash-v2312/run/.venv/bin/activate
python -m app
```

### 方式二：新建 venv（推荐）

```bash
cd /home/flash/OpenFOAM/flash-v2312/run/FOAMFlask

# 创建 venv（Python 3.11+）
python3.11 -m venv .venv

# 激活
source .venv/bin/activate

# 安装依赖
pip install -e .
```

### 方式三：使用 uv（推荐用于开发）

```bash
cd /home/flash/OpenFOAM/flash-v2312/run/FOAMFlask

# 安装 uv（如果没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并同步依赖
uv sync

# 运行
uv run python -m app
```

### 验证 Python 版本和依赖

```bash
python --version        # 应显示 3.11 或更高
python -c "import trame; import pyvista; print('OK')"   # 应输出 OK
```

---

## ⚙️ 后端模式配置

FOAMFlask 支持三种 OpenFOAM 运行后端，配置统一写在项目根目录的 `config/foamflask.yaml` 中。

### 配置文件路径

- **Windows 开发端**: `D:\Code\OpenFoam\FOAMFlask\config\foamflask.yaml`
- **WSL 服务器端**: `/home/flash/OpenFOAM/flash-v2312/run/FOAMFlask/config/foamflask.yaml`

### 配置结构说明

```yaml
# 选择后端模式：docker / wsl / native
backend:
  mode: wsl          # ← 改这里切换模式

  # Docker 模式配置
  docker:
    image: openfoam/openfoam-v2312   # OpenFOAM Docker 镜像
    user: ''                         # 运行用户（空=自动检测）

  # Native Linux 模式配置
  native:
    bashrc: /opt/openfoam/etc/bashrc           # OpenFOAM bashrc 路径
    openfoam_script: /opt/openfoam/etc/openfoam # openfoam 脚本路径
    tutorials_dir: /opt/openfoam/tutorials      # tutorials 目录

  # WSL 模式配置
  wsl:
    distro: FOAM              # WSL 发行版名称（wsl -d <name>）
    bashrc: /home/flash/OpenFOAM/flash-v2312/etc/bashrc  # OpenFOAM bashrc
    openfoam_script: /home/flash/OpenFOAM/flash-v2312/etc/openfoam
    tutorials_dir: /home/flash/OpenFOAM/flash-v2312/tutorials

# 案例根目录（启动时自动读取上次路径）
cases:
  root: ''

# 日志级别
logging:
  level: INFO    # DEBUG / INFO / WARNING
```

### 如何切换后端模式

只需修改 `backend.mode` 字段，保存后重启服务器即可生效：

| 模式 | `backend.mode` 值 | 适用场景 |
|------|-------------------|----------|
| Docker | `docker` | Windows / 需要隔离的环境 |
| WSL | `wsl` | WSL2 已安装 OpenFOAM（**推荐**） |
| Native | `native` | 直接在 Linux 原生环境运行 |

### 自动检测逻辑

服务器启动时按以下顺序自动检测可用后端：
1. 若 `config/foamflask.yaml` 中 `backend.mode` 已设置，优先使用该模式
2. 否则依次尝试 Docker → WSL → Native，找到第一个可用的

### 确认当前模式

服务器启动后，日志会显示：

```
FOAMFlask backend: wsl
```

前端页面底部状态栏也会显示当前后端模式。

---

## 🚀 启动服务

### 基本启动

```bash
cd /home/flash/OpenFOAM/flash-v2312/run/FOAMFlask
python -m app
```

服务启动后访问：**http://localhost:5000**

### 后台运行

```bash
# 停止旧进程
pkill -f "python.*app" || true

# 后台启动
cd /home/flash/OpenFOAM/flash-v2312/run/FOAMFlask
nohup python -m app > app.log 2>&1 &

# 查看日志
tail -f app.log
```

### 调试模式（代码修改后热重载）

```bash
FLASK_DEBUG=1 python -m app
```

---

## 🖥️ 三种后端模式详解

### 模式 1：Docker

- **原理**：通过 Docker SDK 启动 OpenFOAM 容器执行命令
- **优点**：环境隔离，跨平台一致
- **缺点**：需要 Docker，文件 I/O 有额外开销
- **依赖**：Docker Desktop (Windows) / Docker Engine (Linux)

### 模式 2：WSL（推荐）

- **原理**：通过 `wsl -d <distro>` 调用 WSL 子系统内部的 OpenFOAM 命令
- **优点**：无需 Docker，性能好，适合 Windows + WSL2 用户
- **缺点**：依赖 WSL2 + OpenFOAM 已安装在 WSL 中
- **依赖**：WSL2 + WSL 内已安装 OpenFOAM（如 `flash-v2312`）

### 模式 3：Native

- **原理**：直接在当前 Linux 系统上执行 OpenFOAM 命令
- **优点**：零开销，最高效率，适合服务器环境
- **缺点**：需要本地安装 OpenFOAM
- **依赖**：OpenFOAM 已全局安装并 source bashrc

---

## 🐛 已修复的历史 Bug（供参考）

以下问题在开发过程中已全部解决，了解问题根因有助于排查类似情况：

### 1. Docker import 崩溃（WSL/Native 模式）
- **问题**：WSL/Native 模式下没有安装 `docker` Python 包，但 `app.py` 在模块级别执行了 `import docker`，导致服务器启动时立即崩溃
- **修复**：改为 `try/except ImportError` 懒加载，`docker` 模块仅在 Docker 模式下使用

### 2. VTK 文件复制损坏（二进制模式）
- **问题**：VTK 文件（mesh 数据）通过 `'rb'/'wb'` 模式复制时，内容被截断（约 38MB 处）
- **影响**：等值面可视化时 `pyvista.read()` 失败，报 "no element found"
- **修复**：改为文本模式 `'r'/'w'` + `encoding='utf-8'`

### 3. 等值面为零值时崩溃
- **问题**：`mesh.contour()` 在等值面落在数据范围外时返回空 PolyData
- **修复**：增加 `isosurface.n_points == 0` 检查，使用数据范围中点作为 fallback

### 4. WSL/Native 的 `source bashrc` 被错误删除
- **问题**：`_fix_bashrc_path()` 函数本应替换 Docker bashrc 路径为实际路径，但逻辑错误导致整个 `source bashrc` 命令被删除
- **影响**：OpenFOAM 命令（`blockMesh` 等）找不到，报 `command not found`
- **修复**：改为精确替换 `/opt/openfoam*/etc/bashrc` 为实际路径，保留 `source` 命令

### 5. WSL 模式下 `$FOAM_TUTORIALS` 变量展开失效
- **问题**：Geometry Management 列表为空；`api_list_resource_geometry` 使用 Python 双引号字符串，导致 `$FOAM_TUTORIALS` 被 Python 解释为空字符串而非传给 bash
- **修复**：改用单引号 Python 字符串 + 位置参数传递 tutorials 目录路径

### 6. multiprocessing queue 收到类型对象而非字典
- **问题**：`_run_trame_process` 子进程崩溃时，multiprocessing 将异常 **类型**（class）而非实例序列化到 queue；父进程执行 `result["error"]` 时抛出 `'type' object is not subscriptable`
- **修复**：增加 `isinstance(result, dict)` 检查，区分正常 dict 和异常类型

---

## ❓ 常见问题

### Q: 启动后显示 "Docker Desktop is not running"，但我不想用 Docker？

将 `config/foamflask.yaml` 中的 `backend.mode` 改为 `wsl` 或 `native`，保存后重启服务器。

### Q: 显示 "command not found: blockMesh"？

检查 `config/foamflask.yaml` 中的 `backend.wsl.bashrc` 路径是否正确，确保 OpenFOAM bashrc 文件存在。

### Q: Isosurface 可视化报错 "'type' object is not subscriptable"？

确保服务器端的 `backend/post/isosurface.py` 是最新版本（包含 queue 类型检查修复）。如未更新，请从 Windows 端复制最新代码后重启服务器。

### Q: Geometry 列表为空？

在 WSL 终端手动测试：
```bash
source /path/to/your/bashrc && echo $FOAM_TUTORIALS
```
确保路径有效，并将 `tutorials_dir` 写入 `config/foamflask.yaml`。

### Q: Python 版本不对？

```bash
# 检查当前版本
python --version

# 如果低于 3.11，安装新版
# Ubuntu:
sudo apt update && sudo apt install python3.11
# 或使用 pyenv / conda 管理多版本
```

---

## 📁 项目结构

```
FOAMFlask/
├── app.py                      # 主应用入口
├── config/foamflask.yaml       # 后端模式配置文件（重要！）
├── backend/
│   ├── meshing/runner.py       # MeshingRunner（网格模式抽象）
│   ├── post/isosurface.py       # 等值面可视化（Trame + PyVista）
│   ├── geometry/                # Geometry 管理
│   └── plots/                   # 实时绘图
├── static/
│   ├── ts/                      # TypeScript 源码（前端）
│   └── html/                     # HTML 模板
├── instance/                    # SQLite 数据库（仿真记录）
└── tutorial_cases/              # 内置教程案例
```

---

## 🔒 安全说明

- 命令执行前经过严格的输入验证，防止注入攻击
- Docker 模式下的文件权限由 FOAMFlask 启动检查自动修复
- 服务默认绑定 `0.0.0.0`；生产环境建议设置 `FLASK_HOST=127.0.0.1`

---

## 📝 开发说明

### 修改前端

1. 编辑 `static/ts/foamflask_frontend.ts`
2. 编译：`pnpm run build`
3. 刷新浏览器

### 调试模式

```bash
FLASK_DEBUG=1 python -m app
```

### 运行测试

```bash
uv run pytest
```

---