life-echo/docs/nginx-config-guide.md

# Nginx 配置调整指南

## 问题说明

根据 `docker-compose.yml` 配置：
- **服务名**：`api`
- **容器名**：`life-echo-api-prod`
- **网络名**：`life-echo-network`
- **端口映射**：`8000:8000`

原配置中使用的是 `lifecho-api:8000`，需要根据实际部署方式调整。

## 配置方案

### 方案 1：Nginx 在同一个 Docker Compose 网络中（推荐）

如果 nginx 容器也在 `life-echo-network` 网络中，使用**服务名**：

```nginx
upstream lifecho_api_backend {
    server api:8000;
}
```

**如何实现**：
1. 在 nginx 的 docker-compose 配置中添加网络：
```yaml
services:
  nginx:
    # ... 其他配置
    networks:
      - life-echo-network

networks:
  life-echo-network:
    external: true  # 使用已存在的网络
```

### 方案 2：Nginx 在外部容器但连接到同一网络

如果 nginx 容器连接到 `life-echo-network` 网络，可以使用**容器名**：

```nginx
upstream lifecho_api_backend {
    server life-echo-api-prod:8000;
}
```

**如何实现**：
```bash
# 将 nginx 容器连接到网络
docker network connect life-echo-network <nginx-container-name>
```

### 方案 3：Nginx 在主机上（通过端口映射）

如果 nginx 直接运行在主机上，使用**本地端口**：

```nginx
upstream lifecho_api_backend {
    server 127.0.0.1:8000;
}
```

这是最简单的方案，因为 `docker-compose.yml` 已经将容器的 8000 端口映射到主机的 8000 端口。

## 推荐配置

根据最常见的部署场景，**推荐使用方案 1（服务名）**，因为：
1. 更灵活，不依赖容器名
2. Docker Compose 会自动处理服务发现
3. 如果容器重启，服务名保持不变

## 验证配置

配置完成后，测试连接：

```bash
# 测试健康检查端点
curl https://lifecho.worldsplats.com/health

# 测试 API 端点
curl https://lifecho.worldsplats.com/api/your-endpoint
```

## 故障排查

如果连接失败，检查：

1. **网络连接**：
```bash
# 检查容器是否在同一网络
docker network inspect life-echo-network

# 检查容器 IP
docker inspect life-echo-api-prod | grep IPAddress
```

2. **端口映射**：
```bash
# 检查端口是否映射
docker ps | grep life-echo-api-prod
```

3. **Nginx 日志**：
```bash
# 查看错误日志
tail -f /var/log/nginx/error.log
```