Files

构建并部署 AI Agent 服务 / deploy (push) Failing after 1s

Details

```

docs(.gitignore/README/QUICKSTART): 更新文档和忽略配置

- 添加IDE配置、日志和数据文件到.gitignore
- 重构QUICKSTART.md，提供Docker Compose和本地开发两种部署方式
- 更新README.md，优化项目介绍和架构说明
- 移除旧的agent.py和backend.py文件
```

2026-04-13 23:57:16 +08:00

6.6 KiB

Raw Blame History

快速开始指南

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

🚀 快速启动（3 步）

方式一：Docker Compose（推荐 ⭐）

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

1. 配置环境变量

cat > .env << EOF
ZHIPUAI_API_KEY=your_zhipuai_api_key_here
VLLM_LOCAL_KEY=token-abc123
EOF

2. 启动服务

docker compose up -d --build

3. 访问应用

前端: http://localhost:8501
后端 API: http://localhost:8001

常用命令

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 重启特定服务
docker compose restart backend

# 停止所有服务
docker compose down

方式二：本地开发模式

适合开发和调试。

前置要求

Python 3.10+
Docker（用于 PostgreSQL）

1. 启动 PostgreSQL

docker run -d \
  --name postgres-langgraph \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=langgraph_db \
  -p 5432:5432 \
  -v ~/docker_volumes/postgres_data:/var/lib/postgresql/data \
  postgres:16

2. 安装依赖

pip install -r requirement.txt

3. 配置环境变量

编辑 .env 文件：

ZHIPUAI_API_KEY=your_api_key_here

4. 启动服务

终端 1 - 后端：

python backend.py

终端 2 - 前端：

streamlit run frontend.py

浏览器自动打开 http://localhost:8501

🐳 Docker 部署详解

文件说明

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

docker-compose.yml 结构

services:
  postgres:     # PostgreSQL 数据库
  backend:      # FastAPI 后端服务
  frontend:     # Streamlit 前端界面

特性：

✅ PostgreSQL 健康检查，确保数据库就绪后才启动后端
✅ 数据持久化到 Docker volume
✅ 自动重启策略（restart: unless-stopped）
✅ 内部网络隔离，外部无法直接访问数据库

只更新特定服务

# 只重新构建后端（不影响数据库）
docker compose up -d --build backend

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

数据持久化

PostgreSQL 数据存储在命名 volume pg_data 中：

# 查看 volume
docker volume ls | grep pg_data

# 备份数据
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar czf /backup/pg_backup.tar.gz /data

# 恢复数据
docker run --rm -v pg_data:/data -v $(pwd):/backup alpine tar xzf /backup/pg_backup.tar.gz -C /

🔧 开发指南

添加新工具

在 tools.py 中添加：

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

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

添加新模型

在 agent.py 中：

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.py 中添加选项：

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

调试技巧

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

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

# 检查数据库连接
docker compose exec postgres psql -U postgres -d langgraph_db -c "\dt"

# 测试后端 API
curl http://localhost:8001/

🔄 CI/CD 自动化部署

Gitea Workflows

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

触发条件：

推送到 main 或 master 分支
手动触发（workflow_dispatch）

部署流程：

检出代码
安装 Python 依赖（验证用）
准备环境变量
重新构建并启动前后端（不影响数据库）
健康检查（等待后端就绪）
清理无用 Docker 资源

配置 Secrets：

在 Gitea 仓库设置中添加：

ZHIPUAI_API_KEY
VLLM_LOCAL_KEY

🐛 故障排查

常见问题

1. PostgreSQL 连接失败

# 检查容器状态
docker compose ps postgres

# 查看日志
docker compose logs postgres

# 测试连接
docker compose exec postgres pg_isready -U postgres

解决方案：

确认容器正在运行
检查密码是否正确
等待健康检查通过（约 10-30 秒）

2. 后端启动失败

# 查看详细日志
docker compose logs backend

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

常见原因：

API Key 未配置或错误
端口 8001 被占用
依赖包缺失

3. 前端无法连接后端

# 检查后端是否正常运行
curl http://localhost:8001/

# 检查网络连接
docker compose exec frontend ping backend