当前位置：首页 > news >正文

3台2核4G服务器搭建高可用AI Agent生产集群：从Demo到部署实战

news 2026/8/9 2:11:10

1. 项目概述：从概念验证到生产落地

最近和不少技术团队交流，发现一个挺普遍的现象：大家玩转各种AI Agent框架（比如LangChain、AutoGen、CrewAI）做Demo时热情高涨，但一到“怎么把它真正部署上线，让业务部门能用起来”这个环节，就卡壳了。Demo在本地笔记本上跑得欢，一旦要搬到服务器，面对并发请求、服务稳定性、资源调度这些生产环境的问题，很多方案就显得力不从心了。这背后反映的，其实是从“玩具”到“工具”的鸿沟。

今天要聊的，就是一个务实的、能落地的解决方案：如何用3台最基础的2核4G云服务器，搭建一个能扛住初期生产流量、具备扩展能力的企业级AI Agent服务集群。这个配置不是拍脑袋想的，而是基于大量中小型团队在PoC（概念验证）转向MVP（最小可行产品）阶段的真实资源预算和需求提炼出来的。2C4G是各大云厂商的入门级计算型实例，成本可控，性能上足以支撑多个轻量级Agent服务容器化部署。三台服务器则构成了最小可用集群的基石，一台出问题，服务不至于全挂。

这套方案的核心目标很明确：低成本、高可用、易运维。我们不追求大而全的复杂架构，而是聚焦于如何用最小的资源代价，实现服务不中断、请求不丢失、性能可监控这几个生产级的基本要求。你会看到，这里面没有用到特别昂贵的商业中间件，所有的组件都是开源且久经考验的，像Docker、Nginx、Redis、PostgreSQL，它们组合在一起，就能形成一个坚固的底座。

2. 架构设计与核心思路拆解

2.1 为什么是“3台服务器”的集群模式？

很多朋友的第一反应可能是：我一个Agent应用，用一台好点的服务器不就行了吗？为什么要三台？这里的关键在于对“生产环境”的理解。单点部署的风险极高，无论是服务器硬件故障、网络抖动，还是操作系统级的问题，都可能导致服务彻底不可用。对于企业应用，尤其是开始承载内部工作流或对外提供API的Agent服务，这种不可用是无法接受的。

采用三台服务器组成集群，主要基于以下几个考量：

高可用与故障隔离：这是最核心的原因。我们可以将服务无状态化部署在多台服务器上，通过负载均衡对外提供服务。当其中一台服务器宕机时，流量可以自动切换到其他健康的节点，用户几乎无感知。三台是构成一个简单集群的最小数量，它允许一台机器故障时，系统仍有足够的冗余继续运行，同时成本相对两台不会有数量级增长。
资源隔离与弹性伸缩：AI Agent服务通常包含多个组件，例如：接收HTTP请求的Web API服务、执行具体Agent逻辑的工作进程、用于存储对话历史和状态的数据库、用于任务队列和缓存的中间件。将这些组件混合部署在一台机器上，容易出现资源争抢（比如CPU密集的推理任务影响了API响应）。通过三台服务器，我们可以更合理地进行规划部署。
蓝绿部署与无损升级：集群模式为平滑升级提供了可能。我们可以先在一台服务器上部署新版本服务并完成测试，然后通过负载均衡逐步将流量切到新版本，出现问题可以快速回切，实现业务零中断的更新。

2.2 组件选型与职责划分

在三台服务器（我们命名为 Node-1, Node-2, Node-3）上，我们需要部署一套完整的服务栈。以下是基于开源、轻量、高效原则的选型及规划：

