Tolan/NETWORK_CONFIG.md

网络配置指南

快速开始

场景1：本地开发（默认配置）

无需任何配置，直接启动即可：

# 启动后端
cd backend
python main.py

# 启动前端（新终端）
cd frontend  
npm run dev

访问：http://localhost:5173

---

场景2：手机访问电脑服务（局域网）

步骤1：查看电脑IP地址

Mac：

ifconfig | grep "inet " | grep -v 127.0.0.1
# 或
ipconfig getifaddr en0  # Wi-Fi
ipconfig getifaddr en1  # 以太网

Windows：

ipconfig
# 查找 IPv4 地址

Linux：

ip addr show | grep inet

假设得到IP：192.168.2.105

步骤2：修改前端配置

编辑 frontend/.env：

# 修改这一行
VITE_BACKEND_HOST=192.168.2.105
VITE_BACKEND_PORT=8000

步骤3：重启服务

# 重启前端（按Ctrl+C停止，然后）
npm run dev

后端无需重启（已默认允许所有来源）

步骤4：访问

电脑浏览器：

http://192.168.2.105:5173

手机浏览器（确保在同一Wi-Fi）：

http://192.168.2.105:5173

---

场景3：HTTPS访问（生产环境）

为什么需要HTTPS？

• ✅ 浏览器安全策略要求
• ✅ PWA安装需要
• ✅ 某些浏览器的麦克风权限要求

步骤1：生成SSL证书

开发环境（自签名证书）：

cd ssl/
# 生成自签名证书
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

生产环境：使用Let's Encrypt或购买证书

步骤2：修改后端配置

编辑 backend/.env 或直接修改 backend/config.py：

SSL_KEYFILE = "../ssl/key.pem"
SSL_CERTFILE = "../ssl/cert.pem"

步骤3：修改前端配置

编辑 frontend/.env：

VITE_WS_URL=wss://192.168.2.105:8000/ws/realtime

或修改 frontend/vite.config.ts：

server: {
  https: {
    key: fs.readFileSync('../ssl/key.pem'),
    cert: fs.readFileSync('../ssl/cert.pem'),
  },
}

步骤4：访问

https://192.168.2.105:5173

注意：自签名证书会有安全警告，点击"继续访问"即可。

---

常见问题

Q1: 手机无法连接

检查清单：

• 电脑和手机在同一Wi-Fi
• 电脑防火墙允许5173和8000端口
• 后端服务正常运行
• IP地址正确

Mac防火墙设置：

系统设置 → 网络 → 防火墙 → 选项
→ 允许Python/Python3访问网络

Windows防火墙：

控制面板 → Windows Defender防火墙
→ 允许应用通过防火墙
→ 添加Python

Q2: WebSocket连接失败

浏览器控制台检查：

// 应该看到
连接WebSocket: ws://192.168.2.105:8000/ws/realtime
WebSocket连接成功

如果失败：

1. 检查后端是否启动：访问 http://192.168.2.105:8000/docs
2. 检查.env配置是否正确
3. 清除浏览器缓存并刷新

Q3: CORS错误

错误信息：

Access to XMLHttpRequest at '...' from origin '...' 
has been blocked by CORS policy

解决方案：

确认 backend/config.py 中：

CORS_ALLOW_ALL: bool = True  # 开发环境

或在 backend/.env 添加：

CORS_ALLOW_ALL=true

Q4: 麦克风权限问题

HTTPS警告后无法录音：

1. 浏览器设置 → 网站权限 → 允许麦克风
2. 或使用http:// (开发环境)
3. 或配置有效的SSL证书（生产环境）

---

网络架构

用户设备                 电脑（服务器）
┌─────────┐             ┌──────────────────┐
│ 浏览器  │             │                  │
│         │  HTTP       │  Vite Dev Server │
│         ├────────────→│  :5173          │
│         │             └──────────────────┘
│         │                      
│         │  WebSocket  ┌──────────────────┐
│         ├────────────→│  FastAPI Backend │
│         │             │  :8000          │
└─────────┘             └──────────────────┘
                               │
                               ↓ WebSocket
                        ┌──────────────────┐
                        │  豆包API         │
                        └──────────────────┘

---

快速配置命令

本地开发

# 无需配置，直接启动
cd backend && python main.py &
cd frontend && npm run dev

局域网IP访问

# 1. 查看IP
ifconfig | grep "inet " | grep -v 127.0.0.1

# 2. 修改配置
echo "VITE_BACKEND_HOST=192.168.2.105" > frontend/.env
echo "VITE_BACKEND_PORT=8000" >> frontend/.env

# 3. 启动服务
cd backend && python main.py &
cd frontend && npm run dev

# 4. 手机访问
# http://192.168.2.105:5173

生产部署

# 1. 生成SSL证书
cd ssl && openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem -days 365 -nodes

# 2. 配置HTTPS
echo "VITE_WS_URL=wss://your-ip:8000/ws/realtime" > frontend/.env

# 3. 构建前端
cd frontend && npm run build

# 4. 部署...

---

测试配置

启动后，在浏览器控制台应该看到：

✅ 开始初始化应用...
✅ 连接WebSocket: ws://192.168.2.105:8000/ws/realtime
✅ WebSocket连接成功
✅ 会话已建立: session_xxxxx
✅ 应用初始化完成

如有问题，查看完整的错误日志。