insar-management-system-v2/README.md

# InSAR 管理系统 v2 - 技术文档

> 最后更新：2026-03-05

## 文档导航

### 📖 用户文档
- [部署指南](#部署指南) - 系统安装、配置、启动
- [配置说明](#配置说明) - `.env` 配置项详解
- [功能说明](#功能说明) - 各模块功能介绍

### 🔧 开发文档
- [架构设计](#架构设计) - 系统架构和技术栈
- [开发规范](#开发规范) - 代码规范和最佳实践
- [API 文档](#api-文档) - RESTful API 接口

### 🔒 安全文档
- [安全审计](#安全审计) - 安全问题和修复记录
- [部署安全](#部署安全) - 生产环境安全配置

---

## 部署指南

### 系统要求

**硬件要求**：
- CPU：4 核及以上
- 内存：16GB 及以上
- 硬盘：500GB 及以上（SSD 推荐）

**软件要求**：
- 操作系统：Windows 10/11 或 Windows Server 2019+
- Python：3.9+ (推荐使用 Conda 环境)
- PostgreSQL：14+ (含 PostGIS 扩展)
- Nginx：1.20+
- IDL/ENVI：8.8+ / 5.6+ (可选，用于 D-InSAR 处理)
- Ollama：最新版 (可选，用于 AI 诊断)

### 快速开始

#### 1. 环境准备

```bash
# 创建 Conda 环境
conda create -n InSAR python=3.9
conda activate InSAR

# 安装依赖
pip install -r requirements.txt
```

#### 2. 数据库配置

```bash
# 创建数据库
createdb -U postgres insar_management

# 启用 PostGIS 扩展（系统会自动执行）
```

#### 3. 配置文件

复制 `.env.example` 为 `.env`，修改以下配置：

```bash
# 数据库连接
DATABASE_URL=postgresql+asyncpg://postgres:your_password@localhost:5432/insar_management

# 数据目录（根据实际环境修改）
MONITOR_RADAR_DIRS=\\\\server\\share\\RadarData
MONITOR_ORBIT_DIR=\\\\server\\share\\Orbit
MONITOR_DINSAR_DIRS=\\\\server\\share\\DinsarResults

# IDL/ENVI 路径（如果使用 D-InSAR 功能）
IDL_EXECUTABLE=C:\\Program Files\\Harris\\ENVI56\\IDL88\\bin\\bin.x86_64\\idl.exe
IDL_DINSAR_DEM_BASE_FILE=D:\\SRTM30m\\SRTMDEM_RSP_SARscape

# 服务端口
PORT=8000
```

#### 4. 启动系统

**方式 1：使用启动脚本（推荐）**
```bash
# Windows
start_system.bat
```

**方式 2：手动启动**
```bash
# 启动后端
python run_backend.py

# 启动 Nginx（另一个终端）
nginx.exe

# 启动 Job Worker（另一个终端）
python -m backend.app.job_worker
```

#### 5. 访问系统

打开浏览器访问：`http://localhost`

默认管理员账号：
- 用户名：`admin`
- 密码：`.env` 中的 `INIT_ADMIN_PASSWORD`

---

## 配置说明

### 核心配置

#### 数据库配置

```bash
# PostgreSQL 连接字符串
DATABASE_URL=postgresql+asyncpg://用户名:密码@主机:端口/数据库名
```

#### 数据目录配置

```bash
# 雷达数据监控目录（支持 UNC 路径，多个路径用逗号分隔）
MONITOR_RADAR_DIRS=\\\\server1\\share\\data,\\\\server2\\share\\data

# 轨道数据目录
MONITOR_ORBIT_DIR=\\\\server\\share\\orbit

# D-InSAR 结果目录
MONITOR_DINSAR_DIRS=\\\\server\\share\\results

# 水体监测结果目录
WATER_RESULTS_DIR=\\\\server\\share\\water
```

#### 服务配置

```bash
# 后端服务端口
PORT=8000

# 后端绑定地址（127.0.0.1 仅本地，0.0.0.0 允许外部访问）
BACKEND_BIND_HOST=127.0.0.1

# Ollama 服务地址（用于 AI 诊断）
OLLAMA_BASE_URL=http://127.0.0.1:11434

# Nginx 健康检查地址
NGINX_HEALTH_URL=http://127.0.0.1/
```

#### PROJ 数据库配置

```bash
# PROJ 数据库路径（用于地理空间坐标转换）
# 留空则自动使用 pyproj 的 PROJ 数据库（推荐）
# PROJ_LIB=C:\\path\\to\\proj\\data
```

**重要提示**：
- PostgreSQL PostGIS 的 PROJ 数据库版本较旧（v2），可能导致坐标转换错误
- 推荐使用 pyproj 的 PROJ 数据库（v9.2+）
- 详见：[PROJ 配置指南](#proj-配置指南)

#### IDL/ENVI 配置

```bash
# IDL 可执行文件路径
IDL_EXECUTABLE=C:\\Program Files\\Harris\\ENVI56\\IDL88\\bin\\bin.x86_64\\idl.exe

# ENVI Workbench 路径
IDL_WORKBENCH_PATH=C:\\Program Files\\Harris\\ENVI56\\IDL88\\bin\\bin.x86_64\\idlde.exe

# DEM 文件路径（D-InSAR 处理必需）
IDL_DINSAR_DEM_BASE_FILE=D:\\SRTM30m\\SRTMDEM_RSP_SARscape

# 工作目录
IDL_WORKER_RUNTIME_DIR=Z:\\Code\\Insar_management_system_v2\\backend\\runtime\\idl_worker

# 超时配置
IDL_WORKER_DEFAULT_TIMEOUT_SECONDS=14400
IDL_WORKER_MAX_TIMEOUT_SECONDS=43200
```

#### 解包配置

```bash
# 压缩包源目录（支持 UNC 路径）
UNPACK_SOURCE_DIRS=\\\\server\\share\\archives

# 解包目标目录
INSAR_STORAGE_DIRS=\\\\server\\share\\storage

# 最小剩余空间（GB）
UNPACK_MIN_DISK_SPACE_GB=50

# 解包后是否删除压缩包
UNPACK_DELETE_ARCHIVE=true
```

### 部署场景配置

#### 场景 1：本地开发

```bash
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/insar_management
BACKEND_BIND_HOST=127.0.0.1
PORT=8000
```

#### 场景 2：Docker 容器

```bash
DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/insar_management
BACKEND_BIND_HOST=0.0.0.0
PORT=8000
```

#### 场景 3：远程 Ollama

```bash
OLLAMA_BASE_URL=http://192.168.1.100:11434
```

#### 场景 4：客户现场

```bash
# 根据客户环境修改所有路径和地址
DATABASE_URL=postgresql+asyncpg://user:pass@192.168.1.10:5432/insar
MONITOR_RADAR_DIRS=D:\\InSAR_Data\\Radar
MONITOR_ORBIT_DIR=D:\\InSAR_Data\\Orbit
MONITOR_DINSAR_DIRS=D:\\InSAR_Data\\Results
IDL_EXECUTABLE=C:\\Program Files\\Harris\\ENVI56\\IDL88\\bin\\bin.x86_64\\idl.exe
IDL_DINSAR_DEM_BASE_FILE=D:\\DEM\\SRTM30m\\SRTMDEM_RSP_SARscape
BACKEND_BIND_HOST=127.0.0.1
PORT=8080
```

---

## 功能说明

### 数据管理

#### 雷达数据管理
- 自动扫描网络共享目录
- 解析影像元数据（时间、位置、极化方式）
- 生成预览缩略图
- 空间范围可视化

#### 轨道数据管理
- 轨道文件自动关联
- 时间窗口匹配

#### D-InSAR 结果管理
- 结果自动入库
- 形变图可视化
- 统计分析

### D-InSAR 处理

#### 自动化处理流程
1. 影像导入（SARscape Import）
2. 影像配准（Coregistration）
3. 干涉处理（Interferogram Generation）
4. 相位滤波（Goldstein Filter）
5. 相位解缠（Phase Unwrapping）
6. 相位转位移（Phase to Displacement）
7. 地理编码（Geocoding）

#### 批量处理
- 支持多对影像批量处理
- 进度实时显示
- 失败自动重试

### 水体监测

#### 单景预处理
- 多视处理（Multilooking）
- 地理编码（Geocoding）
- 辐射定标

#### 洪涝检测
- 两景配对
- 洪涝分类
- MRF 精化（可选）

### AI 诊断

#### 多模态分析
- 支持 Ollama 本地部署
- 推荐模型：Qwen2-VL、LLaVA、MiniCPM-V
- 自动分析形变图
- 生成诊断报告

#### Prompt 模板
- Quick：快速分析
- Standard：标准分析（推荐）
- Detailed：详细分析

### 隐患点管理

- Shapefile 导入
- 空间查询
- 与影像范围关联

### 系统管理

#### 用户管理
- 管理员/只读用户
- 权限控制
- 审计日志

#### 运维自检
- 数据库健康检查
- IDL/ENVI 状态检查
- Ollama 状态检查
- Nginx 状态检查
- 一致性检测

#### 日志管理
- 统一日志目录
- 日志查看
- 日志删除（仅管理员）

---

## 架构设计

### 技术栈

**后端**：
- FastAPI：Web 框架
- SQLAlchemy：ORM
- PostgreSQL + PostGIS：数据库
- asyncpg：异步数据库驱动
- httpx：HTTP 客户端
- Pydantic：数据验证

**前端**：
- React：UI 框架
- Leaflet：地图组件
- Chart.js：图表组件
- Axios：HTTP 客户端

**地理空间**：
- GDAL/OGR：地理数据处理
- pyproj：坐标转换
- Shapely：几何运算
- Rasterio：栅格数据处理

**IDL/ENVI**：
- envipyengine：Python 调用 ENVI
- SARscape：SAR 数据处理

**AI**：
- Ollama：本地 LLM 部署
- 多模态模型：Qwen2-VL、LLaVA、MiniCPM-V

### 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                        Nginx                             │
│                  (反向代理 + 静态文件)                    │
└────────────┬────────────────────────────────────────────┘
             │
             ├─────────────────────────────────────────────┐
             │                                             │
┌────────────▼──────────┐                    ┌────────────▼──────────┐
│   FastAPI Backend     │                    │   React Frontend      │
│   (RESTful API)       │                    │   (SPA)               │
└────────────┬──────────┘                    └───────────────────────┘
             │
             ├─────────────────────────────────────────────┐
             │                                             │
┌────────────▼──────────┐                    ┌────────────▼──────────┐
│  PostgreSQL + PostGIS │                    │   Job Worker          │
│  (数据存储)            │                    │   (后台任务)           │
└───────────────────────┘                    └────────────┬──────────┘
                                                          │
                                             ┌────────────▼──────────┐
                                             │   IDL/ENVI            │
                                             │   (D-InSAR 处理)      │
                                             └───────────────────────┘
```

### 数据流

#### 雷达数据扫描流程
```
用户触发扫描 → FastAPI → 扫描网络目录 → 解析元数据 →
生成缩略图 → 入库 → 返回结果
```

#### D-InSAR 处理流程
```
用户提交任务 → FastAPI → 创建 SystemTask → Job Worker →
调用 IDL/ENVI → 执行 SARscape 流程 → 更新进度 →
结果入库 → 通知前端
```

#### AI 诊断流程
```
用户创建诊断 → FastAPI → 创建 SystemTask → Job Worker →
加载影像 → 查询隐患点 → 调用 Ollama → 解析结果 →
保存报告 → 通知前端
```

---

## 开发规范

### 代码规范

#### Python
- 遵循 PEP 8
- 使用类型注解
- 函数/类添加 docstring
- 异步函数使用 `async/await`

#### JavaScript/React
- 使用 ES6+ 语法
- 组件使用函数式组件 + Hooks
- 使用 PropTypes 或 TypeScript

### Git 规范

#### 提交信息格式
```
<type>(<scope>): <subject>

<body>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
```

**type**：
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具相关

**scope**：
- `backend`: 后端
- `frontend`: 前端
- `db`: 数据库
- `config`: 配置
- `docs`: 文档

### 安全规范

1. **不允许硬编码**
   - 所有路径、IP、端口必须通过 `.env` 配置
   - 不允许在代码中硬编码敏感信息

2. **输入验证**
   - 所有用户输入必须验证
   - 防止 SQL 注入、XSS、路径遍历

3. **权限控制**
   - 敏感操作仅管理员可执行
   - API 端点添加权限检查

4. **日志脱敏**
   - 日志中不记录密码、Token
   - 敏感信息使用 `***` 替代

---

## PROJ 配置指南

### 问题背景

PostgreSQL PostGIS 扩展自带 PROJ 数据库 v2（旧版本），而 GDAL/pyproj 期望 PROJ v3+（新版本）。版本不匹配会导致：
- 坐标转换警告
- 坐标转换精度下降
- 某些坐标系不支持

### 解决方案

系统会自动使用 pyproj 的 PROJ 数据库（v9.2+），无需手动配置。

启动后端时，会看到：
```
[*] Configuring PROJ database...
[*] Auto-detected PROJ_LIB: C:\\Users\\...\\pyproj\\proj_dir\\share\\proj
[*] PROJ version: 9.2.0
```

### 手动配置（可选）

如果需要使用自定义 PROJ 数据库，在 `.env` 中设置：

```bash
PROJ_LIB=C:\\path\\to\\proj\\data
```

### 验证配置

运行诊断脚本：
```bash
conda activate InSAR
python scripts/check_proj.py
```

---

## 安全审计

### 审计记录

#### 2026-03-12：当前有效安全审计记录
- 已区分“开发机阶段可接受暴露”和“上线前必须修复的问题”
- 当前结论以 `docs/SECURITY_AUDIT_2026-03-12.md` 为准
- 详见：`docs/SECURITY_AUDIT_2026-03-12.md`

#### 历史审计归档
- 2026-03-04 安全审计：`docs/archive/SECURITY_AUDIT_2026-03-04.md`
- 2026-03-05 硬编码审计：`docs/archive/HARDCODE_AUDIT_2026-03-05.md`
- 其他过程性安全文档已统一整理到：`docs/archive/`

### 安全配置

#### 生产环境建议

1. **数据库安全**
   ```bash
   # 使用强密码
   DATABASE_URL=postgresql+asyncpg://user:strong_password@localhost:5432/insar

   # 限制数据库访问
   # 在 PostgreSQL pg_hba.conf 中配置
   ```

2. **CORS 配置**
   ```bash
   # 生产环境使用明确的域名
   CORS_ORIGINS=https://insar.yourdomain.com
   ```

3. **Cookie 安全**
   ```bash
   # HTTPS 环境启用 Secure 标志
   AUTH_COOKIE_SECURE=true
   ```

4. **登录限流**
   ```bash
   # 防止暴力破解
   AUTH_LOGIN_MAX_FAILURES=5
   AUTH_LOGIN_WINDOW_SECONDS=300
   AUTH_LOGIN_LOCK_SECONDS=600
   ```

5. **Nginx 安全头**
   ```nginx
   # 在 nginx.conf 中添加
   add_header X-Frame-Options "SAMEORIGIN";
   add_header X-Content-Type-Options "nosniff";
   add_header X-XSS-Protection "1; mode=block";
   add_header Content-Security-Policy "default-src 'self'";
   ```

---

## 部署检查清单

### 部署前检查

- [ ] 所有配置项在 `.env` 中设置
- [ ] 数据库连接测试通过
- [ ] 数据目录路径正确且可访问
- [ ] IDL/ENVI 路径正确（如果使用）
- [ ] DEM 文件存在（如果使用 D-InSAR）
- [ ] Ollama 服务运行（如果使用 AI 诊断）
- [ ] Nginx 配置正确
- [ ] 防火墙规则配置
- [ ] CORS 配置为明确域名
- [ ] Cookie Secure 标志启用（HTTPS）
- [ ] 管理员密码已修改

### 部署后验证

- [ ] 访问前端页面正常
- [ ] 管理员登录成功
- [ ] 运维自检全部通过
- [ ] 雷达数据扫描正常
- [ ] D-InSAR 处理测试通过（如果使用）
- [ ] AI 诊断测试通过（如果使用）
- [ ] 日志记录正常
- [ ] 性能测试通过

---

## 常见问题

### Q1: 启动时报 "数据库连接失败"

**A**: 检查：
1. PostgreSQL 服务是否运行
2. `.env` 中的 `DATABASE_URL` 是否正确
3. 数据库是否已创建
4. 用户名密码是否正确

### Q2: PROJ 警告重复出现

**A**:
1. 检查启动日志是否显示 `Auto-detected PROJ_LIB`
2. 运行 `python scripts/check_proj.py` 诊断
3. 如果问题持续，在 `.env` 中手动设置 `PROJ_LIB`

### Q3: IDL/ENVI 任务失败

**A**: 检查：
1. IDL_EXECUTABLE 路径是否正确
2. IDL_DINSAR_DEM_BASE_FILE 是否存在
3. 查看任务日志：`logs/tasks/envi/`
4. 检查 ENVI 许可证是否有效

### Q4: Ollama 连接失败

**A**: 检查：
1. Ollama 服务是否运行
2. `.env` 中的 `OLLAMA_BASE_URL` 是否正确
3. 防火墙是否阻止连接
4. 运行 `curl http://127.0.0.1:11434/api/tags` 测试

### Q5: 前端无法访问后端 API

**A**: 检查：
1. Nginx 是否运行
2. Nginx 配置中的 proxy_pass 是否正确
3. 后端服务是否运行
4. 防火墙规则

---

## 更新日志

### 2026-03-05
- ✅ 修复硬编码问题（Ollama API、Nginx、后端绑定地址）
- ✅ 修复 PROJ 数据库版本冲突
- ✅ 实现统一日志管理系统
- ✅ 优化前端按钮布局

### 2026-03-04
- ✅ 完成安全审计第一阶段修复
- ✅ 修复 ENVI 工作流返回值缺失
- ✅ 修复失败计数重复累加
- ✅ 修复 PowerShell 编码问题

### 2026-03-03
- ✅ 实现 AI 诊断模块（Phase 1 + Phase 2）
- ✅ 修复前端全局锁问题
- ✅ 优化前端进度显示

---

## 联系方式

- 项目仓库：（待添加）
- 问题反馈：（待添加）
- 技术支持：（待添加）

---

**文档版本**：v2.0
**最后更新**：2026-03-05
**维护者**：开发团队