docs: 更新文档路径引用，移除硬编码密钥，修复 Docker 配置

2026-04-22 00:43:06 +08:00
parent 38646001e6
commit a869d884b7
7 changed files with 125 additions and 90 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -106,7 +106,7 @@ VLLM_BASE_URL=http://127.0.0.1:8081/v1
 LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1

 # 远程数据库和向量存储
-DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
+DB_URI=postgresql://postgres:your_password_here@115.190.121.151:5432/langgraph_db?sslmode=disable
 QDRANT_URL=http://115.190.121.151:6333

 # 日志和调试
@@ -119,12 +119,17 @@ MEMORY_SUMMARIZE_INTERVAL=10

 **终端 1 - 后端：**
 ```bash
-python app/backend.py
+python backend/app/backend.py
 ```

 **终端 2 - 前端：**
 ```bash
-streamlit run frontend/frontend_main.py
+streamlit run frontend/src/frontend_main.py
+```
+
+或者使用启动脚本（推荐）：
+```bash
+./scripts/start.sh both
 ```

 浏览器自动打开前端页面，访问 http://127.0.0.1:8501
@@ -137,9 +142,9 @@ streamlit run frontend/frontend_main.py

 | 文件 | 用途 |
 |------|------|
-| `docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） |
-| `Dockerfile.backend` | 后端镜像构建 |
-| `Dockerfile.frontend` | 前端镜像构建 |
+| `docker/docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） |
+| `docker/backend/Dockerfile` | 后端镜像构建 |
+| `docker/frontend/Dockerfile` | 前端镜像构建 |
 | `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |

 ### docker-compose.yml 结构
@@ -173,7 +178,7 @@ docker compose up -d frontend

 ### 添加新工具

-在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加：
+在 [backend/app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/graph/graph_tools.py) 中添加：

 ```python
@tool
@@ -195,7 +200,7 @@ def my_new_tool(param: str) -> str:

 ### 添加新模型

-在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中：
+在 [backend/app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/backend/app/agent/llm_factory.py) 中：

 ```python
@staticmethod
--- a/README.md
+++ b/README.md
@@ -169,47 +169,61 @@ stateDiagram-v2

 ```
 Agent1/
-├── app/
+├── backend/
+│   ├── app/
+│   │   ├── __init__.py
+│   │   ├── config.py              # 配置管理
+│   │   ├── logger.py              # 日志工具
+│   │   ├── backend.py             # FastAPI 后端应用
+│   │   ├── agent/
+│   │   │   ├── __init__.py
+│   │   │   ├── service.py         # Agent 服务核心
+│   │   │   ├── llm_factory.py     # LLM 工厂
+│   │   │   ├── history.py         # 历史查询服务
+│   │   │   ├── prompts.py         # 提示模板
+│   │   │   └── rag_initializer.py # RAG 工具初始化
+│   │   ├── graph/
+│   │   │   ├── __init__.py
+│   │   │   ├── graph_builder.py   # LangGraph 图构建器
+│   │   │   ├── graph_tools.py     # 工具定义
+│   │   │   ├── state.py           # 状态定义
+│   │   │   └── retrieve_memory.py # 记忆检索
+│   │   ├── nodes/
+│   │   │   ├── __init__.py
+│   │   │   ├── router.py          # 路由决策
+│   │   │   ├── llm_call.py        # LLM 调用节点
+│   │   │   ├── tool_call.py       # 工具执行节点
+│   │   │   ├── retrieve_memory.py # 记忆检索节点
+│   │   │   ├── summarize.py       # 记忆存储节点
+│   │   │   ├── finalize.py        # 最终处理节点
+│   │   │   └── memory_trigger.py  # 记忆触发节点
+│   │   ├── memory/
+│   │   │   ├── __init__.py
+│   │   │   └── mem0_client.py     # Mem0 客户端封装
+│   │   ├── rag/
+│   │   │   ├── __init__.py
+│   │   │   ├── retriever.py       # 检索器
+│   │   │   ├── reranker.py        # 重排序
+│   │   │   ├── query_transform.py # 查询转换
+│   │   │   ├── pipeline.py        # RAG 流水线
+│   │   │   ├── fusion.py          # RAG-Fusion
+│   │   │   └── tools.py           # RAG 工具
+│   │   └── utils/
+│   │       └── __init__.py
+│   └── rag_core/
 │       ├── __init__.py
