WSL基础环境配置方案

在 Windows Subsystem for Linux (WSL) 环境中搭建一个完整的基础开发环境，可以极大地提升在 Windows 上进行 Linux 开发和运维任务的效率。以下是一套详细的方案，涵盖从安装 WSL 到配置 Docker、Kubernetes、Tekton 以及其他必要工具的所有步骤。该方案特别适用于需要在 WSL 中部署和管理 Tekton 的场景。

目录

1. 前置条件
2. 步骤 1：安装 WSL 和 Ubuntu
3. 步骤 2：更新系统软件包
4. 步骤 3：安装 Docker 和 Docker Desktop
5. 步骤 4：安装 kubectl
6. 步骤 5：安装 Helm
7. 步骤 6：安装 yq
8. 步骤 7：安装 Git
9. 步骤 8：安装其他常用工具
10. 步骤 9：配置环境变量和别名
11. 步骤 10：验证安装
12. 步骤 11：配置 Kubernetes 集群（可选）
13. 步骤 12：安装 Tekton
14. 常见问题与解决方案
15. 总结

---

前置条件

在开始之前，请确保您具备以下条件：

• Windows 10/11：已安装并启用 WSL。
• 管理员权限：在 Windows 上执行安装和配置操作需要管理员权限。
• 稳定的互联网连接：用于下载所需的软件包和工具。

步骤 1：安装 WSL 和 Ubuntu

1.1 启用 WSL 和虚拟机功能

打开 PowerShell，以管理员身份运行以下命令来启用 WSL 和虚拟机平台：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

1.2 更新 WSL 至 WSL 2

WSL 2 提供了更好的性能和完整的 Linux 内核支持。首先，确保您的 Windows 版本支持 WSL 2（Windows 10 版本 1903 或更高，构建号 18362 或更高）。

下载并安装 WSL 2 内核更新包：WSL 2 Linux 内核更新包

1.3 设置 WSL 2 作为默认版本

wsl --set-default-version 2

1.4 安装 Ubuntu 发行版

在 Microsoft Store 中搜索 Ubuntu，选择最新的 LTS 版本（例如 Ubuntu 22.04 LTS）并安装。

或者，使用 PowerShell 安装特定版本：

wsl --install -d Ubuntu-22.04

1.5 初始化 Ubuntu

安装完成后，启动 Ubuntu 应用，设置用户名和密码。

步骤 2：更新系统软件包

启动 Ubuntu 终端，运行以下命令更新软件包列表并升级已安装的软件包：

sudo apt update && sudo apt upgrade -y

步骤 3：安装 Docker 和 Docker Desktop

3.1 安装 Docker Desktop for Windows

1. 下载 Docker Desktop：Docker Desktop 下载页面
2. 安装 Docker Desktop：按照提示完成安装。
3. 配置 WSL 集成：

• • 打开 Docker Desktop，进入 Settings > Resources > WSL Integration。
  • 启用与您安装的 Ubuntu 发行版的集成。

3.2 验证 Docker 安装

在 Ubuntu 终端中运行：

docker --version

您应该看到类似如下的输出：

Docker version 20.10.7, build f0df350

3.3 配置非 root 用户使用 Docker（可选）

默认情况下，使用 Docker 需要 root 权限。为了避免每次使用 sudo，可以将当前用户添加到 docker 组：

sudo usermod -aG docker $USER

注意：添加到 docker 组后，需要重新启动 WSL 终端或注销并重新登录。

步骤 4：安装 kubectl

kubectl 是 Kubernetes 的命令行工具，用于与集群交互。

4.1 下载 kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

4.2 安装 kubectl

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

4.3 验证 kubectl 安装

kubectl version --client

您应该看到类似如下的输出：

Client Version: version.Info{Major:"1", Minor:"21", GitVersion:"v1.21.0", ...}

步骤 5：安装 Helm

Helm 是 Kubernetes 的包管理工具。

5.1 下载并安装 Helm

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

