155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
---
|
||
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 资源管理
|