feat: environment-setup v1.1.0 — 增加 Docker/Podman 容器环境 + WSL2 配置

- frontmatter: description 和触发词覆盖 Docker/Podman/WSL2/容器关键词 - 快速诊断: 增加 Docker/Podman/WSL2 检测命令 - 新增「容器运行环境」章节: Docker 各平台安装、Podman 替代方案、常见问题 - 新增「WSL2 安装与配置」章节: 检测/安装/发行版/开发环境配置/文件互访/常见问题 - 版本升级 1.0.0 → 1.1.0
2026-04-21 13:30:48 +08:00 · 2026-04-09 12:36:13 +08:00
parent a5efc3b9a9
commit 187d42e302
1 changed files with 304 additions and 12 deletions
--- a/skills/environment-setup/SKILL.md
+++ b/skills/environment-setup/SKILL.md
@@ -1,18 +1,21 @@
 ---
 name: 开发环境配置
 description: >-
-  Use this skill when the user needs help setting up a development environment,
-  installing Python, Node.js, or their package managers, managing multiple
-  runtime versions, creating virtual environments, or troubleshooting
-  environment-related issues. Triggers include: "install python", "install
-  node", "setup environment", "virtual environment", "venv", "nvm", "pyenv",
+  Use this skill when the user needs help setting up a development environment.
+  Covers three pillars: (1) Python/Node.js runtime installation and multi-version
+  management (Hatch, Volta, pyenv, nvm); (2) Docker/Podman container runtime
+  detection, installation, and usage; (3) WSL2 setup on Windows for Linux
+  compatibility. Triggers include: "install python", "install node", "install
+  docker", "setup environment", "virtual environment", "venv", "nvm", "pyenv",
  "pip not found", "python not found", "node not found", "npm not found",