5.2 验证 Helm 安装

helm version

您应该看到类似如下的输出：

version.BuildInfo{Version:"v3.7.1", GitCommit:"...", GitTreeState:"clean", GoVersion:"go1.16.5"}

步骤 6：安装 yq

yq 是一个用于处理 YAML 文件的命令行工具。

6.1 下载 yq

sudo wget https://github.com/mikefarah/yq/releases/download/v4.30.6/yq_linux_amd64 -O /usr/local/bin/yq

6.2 赋予执行权限

sudo chmod +x /usr/local/bin/yq

6.3 验证 yq 安装

yq --version

您应该看到类似如下的输出：

yq version 4.30.6

步骤 7：安装 Git

Git 是版本控制系统，常用于代码管理。

7.1 安装 Git

sudo apt install git -y

7.2 验证 Git 安装

git --version

您应该看到类似如下的输出：

git version 2.25.1

7.3 配置 Git（可选）

设置您的用户名和电子邮件：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

步骤 8：安装其他常用工具

为了提高开发效率，建议安装以下工具：

8.1 Vim 或 Nano

sudo apt install vim -y
# 或
sudo apt install nano -y

8.2 Curl 和 Wget

sudo apt install curl wget -y

8.3 Git-lfs（可选）

用于处理大文件的 Git 扩展。

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt install git-lfs -y
git lfs install

步骤 9：配置环境变量和别名

编辑 ~/.bashrc 或 ~/.zshrc 文件，添加常用的环境变量和别名：

nano ~/.bashrc

添加以下内容（示例）：

# 设置 PATH
export PATH=$PATH:/usr/local/bin# 常用别名
alias ll='ls -alF'
alias la='ls -A'
alias l='ls -CF'# Kubernetes 颜色输出
export KUBECTL_EXTERNAL_DIFF=diff

保存并应用更改：

source ~/.bashrc

步骤 10：验证安装

确保所有工具已正确安装并配置：

docker --version
kubectl version --client
helm version
yq --version
git --version

每个命令都应返回对应工具的版本信息。

步骤 11：配置 Kubernetes 集群（可选）

如果您计划在 WSL 中管理 Kubernetes 集群，以下是常见的配置步骤：

11.1 使用 Minikube（本地 Kubernetes）

11.1.1 安装 Minikube

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

11.1.2 启动 Minikube

minikube start --driver=docker

11.2 连接到远程 Kubernetes 集群

如果您使用阿里云容器服务（ACK），请参考阿里云文档获取 kubeconfig 并配置 kubectl。

# 假设 kubeconfig 文件已下载到 Windows，路径如 C:\Users\YourUser\.kube\config
# 在 WSL 中创建 .kube 目录并链接
mkdir -p ~/.kube
ln -s /mnt/c/Users/YourUser/.kube/config ~/.kube/config

注意：根据实际的 Windows 用户名和路径进行调整。

步骤 12：安装 Tekton

在完成基础环境搭建后，您可以按照前面的指导使用阿里云镜像加速和自定义脚本来安装 Tekton。以下是简要步骤：

12.1 准备 Tekton Release YAML 文件

下载 Tekton Pipelines 的 release.yaml 文件：

wget https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml -O tekton-release.yaml

12.2 同步镜像到阿里云

使用之前提供的 sync_tekton_images_wsl.sh 脚本同步镜像。

1. 保存脚本：

nano sync_tekton_images_wsl.sh

粘贴脚本内容，保存并退出。

1. 赋予执行权限：

chmod +x sync_tekton_images_wsl.sh

1. 配置脚本：编辑脚本，修改配置部分：

ALIYUN_REGION="cn-hangzhou"
ALIYUN_NAMESPACE="your-namespace"
ALIYUN_ACCESS_KEY_ID="your-access-key-id"
ALIYUN_ACCESS_KEY_SECRET="your-access-key-secret"
ORIGINAL_YAML_FILE="tekton-release.yaml"
MODIFIED_YAML_FILE="tekton-release-aliyun.yaml"
DOCKER_MIRROR_URL="https://<your-accelerator-url>.mirror.aliyuncs.com"

