---
title: "external配置"
type: concept
tags: [docker, compose, configuration, volume, network]
date: 2026-04-22
---

# external配置

## Definition
`external: true` 是 Docker Compose 文件中的一种声明式配置，用于告诉 Compose 某个 Volume 或 Network 已经存在，不要尝试创建它，而是直接使用已存在的资源。适用于需要保留数据、不希望 Compose 管理资源生命周期的场景。

## Syntax

### Volume（卷）
```yaml
volumes:
  portainer_data:
    external: true

# 引用时直接使用名称
services:
  portainer:
    volumes:
      - portainer_data:/data
```

### Network（网络）
```yaml
networks:
  portainer_network:
    external: true

services:
  portainer:
    networks:
      - portainer_network
```

## Behavior Comparison

| 配置 | Compose up | Compose down |
|------|-----------|-------------|
| `external: false`（默认） | 自动创建资源 | 自动删除资源 |
| `external: true` | **不会创建**，直接使用已存在的 | **不会删除**，保持资源 |
| `external: { name: xxx }` | 使用指定名称的已存在资源 | 不会删除 |

## Common Use Cases

### Case 1: 保留数据重装应用
```yaml
# Portainer 重装时保留 portainer_data 卷
volumes:
  portainer_data:
    external: true

services:
  portainer:
    image: portainer/portainer-ce:lts
    volumes:
      - portainer_data:/data
```
这样即使删除并重建 Portainer 容器，用户账户和配置也不会丢失。

### Case 2: 多个 Compose 共享网络
```yaml
# compose-a.yml
networks:
  shared_backend:
    external: true

# compose-b.yml（同一机器上的另一个项目）
networks:
  shared_backend:
    external: true
```
两个 compose 文件可以连接同一个外部网络，实现跨项目通信。

### Case 3: 预创建的基础设施
运维人员预先创建好 Volume/Network，开发者通过 `external: true` 引用：
```bash
# 运维预先创建
docker network create monitoring
docker volume create prometheus_data

# 开发 compose 中声明
networks:
  monitoring:
    external: true
volumes:
  prometheus_data:
    external: true
```

## Limitations

### 1. 资源不存在会导致错误
```bash
# 如果 portainer_data 卷不存在，compose up 会报错：
# ERROR: Volume portainer_data declared as external, but could not be found
```

**解决**：先确认资源存在，或使用脚本预创建：
```bash
docker volume create portainer_data 2>/dev/null || true
docker compose up -d
```

### 2. 不能控制生命周期
`external: true` 资源不会被 `docker compose down --volumes` 删除。需要手动清理：
```bash
docker volume rm portainer_data
docker network rm portainer_network
```

### 3. Compose 文件中的其他字段无效
```yaml
volumes:
  portainer_data:
    external: true
    driver: local    # ❌ 会被忽略
    driver_opts: {}  # ❌ 会被忽略
```

## External with Custom Name

如果已存在的资源名称与 compose 中声明的名称不同，使用 `external.name` 指定：
```yaml
volumes:
  app_data:
    external:
      name: old_project_data_volume
```

## Best Practices

1. **始终显式声明**：所有 `external` 资源都应在 compose 文件中明确声明，便于维护者理解
2. **文档化**：在 README 中记录哪些资源需要预先创建
3. **命名规范**：使用统一的前缀或命名约定（如 `project_name_resource`）
4. **验证脚本**：部署前运行验证脚本确保依赖资源存在

## Related Concepts
- [[Docker Compose]] — external 配置所在的上下文
- [[Docker卷]] — external volume 的目标对象
- [[Docker Network]] — external network 的目标对象
- [[Docker容器生命周期管理]] — external 资源与生命周期管理的关系
- [[Docker警告处理]] — external 配置用于解决警告的典型场景

## Related Entities
- [[Portainer]] — 典型的需要 external 配置保留数据的应用

## See Also
- [[如何删除旧的废弃的docker-container-volume]] — external 配置的实操案例
- [[Docker堆栈]] — 多容器场景下的 external 资源管理