添加长期记忆

QUICKSTART.md

@@ -13,8 +13,8 @@
 #### 1. 配置环境变量
 
 ```bash
-# 复制模板文件
-cp .env.example .env
+# 复制 Docker 部署模板
+cp .env.docker .env
 
 # 编辑 .env 文件，填入真实的 API Key
 vim .env  # 或使用你喜欢的编辑器
@@ -25,7 +25,10 @@ vim .env  # 或使用你喜欢的编辑器
 - `VLLM_LOCAL_KEY` - 本地 vLLM 服务认证 Token（与 vLLM 容器的 `--api-key` 参数一致）
 
 **可选配置项**：
-- `DB_URI` - PostgreSQL 连接字符串（默认已配置，通常无需修改）
+- `VLLM_BASE_URL` - vLLM 服务地址（默认已配置为 FRP 穿透地址）
+- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用 Docker 服务名 `postgres`）
+
+**注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。
 
 #### 2. 启动服务
 
@@ -91,19 +94,24 @@ pip install -r requirement.txt
 
 复制并编辑 `.env` 文件：
 
-```bash
-cp .env.example .env
+```
+# 基于 Docker 模板创建，然后修改为本地配置
+cp .env.docker .env
 vim .env
 ```
 
-**本地开发需要额外配置数据库连接**：
+**本地开发需要修改以下配置**：
 
 ```env
 ZHIPUAI_API_KEY=your_api_key_here
 VLLM_LOCAL_KEY=token-abc123
 
-# 本地开发时，数据库主机改为 localhost
+# 本地开发时，vLLM 和数据库都在 localhost
+VLLM_BASE_URL=http://localhost:8000/v1
 DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable
+
+# 本地开发时，后端也在 localhost
+API_URL=http://localhost:8001/chat
 ```
 
 #### 4. 启动服务
@@ -310,20 +318,70 @@ lsof -i :8001
 - 端口 8001 被占用
 - 依赖包缺失
 
-#### 3. 前端无法连接后端
+#### 3. 前端无法连接后端（NameResolutionError）
 
-```bash
-# 检查后端是否正常运行
-curl http://localhost:8001/
-
-# 检查网络连接
-docker compose exec frontend ping backend
+**错误信息：**
+```
+HTTPConnectionPool(host='backend', port=8001): Max retries exceeded with url: /chat 
+(Caused by NameResolutionError("HTTPConnection(host='backend', port=8001): Failed to resolve 'backend'"))
 ```
 
+**原因分析：**
+- 前端容器和后端容器不在同一个 Docker 网络中
+- docker-compose.yml 中的服务名配置错误
+- 环境变量 `API_URL` 配置不正确
+
 **解决方案：**
-- 确认后端服务已启动
-- 检查防火墙设置
-- 重启前端服务
+
+1. **检查容器是否在同一网络中：**
+```bash
+# 查看所有 Docker 网络
+docker network ls
+
+# 检查 ai-network 网络中的容器
+docker network inspect docker_ai-network
+```
+
+2. **确认服务名正确：**
+```bash
+# 查看运行中的容器
+docker compose ps
+
+# 应该看到：ai-backend, ai-frontend, ai-postgres
+```
+
+3. **验证环境变量配置：**
+```bash
+# 进入前端容器检查环境变量
+docker compose exec frontend env | grep API_URL
+
+# 应该输出：API_URL=http://backend:8001/chat
+```
+
+4. **重启服务：**
+```bash
+# 完全停止并重新启动所有服务
+docker compose down
+docker compose up -d --build
+
+# 查看启动日志
+docker compose logs -f
+```
+
+5. **测试网络连通性：**
+```bash
+# 从前端容器 ping 后端服务
+docker compose exec frontend ping backend
+
+# 从前端容器访问后端 API
+docker compose exec frontend curl http://backend:8001/health
+```
+
+**重要提示：**
+- Docker Compose 会自动创建名为 `<项目目录>_ai-network` 的网络
+- 容器间通过**服务名**（而非容器名）进行通信
+- 在 `docker-compose.yml` 中，服务名是 `backend`、`frontend`、`postgres`
+- 确保所有服务都连接到同一个自定义网络（`ai-network`）
 
 #### 4. 模型初始化失败
 
@@ -337,6 +395,46 @@ docker compose logs backend | grep -i "model\|error"
 - vLLM 容器未启动（如使用本地模型）
 - 网络连接问题
 
+#### 5. 环境变量未生效
+
+**症状：**
+- 服务启动时提示缺少必需的环境变量
+- API Key 为空或使用默认值
+
+**解决方案：**
+
+1. **检查 .env 文件格式：**
+```bash
+# 确保文件末尾没有多余字符（如 EOF）
+cat -A .env
+
+# 正确格式应该是每行一个变量，无多余空格或特殊字符
+```
+
+2. **验证环境变量已加载：**
+```bash
+# 检查后端容器的环境变量
+docker compose exec backend env | grep ZHIPUAI_API_KEY
+
+# 检查前端容器的环境变量
+docker compose exec frontend env | grep API_URL
+```
+
+3. **重新构建容器：**
+```bash
+# 修改 .env 后需要重新创建容器
+docker compose down
+docker compose up -d --build
+```
+
+4. **确认 .env 文件位置：**
+```bash
+# .env 文件应该在项目根目录（与 docker-compose.yml 的父目录同级）
+ls -la .env
+
+# docker-compose.yml 中使用了 context: .. ，所以 .env 应该在上一级目录
+```
+
 ---
 
 ## 📊 监控和维护