-│   ├── config.py              # 配置管理
-│   ├── logger.py              # 日志工具
-│   ├── backend.py             # FastAPI 后端应用
-│   ├── agent/
-│   │   ├── __init__.py
-│   │   ├── service.py         # Agent 服务核心
-│   │   ├── llm_factory.py     # LLM 工厂
-│   │   ├── history.py         # 历史查询服务
-│   │   ├── prompts.py         # 提示模板
-│   │   └── rag_initializer.py # RAG 工具初始化
-│   ├── graph/
-│   │   ├── __init__.py
-│   │   ├── graph_builder.py   # LangGraph 图构建器
-│   │   ├── graph_tools.py     # 工具定义
-│   │   ├── state.py           # 状态定义
-│   │   └── retrieve_memory.py # 记忆检索
-│   ├── nodes/
-│   │   ├── __init__.py
-│   │   ├── router.py          # 路由决策
-│   │   ├── llm_call.py        # LLM 调用节点
-│   │   ├── tool_call.py       # 工具执行节点
-│   │   ├── retrieve_memory.py # 记忆检索节点
-│   │   ├── summarize.py       # 记忆存储节点
-│   │   ├── finalize.py        # 最终处理节点
-│   │   └── memory_trigger.py  # 记忆触发节点
-│   ├── memory/
-│   │   ├── __init__.py
-│   │   └── mem0_client.py     # Mem0 客户端封装
-│   ├── rag/
-│   │   ├── __init__.py
-│   │   ├── retriever.py       # 检索器
-│   │   ├── reranker.py        # 重排序
-│   │   ├── query_transform.py # 查询转换
-│   │   ├── pipeline.py        # RAG 流水线
-│   │   ├── fusion.py          # RAG-Fusion
-│   │   └── tools.py           # RAG 工具
-│   └── utils/
-│       └── __init__.py
+│       ├── client.py              # RAG 核心客户端
+│       ├── embedders.py           # 嵌入模型
+│       ├── vector_store.py        # 向量存储
+│       ├── retriever_factory.py   # 检索器工厂
+│       └── store/
+│           ├── __init__.py
+│           ├── factory.py         # 存储工厂
+│           └── postgres.py        # PostgreSQL 存储
 ├── frontend/
+│   ├── run.py                   # 前端启动脚本
+│   ├── requirements.txt
+│   └── src/
 │       ├── __init__.py
 │       ├── frontend_main.py       # Streamlit 主入口
 │       ├── api_client.py          # API 客户端
@@ -229,22 +243,20 @@ Agent1/
 │   ├── loaders.py             # 文档加载器
 │   ├── splitters.py           # 文本切分器
 │   └── test/                  # 测试脚本
-├── rag_core/
-│   ├── __init__.py
-│   ├── client.py              # RAG 核心客户端
-│   ├── embedders.py           # 嵌入模型
-│   ├── vector_store.py        # 向量存储
-│   ├── retriever_factory.py   # 检索器工厂
-│   └── store/
-│       ├── __init__.py
-│       ├── factory.py         # 存储工厂
-│       └── postgres.py        # PostgreSQL 存储
 ├── docker/
 │   ├── docker-compose.yml     # Docker 服务编排
-│   ├── Dockerfile.backend     # 后端镜像构建
-│   └── Dockerfile.frontend    # 前端镜像构建
+│   ├── backend/
+│   │   └── Dockerfile         # 后端镜像构建
+│   ├── frontend/
+│   │   └── Dockerfile         # 前端镜像构建
+│   └── models/                # spaCy 模型文件
 ├── scripts/
 │   └── start.sh               # 启动脚本
+├── test/                      # 测试目录
+│   ├── test_backend.py
+│   ├── test_rag.py
+│   ├── test_dqrant.py
+│   └── test_rag_indexer_result.py
 ├── .gitea/
 │   └── workflows/
 │       └── deploy.yml         # CI/CD 自动化部署
@@ -584,7 +596,7 @@ RAG 系统分为两个独立但协同的阶段：
 │  └────────────────────────────────────────────────────────┘     │
 │                              │                                    │
 │                              ▼                                    │
-│  阶段二：在线检索生成 (app/rag)                                   │
+│  阶段二：在线检索生成 (backend/app/rag)                                   │
 │  ┌────────────────────────────────────────────────────────┐     │
 │  │  用户查询 → 查询改写 → 多路检索 → RRF 融合 → 重排序      │     │
 │  │              MultiQuery    Dense+Sparse    Cross-Encoder     │     │
@@ -803,10 +815,13 @@ cp .env.docker .env
 # 编辑 .env，根据本地/远程环境调整配置

 # 3. 启动后端
-python app/backend.py
+python backend/app/backend.py

 # 4. 启动前端（新终端）
-streamlit run frontend/frontend_main.py
+streamlit run frontend/src/frontend_main.py
+
+# 或者使用启动脚本（推荐）
+./scripts/start.sh both
 ```

 ---
@@ -851,7 +866,7 @@ streamlit run frontend/frontend_main.py

 ### 添加新工具

-在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加新的 `@tool` 装饰函数：
+在 [backend/app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/graph/graph_tools.py) 中添加新的 `@tool` 装饰函数：

 ```python
@tool
@@ -873,7 +888,7 @@ def my_new_tool(param: str) -> str:

 ### 添加新模型

-在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中添加模型创建方法：
+在 [backend/app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/backend/app/agent/llm_factory.py) 中添加模型创建方法：

 ```python
@staticmethod
@@ -1096,7 +1111,7 @@ curl -X POST http://localhost:6333/collections/my_docs/actions \
 #### 3.1 添加自定义工具

 ```python
-# 在 app/graph/graph_tools.py 中添加
+# 在 backend/app/graph/graph_tools.py 中添加

 from langchain_core.tools import tool
 from typing import Optional