-  "PATH issues", "version manager", or any error message indicating a missing
-  runtime or package manager. Also use when other skills (docx, pdf, xlsx,
+  "docker not found", "container", "podman", "WSL", "WSL2", "PATH issues",
+  "version manager", or any error message indicating a missing runtime, package
+  manager, or container engine. Also use when other skills (docx, pdf, xlsx,
  pptx) report that Python or Node.js is not available and the user needs
-  guidance. Use when 用户提到 安装Python、安装Node、环境配置、虚拟环境、
-  版本管理、PATH问题、pip找不到、python找不到。
-version: 1.0.0
+  guidance. Use when 用户提到 安装Python、安装Node、安装Docker、容器、Podman、
+  WSL、WSL2、环境配置、虚拟环境、版本管理、PATH问题、pip找不到、python找不到、
+  docker找不到、容器运行环境。
+version: 1.1.0
 type: procedural
 risk_level: low
 status: enabled
@@ -21,6 +24,9 @@ tags:
  - environment
  - python
  - nodejs
+  - docker
+  - container
+  - wsl
  - setup
  - troubleshooting
 metadata:
@@ -37,7 +43,7 @@ market:
    stroke="url(#env-a)" stroke-width="1.5" stroke-linecap="round"
    stroke-linejoin="round"/><path d="M13 16h4" stroke="url(#env-a)"
    stroke-width="1.5" stroke-linecap="round"/></svg>
-  short_desc: Python / Node.js 环境安装、版本管理与问题排查
+  short_desc: Python / Node.js / Docker 环境安装、版本管理与问题排查
  category: productivity
  maintainer:
    name: DesireCore Official
@@ -47,7 +53,11 @@ market:

 # Environment Setup Guide

-本技能提供 Python 和 Node.js 开发环境的完整安装、多版本管理、虚拟环境配置以及常见问题排查指南。
+本技能提供开发环境的完整配置指南，涵盖三大支柱：
+
+1. **运行时环境**：Python / Node.js 安装与多版本管理（Hatch、Volta、pyenv、nvm）
+2. **容器环境**：Docker / Podman 检测、安装与使用
+3. **Windows 子系统**：WSL2 安装与配置（仅 Windows）

 ---

@@ -61,9 +71,18 @@ echo "=== Python ===" && python3 --version 2>/dev/null || python --version 2>/de
 echo "=== pip ===" && pip3 --version 2>/dev/null || pip --version 2>/dev/null || echo "NOT FOUND"
 echo "=== Node.js ===" && node --version 2>/dev/null || echo "NOT FOUND"
 echo "=== npm ===" && npm --version 2>/dev/null || echo "NOT FOUND"
+echo "=== Docker ===" && docker --version 2>/dev/null || echo "NOT FOUND"
+echo "=== Podman ===" && podman --version 2>/dev/null || echo "NOT FOUND"
 echo "=== PATH ===" && echo "$PATH" | tr ':' '\n'
 ```

+**Windows 额外检测**（在 PowerShell 中运行）：
+
+```powershell
+Write-Host "=== WSL ===" ; wsl --status 2>&1
+Write-Host "=== Docker ===" ; docker --version 2>$null ; if (-not $?) { Write-Host "NOT FOUND" }
+```
+
 根据输出结果，跳转到对应章节。

 ---
@@ -942,6 +961,279 @@ npm install -g docx pptxgenjs

 ---

+## 容器运行环境（Docker / Podman）
+
+容器环境在开发中越来越常见，许多工具和服务（数据库、消息队列、AI 推理服务等）通过容器部署最为便捷。
+
+### 检测容器环境
+
+```bash
+# Docker
+docker --version 2>/dev/null && docker info --format '{{.OperatingSystem}}' 2>/dev/null || echo "Docker NOT FOUND or not running"
+
+# Podman（Docker 的无守护进程替代品）
+podman --version 2>/dev/null || echo "Podman NOT FOUND"
+```
+
+### Docker 安装
+
+#### macOS
+
+推荐使用 Docker Desktop（包含 Docker Engine + Docker Compose + GUI）：
+
+```bash
+# 方式 1：Homebrew Cask（推荐）
+brew install --cask docker
+
+# 安装后启动 Docker Desktop 应用
+# 首次启动需要授权特权访问
+
+# 方式 2：从官网下载
+# https://www.docker.com/products/docker-desktop/
+# 选择 Apple Silicon (M1/M2/M3) 或 Intel 版本
+```
+
+安装后验证：
+```bash
+docker --version
+docker run hello-world
+```
+
+#### Windows
+
+**推荐 Docker Desktop + WSL2 后端**（需要先安装 WSL2，见下方 WSL2 章节）：
+
+1. 下载 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
+2. 安装时勾选 "Use WSL 2 instead of Hyper-V"
+3. 安装后在 Settings → General 中确认 "Use the WSL 2 based engine" 已启用
+
+```powershell
+# 或通过 winget 安装
+winget install Docker.DockerDesktop
+```
+
+验证：
+```powershell
+docker --version
+docker run hello-world
+```
+
+**不需要 Docker Desktop 的轻量方案**（仅 CLI，通过 WSL2）：
+
+```bash
+# 在 WSL2 Ubuntu 中：
+sudo apt update
+sudo apt install docker.io docker-compose-v2
+sudo usermod -aG docker $USER
+# 重新登录 WSL2 后生效
+```
+
+#### Linux (Debian/Ubuntu)
+
+```bash
+# 安装 Docker Engine（官方仓库）
+sudo apt update
+sudo apt install ca-certificates curl
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+sudo apt update
+sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+# 免 sudo 使用 Docker
+sudo usermod -aG docker $USER
+newgrp docker
+
+# 验证
+docker --version
+docker run hello-world
+```
+
+#### Linux (Fedora/RHEL)
+
+```bash
+sudo dnf install dnf-plugins-core
+sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
+sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+```
+
+### Podman（Docker 替代品，无守护进程）
+
+Podman 兼容 Docker CLI 命令，但不需要后台守护进程，更轻量：
+
+```bash
+# macOS
+brew install podman
+podman machine init
+podman machine start
+
+# Ubuntu/Debian
+sudo apt install podman
+
+# Fedora（预装）
+podman --version
+
+# Windows
+winget install RedHat.Podman
+```
+
+使用方式与 Docker 几乎一致（将 `docker` 替换为 `podman`）：
+```bash
+podman run hello-world
+podman ps
+podman images
+```
+
+### Docker 常见问题
+
+**"Cannot connect to the Docker daemon"**：
+```bash
+# Linux：启动 Docker 服务
+sudo systemctl start docker
+
+# macOS/Windows：确保 Docker Desktop 正在运行
+
+# WSL2：可能需要重启 Docker Desktop
+```
+
+**"permission denied while trying to connect to the Docker daemon socket"**：
+```bash
+# 将当前用户加入 docker 组
+sudo usermod -aG docker $USER
+# 重新登录（或执行 newgrp docker）
+```
+
+**Docker Desktop 占用资源过高**：
+在 Docker Desktop Settings → Resources 中调整 CPU 和内存限制。WSL2 后端用户也可编辑 `~/.wslconfig`：
+```ini
+[wsl2]
+memory=4GB
+processors=2
+```
+
+---
+
+## WSL2 安装与配置（仅 Windows）
+
+WSL2（Windows Subsystem for Linux 2）让 Windows 用户可以原生运行 Linux 环境，是运行 Python 脚本、Docker、以及各种开发工具的最佳方式。
+
+### 检测 WSL2
+
+```powershell
+# 检查 WSL 是否已安装
+wsl --status
+
+# 查看已安装的 Linux 发行版
+wsl --list --verbose
+```
+
+### 系统要求
+
+- Windows 11（21H2 或更高）或 Windows 10（版本 2004，Build 19041 或更高）
+- CPU 虚拟化已启用（BIOS 中的 Intel VT-x / AMD-V）
+
+### 安装 WSL2
+
+```powershell
+# 以管理员权限运行 PowerShell
+
+# 一键安装（包括 WSL2 内核 + Ubuntu 默认发行版）
+wsl --install
+
+# 安装完成后需要重启计算机
+# 重启后 Ubuntu 窗口会自动打开，提示设置用户名和密码
+```
+
+### 安装指定发行版
+
+```powershell
+# 查看可用发行版
+wsl --list --online
+
+# 安装指定发行版
+wsl --install -d Ubuntu-24.04
+wsl --install -d Debian
+
+# 设置默认发行版
+wsl --set-default Ubuntu-24.04
+```
+
+### 确保使用 WSL2（而非 WSL1）
+
+```powershell
+# 查看当前版本
+wsl --list --verbose
+# 输出中 VERSION 列应为 2
+
+# 如果显示为 1，升级到 WSL2
+wsl --set-version Ubuntu 2
+
+# 将 WSL2 设为未来安装的默认版本
+wsl --set-default-version 2
+```
+
+### WSL2 中配置开发环境
+
+进入 WSL2 后，按 Linux 方式配置即可（参考上方的 Python/Node.js/Docker Linux 安装章节）：
+
+```bash
+# 进入 WSL2
+wsl
+
+# 更新系统
+sudo apt update && sudo apt upgrade -y
+
+# 安装 Python
+sudo apt install python3 python3-pip python3-venv
+
+# 安装 Node.js
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install nodejs
+
+# 安装 Docker（推荐使用 Docker Desktop 的 WSL2 后端，而非在 WSL2 内安装）
+```
+
+### WSL2 与 Windows 文件互访
+
+```bash
+# 在 WSL2 中访问 Windows 文件
+ls /mnt/c/Users/你的用户名/Desktop/
+
+# 在 Windows 中访问 WSL2 文件（资源管理器地址栏）
+# \\wsl$\Ubuntu\home\你的用户名\
+
+# 在 Windows Terminal 中打开 WSL2
+wsl ~
+```
+
+### WSL2 常见问题
+
+**"WslRegisterDistribution failed with error: 0x80370102"**：
+CPU 虚拟化未启用。重启计算机进入 BIOS，启用 Intel VT-x 或 AMD-V。
+
+**WSL2 网络问题（无法访问互联网）**：
+```bash
+# 在 WSL2 中
+echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
+```
+
+**WSL2 磁盘空间不足**：
+```powershell
+# 压缩 WSL2 虚拟磁盘
+wsl --shutdown
+# 使用 diskpart 压缩 ext4.vhdx（高级操作，请备份后再执行）
+```
+
+**DesireCore Windows 用户建议**：DesireCore 的环境检查功能（设置 → 环境检查）可以自动检测 Windows 版本、CPU 虚拟化、WSL2 安装状态，并提供一键修复。
+
+---
+
 ## 系统工具安装

 ### LibreOffice