From 14bfc21b0ace4318e6ade08724e8f2117662b36d Mon Sep 17 00:00:00 2001
From: LuoXingchen <42908923+LuoXingchen935@users.noreply.github.com>
Date: Fri, 10 Jul 2026 05:06:03 +0800
Subject: [PATCH] feat(docker-compose-memo): add Chinese translation and
refactor locale-based memo loading (#421)
- Add docker-compose.zh.md with full Chinese translation
- Refactor docker-compose-memo.vue to dynamically load memo by current locale
---
.../docker-compose-memo.vue | 27 +-
.../docker-compose-memo/docker-compose.zh.md | 462 ++++++++++++++++++
2 files changed, 487 insertions(+), 2 deletions(-)
create mode 100644 src/tools/docker-compose-memo/docker-compose.zh.md
diff --git a/src/tools/docker-compose-memo/docker-compose-memo.vue b/src/tools/docker-compose-memo/docker-compose-memo.vue
index c455b35b..8a18c41d 100644
--- a/src/tools/docker-compose-memo/docker-compose-memo.vue
+++ b/src/tools/docker-compose-memo/docker-compose-memo.vue
@@ -1,13 +1,36 @@
-
+
diff --git a/src/tools/docker-compose-memo/docker-compose.zh.md b/src/tools/docker-compose-memo/docker-compose.zh.md
new file mode 100644
index 00000000..68ea68b7
--- /dev/null
+++ b/src/tools/docker-compose-memo/docker-compose.zh.md
@@ -0,0 +1,462 @@
+Docker Compose 是一个用于定义和运行多容器 Docker 应用程序的强大工具。它使用一个 YAML 文件(`compose.yaml`)来配置应用服务、网络、卷等。该文件允许开发者以声明式的方式描述基础设施和依赖关系,从而更轻松地管理复杂的环境。
+
+无论你是在搭建本地开发环境,还是部署到生产环境,Compose 都能简化编排过程,并让你的配置保持可读、可版本控制。
+
+## 📁 文件名
+```yaml
+compose.yaml
+```
+
+### ✅ YAML 格式规则
+
+- 缩进使用 **2 个空格**(不要使用制表符)
+- 键和值是 **区分大小写** 的
+- 列表使用 `-` 表示每一项
+- 包含特殊字符的字符串应使用引号括起来
+- 环境变量可以内联定义,也可以通过 `.env` 文件定义
+
+## 🧱 基本结构
+
+```yaml
+services:
+ service_name:
+ image: image_name:tag
+ build:
+ context: .
+ dockerfile: Dockerfile
+ ports:
+ - "host_port:container_port"
+ volumes:
+ - ./host_path:/container_path
+ environment:
+ - VAR_NAME=value
+ depends_on:
+ - other_service
+ networks:
+ - custom_network
+networks:
+ custom_network:
+ driver: bridge
+volumes:
+ custom_volume:
+```
+
+## ⚙️ 服务(Services)
+
+每个 service 都定义一个容器。
+
+### 常用服务选项
+
+```yaml
+services:
+ web:
+ image: nginx:latest
+ build:
+ context: ./app
+ dockerfile: Dockerfile
+ command: ["nginx", "-g", "daemon off;"]
+ container_name: custom_name
+ ports:
+ - "8080:80"
+ expose:
+ - "80"
+ environment:
+ - DEBUG=true
+ env_file:
+ - .env
+ volumes:
+ - ./data:/data
+ restart: always
+ depends_on:
+ - db
+ networks:
+ - frontend
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost"]
+ interval: 30s
+ timeout: 10s
+ retries: 5
+```
+
+## 🏗️ 构建选项(Build Options)
+
+```yaml
+build:
+ context: ./dir
+ dockerfile: Dockerfile
+ args:
+ build_arg: value
+ target: build-stage
+```
+
+- **`build:`** 告诉 Compose 如何构建镜像。
+ - `context:` 是包含 Dockerfile 和源代码的目录。
+ - `dockerfile:` 允许你指定自定义的 Dockerfile 名称或路径。
+
+## 📦 卷(Volumes)
+
+```yaml
+volumes:
+ data_volume:
+ driver: local
+ driver_opts:
+ type: none
+ device: /path/on/host
+ o: bind
+```
+
+### 挂载卷
+
+```yaml
+volumes:
+ - data_volume:/app/data
+ - ./local:/container/path
+```
+
+- **`volumes:`** 将宿主机目录或具名卷挂载到容器中。
+ - `./src:/app/src` 将本地的 `src` 文件夹挂载到容器中的 `/app/src`。
+
+## 🌐 网络(Networks)
+
+```yaml
+networks:
+ frontend:
+ driver: bridge
+ backend:
+ driver: overlay
+```
+
+- **`networks:`** 将服务连接到一个或多个自定义网络。可实现服务发现和隔离。
+
+### 为服务分配网络
+
+```yaml
+services:
+ app:
+ networks:
+ - frontend
+ - backend
+```
+
+## 🌐 端口(Ports)
+
+```yaml
+ ports:
+ - "3000:3000"
+```
+- **`ports:`** 将容器端口映射到宿主机端口。格式为 `"宿主机:容器"`。常用于将服务暴露给本机访问。
+
+## 🔐 密钥(Secrets,仅 Docker Swarm)
+
+```yaml
+secrets:
+ db_password:
+ file: ./db_password.txt
+
+services:
+ db:
+ secrets:
+ - db_password
+```
+
+## 🔑 配置(Configs,仅 Docker Swarm)
+
+```yaml
+configs:
+ my_config:
+ file: ./config.txt
+
+services:
+ app:
+ configs:
+ - source: my_config
+ target: /etc/config.txt
+```
+
+## 🧪 健康检查(Healthcheck)
+
+```yaml
+healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 5s
+```
+
+- **`healthcheck:`** 定义 Docker 如何检查容器是否健康。
+ - `test:` 要运行的命令
+ - `interval:` 检查的间隔时间
+ - `timeout:` 等待响应的超时时间
+ - `retries:` 在标记为不健康之前允许失败的次数
+
+## 🔄 重启策略(Restart Policies)
+
+```yaml
+restart: no # 从不重启
+restart: always # 总是重启
+restart: on-failure # 失败时重启
+restart: unless-stopped
+```
+
+## 🧬 环境变量(Environment Variables)
+
+```yaml
+environment:
+ - VAR1=value1
+ - VAR2=value2
+env_file:
+ - .env
+```
+
+- **`environment:`** 在容器内设置环境变量。常用于配置。
+- **`env_file:`** 从文件加载环境变量。可以将密钥和配置与 Compose 文件分离。
+
+## 命令(Command)
+
+```yaml
+ command: npm start
+```
+- **`command:`** 覆盖 Dockerfile 中定义的默认命令。常用于自定义容器行为。
+
+## 依赖(Dependencies)
+
+```yaml
+ depends_on:
+ - db
+```
+- **`depends_on:`** 指定服务的启动顺序。在 Compose 中,这并不会等待服务"就绪"——只是"已启动"。
+
+## 🧹 清理(Clean Up)
+
+```bash
+docker compose down # 停止并删除容器、网络、卷
+docker compose down -v # 同时删除具名卷
+```
+
+## 🚀 命令(Commands)
+
+| 命令 | 描述 |
+|--------|-------------|
+| `docker compose up` | 启动服务 |
+| `docker compose up -d` | 以分离(后台)模式启动 |
+| `docker compose down` | 停止并删除服务 |
+| `docker compose build` | 构建镜像 |
+| `docker compose ps` | 列出容器 |
+| `docker compose logs` | 查看日志 |
+| `docker compose exec ` | 在容器中执行命令 |
+| `docker compose config` | 校验并查看配置 |
+
+## 🧠 挂载 GPU / iGPU
+
+Docker Compose 通过 `device_requests` 字段支持 GPU 访问(Compose v3.8+ 和 Docker 19.03+)。
+
+### ✅ NVIDIA GPU 示例
+
+```yaml
+services:
+ gpu-app:
+ image: nvidia/cuda:11.0-base
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: all
+ capabilities: [gpu]
+```
+
+### ✅ Intel iGPU(通过 VAAPI 或 OpenCL)
+
+```yaml
+services:
+ igpu-app:
+ image: intel/openvino
+ devices:
+ - /dev/dri:/dev/dri
+```
+
+> 🔧 请确保你的宿主机上安装了必要的驱动和运行时(例如 NVIDIA Container Toolkit 或 Intel Media SDK)。
+
+## 🔄 Compose 与 Swarm YAML 差异
+
+| 特性 | Docker Compose (`compose.yaml`) | Docker Swarm (`stack.yml`) |
+|--------------------|----------------------------------------|-----------------------------|
+| `restart` | ✅ 支持 | ❌ 不支持 |
+| `depends_on` | ✅ 支持 | ❌ 不支持 |
+| `deploy` | ❌ 忽略 | ✅ 副本数必需 |
+| `build` | ✅ 支持 | ❌ 不支持 |
+| `volumes`(bind) | ✅ 支持 | ✅ 支持 |
+| `configs` / `secrets`| ❌ 忽略 | ✅ 支持 |
+| `healthcheck` | ✅ 支持 | ✅ 支持 |
+
+> 🧠 **提示:** 本地开发请使用 `compose.yaml`,Swarm 部署请使用 `stack.yml`。
+
+## 🧬 Profiles(Compose v3.9+)
+
+Profiles 允许根据当前激活的 profile 有条件地包含服务。这对于区分 dev / test / staging 环境非常有用。
+
+### ✅ 定义 Profiles
+
+```yaml
+services:
+ web:
+ image: nginx
+ profiles:
+ - default
+
+ debug:
+ image: busybox
+ command: top
+ profiles:
+ - debug
+```
+
+### ✅ 激活 Profiles
+
+```bash
+docker compose --profile debug up
+```
+
+### ✅ 注意事项
+
+- 没有 `profiles` 键的服务始终会被包含。
+- 多个 profile 可以同时激活。
+- 适用于功能开关、可选服务或针对不同环境的配置。
+
+## ⚔️ YAML 差异:Docker Compose 与 Docker Swarm 模式
+
+Docker Compose 和 Docker Swarm 都使用 YAML 文件来定义服务,但它们用途不同,支持的特性也不同。Compose 针对本地开发和测试进行了优化,而 Swarm 则是为跨集群的生产级编排而设计。
+
+### 🧭 用途
+
+| 模式 | 用途 |
+|-------------|-----------------------------------|
+| Compose | 本地开发、测试 |
+| Swarm | 集群部署、扩缩容 |
+
+### 🧩 YAML 结构上的关键差异
+
+| 特性 | Compose (`compose.yaml`) | Swarm (`stack.yml`) |
+|----------------------|-------------------------------|----------------------|
+| `build:` | ✅ 支持 | ❌ 忽略 |
+| `restart:` | ✅ 支持 | ❌ 忽略 |
+| `depends_on:` | ✅ 支持 | ❌ 忽略 |
+| `deploy:` | ❌ 忽略 | ✅ 扩缩容、调度必需 |
+| `configs:` | ❌ 忽略 | ✅ 支持 |
+| `secrets:` | ❌ 忽略 | ✅ 支持 |
+| `healthcheck:` | ✅ 支持 | ✅ 支持 |
+| `volumes:`(bind) | ✅ 支持 | ✅ 支持 |
+| `networks:` | ✅ 支持 | ✅ 支持 |
+| `profiles:` | ✅ 支持(v3.9+) | ❌ 不支持 |
+
+### 🔧 仅 Compose 支持的特性
+
+以下特性对本地开发很有用,但在 Swarm 中会被忽略:
+
+#### `build:`
+```yaml
+services:
+ app:
+ build:
+ context: .
+ dockerfile: Dockerfile
+```
+- Compose 在本地构建镜像。
+- Swarm 要求使用已推送到镜像仓库的预构建镜像。
+
+#### `restart:`
+```yaml
+restart: unless-stopped
+```
+- Compose 使用此配置自动重启容器。
+- Swarm 使用 `deploy.restart_policy`。
+
+#### `depends_on:`
+```yaml
+depends_on:
+ - db
+```
+- Compose 按顺序启动服务。
+- Swarm 会忽略此配置;请使用 healthcheck 和 wait-for-it 脚本。
+
+### 🛡️ 仅 Swarm 支持的特性
+
+以下特性是 Swarm 独有的,Compose 会忽略:
+
+#### `deploy:`
+```yaml
+services:
+ app:
+ deploy:
+ replicas: 3
+ placement:
+ constraints:
+ - node.role == manager
+ restart_policy:
+ condition: on-failure
+```
+- 用于在集群中控制扩缩容、调度和重启行为。
+
+#### `configs:` 和 `secrets:`
+```yaml
+configs:
+ app_config:
+ file: ./config.yml
+
+secrets:
+ db_password:
+ file: ./password.txt
+```
+- 用于在节点间安全地分发配置和密钥。
+
+#### `placement:`(位于 `deploy` 内)
+```yaml
+placement:
+ constraints:
+ - node.labels.env == production
+```
+- 根据 label 将服务分配到指定节点。
+
+### 🧪 健康检查(两者均支持)
+
+```yaml
+healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+```
+- 在 Compose 和 Swarm 中均可使用。
+- 在 Swarm 中,健康状态会影响服务的重新调度。
+
+### 📦 卷的差异
+
+| 类型 | Compose | Swarm |
+|-------------|---------|-------|
+| Bind mount(绑定挂载) | ✅ | ✅ |
+| Named volume(具名卷)| ✅ | ✅ |
+| External volume(外部卷) | ✅ | ✅ |
+| Volume driver options(卷驱动选项) | ✅ | ✅ |
+
+Swarm 要求外部卷必须预先在所有节点上创建好。
+
+### 🧠 总结
+
+| 特性类别 | Compose | Swarm |
+|----------------------|---------|-------|
+| 本地构建 | ✅ | ❌ |
+| 集群扩缩容 | ❌ | ✅ |
+| Secrets / Configs | ❌ | ✅ |
+| Profiles | ✅ | ❌ |
+| 重启策略 | ✅ | ✅(通过 `deploy`) |
+| 服务依赖 | ✅ | ❌ |
+
+> 🧭 **提示:** 开发请使用 `compose.yaml`,Swarm 请使用 `stack.yml`。你也可以将配置拆分为多个文件,或使用 `kompose` 等工具将 Kubernetes 的清单进行转换。
+
+## 📚 资源
+
+- [Compose 文件参考](https://docs.docker.com/compose/compose-file/)
+- [Docker CLI 参考](https://docs.docker.com/engine/reference/commandline/compose/)
+- [NVIDIA GPU 支持](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
+- [Intel GPU 支持](https://github.com/intel/media-driver)