docs: 添加生产环境API连接配置指南

- 创建 frontend/.env.production.example 示例文件 - 新增 API_CONNECTION_FIX.md 详细配置文档 - 说明 CORS 配置和生产模式 API 连接方法 - 提供故障排查和常见问题解决方案 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
2025-12-25 19:16:02 +08:00
parent 7369e025d3
commit 3c2d9f4cad
2 changed files with 304 additions and 0 deletions
@@ -0,0 +1,296 @@
+# API 连接配置指南
+
+**更新时间**: 2025-12-25
+**状态**: ✅ 已修复
+
+---
+
+## 问题描述
+
+生产构建模式下，前端无法访问后端API：
+- "今日推荐" 加载失败
+- "获取策略失败: Failed to fetch"
+- 浏览器控制台显示 CORS 错误
+
+## 根本原因
+
+### 1. 代理配置失效
+
+使用 `serve` 静态服务器后，Vite dev server 的代理配置不生效：
+
+```javascript
+// vite.config.js 中的代理配置（仅在开发模式有效）
+proxy: {
+  '/api': {
+    target: 'http://localhost:8028',  // ❌ 生产模式下不工作
+    changeOrigin: true
+  }
+}
+```
+
+**原因**: `serve` 是纯静态文件服务器，不支持反向代理功能。
+
+### 2. CORS 配置不完整
+
+后端默认 CORS 配置：
+```env
+# backend/.env (默认值)
+CORS_ORIGINS=http://localhost:8080,http://localhost:5173
+```
+
+**问题**: 不包含生产环境前端 URL (`http://192.168.1.83:8448`)，浏览器阻止跨域请求。
+
+---
+
+## 解决方案
+
+### 步骤 1: 配置前端生产环境变量
+
+创建 `frontend/.env.production` 文件：
+
+```bash
+cp frontend/.env.production.example frontend/.env.production
+```
+
+编辑内容（根据实际IP地址修改）：
+
+```env
+# 生产环境配置 - 前端直接连接后端API
+# 使用本机IP地址，支持局域网访问
+
+# 后端API地址（使用局域网IP，支持远程访问）
+VITE_API_URL=http://192.168.1.83:8028/api
+
+# WebSocket地址
+VITE_WS_URL=ws://192.168.1.83:8028/ws/recommendations
+```
+
+**重要**:
+- 将 `192.168.1.83` 替换为您的实际局域网 IP
+- 如果仅本地访问，可以使用 `http://localhost:8028/api`
+
+### 步骤 2: 配置后端 CORS
+
+编辑 `backend/.env`，添加或更新 CORS 配置：
+
+```env
+# CORS配置 - 允许前端访问
+CORS_ORIGINS=http://localhost:8448,http://192.168.1.83:8448,http://localhost:5173,http://localhost:8080
+```
+
+**说明**:
+- `http://localhost:8448`: 本地前端访问
+- `http://192.168.1.83:8448`: 局域网前端访问
+- `http://localhost:5173`: Vite 开发服务器
+- `http://localhost:8080`: 其他可能的开发端口
+
+### 步骤 3: 重新构建和部署
+
+```bash
+# 1. 重新构建前端（使用 .env.production 配置）
+cd frontend
+npm run build
+
+# 2. 重启服务
+pm2 restart ljwx-stock-frontend ljwx-stock-backend
+
+# 3. 保存 PM2 配置
+pm2 save
+```
+
+---
+
+## 验证步骤
+
+### 1. 检查服务状态
+
+```bash
+pm2 list
+# 确保两个服务都是 online 状态
+```
+
+### 2. 测试后端 API
+
+```bash
+# 健康检查
+curl http://192.168.1.83:8028/health
+# 预期输出: {"status":"healthy"}
+
+# 策略列表 API
+curl http://192.168.1.83:8028/api/strategies/list
+# 预期输出: JSON 策略列表
+
+# 推荐 API
+curl http://192.168.1.83:8028/api/recommendations?limit=3
+# 预期输出: JSON 推荐列表
+```
+
+### 3. 浏览器测试
+
+打开浏览器访问：
+- 本地: http://localhost:8448
+- 远程: http://192.168.1.83:8448
+
+打开浏览器开发者工具（F12），检查：
+- **Network** 标签: API 请求应该返回 200 状态码
+- **Console** 标签: 不应该有 CORS 错误
+
+---
+
+## 常见问题
+
+### Q1: 页面显示 "获取策略失败: Failed to fetch"
+
+**原因**: 前端无法连接到后端 API
+
+**解决步骤**:
+1. 确认后端服务运行正常: `pm2 list | grep backend`
+2. 测试后端 API: `curl http://192.168.1.83:8028/health`
+3. 检查防火墙是否允许 8028 端口访问
+4. 确认 `frontend/.env.production` 中的 URL 正确
+
+### Q2: 浏览器控制台显示 CORS 错误
+
+**错误示例**:
+```
+Access to fetch at 'http://192.168.1.83:8028/api/...' from origin 'http://192.168.1.83:8448'
+has been blocked by CORS policy
+```
+
+**解决步骤**:
+1. 检查 `backend/.env` 中的 `CORS_ORIGINS` 是否包含前端 URL
+2. 重启后端: `pm2 restart ljwx-stock-backend`
+3. 清除浏览器缓存并刷新
+
+### Q3: 更改IP地址后API不工作
+
+**场景**: 路由器重新分配了IP地址（例如从 192.168.1.83 变为 192.168.1.100）
+
+**解决步骤**:
+1. 查看新IP地址: `ifconfig | grep "inet "`
+2. 更新 `frontend/.env.production`:
+   ```env
+   VITE_API_URL=http://192.168.1.100:8028/api
+   VITE_WS_URL=ws://192.168.1.100:8028/ws/recommendations
+   ```
+3. 更新 `backend/.env`:
+   ```env
+   CORS_ORIGINS=http://localhost:8448,http://192.168.1.100:8448,http://localhost:5173,http://localhost:8080
+   ```
+4. 重新构建和重启:
+   ```bash
+   cd frontend
+   npm run build
+   pm2 restart all
+   ```
+
+### Q4: 推荐API响应很慢（10秒以上）
+
+**原因**: AI 推荐需要：
+- 获取实时股票数据（TuShare/yfinance）
+- 计算技术指标
+- 运行 ML 模型
+- 调用本地 Ollama（lingjingwanxiang:32b）
+
+**正常响应时间**:
+- 首次请求（冷启动）: 10-30 秒
+- 缓存命中: 2-5 秒
+
+**优化建议**:
+- 等待缓存预热（60秒 TTL）
+- 减少请求的股票数量: `?limit=5`
+
+---
+
+## 架构说明
+
+### 开发模式 (Vite dev server)
+
+```
+浏览器 → Vite (localhost:8448) → [内置代理] → Backend (localhost:8028)
+                                      ↑
+                                 vite.config.js
+```
+
+### 生产模式 (serve + 直连)
+
+```
+浏览器 → Serve (192.168.1.83:8448) → Backend (192.168.1.83:8028)
+                                          ↑
+                                    需要 CORS 配置
+```
+
+**关键区别**:
+- 开发模式: Vite 代理所有 `/api` 请求，无跨域问题
+- 生产模式: 浏览器直接请求后端，需要正确的 CORS 配置
+
+---
+
+## 替代方案（可选）
+
+### 方案 A: 使用 Caddy（推荐，自动反向代理）
+
+安装 Caddy:
+```bash
+brew install caddy  # macOS
+# 或
+sudo apt install caddy  # Linux
+```
+
+创建 `Caddyfile`:
+```caddyfile
+:8448 {
+    root * frontend/dist
+    encode gzip
+    file_server
+
+    # API代理
+    reverse_proxy /api/* localhost:8028
+    reverse_proxy /ws/* localhost:8028
+
+    # SPA路由
+    try_files {path} /index.html
+}
+```
+
+启动:
+```bash
+caddy run
+```
+
+**优点**:
+- 自动处理反向代理，无需配置 CORS
+- HTTPS 自动化
+- 性能优秀
+
+### 方案 B: 使用 Nginx
+
+参考 `FRONTEND_CRASH_ANALYSIS.md` 中的 Nginx 配置。
+
+---
+
+## 文件清单
+
+生产环境需要配置的文件：
+
+- ✅ `frontend/.env.production` - 前端生产环境变量（未纳入 Git）
+- ✅ `frontend/.env.production.example` - 示例配置（已纳入 Git）
+- ✅ `backend/.env` - 后端环境变量，添加 CORS_ORIGINS（未纳入 Git）
+- ✅ `ecosystem.config.js` - PM2 配置（已纳入 Git）
+
+**安全提示**: `.env` 文件包含敏感信息，已通过 `.gitignore` 排除，不会提交到 Git。
+
+---
+
+## 相关文档
+
+- `FRONTEND_CRASH_ANALYSIS.md` - 前端崩溃问题分析和生产构建方案
+- `CURRENT_STATUS.md` - 系统当前状态和配置说明
+- `.env.example` - 后端环境变量示例
+- `frontend/.env.production.example` - 前端生产环境变量示例
+
+---
+
+**最后更新**: 2025-12-25
+**维护者**: Claude Code
+**状态**: ✅ 问题已彻底解决
@@ -0,0 +1,8 @@
+# 生产环境配置 - 前端直接连接后端API
+# 使用本机IP地址，支持局域网访问
+
+# 后端API地址（使用局域网IP，支持远程访问）
+VITE_API_URL=http://192.168.1.83:8028/api
+
+# WebSocket地址
+VITE_WS_URL=ws://192.168.1.83:8028/ws/recommendations