ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update nexus: fix conflicts and sync local changes

Browse Source
This commit is contained in:
Shen Wei
2026-04-26 12:06:50 +08:00
parent 191797c01b
commit f09834b5a5
2443 changed files with 254323 additions and 255154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
wiki/concepts/external配置.md
View File

@@ -1,154 +1,154 @@
---
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 资源管理
---
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 资源管理