Node-1：作为接入与调度层
- Nginx：充当反向代理和负载均衡器。所有外部请求首先到达这里，由Nginx根据策略（如轮询、最小连接数）分发到后端的Agent API服务实例。同时，Nginx还可以处理静态文件、SSL/TLS终止、限流等，减轻后端压力。
- Keepalived（可选但推荐）：为Nginx服务提供虚拟IP（VIP）高可用。如果主Nginx节点（Node-1）宕机，Keepalived会自动将VIP漂移到备机（例如在Node-2上也部署一个Nginx备机），确保入口层的高可用。
- 监控代理：如Prometheus Node Exporter，用于收集该节点的系统指标（CPU、内存、磁盘、网络）。
Node-2 & Node-3：作为应用与数据层
- Docker & Docker Compose：所有核心服务均容器化部署。这保证了环境一致性，简化了部署和迁移流程。每台节点上都会运行一套相同的Agent服务容器。
- Agent API 服务：这是你的核心业务代码，例如基于FastAPI或Flask构建的Web服务，暴露/chat、/task等端点。它在两台节点上以多个副本（Replica）形式运行，实现水平扩展和负载均衡。
- Redis：部署为单实例或主从模式（生产环境建议至少主从）。承担两大关键角色：
  1. 缓存：缓存频繁访问的提示词模板、模型输出结果、会话上下文（如果较短），大幅降低对数据库的重复查询压力。
  2. 消息队列/任务队列：使用Redis的List或Stream数据结构，或者配合RQ、Celery（使用Redis作为Broker）实现异步任务队列。Agent的耗时任务（如长文本总结、文档处理）可以丢到队列，由后台工作进程异步处理，避免阻塞HTTP请求。
- PostgreSQL：作为主数据库，存储结构化的持久化数据，例如用户信息、对话会话元数据、任务日志、知识库索引关联信息等。在初期，可以在Node-2上运行PostgreSQL主库，在Node-3上运行一个只读从库，实现读写分离和基础的数据高可用。
- 向量数据库：如果你的Agent涉及RAG（检索增强生成），则需要一个向量数据库来存储和检索嵌入向量。Chroma或Qdrant是轻量且性能不错的选择。考虑到资源，可以将其与Agent API服务共存在Node-2和Node-3上，或者选择云端的向量数据库服务。
- 后台工作进程：执行从Redis队列中取出的异步任务，例如调用大语言模型API、处理文件、更新向量数据库等。

注意：这里没有将Redis和PostgreSQL部署在独立的服务器上，是基于2C4G资源限制和初期成本的权衡。在资源允许后，应将它们迁移到独立、配置更高的专用实例上，这是架构演进的关键一步。

2.3 网络与数据流设计

整个系统的数据流是这样的：

用户请求到达https://agent.your-company.com（DNS解析到Nginx的VIP或公网IP）。
Nginx（在Node-1）根据负载均衡策略，将请求转发到 Node-2 或 Node-3 上的某个Agent API服务容器（例如http://node-2:8000）。
Agent API服务接收到请求：
- 首先可能查询Redis缓存获取会话上下文。
- 如果需要持久化数据，向PostgreSQL（主库在Node-2）发起查询或写入。
- 如果需要检索知识，向同节点或邻节点的向量数据库发起查询。
- 如果任务是同步的轻量操作，直接调用LLM API并返回结果。
- 如果任务是耗时的，则将任务信息（如任务ID、参数）推入Redis队列，并立即返回一个“任务已接收”的响应和任务ID。后台工作进程会监听该队列，取出任务执行，并将结果写入Redis或PostgreSQL，客户端可以通过另一个端点轮询任务结果。
响应结果经由Agent API服务返回给Nginx，再最终返回给用户。

3. 核心细节解析与实操要点

3.1 云服务器规格与系统配置要点

选择2核4G的云服务器时，不能只看规格名称，细节决定稳定性。

CPU与内存：确保是“计算优化型”或“通用型”实例。对于AI Agent，CPU的单核性能很重要，因为很多Python库和模型推理是单线程或有限并发的。4G内存是底线，需要精细规划：操作系统预留500MB，Docker引擎预留200-300MB，每个运行中的容器（Python应用）可能占用300-800MB不等。三台机器需要统一规格，避免因性能差异导致负载不均。
系统盘与数据盘：务必为数据盘选择SSD云盘。数据库（PostgreSQL）、向量数据库（Chroma/Qdrant）和Redis的持久化都是IO密集型操作，机械硬盘或普通云盘会成为巨大瓶颈。系统盘可以用较低配置的SSD，但数据盘必须高性能SSD，容量建议50GB起步，根据知识库大小预估。
网络与安全组：
- 将三台服务器放在同一个私有网络（VPC）内，它们之间通过内网IP通信，速度更快且免流量费。
- 配置安全组时，遵循最小权限原则。仅对公网开放Nginx节点的80/443端口。内网安全组需开放：节点间用于Docker Swarm或服务发现（如Consul）的端口（如2377, 7946, 4789）、数据库端口（PostgreSQL的5432， Redis的6379）、监控端口（如9100 for Node Exporter）。
- 为Nginx节点申请一个弹性公网IP（EIP），并绑定到实例上，用于对外服务。
操作系统与基础环境：
- 统一使用一个稳定的Linux发行版，如Ubuntu 22.04 LTS或CentOS 7.9（考虑到其生命周期，更推荐Ubuntu）。
- 第一件事：更新系统，并设置时区为Asia/Shanghai，确保日志时间准确。
- 修改/etc/ssh/sshd_config，禁用密码登录，使用SSH密钥对认证，并更改默认的22端口，这是服务器安全的基本防线。