@@ -1154,7 +1169,7 @@ def calculate_expression(
 #### 3.2 添加自定义 LLM 提供商

 ```python
-# 在 app/agent/llm_factory.py 中添加
+# 在 backend/app/agent/llm_factory.py 中添加

 from langchain_openai import ChatOpenAI
 from langchain_core.language_models import BaseChatModel
@@ -1186,7 +1201,7 @@ class LLMFactory:
 #### 3.3 添加自定义 RAG 检索器

 ```python
-# 在 app/rag/retriever.py 中添加
+# 在 backend/app/rag/retriever.py 中添加

 from langchain_core.retrievers import BaseRetriever
 from langchain_core.documents import Document
--- a/backend/app/rag/reranker.py
+++ b/backend/app/rag/reranker.py
@@ -20,7 +20,7 @@ class LLaMaCPPReranker:
        Args:
            base_url: llama.cpp 服务的地址和端口，默认为环境变量 LLAMACPP_RERANKER_URL 或 "http://127.0.0.1:8083"。
            top_n: 返回前 N 个结果。
-            api_key: API 密钥，默认为环境变量 LLAMACPP_API_KEY 或 "huang1998"。
+            api_key: API 密钥，默认为环境变量 LLAMACPP_API_KEY 。
            timeout: 请求超时时间（秒）。
        """
        self.base_url = base_url 
--- a/docker/backend/Dockerfile
+++ b/docker/backend/Dockerfile
@@ -86,4 +86,4 @@ EXPOSE 8079
 # =============================================================================
 # 启动命令
 # =============================================================================
-CMD ["python", "app/backend.py"]
+CMD ["python", "-m", "app.backend"]
--- a/docker/frontend/Dockerfile
+++ b/docker/frontend/Dockerfile
@@ -18,4 +18,4 @@ COPY frontend/src/ ./src/
 EXPOSE 8501

 # 启动命令
-CMD ["streamlit", "run", "src/frontend_main.py", "--server.port", "8501", "--server.address", "0.0.0.0", "--server.baseUrlPath", "/ai"]
+CMD ["streamlit", "run", "src.frontend_main", "--server.port", "8501", "--server.address", "0.0.0.0", "--server.baseUrlPath", "/ai"]
--- a/rag_indexer/clear_qdrant.py
+++ b/rag_indexer/clear_qdrant.py
@@ -13,9 +13,20 @@ import argparse
 from dotenv import load_dotenv
 load_dotenv()

-QDRANT_URL = os.getenv("QDRANT_URL", "http://127.0.0.1:6333")
+QDRANT_URL = os.getenv("QDRANT_URL")
 QDRANT_API_KEY = os.getenv("QDRANT_API_KEY")
-DB_URI = os.getenv("DB_URI", "postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable")
+
+# PostgreSQL 配置（使用分离配置，优先于 DB_URI）
+DB_HOST = os.getenv("DB_HOST")
+DB_PORT = os.getenv("DB_PORT", "5432")
+DB_USER = os.getenv("DB_USER")
+DB_PASSWORD = os.getenv("DB_PASSWORD")
+DB_NAME = os.getenv("DB_NAME")
+
+# 构建 DB_URI（如果没有直接配置）
+DB_URI = os.getenv("DB_URI")
+if not DB_URI and all([DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME]):
+    DB_URI = f"postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?sslmode=disable"
 COLLECTION_NAME = "rag_documents"
 TABLE_NAME = "parent_documents"

--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -145,14 +145,18 @@ check_config() {
    echo ""
    echo "🌐 检查远程服务连接..."
    
-    # 测试 PostgreSQL 连接
+    # 测试 PostgreSQL 连接（从环境变量读取密码）
    if command -v psql &> /dev/null; then
-        if PGPASSWORD=huang1998 psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT 1;" &> /dev/null; then
+        if [ -n "$DB_PASSWORD" ]; then
+            if PGPASSWORD="$DB_PASSWORD" psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT 1;" &> /dev/null; then
                check_pass "PostgreSQL 远程连接正常 (115.190.121.151:5432)"
            else
                check_fail "PostgreSQL 远程连接失败"
                echo "   提示: 检查网络连接和防火墙设置"
            fi
+        else
+            check_warn "DB_PASSWORD 未配置，跳过 PostgreSQL 连接测试"
+        fi
    else
        check_warn "psql 客户端未安装，跳过 PostgreSQL 连接测试"
    fi
@@ -267,7 +271,7 @@ start_embedding() {
        -e LLAMA_ARG_N_PARALLEL=1 \
        -e LLAMA_ARG_BATCH=512 \
        -e LLAMA_ARG_N_GPU_LAYERS=99 \
-        -e LLAMA_ARG_API_KEY=huang1998 \
+        -e LLAMA_ARG_API_KEY="$LLAMACPP_API_KEY" \
        ghcr.io/ggml-org/llama.cpp:server-rocm \
        -m /models/Qwen3-Embedding-0.6B-Q8_0.gguf \
        --host 0.0.0.0 \