ailine/QUICKSTART.md

# 快速开始指南

详细的启动和部署指南，面向开发者和运维人员。

---

## 🚀 快速启动（3 步）

### 方式一：Docker Compose（推荐 ⭐）

适合生产环境，一键启动所有服务。

#### 1. 配置环境变量

```bash
# 复制 Docker 部署模板
cp .env.docker .env

# 编辑 .env 文件，填入真实的 API Key
vim .env  # 或使用你喜欢的编辑器
```

**必需配置项**：
- `ZHIPUAI_API_KEY` - 智谱 AI API 密钥（从 [智谱开放平台](https://open.bigmodel.cn/) 获取）
- `LLAMACPP_API_KEY` - llama.cpp 服务认证 Token（与容器启动参数一致，默认 `token-abc123`）

**可选配置项**：
- `VLLM_BASE_URL` - LLM 服务地址（本地默认：`http://127.0.0.1:8081/v1`，Docker容器访问宿主机：`http://host.docker.internal:18000/v1`）
- `LLAMACPP_EMBEDDING_URL` - Embedding 服务地址（本地默认：`http://127.0.0.1:8082/v1`，Docker容器访问宿主机：`http://host.docker.internal:18001/v1`）
- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用远程服务器地址）
- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置，使用远程服务器地址）

**注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。

#### 2. 启动服务

```bash
docker compose -f docker/docker-compose.yml up -d --build
```

#### 3. 访问应用

**如果配置了 Nginx 反向代理**：
- 访问地址：`http://your-domain.com` 或 `http://your-server-ip`

**如果未配置 Nginx（直接访问容器）**：
- **前端**: http://127.0.0.1:8501
- **后端 API**: http://127.0.0.1:8001

#### 常用命令

```bash
# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 重启特定服务
docker compose restart backend

# 停止所有服务
docker compose down
```

---

### 方式二：本地开发模式

适合开发和调试。

#### 前置要求

- Python 3.10+

#### 1. 安装依赖

```bash
pip install -r requirement.txt
```

#### 2. 配置环境变量

复制并编辑 `.env` 文件：

```
# 基于 Docker 模板创建
cp .env.docker .env
vim .env
```

**本地开发需要修改以下配置**：

``env
ZHIPUAI_API_KEY=your_api_key_here
LLAMACPP_API_KEY=token-abc123

# 本地开发时，llama.cpp 服务在 127.0.0.1
VLLM_BASE_URL=http://127.0.0.1:8081/v1  # 本地开发
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
# 或
VLLM_BASE_URL=http://host.docker.internal:18000/v1  # Docker容器访问宿主机
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机

# 数据库和向量存储使用远程服务器
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
QDRANT_URL=http://115.190.121.151:6333

# 本地开发时，后端也在 127.0.0.1
API_URL=http://127.0.0.1:8083/chat
```

#### 3. 启动服务

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

**终端 2 - 前端：**
```bash
cd frontend && streamlit run app.py
```

浏览器自动打开前端页面（如果配置了 Nginx，访问 `http://your-domain.com`；否则访问 http://127.0.0.1:8501）

---

## 🐳 Docker 部署详解

### 文件说明

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

### docker-compose.yml 结构

```yaml
services:
  backend:      # FastAPI 后端服务（连接远程 PostgreSQL 和 Qdrant）
  frontend:     # Streamlit 前端界面
```

**特性：**
- ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
- ✅ 自动重启策略（`restart: unless-stopped`）
- ✅ 内部网络隔离

### 只更新特定服务

```bash
# 只重新构建后端
docker compose up -d --build backend

# 只重新启动前端
docker compose up -d frontend
```

---

## 🔧 开发指南

### 添加新工具

在 `app/tools.py` 中添加：

```python
@tool
def my_new_tool(param: str) -> str:
    """
    工具描述（会显示给 LLM）
    
    Args:
        param: 参数说明
        
    Returns:
        返回值说明
    """
    # 实现逻辑
    return result
```

工具会自动注册，无需修改其他文件。

### 添加新模型

在 `app/agent.py` 中：

```python
def _create_new_model_llm(self):
    """创建新模型的 LLM"""
    return YourChatModel(
        model="model-name",
        api_key=os.getenv("YOUR_API_KEY"),
    )

# 在 initialize() 方法中注册
model_configs = {
    "zhipu": self._create_zhipu_llm,
    "local": self._create_local_llm,
    "new_model": self._create_new_model_llm,  # 新增
}
```

在前端 `frontend/app.py` 中添加选项：

```python
MODEL_OPTIONS = {
    "智谱 GLM-4": "zhipu",
    "本地 Gemma-4": "local",
    "新模型": "new_model",  # 新增
}
```

### 调试技巧

```bash
# 进入后端容器
docker compose exec backend bash

# 查看实时日志
docker compose logs -f backend

# 测试后端 API
curl http://127.0.0.1:8001/health
```

---

## 🔄 CI/CD 自动化部署

### Gitea Workflows

项目包含自动化部署配置 `.gitea/workflows/deploy.yml`。

**触发条件：**
- 推送到 `main` 或 `master` 分支
- 手动触发（workflow_dispatch）

**部署流程：**
1. 检出代码
2. 准备环境变量
3. 重新构建并启动前后端（不影响远程数据库）
4. 健康检查（等待后端就绪）
5. 清理无用 Docker 资源

**配置 Secrets：**

在 Gitea 仓库设置中添加：
- `ZHIPUAI_API_KEY`
- `LLAMACPP_API_KEY`

---

## 🐛 故障排查

### 常见问题

#### 1. 无法连接远程数据库

```bash
# 测试 PostgreSQL 连接
psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"

# 测试 Qdrant 连接
curl http://115.190.121.151:6333/collections
```

**解决方案：**
- 确认远程服务器防火墙开放了 5432 和 6333 端口
- 检查网络连接是否正常
- 验证用户名和密码是否正确

#### 2. 后端启动失败

```bash
# 查看详细日志
docker compose logs backend

# 检查端口占用
lsof -i :8001
```

**常见原因：**
- API Key 未配置或错误
- 端口 8001 被占用
- 依赖包缺失

#### 3. 前端无法连接后端

**错误信息：**
```
HTTPConnectionPool(host='backend', port=8001): Max retries exceeded
```

**解决方案：**

1. **检查容器是否在同一网络中：**
```bash
docker network inspect docker_ai-network
```

2. **验证环境变量配置：**
```bash
docker compose exec frontend env | grep API_URL
```

3. **重启服务：**
```bash
docker compose down
docker compose up -d --build
docker compose logs -f
```

#### 4. 模型初始化失败

```bash
# 查看后端启动日志
docker compose logs backend | grep -i "model\|error"
```

**可能原因：**
- 智谱 API Key 无效
- vLLM 容器未启动（如使用本地模型）
- 网络连接问题

#### 5. 环境变量未生效

**症状：**
- 服务启动时提示缺少必需的环境变量
- API Key 为空或使用默认值

**解决方案：**

1. **检查 .env 文件格式：**
```bash
cat -A .env
```

2. **验证环境变量已加载：**
```bash
docker compose exec backend env | grep ZHIPUAI_API_KEY
docker compose exec frontend env | grep API_URL
```

3. **重新构建容器：**
```bash
docker compose down
docker compose up -d --build
```

---

## 📊 监控和维护

### 查看资源使用

```bash
# Docker 容器资源使用
docker stats

# 磁盘空间
docker system df

# 清理无用资源
docker system prune -f
```

### 日志管理

```bash
# 查看所有服务日志
docker compose logs

# 查看特定服务最近 100 行日志
docker compose logs --tail=100 backend

# 实时跟踪日志
docker compose logs -f backend frontend
```

### 备份和恢复

```bash
# 备份远程数据库
pg_dump -h 115.190.121.151 -U postgres langgraph_db > backup.sql

# 恢复数据库
cat backup.sql | psql -h 115.190.121.151 -U postgres langgraph_db
```

---

## 🎯 性能优化建议

### 开发环境

- 使用 `docker compose watch` 实现热重载（需配置）
- 挂载代码目录而非复制到镜像
- 启用 Python 调试模式

### 生产环境

- 使用反向代理（Nginx）
- 启用 HTTPS
- 配置日志轮转
- 设置资源限制（CPU、内存）
- 定期备份远程数据库

---

## 📞 获取帮助

- **完整文档**: [README.md](README.md)
- **报告问题**: 提交 Issue 并附上日志

---

**祝您部署顺利！** 🎉