3.2 容器化部署：Docker与Docker Compose实战

容器化是保证环境一致性和简化部署的核心。我们使用Docker Compose来定义和管理多容器应用。

目录结构规划：在每台应用节点（Node-2, Node-3）上，建议建立清晰的目录。

/opt/agentx/ ├── docker-compose.yml # 主编排文件 ├── .env # 环境变量文件（需加入.gitignore） ├── api/ # Agent API服务代码目录 │ ├── Dockerfile │ ├── requirements.txt │ └── src/ # 你的源代码 ├── configs/ # 各服务的配置文件 │ ├── nginx/ # （主要在Node-1） │ ├── postgresql/ │ └── redis/ ├── data/ # 数据持久化目录 │ ├── postgres_data/ # PostgreSQL数据 │ ├── redis_data/ # Redis数据 │ └── chroma_data/ # 向量数据库数据 └── logs/ # 应用日志目录

编写Dockerfile：以Agent API服务为例，一个高效的Dockerfile能减少镜像体积，加速构建。

# api/Dockerfile FROM python:3.11-slim as builder WORKDIR /app COPY requirements.txt . # 使用国内镜像源加速，并安装构建依赖 RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \ pip install --no-cache-dir --user -r requirements.txt FROM python:3.11-slim WORKDIR /app # 从构建阶段拷贝已安装的包 COPY --from=builder /root/.local /root/.local COPY ./src . # 确保pip安装的包在PATH中 ENV PATH=/root/.local/bin:$PATH # 设置Python缓冲，让日志立即输出，方便在容器内调试 ENV PYTHONUNBUFFERED=1 # 以非root用户运行，增强安全性 RUN useradd -m -u 1000 agentuser && chown -R agentuser:agentuser /app USER agentuser CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

实操心得：使用多阶段构建（as builder）可以显著减少最终镜像大小。python:3.11-slim比完整版镜像小很多。PYTHONUNBUFFERED=1对于在Docker中查看实时日志至关重要。使用非root用户运行容器是生产环境的安全最佳实践。

编写docker-compose.yml：这是编排的核心。我们以Node-2上的编排文件为例（Node-3类似）。

# docker-compose.yml version: '3.8' services: agent-api: build: ./api container_name: agent-api restart: unless-stopped # 确保容器异常退出时自动重启 ports: - "8000:8000" # 映射主机端口，供Nginx或内部访问 volumes: - ./logs/api:/app/logs # 挂载日志目录，方便查看和收集 # - ./api/src:/app/src # 开发时可挂载源代码，生产环境不建议 env_file: - .env # 引入环境变量文件 depends_on: - redis - postgres networks: - agent-network # 资源限制，防止单个容器耗尽主机资源 deploy: resources: limits: cpus: '1.0' # 限制最多使用1个CPU核心 memory: 1G # 限制最多使用1G内存 reservations: cpus: '0.5' memory: 512M redis: image: redis:7-alpine # Alpine版本镜像更小 container_name: redis restart: unless-stopped command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD} # 启用持久化并设置密码 ports: - "6379:6379" volumes: - ./data/redis_data:/data - ./configs/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro networks: - agent-network deploy: resources: limits: memory: 512M postgres: image: postgres:15-alpine container_name: postgres restart: unless-stopped environment: POSTGRES_DB: ${PG_DATABASE} POSTGRES_USER: ${PG_USER} POSTGRES_PASSWORD: ${PG_PASSWORD} ports: - "5432:5432" volumes: - ./data/postgres_data:/var/lib/postgresql/data - ./configs/postgresql/postgresql.conf:/etc/postgresql/postgresql.conf:ro networks: - agent-network deploy: resources: limits: memory: 1G # 向量数据库服务示例 (Chroma) chroma: image: chromadb/chroma:latest container_name: chroma restart: unless-stopped environment: - IS_PERSISTENT=TRUE - PERSIST_DIRECTORY=/chroma_data ports: - "8001:8000" # Chroma默认端口8000 volumes: - ./data/chroma_data:/chroma_data networks: - agent-network # 后台工作进程 worker: build: ./api # 可以和api共用Dockerfile，但启动命令不同 container_name: agent-worker restart: unless-stopped command: python -m celery -A tasks worker --loglevel=info # 假设使用Celery volumes: - ./logs/worker:/app/logs env_file: - .env depends_on: - redis networks: - agent-network deploy: resources: limits: cpus: '0.8' memory: 512M networks: agent-network: driver: bridge name: agentx-network # 指定网络名，方便跨主机容器通信（如果未来用Swarm）

