first commit

AIEC-server/docs/service-not-running-fix.md

@@ -0,0 +1,148 @@
+# Graph-RAG-Agent 服务未运行问题解决方案
+
+## 问题描述
+
+错误信息：
+```
+连接错误: HTTPConnectionPool(host='localhost', port=8000): Max retries exceeded with url: /chat/stream 
+(Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x000001DD24E19F60>: 
+Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝，无法连接。'))
+```
+
+这表明 graph-rag-agent 服务没有在 8000 端口运行。
+
+## 解决步骤
+
+### 1. 首先恢复 CORS 支持
+
+由于你恢复了原始文件，需要重新添加 CORS 支持：
+
+```bash
+cd ~/graph-rag-agent/server
+cp main.py.cors_backup main.py
+```
+
+或者手动编辑 main.py，在导入部分添加：
+```python
+from fastapi.middleware.cors import CORSMiddleware
+```
+
+在 `app = FastAPI(...)` 之后添加：
+```python
+# 配置 CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # 允许所有源
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### 2. 检查依赖是否安装
+
+```bash
+cd ~/graph-rag-agent
+pip install -r requirements.txt
+```
+
+### 3. 检查 Neo4j 是否运行
+
+```bash
+# Windows PowerShell
+netstat -an | findstr 7687
+
+# 或在 WSL/Linux 中
+sudo lsof -i :7687
+```
+
+### 4. 启动 graph-rag-agent 服务
+
+在 Windows 中：
+```bash
+cd C:\path\to\graph-rag-agent
+python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+在 WSL/Linux 中：
+```bash
+cd ~/graph-rag-agent
+python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 5. 常见启动问题
+
+#### 问题 1：ModuleNotFoundError
+```
+ModuleNotFoundError: No module named 'xxx'
+```
+解决：安装缺失的模块
+```bash
+pip install xxx
+```
+
+#### 问题 2：Neo4j 连接失败
+```
+neo4j.exceptions.ServiceUnavailable: Unable to connect to localhost:7687
+```
+解决：
+1. 启动 Neo4j 服务
+2. 检查 config/settings.py 中的 Neo4j 配置
+
+#### 问题 3：端口被占用
+```
+[Errno 48] Address already in use
+```
+解决：
+1. 查找占用端口的进程：
+   ```bash
+   # Windows
+   netstat -ano | findstr :8000
+   
+   # Linux/Mac
+   lsof -i :8000
+   ```
+2. 终止进程或使用其他端口
+
+### 6. 验证服务是否启动
+
+1. 在浏览器访问：
+   ```
+   http://localhost:8000/docs
+   ```
+   应该看到 FastAPI 的 API 文档页面
+
+2. 使用 curl 测试：
+   ```bash
+   curl http://localhost:8000/
+   ```
+
+3. 测试 CORS：
+   ```bash
+   curl -I -X OPTIONS http://localhost:8000/chat \
+     -H "Origin: http://localhost:3000" \
+     -H "Access-Control-Request-Method: POST"
+   ```
+
+### 7. 完整启动流程
+
+1. **启动 Neo4j**（如果需要）
+2. **恢复 CORS 配置**
+3. **启动 graph-rag-agent**：
+   ```bash
+   cd ~/graph-rag-agent
+   python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+4. **启动前端**（在另一个终端）：
+   ```bash
+   cd ~/yundage-backserver-test
+   python -m http.server 3000
+   ```
+5. **访问前端**：http://localhost:3000
+
+## 调试建议
+
+1. 查看 graph-rag-agent 的启动日志，看是否有错误
+2. 确保所有依赖都已正确安装
+3. 检查防火墙设置是否阻止了 8000 端口
+4. 如果在 WSL 中运行，确保 Windows 防火墙允许 WSL 访问