erp-ass/docs/LAN_ACCESS.md

# 局域网访问配置指南

## 🌐 配置说明

本项目已配置支持局域网访问，允许团队在同一局域网内访问前端和后端服务。

## ✅ 已完成的配置

### 1. 前端配置 (Vite)

**文件**: `frontend/vite.config.js`

```javascript
server: {
  host: '0.0.0.0',  // 监听所有网络接口，允许局域网访问
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true
    }
  }
}
```

### 2. 后端配置 (FastAPI)

**文件**: `backend/app/main.py`

- **服务监听**: `host="0.0.0.0"` (已配置，监听所有网络接口)
- **CORS 策略**:
  - 开发模式 (`DEBUG=True`): 允许所有来源 (`allow_origins=["*"]`)
  - 生产模式: 仅允许 localhost

## 🚀 使用步骤

### 1. 获取服务器 IP 地址

在运行服务的机器上执行：

**Windows:**
```bash
ipconfig
```
查找 "IPv4 地址"，例如：`192.168.1.100`

**Linux/Mac:**
```bash
ifconfig
# 或
ip addr show
```
查找 `inet` 地址，例如：`inet 192.168.1.100`

### 2. 启动服务

**启动后端:**
```bash
cd backend
source venv/bin/activate  # Windows: venv\Scripts\activate
python -m app.main
```

后端将监听：
- `http://0.0.0.0:8000` (所有网络接口)
- 可通过 `http://localhost:8000` 或 `http://192.168.1.100:8000` 访问

**启动前端:**
```bash
cd frontend
npm run dev
```

Vite 将输出：
```
  VITE v5.0.4  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/
```

### 3. 局域网访问

在同一局域网的其他设备上，使用服务器 IP 地址访问：

- **前端**: `http://192.168.1.100:5173`
- **后端 API**: `http://192.168.1.100:8000`
- **API 文档**: `http://192.168.1.100:8000/docs`

## 🔥 防火墙配置

如果局域网内无法访问，需要检查防火墙设置。

### Windows 防火墙

**方法 1: 允许端口**
```powershell
# 以管理员身份运行 PowerShell
netsh advfirewall firewall add rule name="ERP AI Assistant - Frontend" dir=in action=allow protocol=tcp localport=5173
netsh advfirewall firewall add rule name="ERP AI Assistant - Backend" dir=in action=allow protocol=tcp localport=8000
```

**方法 2: 允许应用**
1. 打开 "Windows Defender 防火墙"
2. 点击 "允许应用通过防火墙"
3. 添加 `node.exe` 和 `python.exe`

### Linux 防火墙

**UFW (Ubuntu):**
```bash
sudo ufw allow 5173/tcp
sudo ufw allow 8000/tcp
sudo ufw reload
```

**Firewalld (CentOS/RHEL):**
```bash
sudo firewall-cmd --permanent --add-port=5173/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload
```

### 云服务器安全组

如果运行在云服务器上，需要在安全组中开放端口：
- 入站规则: 允许 TCP 端口 5173 和 8000

## 📱 测试访问

### 1. 本地测试

在服务器机器上测试：

```bash
# 测试后端
curl http://localhost:8000/health

# 测试前端（浏览器访问）
http://localhost:5173
```

### 2. 局域网测试

在其他设备上测试：

```bash
# 测试后端（替换为实际 IP）
curl http://192.168.1.100:8000/health

# 测试前端（浏览器访问）
http://192.168.1.100:5173
```

## ⚠️ 安全注意事项

### 开发环境

当前配置适合开发环境：
- ✅ CORS 允许所有来源 (`allow_origins=["*"]`)
- ✅ 方便团队协作和测试

### 生产环境

**强烈建议**生产环境进行以下调整：

1. **设置 `DEBUG=False`**
   ```bash
   # .env
   DEBUG=False
   ```

2. **配置具体允许的域名**
   修改 `backend/app/main.py`:
   ```python
   allow_origins=[
       "https://your-domain.com",
       "https://erp.your-company.com",
   ]
   ```

3. **使用 HTTPS**
   - 配置 SSL 证书
   - 使用 Nginx 反向代理

4. **使用环境变量管理 CORS**
   在 `.env` 中配置：
   ```bash
   ALLOWED_ORIGINS=https://domain1.com,https://domain2.com
   ```

## 🔧 高级配置

### 自定义端口

如果默认端口被占用，可以修改：

**前端** (`frontend/vite.config.js`):
```javascript
server: {
  host: '0.0.0.0',
  port: 3000,  // 自定义端口
  // ...
}
```

**后端** (`backend/app/main.py`):
```python
uvicorn.run(
    "app.main:app",
    host="0.0.0.0",
    port=8888,  # 自定义端口
    reload=settings.DEBUG
)
```

### 使用 Nginx 反向代理

生产环境推荐使用 Nginx：

```nginx
server {
    listen 80;
    server_name erp.your-company.com;

    # 前端
    location / {
        proxy_pass http://127.0.0.1:5173;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 后端 API
    location /api/ {
        proxy_pass http://127.0.0.1:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 📊 访问日志

查看访问日志，确认服务正常运行：

**前端日志:**
```bash
# Vite 会显示访问日志
npm run dev
```

**后端日志:**
```bash
# FastAPI/Uvicorn 会显示请求日志
python -m app.main
```

## 🐛 故障排查

### 问题 1: 无法访问

**症状**: 局域网内其他设备无法访问

**检查清单:**
- ✅ 服务器 IP 地址是否正确
- ✅ 防火墙是否开放端口
- ✅ 服务是否正在运行
- ✅ 是否在同一局域网内

**诊断命令:**
```bash
# 测试端口是否开放
telnet 192.168.1.100 5173
telnet 192.168.1.100 8000

# 或使用 nc
nc -zv 192.168.1.100 5173
nc -zv 192.168.1.100 8000
```

### 问题 2: CORS 错误

**症状**: 浏览器控制台显示 CORS 错误

**解决方案:**
- 确认 `DEBUG=True` 在 `.env` 中
- 检查后端 CORS 配置
- 查看浏览器控制台错误详情

### 问题 3: API 代理失败

**症状**: 前端无法调用后端 API

**解决方案:**
- 检查后端是否在 `localhost:8000` 运行
- 确认 Vite proxy 配置正确
- 查看浏览器网络请求

## 📝 快速命令参考

```bash
# 查看本机 IP
ipconfig          # Windows
ifconfig          # Linux/Mac
ip addr show      # Linux

# 测试端口
netstat -an | grep 5173   # Linux/Mac
netstat -an | findstr 5173 # Windows

# 开放防火墙端口
sudo ufw allow 5173/tcp    # Ubuntu
sudo firewall-cmd --add-port=5173/tcp  # CentOS
```

---

**更新时间**: 2026-03-21
**适用版本**: v1.0.0+