# 通过 IP 地址访问配置完整指南

## 📋 已完成的配置

### 1. Vite 服务器配置
✅ `vite.config.js` - 配置服务器监听所有网络接口

### 2. 环境变量配置
✅ `.env.development` - 开发环境配置
✅ `.env.production` - 生产环境配置

### 3. API 配置
✅ `src/services/api.js` - 支持环境变量配置 API 地址

### 4. WebSocket 配置
✅ `src/pages/Dashboard.jsx` - 支持环境变量配置 WebSocket 地址

---

## 🚀 快速开始

### 步骤 1: 获取本机 IP 地址

**Windows 系统**:
```bash
ipconfig
```
找到 "IPv4 地址"，例如: `192.168.1.100`

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

### 步骤 2: 配置环境变量

编辑 `user_frontend/.env.development` 文件:

```env
# 将 localhost 替换为你的 IP 地址
VITE_API_BASE_URL=http://192.168.1.100:8000/api
VITE_WS_BASE_URL=ws://192.168.1.100:8000
```

**重要**: 将 `192.168.1.100` 替换为你实际的 IP 地址！

### 步骤 3: 配置后端允许跨域

确保后端 `backend/main.py` 中的 CORS 配置允许你的 IP:

```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",
        "http://127.0.0.1:5173",
        "http://192.168.1.100:5173",  # 添加你的 IP
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

或者使用通配符（仅开发环境）:
```python
allow_origins=["*"]
```

### 步骤 4: 启动项目

**启动后端**:
```bash
cd backend
python main.py
```

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

### 步骤 5: 访问项目

启动后会显示:
```
➜  Local:   http://localhost:5173/
➜  Network: http://192.168.1.100:5173/
```

**访问方式**:
- 本机: http://localhost:5173/
- 局域网其他设备: http://192.168.1.100:5173/
- 手机（同一WiFi）: http://192.168.1.100:5173/

---

## 🔧 详细配置说明

### 环境变量说明

Vite 使用 `import.meta.env` 来访问环境变量:

- `VITE_API_BASE_URL`: 后端 API 基础地址
- `VITE_WS_BASE_URL`: WebSocket 服务器地址

**注意**: 
- 环境变量必须以 `VITE_` 开头才能在客户端代码中访问
- 修改环境变量后需要重启开发服务器

### 不同场景的配置

#### 场景 1: 本地开发（默认）
```env
VITE_API_BASE_URL=http://localhost:8000/api
VITE_WS_BASE_URL=ws://localhost:8000
```

#### 场景 2: 局域网访问
```env
VITE_API_BASE_URL=http://192.168.1.100:8000/api
VITE_WS_BASE_URL=ws://192.168.1.100:8000
```

#### 场景 3: 生产环境
```env
VITE_API_BASE_URL=https://api.yourdomain.com/api
VITE_WS_BASE_URL=wss://api.yourdomain.com
```

---

## 🛡️ 防火墙配置

### Windows 防火墙

1. 打开 "控制面板" → "Windows Defender 防火墙"
2. 点击 "高级设置"
3. 选择 "入站规则" → "新建规则"
4. 选择 "端口" → "TCP" → 输入 "5173"
5. 选择 "允许连接"
6. 应用到所有配置文件
7. 命名规则（如 "Vite Dev Server"）

### 快速测试（临时关闭防火墙）

**不推荐长期使用，仅用于测试**:
```bash
# Windows
netsh advfirewall set allprofiles state off

# 测试完成后记得开启
netsh advfirewall set allprofiles state on
```

---

## 🐛 常见问题排查

### 问题 1: 其他设备无法访问

**检查清单**:
- [ ] 确认设备在同一局域网（同一WiFi）
- [ ] 确认 IP 地址正确
- [ ] 确认防火墙允许端口 5173
- [ ] 确认后端也配置了 CORS
- [ ] 尝试 ping IP 地址测试网络连通性

**测试命令**:
```bash
# 在其他设备上测试网络连通性
ping 192.168.1.100

# 测试端口是否开放
telnet 192.168.1.100 5173
```

### 问题 2: 页面加载但功能不正常

**可能原因**:
- API 请求失败（检查浏览器控制台）
- WebSocket 连接失败
- 后端 CORS 配置不正确

**解决方案**:
1. 打开浏览器开发者工具（F12）
2. 查看 Console 和 Network 标签
3. 检查是否有 CORS 错误或连接失败
4. 确认 `.env.development` 中的地址配置正确

### 问题 3: 修改环境变量后不生效

**解决方案**:
1. 停止开发服务器（Ctrl+C）
2. 重新启动: `npm run dev`
3. 清除浏览器缓存（Ctrl+Shift+Delete）
4. 硬刷新页面（Ctrl+F5）

### 问题 4: 手机无法访问

**检查清单**:
- [ ] 手机和电脑连接同一WiFi
- [ ] 路由器未开启 AP 隔离
- [ ] 手机浏览器输入正确的 IP 和端口
- [ ] 尝试关闭电脑防火墙测试

---

## 📱 移动设备访问优化

### 响应式设计
项目已使用 Ant Design，自动支持移动端适配。

### 移动端调试
1. 在手机浏览器访问项目
2. 使用 Chrome 远程调试:
   - 电脑 Chrome 打开 `chrome://inspect`
   - 手机通过 USB 连接电脑
   - 在 Chrome 中查看手机页面

---

## 🔒 安全建议

### 开发环境
- ✅ 仅在局域网内使用 IP 访问
- ✅ 不要将开发服务器暴露到公网
- ✅ 使用防火墙限制访问来源

### 生产环境
- ✅ 使用域名而非 IP
- ✅ 启用 HTTPS/WSS
- ✅ 配置严格的 CORS 策略
- ✅ 使用环境变量管理敏感配置

---

## 📝 配置文件清单

### 前端配置文件
```
user_frontend/
├── vite.config.js          # Vite 服务器配置
├── .env.development        # 开发环境变量
├── .env.production         # 生产环境变量
└── src/
    ├── services/
    │   └── api.js          # API 配置（支持环境变量）
    └── pages/
        └── Dashboard.jsx   # WebSocket 配置（支持环境变量）
```

### 后端配置文件
```
backend/
└── main.py                 # CORS 配置
```

---

## ✅ 测试步骤

### 1. 本地测试
```bash
# 启动项目
npm run dev

# 访问
http://localhost:5173/
```

### 2. 局域网测试
```bash
# 修改 .env.development
# 重启项目
npm run dev

# 在其他设备访问
http://你的IP:5173/
```

### 3. 功能测试
- [ ] 登录功能
- [ ] 聊天功能
- [ ] WebSocket 实时通信
- [ ] 表情发送
- [ ] 数字员工交互

---

## 🎯 快速命令参考

```bash
# 获取 IP 地址
ipconfig                    # Windows
ifconfig                    # Linux/Mac

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 测试网络连通性
ping 192.168.1.100

# 查看端口占用
netstat -ano | findstr 5173    # Windows
lsof -i :5173                  # Linux/Mac
```

---

## 📞 需要帮助？

如果遇到问题:
1. 检查浏览器控制台错误信息
2. 查看开发服务器终端输出
3. 确认所有配置步骤都已完成
4. 参考本文档的"常见问题排查"部分

---

## 🎉 完成！

现在你的项目已经配置完成，可以通过 IP 地址在局域网内访问了！

记得根据实际情况修改 `.env.development` 文件中的 IP 地址。
