2026-04-29-22-37-36 - 修复登录ERR_CONNECTION_REFUSED：前端baseURL改IP+后端CORS扩origin

工程分析/经验记录.md

@@ -117,4 +117,29 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装
 
 ---
 
+## 2026-04-29-22-37-36 — 登录报错 ERR_CONNECTION_REFUSED
+
+### A. 具体问题
+用户通过浏览器访问前端并点击登录时，控制台报错 `POST http://localhost:8000/api/auth/login net::ERR_CONNECTION_REFUSED`，登录失败。
+
+### B. 产生原因
+1. 前端 `api.ts` 中 `baseURL` 硬编码为 `http://localhost:8000`
+2. 用户通过局域网 IP（如 `http://192.168.3.11:3000`）访问前端，而非 `http://localhost:3000`
+3. 浏览器运行前端代码时，将 `localhost` 解析为**用户本地机器**（而非服务器），向用户本地 8000 端口发请求
+4. 用户本地 8000 端口无服务，TCP 连接被拒绝
+5. 同时后端 CORS 配置仅允许 `http://localhost:3000`，未允许 IP 地址访问
+
+### C. 解决方案
+1. 将 `src/lib/api.ts` 的 `baseURL` 从 `http://localhost:8000` 改为服务器实际 IP `http://192.168.3.11:8000`
+2. 将 `backend/config.py` 的 `cors_origins` 从 `["http://localhost:3000"]` 扩展为 `["http://localhost:3000", "http://192.168.3.11:3000"]`
+3. 重启后端服务使 CORS 生效，重新构建前端使 baseURL 生效
+
+### D. 后续如何避免问题
+1. 部署时统一使用服务器实际 IP 替代 localhost，避免浏览器端解析歧义
+2. 前端 baseURL 应支持环境变量配置（如 `VITE_API_BASE_URL`），不同环境注入不同值
+3. 后端 CORS origins 应使用配置化列表，支持开发/测试/生产多环境
+4. 在 README 中明确说明访问地址，提醒用户必须使用服务器 IP 而非 localhost
+
+---
+
 > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。