安全提示：建议使用环境变量存储 AccessKey 信息。

1. 运行脚本：

./sync_tekton_images_wsl.sh

12.3 部署 Tekton

应用修改后的 YAML 文件：

kubectl apply -f tekton-release-aliyun.yaml

12.4 验证 Tekton 部署

检查 Tekton Pods 是否运行正常：

kubectl get pods -n tekton-pipelines

所有 Pods 应处于 Running 状态。

常见问题与解决方案

问题 1：Docker 命令无权限

症状：运行 docker 命令时出现 permission denied 错误。

解决方案：

1. 确保当前用户已添加到 docker 组：

sudo usermod -aG docker $USER

1. 重新启动 WSL 终端或注销并重新登录。

问题 2：yq 解析复杂 YAML 文件失败

症状：脚本无法正确替换 YAML 文件中的所有镜像地址。

解决方案：

1. 检查 YAML 文件结构，确保 image 字段的位置和层级正确。
2. 根据实际 YAML 结构，调整 yq 替换命令。例如，使用更精确的路径或表达式。
3. 考虑使用更高级的脚本或工具处理复杂的 YAML 结构。

问题 3：Tekton Pod 无法启动

症状：Tekton 部署的 Pods 无法启动，状态为 CrashLoopBackOff 或 Error。

解决方案：

1. 查看 Pod 日志，定位具体错误：

kubectl logs <pod-name> -n tekton-pipelines

1. 确认镜像已正确推送到阿里云，并且修改后的 YAML 文件中镜像地址正确。
2. 检查 Kubernetes 集群资源（CPU、内存）是否充足。
3. 确认网络配置和访问权限，确保 Pod 能够访问所需的外部资源。

问题 4：Docker 镜像加速器配置无效

症状：镜像拉取速度仍然缓慢或失败。

解决方案：

1. 确认 DOCKER_MIRROR_URL 配置正确，指向阿里云镜像加速器。
2. 验证 Docker 配置文件是否正确更新：

cat ~/.docker/config.json

应包含 "registry-mirrors" 字段。

1. 重启 Docker 服务：

sudo service docker restart
# 或
sudo systemctl restart docker

1. 测试镜像加速器是否生效：

docker pull busybox

观察是否通过加速器地址拉取。

问题 5：WSL 与 Docker Desktop 网络问题

症状：WSL 无法访问互联网或 Docker 容器无法访问外部网络。

解决方案：

1. 确保 Docker Desktop 的 WSL 集成已启用。
2. 重启 Docker Desktop 和 WSL 实例：

wsl --shutdown

然后重新启动 Docker Desktop 和 WSL 终端。

1. 检查防火墙设置，确保 Docker 和 WSL 不受阻碍。

总结

通过以上步骤，您已经在 Windows 的 WSL 环境中成功搭建了一个完整的基础开发环境，包含 Docker、Kubernetes、Helm、kubectl、yq、Git 等工具。这套环境特别适用于在国内使用阿里云镜像服务部署和管理 Tekton，提升了开发和运维的效率和稳定性。

扩展建议

• 自动化脚本：将环境搭建过程脚本化，便于在不同机器上快速复用。
• 环境变量管理：使用 .env 文件或工具（如 direnv）管理环境变量，增强安全性和可维护性。
• 版本管理：使用工具（如 asdf）管理多版本工具（如 Docker、kubectl、yq 等），便于在项目间切换。
• 备份与恢复：定期备份 WSL 配置和关键文件，确保环境可恢复。

参考资料

• WSL 官方文档
• Docker Desktop for Windows 文档
• Kubernetes 官方文档
• Helm 官方文档
• yq GitHub 仓库
• Tekton 官方文档
• 阿里云容器镜像服务文档

如有任何疑问或需要进一步的帮助，请随时提问！