环境变量文件 (.env)：敏感信息和配置项通过环境变量管理，切勿写入代码。

# .env # PostgreSQL PG_DATABASE=agentx_prod PG_USER=agentx_user PG_PASSWORD=你的强密码 # Redis REDIS_PASSWORD=你的强密码 REDIS_HOST=redis REDIS_PORT=6379 # LLM API Keys (e.g., OpenAI, 国内大模型) OPENAI_API_KEY=sk-... DASHSCOPE_API_KEY=sk-... # Agent 配置 AGENT_MAX_TOKENS=2000 AGENT_TEMPERATURE=0.7

3.3 Nginx配置与负载均衡策略

Node-1上的Nginx是整个集群的流量入口，其配置至关重要。

基础配置：首先安装Nginx，并创建一个专门的站点配置。

# 在Node-1上操作 sudo apt update && sudo apt install nginx -y sudo systemctl enable nginx

负载均衡配置：编辑/etc/nginx/sites-available/agentx。

upstream agent_backend { # 配置后端服务器池，使用内网IP server 10.0.1.12:8000 max_fails=3 fail_timeout=30s; # Node-2 内网IP server 10.0.1.13:8000 max_fails=3 fail_timeout=30s; # Node-3 内网IP # 可配置负载均衡策略，如 least_conn; (默认是轮询 round-robin) } server { listen 80; server_name agent.your-company.com; # 你的域名 # 强烈建议在生产环境使用HTTPS，这里仅展示HTTP配置 # listen 443 ssl; # ssl_certificate /path/to/cert.pem; # ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://agent_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 超时设置，根据Agent处理时间调整 proxy_connect_timeout 60s; proxy_send_timeout 300s; # 长任务可能需要更长时间 proxy_read_timeout 300s; client_max_body_size 20M; # 允许上传文件 } # 健康检查端点 location /health { proxy_pass http://agent_backend/health; # 假设你的Agent服务有/health端点 access_log off; } # 静态文件服务（如果有） location /static/ { alias /path/to/your/static/files/; expires 1d; } }

创建软链接并测试配置：

sudo ln -s /etc/nginx/sites-available/agentx /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置语法 sudo systemctl reload nginx # 重载配置

使用Keepalived实现Nginx高可用（进阶）：为了避免Node-1成为单点，可以在Node-2上也安装Nginx作为备用，并使用Keepalived管理一个虚拟IP（VIP）。当主Nginx故障时，VIP会自动漂移到备用节点。配置略复杂，但能极大提升入口层可靠性。

4. 实操过程与核心环节实现

4.1 初始化三台服务器与基础环境

假设你已经购买了三台2C4G的云服务器，内网IP分别为：10.0.1.11(Node-1),10.0.1.12(Node-2),10.0.1.13(Node-3)。

系统初始化（三台均需执行）：

# 1. 更新系统 sudo apt update && sudo apt upgrade -y # 2. 设置时区 sudo timedatectl set-timezone Asia/Shanghai # 3. 安装必要工具 sudo apt install -y curl wget vim git htop net-tools # 4. 创建部署用户（非root） sudo adduser deploy sudo usermod -aG sudo deploy # 赋予sudo权限 # 切换到deploy用户，后续操作建议在此用户下进行 su - deploy

在Node-2和Node-3上安装Docker和Docker Compose：

# 安装Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 将当前用户加入docker组 newgrp docker # 刷新组权限，或退出重新登录 # 安装Docker Compose Plugin (Docker Compose V2) sudo apt install -y docker-compose-plugin # 验证安装 docker --version docker compose version

在Node-1上安装并配置Nginx（如前文所述）。

4.2 部署应用服务到Node-2和Node-3

我们将应用代码和配置推送到Node-2和Node-3。可以使用Git、rsync或通过CI/CD工具。

传输项目文件：以rsync为例，从本地开发机同步到服务器。

# 在本地开发机执行 rsync -avz --exclude='.git' --exclude='.env' ./agentx-project/ deploy@10.0.1.12:/opt/agentx/ rsync -avz --exclude='.git' --exclude='.env' ./agentx-project/ deploy@10.0.1.13:/opt/agentx/ # 注意：.env文件包含密码，需要手动安全地拷贝过去，或使用配置管理工具。

在Node-2和Node-3上启动服务：

# 登录到Node-2 ssh deploy@10.0.1.12 cd /opt/agentx # 创建并编辑.env文件（从安全的地方复制过来） vim .env # 粘贴你的环境变量并保存 # 启动所有服务 docker compose up -d # 查看服务状态和日志 docker compose ps docker compose logs -f agent-api # 跟踪API服务日志

在Node-3上重复完全相同的步骤。现在，你的Agent API服务已经在两台服务器上运行起来了。

4.3 配置数据库初始化与连接

服务启动后，需要初始化数据库表结构。通常你的Agent API服务在启动时会通过ORM（如SQLAlchemy）的create_all()来创建表，但这需要数据库连接正常。

检查数据库连接：在Node-2或Node-3上，进入Agent API容器内部执行健康检查。

docker exec -it agent-api bash # 在容器内，可以尝试用python脚本测试连接 python -c " import os, sys from sqlalchemy import create_engine, text engine = create_engine(os.getenv('DATABASE_URL')) try: with engine.connect() as conn: result = conn.execute(text('SELECT 1')) print('Database connection successful.') except Exception as e: print(f'Database connection failed: {e}') sys.exit(1) "

数据迁移（如果使用Alembic等工具）：如果你的项目使用了数据库迁移工具，需要在容器内执行迁移命令。
```
docker exec agent-api alembic upgrade head
```

验证服务端点：在服务器本地测试API是否正常。

curl http://localhost:8000/health # 应返回类似 {"status": "healthy"} 的JSON curl -X POST http://localhost:8000/chat \ -H "Content-Type: application/json" \ -d '{"message": "你好", "session_id": "test123"}'

4.4 配置Nginx负载均衡与域名解析

回到Node-1，确保Nginx配置正确并重载。

配置域名解析：在你的域名DNS管理后台，将agent.your-company.com的A记录指向Node-1的公网IP地址（或Keepalived管理的VIP）。

测试负载均衡：从外部访问你的服务。

# 使用curl测试，观察响应头中的`X-Upstream`（如果配置了）或轮流访问两个后端 curl -v http://agent.your-company.com/health

你可以通过查看Node-2和Node-3上Agent API容器的日志，来确认请求是否被均匀分配。

# 在Node-2上 docker compose logs --tail=10 agent-api # 在Node-3上同样执行

5. 监控、日志与维护实战

系统跑起来只是第一步，能看得清、管得住才是生产部署。

5.1 基础监控搭建（Prometheus + Grafana）

虽然只有三台服务器，但基础监控必不可少。我们可以在Node-1上部署一个轻量的Prometheus和Grafana。

在Node-1上部署Prometheus：

创建目录/opt/monitoring/prometheus。
编写prometheus.yml配置文件，抓取三台节点的Node Exporter指标和Agent服务的业务指标（如果暴露了/metrics端点）。

global: scrape_interval: 15s scrape_configs: - job_name: 'node' static_configs: - targets: ['10.0.1.11:9100', '10.0.1.12:9100', '10.0.1.13:9100'] - job_name: 'agent-api' metrics_path: /metrics # 假设你的FastAPI应用使用了prometheus_fastapi_instrumentator static_configs: - targets: ['10.0.1.12:8000', '10.0.1.13:8000']

使用Docker运行Prometheus。

docker run -d \ --name=prometheus \ -p 9090:9090 \ -v /opt/monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \ prom/prometheus

在三台节点上部署Node Exporter：

# 在每台服务器上执行 docker run -d \ --name=node-exporter \ --net="host" \ --pid="host" \ -v "/:/host:ro,rslave" \ quay.io/prometheus/node-exporter:latest \ --path.rootfs=/host

在Node-1上部署Grafana：
```
docker run -d \ --name=grafana \ -p 3000:3000 \ grafana/grafana-oss
```
访问http://<Node-1公网IP>:3000，默认账号密码admin/admin。添加Prometheus数据源（地址为http://localhost:9090），然后导入常用的Node Exporter仪表盘（如ID：1860），即可看到三台服务器的CPU、内存、磁盘、网络使用情况。

5.2 日志收集与集中查看

容器日志分散在各台服务器上，排查问题不方便。一个简单的方案是使用docker logs命令结合日志文件挂载。

在Docker Compose中挂载日志卷：如前文配置，我们将容器内的日志目录/app/logs挂载到主机的./logs下。
使用tail和grep进行集中查看：可以通过SSH在多台机器上执行命令，或者使用像lnav这样的工具查看结构化日志。
（进阶）使用Fluentd或Loki：如果日志量增大，可以考虑在每台服务器上部署Fluentd作为日志收集器，将日志统一发送到一台服务器的Elasticsearch或Grafana Loki中，实现集中存储和检索。

5.3 备份与恢复策略

数据无价，必须定期备份。

PostgreSQL备份：

# 在Node-2上创建备份脚本 /opt/backup/backup_pg.sh #!/bin/bash BACKUP_DIR="/opt/backup/data" DATE=$(date +%Y%m%d_%H%M%S) docker exec postgres pg_dump -U agentx_user agentx_prod | gzip > $BACKUP_DIR/agentx_db_$DATE.sql.gz # 保留最近7天的备份 find $BACKUP_DIR -name "agentx_db_*.sql.gz" -mtime +7 -delete

使用cron定时任务每天执行。

crontab -e # 添加一行，每天凌晨2点执行备份 0 2 * * * /bin/bash /opt/backup/backup_pg.sh

Redis RDB文件备份：Redis配置了appendonly yes，AOF文件本身具有持久性。也可以定期手动执行SAVE或配置bgsave，并将RDB文件拷贝到备份目录。
向量数据库备份：Chroma的数据存储在挂载的卷./data/chroma_data中，直接备份这个目录即可。注意备份时需要停止服务或确保数据一致性。

5.4 日常运维命令速查

查看服务状态：docker compose ps
查看实时日志：docker compose logs -f [service_name]
进入容器：docker exec -it [container_name] /bin/bash
重启服务：docker compose restart [service_name]

更新代码并重新部署：

git pull origin main # 拉取最新代码 docker compose build agent-api # 重建镜像 docker compose up -d --force-recreate agent-api # 重启服务

查看系统资源：htop,df -h,free -m

6. 常见问题与排查技巧实录

即使方案再完善，生产环境总会遇到问题。这里记录几个我踩过的坑和解决方法。

6.1 服务启动失败：端口冲突或依赖未就绪

问题：执行docker compose up -d后，某个服务（如agent-api）状态一直是Restarting或Exit 1。

排查：

docker compose logs agent-api查看具体错误日志。
常见原因一：端口被占用。netstat -tlnp | grep :8000检查端口。
常见原因二：依赖服务（如PostgreSQL）还没启动完成，Agent API连接失败。Docker Compose的depends_on只控制启动顺序，不等待服务“健康”。需要在应用代码中添加连接重试逻辑，或者使用healthcheck指令。

解决：在docker-compose.yml中为PostgreSQL和Redis添加健康检查，并让agent-api依赖健康状态。

services: postgres: ... healthcheck: test: ["CMD-SHELL", "pg_isready -U ${PG_USER}"] interval: 10s timeout: 5s retries: 5 start_period: 30s redis: ... healthcheck: test: ["CMD", "redis-cli", "--raw", "incr", "ping"] interval: 10s timeout: 5s retries: 5 agent-api: ... depends_on: postgres: condition: service_healthy redis: condition: service_healthy

6.2 性能瓶颈：响应慢或超时

问题：用户反馈请求响应慢，Nginx日志出现大量504 Gateway Timeout。

排查：

首先检查监控，看是CPU、内存还是磁盘IO达到瓶颈。htop看CPU，free -m看内存，iostat -x 1看磁盘IO。
如果是CPU持续满载，可能是某个Agent任务计算量过大。需要优化提示词、减少上下文长度，或者将耗时任务异步化。
如果是内存不足，查看是否有个别容器内存泄漏，或者Redis缓存了过多数据。调整Docker内存限制，或为Redis设置maxmemory策略。
检查网络延迟，特别是调用外部LLM API（如OpenAI）时。考虑使用国内镜像站或部署本地模型。

解决：

优化Nginx和Agent服务超时设置：如前文配置，适当增加proxy_read_timeout。
实施异步处理：将超过5秒的任务都丢到Redis队列，由Worker处理，API立即返回任务ID。
引入缓存：对频繁且结果不变的查询（如某些知识库问答），将结果缓存到Redis，设置合理的过期时间。
限流：在Nginx或应用层对API进行限流，防止突发流量打垮服务。

6.3 数据库连接数暴涨

问题：PostgreSQL日志出现“too many connections”错误，导致服务不可用。

排查：进入PostgreSQL容器，查看当前连接数。

docker exec postgres psql -U agentx_user -d agentx_prod -c "SELECT count(*) FROM pg_stat_activity;"

查看是哪个应用连接过多。

解决：

配置连接池：在Agent API代码中，使用SQLAlchemy的QueuePool，并设置合理的pool_size和max_overflow。

# 数据库连接URL示例 DATABASE_URL = f"postgresql+psycopg2://{user}:{password}@{host}:{port}/{dbname}?pool_size=10&max_overflow=20"

调整PostgreSQL最大连接数：修改postgresql.conf中的max_connections（默认100），通过Docker卷挂载覆盖。

# configs/postgresql/postgresql.conf max_connections = 200 shared_buffers = 256MB # 根据内存调整，通常为内存的1/4

确保连接关闭：检查代码中是否每次请求都正确关闭了数据库会话，避免连接泄漏。

6.4 Redis内存使用过高

问题：Redis内存占用持续增长，触发OOM（内存溢出）或被操作系统杀死。

排查：连接Redis，查看内存信息。

docker exec redis redis-cli -a your_password info memory

查看used_memory_human和maxmemory_human（如果设置了）。

解决：

设置内存上限和淘汰策略：在Redis配置文件中设置。

# configs/redis/redis.conf maxmemory 1gb # 根据你的服务器内存分配，例如1GB maxmemory-policy allkeys-lru # 内存满时，淘汰最近最少使用的键

区分缓存和队列数据：为缓存数据设置TTL（过期时间）。对于队列数据，确保消费者能及时处理，避免堆积。
监控大Key：使用redis-cli --bigkeys命令找出占用空间过大的键，优化数据结构。

6.5 容器内时间不对

问题：日志时间或业务逻辑中生成的时间与北京时间不符。

解决：确保宿主机时区正确，并在运行容器时挂载宿主机时区文件。

# 在docker-compose.yml的每个服务中增加 services: agent-api: ... volumes: - /etc/localtime:/etc/localtime:ro - /etc/timezone:/etc/timezone:ro ...

这套基于3台2C4G云服务器的企业级Agent部署方案，已经成功支撑了多个内部工具和中小型对客产品的初期运行。它的价值在于提供了一个完整、可运行、可观测、可维护的起点，而不是一个停留在PPT上的架构图。当你的业务量增长时，你可以沿着这个架构轻松扩展：给数据库单独升配服务器、将Redis集群化、增加更多的Agent API服务器节点、引入更复杂的服务网格。但所有这些演进，都源于一个稳定可靠的起点。

查看全文

http://www.jsqmd.com/news/1356486/