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

# 网络配置指南

## 配置说明

### 当前配置

1. **Nginx 配置**（已连接到外部网络）：
```yaml
networks:
  life-echo-network:
    external: true
    name: api_life-echo-network
```

2. **Life-Echo API 配置**（已更新为使用相同外部网络）：
```yaml
networks:
  life-echo-network:
    external: true
    name: api_life-echo-network
```

3. **Nginx upstream 配置**（使用服务名）：
```nginx
upstream lifecho_api_backend {
    server api:8000;
}
```

## 部署步骤

### 1. 确保网络存在

首先检查网络是否存在：

```bash
docker network ls | grep api_life-echo-network
```

如果网络不存在，需要先创建：

```bash
docker network create api_life-echo-network
```

### 2. 启动 Life-Echo 服务

```bash
cd /home/ubuntu/production/lifecho/api
docker-compose down
docker-compose up -d
```

### 3. 验证网络连接

检查容器是否在正确的网络中：

```bash
# 检查网络中的容器
docker network inspect api_life-echo-network

# 应该能看到：
# - nginx 容器
# - life-echo-api-prod 容器
# - life-echo-postgres 容器
# - life-echo-redis 容器
# - life-echo-celery-worker 容器
```

### 4. 测试连接

从 nginx 容器内测试：

```bash
# 进入 nginx 容器
docker exec -it nginx sh

# 测试 DNS 解析
nslookup api
# 或
ping api

# 测试 HTTP 连接
wget -O- http://api:8000/health
```

### 5. 重启 Nginx

```bash
docker restart nginx
```

## 故障排查

### 问题 1：网络名称不匹配

如果遇到网络名称错误，检查实际网络名称：

```bash
# 查看所有网络
docker network ls

# 查看 life-echo 服务使用的网络
docker inspect life-echo-api-prod | grep -A 10 Networks
```

然后更新 docker-compose.yml 中的网络名称。

### 问题 2：服务名无法解析

如果 `api:8000` 不工作，可以尝试使用容器名：

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

### 问题 3：网络连接失败

如果容器无法连接到网络，手动连接：

```bash
# 连接现有容器到网络
docker network connect api_life-echo-network life-echo-api-prod
docker network connect api_life-echo-network life-echo-postgres
docker network connect api_life-echo-network life-echo-redis
docker network connect api_life-echo-network life-echo-celery-worker
```

## 验证清单

- [ ] 网络 `api_life-echo-network` 存在
- [ ] Life-Echo 服务使用外部网络配置
- [ ] Nginx 配置使用服务名 `api:8000`
- [ ] 所有容器都在同一网络中
- [ ] Nginx 可以解析 `api` 主机名
- [ ] HTTP 健康检查通过：`curl https://lifecho.worldsplats.com/health`