TraceStudio-dev/docs/studio1.3/LAN_ACCESS.md

# TraceStudio 局域网访问配置指南

## 🌐 配置局域网访问

### 1. 启动后端服务器（监听所有接口）

```bash
cd server
conda activate tracestudio
python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
```

**注意**：`--host 0.0.0.0` 表示监听所有网络接口，支持局域网访问。

### 2. 配置前端API地址

创建 `web/.env.local` 文件，设置你的本机IP：

```bash
cd web
echo "VITE_API_BASE_URL=http://10.18.8.106:8000" > .env.local
```

**获取本机IP**：
```bash
# Windows
ipconfig

# Linux/Mac
ifconfig
# 或
ip addr show
```

### 3. 启动前端服务器（监听所有接口）

```bash
cd web
npm run dev
```

Vite 配置已默认监听 `0.0.0.0:5173`。

### 4. 访问地址

从局域网内其他设备访问：

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

## 🔥 Windows 防火墙配置

如果无法访问，需要开放端口：

### 方法一：PowerShell 命令（管理员权限）

```powershell
# 开放前端端口 5173
New-NetFirewallRule -DisplayName "TraceStudio Frontend" -Direction Inbound -Protocol TCP -LocalPort 5173 -Action Allow

# 开放后端端口 8000
New-NetFirewallRule -DisplayName "TraceStudio Backend" -Direction Inbound -Protocol TCP -LocalPort 8000 -Action Allow
```

### 方法二：图形界面

1. 打开 **Windows Defender 防火墙**
2. 点击 **高级设置**
3. 选择 **入站规则** → **新建规则**
4. 选择 **端口** → 下一步
5. 选择 **TCP**，输入端口 `5173` 或 `8000`
6. 选择 **允许连接**
7. 全选配置文件（域、专用、公用）
8. 输入规则名称，完成

## 📱 移动设备访问

确保移动设备与电脑在同一局域网，然后访问：

```
http://10.18.8.106:5173
```

## 🚀 快速启动脚本

### Windows (start-lan.bat)

```batch
@echo off
echo Starting TraceStudio for LAN access...

REM 获取本机IP
for /f "tokens=2 delims=:" %%a in ('ipconfig ^| findstr /C:"IPv4"') do set IP=%%a
set IP=%IP: =%
echo Your IP: %IP%

REM 启动后端
start "Backend" cmd /k "cd server && conda activate tracestudio && python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000"

REM 等待3秒
timeout /t 3

REM 启动前端
start "Frontend" cmd /k "cd web && npm run dev"

echo.
echo ========================================
echo TraceStudio is starting...
echo Frontend: http://%IP%:5173
echo Backend:  http://%IP%:8000
echo API Docs: http://%IP%:8000/docs
echo ========================================
```

### Linux/Mac (start-lan.sh)

```bash
#!/bin/bash

echo "Starting TraceStudio for LAN access..."

# 获取本机IP
IP=$(hostname -I | awk '{print $1}')
echo "Your IP: $IP"

# 启动后端
cd server
conda activate tracestudio
python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000 &

# 等待3秒
sleep 3

# 启动前端
cd ../web
npm run dev &

echo ""
echo "========================================"
echo "TraceStudio is starting..."
echo "Frontend: http://$IP:5173"
echo "Backend:  http://$IP:8000"
echo "API Docs: http://$IP:8000/docs"
echo "========================================"
```

## 🔒 安全建议

1. **仅在可信局域网使用**
2. **不要暴露到公网**
3. **生产环境建议使用反向代理（Nginx）**
4. **添加身份认证机制**

## 🐛 常见问题

### 问题1：防火墙阻止连接

**解决方案**：按照上述步骤开放端口 5173 和 8000

### 问题2：浏览器显示 ERR_CONNECTION_REFUSED

**检查清单**：
- [ ] 后端是否使用 `--host 0.0.0.0` 启动
- [ ] 前端 vite.config.ts 是否配置了 `host: '0.0.0.0'`
- [ ] 防火墙是否开放端口
- [ ] IP地址是否正确

### 问题3：前端可以访问，但API请求失败

**解决方案**：
1. 检查 `.env.local` 中的 `VITE_API_BASE_URL` 是否设置为本机IP
2. 确保后端监听 `0.0.0.0:8000`
3. 测试后端是否可访问：
   ```bash
   curl http://10.18.8.106:8000/
   ```

### 问题4：其他设备无法访问

**检查清单**：
- [ ] 设备是否在同一局域网
- [ ] 本机IP是否正确
- [ ] 公司网络是否有访问限制
- [ ] 尝试关闭所有防火墙进行测试

## 📞 验证访问

从另一台设备测试：

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

# 测试API
curl http://10.18.8.106:8000/api/users/list
```

预期返回JSON数据表示成功！