# Gateway 部署指南

**更新日期：** 2026-03-04

## 文档维护规范

0. **先改文档，再动代码**
1. **文档分层，链接代码**
2. **简洁快照，日志分离**

---

## 部署方式

### 方式 1：单体部署（开发/小团队）

一个进程运行 Agent Core + Gateway。

```bash
# 启动
python main.py

# 配置
# config/gateway.yaml
gateway:
  enabled: true
  port: 8000
  heartbeat_timeout: 60
```

**适用场景**：
- 开发环境
- 小团队（< 10 个 Agent）
- 快速原型

### 方式 2：分离部署（生产环境）

两个独立进程。

```bash
# 终端 1：启动 Agent Core
python api_server.py

# 终端 2：启动 Gateway
python gateway_server.py
```

**配置**：

```yaml
# config/gateway.yaml
gateway:
  port: 8000
  agent_api: http://localhost:8001  # Agent Core API
  heartbeat_timeout: 60
```

**适用场景**：
- 生产环境
- 中等规模（10-1000 个 Agent）
- 需要独立扩展

### 方式 3：分层部署（大规模/企业）

三个独立进程。

```bash
# 终端 1：Agent Core
python api_server.py

# 终端 2：Gateway Core
python gateway_server.py

# 终端 3：Enterprise Gateway
python enterprise_gateway.py
```

**适用场景**：
- 大规模（> 1000 个 Agent）
- 企业部署
- 需要独立扩展各层

---

## Docker 部署

### 单容器部署

```dockerfile
# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

CMD ["python", "gateway_server.py"]
```

```bash
# 构建
docker build -t a2a-gateway .

# 运行
docker run -p 8000:8000 a2a-gateway
```

### Docker Compose 部署

```yaml
# docker-compose.yml
version: '3.8'

services:
  agent-core:
    build: .
    command: python api_server.py
    ports:
      - "8001:8001"
    volumes:
      - ./.trace:/app/.trace

  gateway:
    build: .
    command: python gateway_server.py
    ports:
      - "8000:8000"
    environment:
      - AGENT_API=http://agent-core:8001
    depends_on:
      - agent-core
```

```bash
# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f gateway
```

---

## 配置

### 基础配置

```yaml
# config/gateway.yaml
gateway:
  # 服务配置
  host: 0.0.0.0
  port: 8000

  # 注册表配置
  heartbeat_timeout: 60  # 心跳超时（秒）
  cleanup_interval: 30   # 清理间隔（秒）

  # Agent Core API
  agent_api: http://localhost:8001
```

### Enterprise 配置

```yaml
# config/gateway.yaml
gateway:
  # ... 基础配置

  # Enterprise 功能
  enterprise:
    enabled: true

    # 认证
    auth:
      provider: feishu_oauth
      feishu:
        app_id: xxx
        app_secret: xxx

    # 审计
    audit:
      enabled: true
      log_file: /var/log/gateway/audit.jsonl

    # 成本管理
    cost:
      enabled: true
      user_daily_limit: 1000  # Token 限额
```

---

## 监控

### 健康检查

```bash
# 检查 Gateway 状态
curl http://localhost:8000/health

# 返回
{
  "status": "ok",
  "agents_online": 5,
  "uptime": 3600
}
```

### 指标监控

```python
# 暴露 Prometheus 指标
from prometheus_client import Counter, Gauge

agents_online = Gauge('gateway_agents_online', 'Number of online agents')
messages_sent = Counter('gateway_messages_sent', 'Total messages sent')
```

### 日志

```python
# 配置日志
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('/var/log/gateway/gateway.log'),
        logging.StreamHandler()
    ]
)
```

---

## 扩展

### 水平扩展

部署多个 Gateway 实例：

```bash
# 实例 1
python gateway_server.py --port 8000

# 实例 2
python gateway_server.py --port 8001

# 实例 3
python gateway_server.py --port 8002
```

使用负载均衡器：

```nginx
# nginx.conf
upstream gateway {
    server localhost:8000;
    server localhost:8001;
    server localhost:8002;
}

server {
    listen 80;
    location /gateway/ {
        proxy_pass http://gateway;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

### 服务发现

使用 Consul 进行服务发现：

```python
# 注册到 Consul
import consul

c = consul.Consul()
c.agent.service.register(
    name='gateway',
    service_id='gateway-1',
    address='localhost',
    port=8000,
    check=consul.Check.http('http://localhost:8000/health', '10s')
)
```

---

## 故障排查

### 问题：Agent 无法连接

**症状**：PC Agent 连接失败

**排查**：
1. 检查 Gateway 是否启动：`curl http://localhost:8000/health`
2. 检查防火墙：`telnet localhost 8000`
3. 查看 Gateway 日志

### 问题：消息发送失败

**症状**：send_to_agent 返回错误

**排查**：
1. 检查目标 Agent 是否在线：`GET /gateway/status/{agent_uri}`
2. 检查 agent_uri 格式
3. 查看 Gateway 日志

### 问题：心跳超时

**症状**：Agent 频繁离线

**排查**：
1. 检查网络稳定性
2. 调整 heartbeat_timeout 配置
3. 检查 PC Agent 心跳逻辑

---

## 安全

### HTTPS/WSS

使用 SSL 证书：

```python
import ssl

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.load_cert_chain('cert.pem', 'key.pem')

uvicorn.run(app, host="0.0.0.0", port=8000, ssl=ssl_context)
```

### 认证

添加 API Key 认证：

```python
from fastapi import Header, HTTPException

async def verify_api_key(x_api_key: str = Header(...)):
    if x_api_key not in valid_api_keys:
        raise HTTPException(401, "Invalid API Key")
```

---

## 相关文档

- [架构设计](./architecture.md)：Gateway 架构和设计决策
- [API 文档](./api.md)：完整的 API 参考
- [A2A IM 系统](../../docs/a2a-im.md)：完整的 A2A IM 文档