# 硬编码审计报告（2026-03-05）

## 审计目的

确保系统可以在不同环境（开发机、生产环境、客户现场）部署，所有配置必须通过 `.env` 文件管理，不允许硬编码。

## 审计范围

- 后端代码（`backend/`）
- 启动脚本（`run_backend.py`, `scripts/`）
- 配置文件（`.env`, `config.py`）

## 发现的硬编码问题

### 🔴 高优先级（必须修复）

#### 1. Ollama API 地址硬编码

**位置**：
- `backend/app/ai_service.py:231`
- `backend/app/services/health_service.py:115`

**问题**：
```python
# 硬编码 Ollama API 地址
resp = await client.get("http://127.0.0.1:11434/api/tags")
```

**影响**：
- 如果 Ollama 部署在其他机器或端口，无法连接
- 客户环境可能使用不同的 Ollama 地址

**修复方案**：
```python
# 从环境变量读取
OLLAMA_BASE_URL = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
resp = await client.get(f"{OLLAMA_BASE_URL}/api/tags")
```

**`.env` 配置**：
```bash
# Ollama 服务地址（基础 URL）
OLLAMA_BASE_URL=http://127.0.0.1:11434
```

---

#### 2. Nginx 健康检查地址硬编码

**位置**：
- `backend/app/services/health_service.py:130`

**问题**：
```python
# 硬编码 Nginx 地址
resp = await client.get("http://127.0.0.1/")
```

**影响**：
- 如果 Nginx 监听其他端口或地址，健康检查失败
- 客户环境可能使用不同的 Nginx 配置

**修复方案**：
```python
# 从环境变量读取
NGINX_HEALTH_URL = os.getenv("NGINX_HEALTH_URL", "http://127.0.0.1/")
resp = await client.get(NGINX_HEALTH_URL)
```

**`.env` 配置**：
```bash
# Nginx 健康检查地址
NGINX_HEALTH_URL=http://127.0.0.1/
```

---

#### 3. 后端绑定地址硬编码

**位置**：
- `run_backend.py:29`

**问题**：
```python
# 硬编码绑定地址
bind_host = "127.0.0.1"
```

**影响**：
- 无法从外部访问（Docker 容器、远程部署）
- 某些部署场景需要绑定 `0.0.0.0`

**修复方案**：
```python
# 从环境变量读取
bind_host = os.getenv("BACKEND_BIND_HOST", "127.0.0.1")
```

**`.env` 配置**：
```bash
# 后端绑定地址（127.0.0.1 仅本地，0.0.0.0 允许外部访问）
BACKEND_BIND_HOST=127.0.0.1
```

---

### 🟡 中优先级（建议修复）

#### 4. PROJ 数据库路径检查脚本硬编码

**位置**：
- `scripts/check_proj.py:62`

**问题**：
```python
# 硬编码 PostgreSQL PROJ 路径
pg_proj = r"C:\Program Files\PostgreSQL\17\share\contrib\postgis-3.6\proj\proj.db"
```

**影响**：
- 不同 PostgreSQL 版本路径不同
- 客户环境可能安装在其他位置

**修复方案**：
```python
# 从环境变量读取，或自动检测
pg_proj = os.getenv("POSTGRESQL_PROJ_PATH", r"C:\Program Files\PostgreSQL\17\share\contrib\postgis-3.6\proj\proj.db")
```

---

### 🟢 低优先级（可选优化）

#### 5. 默认值中的硬编码

**位置**：
- `backend/app/config.py:33-34`

**问题**：
```python
OLLAMA_API_URL: str = "http://127.0.0.1:11434/api/generate"
DEFAULT_VLM_MODEL: str = "qwen3-vl:8b"
```

**说明**：
- 这些是默认值，已经通过 `os.getenv()` 读取
- 但默认值本身是硬编码的

**修复方案**：
- 保持现状（默认值是合理的）
- 或者在文档中明确说明这些默认值

