ishenwei/nexus

Fork 0

Files

Shen Wei f09834b5a5 Update nexus: fix conflicts and sync local changes

2026-04-26 12:06:50 +08:00

4.2 KiB

Raw Blame History

title, type, tags, date

title

type

external配置

Definition

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

Syntax

Volume（卷）

volumes:
  portainer_data:
    external: true

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

Network（网络）

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: 保留数据重装应用

# Portainer 重装时保留 portainer_data 卷
volumes:
  portainer_data:
    external: true

services:
  portainer:
    image: portainer/portainer-ce:lts
    volumes:
      - portainer_data:/data

这样即使删除并重建 Portainer 容器，用户账户和配置也不会丢失。

Case 2: 多个 Compose 共享网络

# compose-a.yml
networks:
  shared_backend:
    external: true

# compose-b.yml（同一机器上的另一个项目）
networks:
  shared_backend:
    external: true

两个 compose 文件可以连接同一个外部网络，实现跨项目通信。

Case 3: 预创建的基础设施

运维人员预先创建好 Volume/Network，开发者通过 external: true 引用：

# 运维预先创建
docker network create monitoring
docker volume create prometheus_data

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

Limitations

1. 资源不存在会导致错误

# 如果 portainer_data 卷不存在，compose up 会报错：
# ERROR: Volume portainer_data declared as external, but could not be found

解决：先确认资源存在，或使用脚本预创建：

docker volume create portainer_data 2>/dev/null || true
docker compose up -d

2. 不能控制生命周期

external: true 资源不会被 docker compose down --volumes 删除。需要手动清理：

docker volume rm portainer_data
docker network rm portainer_network

3. Compose 文件中的其他字段无效

volumes:
  portainer_data:
    external: true
    driver: local    # ❌ 会被忽略
    driver_opts: {}  # ❌ 会被忽略

External with Custom Name

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

volumes:
  app_data:
    external:
      name: old_project_data_volume

Best Practices

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

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

Portainer — 典型的需要 external 配置保留数据的应用

4.2 KiB Raw Blame History Unescape Escape