erp-ass/docs/LAN_ACCESS.md

局域网访问配置指南

🌐 配置说明

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

✅ 已完成的配置

1. 前端配置 (Vite)

文件: frontend/vite.config.js

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:

ipconfig

查找 "IPv4 地址"，例如：192.168.1.100

Linux/Mac:

ifconfig
# 或
ip addr show

查找 inet 地址，例如：inet 192.168.1.100

2. 启动服务

启动后端:

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 访问

启动前端:

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
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):

sudo ufw allow 5173/tcp
sudo ufw allow 8000/tcp
sudo ufw reload

Firewalld (CentOS/RHEL):

sudo firewall-cmd --permanent --add-port=5173/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

云服务器安全组

如果运行在云服务器上，需要在安全组中开放端口：

• 入站规则: 允许 TCP 端口 5173 和 8000

📱 测试访问

1. 本地测试

在服务器机器上测试：

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

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

2. 局域网测试

在其他设备上测试：

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

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

⚠️ 安全注意事项

开发环境

当前配置适合开发环境：

• ✅ CORS 允许所有来源 (allow_origins=["*"])
• ✅ 方便团队协作和测试

生产环境

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

1. 设置 DEBUG=False

   # .env
   DEBUG=False
   

2. 配置具体允许的域名 修改 backend/app/main.py:

   allow_origins=[
       "https://your-domain.com",
       "https://erp.your-company.com",
   ]
   

3. 使用 HTTPS

   • 配置 SSL 证书
   • 使用 Nginx 反向代理

4. 使用环境变量管理 CORS 在 .env 中配置：

   ALLOWED_ORIGINS=https://domain1.com,https://domain2.com
   

🔧 高级配置

自定义端口

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

前端 (frontend/vite.config.js):

server: {
  host: '0.0.0.0',
  port: 3000,  // 自定义端口
  // ...
}

后端 (backend/app/main.py):

uvicorn.run(
    "app.main:app",
    host="0.0.0.0",
    port=8888,  # 自定义端口
    reload=settings.DEBUG
)

使用 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;
    }
}

📊 访问日志

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

前端日志:

# Vite 会显示访问日志
npm run dev

后端日志:

# FastAPI/Uvicorn 会显示请求日志
python -m app.main

🐛 故障排查

问题 1: 无法访问

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

检查清单:

• ✅ 服务器 IP 地址是否正确
• ✅ 防火墙是否开放端口
• ✅ 服务是否正在运行
• ✅ 是否在同一局域网内

诊断命令:

# 测试端口是否开放
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 配置正确
• 查看浏览器网络请求

📝 快速命令参考

# 查看本机 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+