---

## 修复优先级

| 优先级 | 问题 | 影响 | 修复难度 |
|--------|------|------|----------|
| 🔴 P0 | Ollama API 地址 | 高 | 低 |
| 🔴 P0 | Nginx 健康检查地址 | 中 | 低 |
| 🔴 P0 | 后端绑定地址 | 高 | 低 |
| 🟡 P1 | PROJ 路径检查 | 低 | 低 |
| 🟢 P2 | 默认值硬编码 | 低 | 无需修复 |

---

## 修复计划

### 阶段 1：立即修复（P0）

1. **修改 `backend/app/ai_service.py`**
   - 添加 `OLLAMA_BASE_URL` 环境变量
   - 修改 API 调用使用动态 URL

2. **修改 `backend/app/services/health_service.py`**
   - 添加 `OLLAMA_BASE_URL` 和 `NGINX_HEALTH_URL` 环境变量
   - 修改健康检查使用动态 URL

3. **修改 `run_backend.py`**
   - 添加 `BACKEND_BIND_HOST` 环境变量
   - 支持配置绑定地址

4. **更新 `.env` 文件**
   - 添加新的配置项和注释

5. **更新文档**
   - 在部署文档中说明这些配置项

### 阶段 2：建议修复（P1）

1. **修改 `scripts/check_proj.py`**
   - 支持从环境变量读取 PostgreSQL 路径
   - 或自动检测 PostgreSQL 安装路径

---

## 验证方法

### 1. 配置文件验证

检查 `.env` 文件是否包含所有必需的配置项：

```bash
# 必需配置
DATABASE_URL=...
IDL_EXECUTABLE=...
IDL_DINSAR_DEM_BASE_FILE=...

# 新增配置
OLLAMA_BASE_URL=http://127.0.0.1:11434
NGINX_HEALTH_URL=http://127.0.0.1/
BACKEND_BIND_HOST=127.0.0.1
```

### 2. 代码审计

运行以下命令检查是否还有硬编码：

```bash
# 检查绝对路径
grep -r "C:\\\\" backend/ --include="*.py"
grep -r "D:\\\\" backend/ --include="*.py"

# 检查 IP 地址
grep -r "127\.0\.0\.1" backend/ --include="*.py"
grep -r "localhost" backend/ --include="*.py"

# 检查端口号
grep -r ":11434" backend/ --include="*.py"
grep -r ":8000" backend/ --include="*.py"
```

### 3. 部署测试

在不同环境测试：

1. **本地开发环境**：使用默认配置
2. **Docker 容器**：修改 `BACKEND_BIND_HOST=0.0.0.0`
3. **远程 Ollama**：修改 `OLLAMA_BASE_URL=http://192.168.1.100:11434`
4. **自定义端口**：修改 `PORT=18000`

---

## 部署检查清单

在部署到客户环境前，确认：

- [ ] 所有路径配置在 `.env` 中
- [ ] 所有 IP 地址/端口配置在 `.env` 中
- [ ] 没有硬编码的绝对路径
- [ ] 没有硬编码的 IP 地址
- [ ] 没有硬编码的端口号
- [ ] 所有配置项都有默认值（合理的）
- [ ] 所有配置项都有注释说明
- [ ] 部署文档已更新

---

## 相关文档

- `.env` 配置文件
- `docs/PROJ_CONFIGURATION.md` - PROJ 数据库配置
- `docs/DEPLOYMENT.md` - 部署文档（待创建）

---

## 总结

**当前状态**：
- ✅ 大部分配置已通过 `.env` 管理
- ❌ 发现 3 个高优先级硬编码问题
- ⚠️ 需要立即修复以支持生产部署

**修复后**：
- ✅ 所有配置通过 `.env` 管理
- ✅ 支持多种部署场景
- ✅ 客户环境可自定义配置
- ✅ 无需修改代码即可部署