Windows (WSL)+Docker 部署 GitLab+Runner 实现 CI/CD 并部署到阿里云

背景

GitLab SaaS 版的免费共享 Runner 有月度分钟数限制，不便于生产/测试，原想着在阿里部署gitlab服务，结果2核4G的带不动，所以选择本地安装部署gitlab，自托管 GitLab Runner（无配额限制，推荐），如果是阿里云直接搭建gitlab，会方便很多，镜像可以选择Linux内核的，比如Ubuntu等，我本地是windows环境，所以还得依赖WSL(Windows Subsystem for Linux)

一、前置条件说明

Windows 10(2004 及以上版本)/11 专业版 / 企业版（家庭版需额外配置 WSL）

    # 可通过`winver`命令查看系统版本
    winver

至少8GB内存（GitLab 对资源要求较高，推荐 16GB）
阿里云 ECS 服务器（CentOS 7/8 或 Ubuntu 20.04+）
阿里云账号（需开通容器镜像服务 ACR，可选但推荐）
基础的 Docker、Linux 命令知识

二、前置准备（Windows 环境初始化）

开启WSL2【Windows 系统提供的 “Linux 运行框架”】

没接触过wsl的可以先看一下下面这篇文章，简单了解一下wsl(juejin.cn/post/760585…)

步骤 1：通过控制面板手动启用 WSL 功能

按下Win+R，输入control打开 “控制面板”；
点击「程序」→「程序和功能」→ 左侧「启用或关闭 Windows 功能」；
在弹出的窗口中，勾选以下两个选项：
- 适用于Linux的Windows子系统
- 虚拟机平台
点击「确定」，等待系统安装组件（约 1-2 分钟）；
组件安装完成后，必须重启电脑（这次重启是强制触发功能生效）

步骤 2：验证 WSL 功能是否真的启用

重启后，以管理员身份打开命令提示符（CMD），执行以下命令： cmd

# 查看已启用的Windows功能，确认WSL和虚拟机平台已开启
dism.exe /online /get-features | findstr "Microsoft-Windows-Subsystem-Linux VirtualMachinePlatform"

也可以使用以下命令展示更详细的信息

# 查看 WSL 功能状态 
dism /online /get-featureinfo /featurename:Microsoft-Windows-Subsystem-Linux
# 查看虚拟机平台功能状态 
dism /online /get-featureinfo /featurename:VirtualMachinePlatform

步骤 3：安装 WSL 更新包

方案一：手动下载并安装 WSL2 更新包（微软官方包，稳定）

【别急着下，先看一下方案二】

1. 下载 WSL2 手动更新包（适配 Windows x64/ARM64）

Windows x64 架构（绝大多数 PC / 笔记本） ：微软官方下载链接：wslstorestorage.blob.core.windows.net/wslblob/wsl…
Windows ARM64 架构（如 Surface Pro X） ：微软官方下载链接：wslstorestorage.blob.core.windows.net/wslblob/wsl…

✅ 操作：直接复制链接到浏览器打开，国内下载速度通常在 1-3MB/s，无需登录，下载完成后得到.msi安装包。

2. 安装 WSL2 更新包

双击下载的wsl_update_x64.msi（或 ARM64 版本），弹出安装向导后，一路点击「Next」→「Install」→「Finish」，完成安装；
安装完成后，必须重启电脑（让更新生效）。

注意：安装的时候可能会弹出上面的弹窗

上面的WSL功能没有成功地启用(那关掉wsl功能并重新启用，重启系统)
如果成功启用了wsl功能还是一直弹出，比如我就是的，更新包的安装程序检测到的系统状态仍然不满足条件。这通常是因为功能启用后未完全生效，或者组件注册出现了问题，那我们可以使用命令行更新（绕过 MSI 安装包）【下面方案二】
也可能是系统已经内置了最新的 WSL2 内核，不需要再手动安装这个更新包（手动下载的更新包版本反而和系统内置版本不兼容）。

方案二：用命令行的方式安装wsl2

以管理员身份打开 PowerShell，执行以下命令重置 WSL：

// 这条命令会直接从微软服务器下载并安装最新的 WSL 内核和组件，**无需手动下载 MSI 包**，也能有效避开你遇到的这个检测错误。
wsl --update
// 更新完成后，执行 `wsl --shutdown` 关闭 WSL，然后再次启动即可
wsl --shutdown

如果命令行更新也报错，说明 WSL 的组件注册可能损坏了，可以尝试修复 可以用步骤一中的5，先禁用掉wsl功能，重启电脑再试一下，也可以用命令行的形式

以管理员身份打开 PowerShell，执行以下命令重置 WSL：

// 禁用WSL功能 
dism /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart 
dism /online /disable-feature /featurename:VirtualMachinePlatform /norestart
// 重启电脑 
Restart-Computer

重启后，再次以管理员身份打开 PowerShell，重新启用功能：

dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart 
dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart 
// 修复系统组件（避免组件损坏）
sfc /scannow
// 修复Windows更新组件（兜底）
dism.exe /online /cleanup-image /restorehealth
// 再次重启 
Restart-Computer

注意：如果wsl不是最新版时，执行wsl相关的指令就是一直弹出以下弹窗，要求你更新，这个更新的过程会比较慢，我更新了三次才成功，有时候更新到一半就断了，甚至还出现403这种情况，核心原因是Windows 官方的 WSL 更新源在国内网络环境下访问受限（被拦截 / 限速） ，命令行自动更新的方式无法完成，多尝试几次，或者用上面提到的手动下载更新包，手动更新，也会有不同的坑哈，上面也说明了

注意：不管哪种方式更新的wsl，请记得执行一些指令

// 设置WSL默认版本为2（不是 “必须执行”，但强烈建议执行，能避免后续踩坑）
wsl --set-default-version 2

安装 WSL2 更新包：仅更新 WSL2 的内核 / 核心组件（让你的系统具备运行 WSL2 的能力），但不会修改 WSL 的全局默认版本配置；
执行 wsl --set-default-version 2：设置「所有新安装的 Linux 发行版」默认使用 WSL2 架构（全局配置），是对 WSL 运行模式的 “规则设定”。

三、安装 Ubuntu 子系统

注意：如果是执行wsl相关指令时，你按了任意键更新的wsl，那Ubuntu就自动下载了，我就是的！如果你命令行更新wsl时，用的wsl --install而不是wsl --update，那Ubuntu也应该自动下载了，可以实操试试~

如果已经安装了Ubuntu，那后面安装Ubuntu的步骤可以省略~

回到正题~

重启后，以管理员身份打开命令提示符（CMD/PowerShell），执行以下命令：

# 安装Ubuntu子系统（Docker Desktop依赖）
wsl --install -d Ubuntu

执行wsl --install -d Ubuntu后，系统会自动下载并安装 Ubuntu 子系统（这次是从微软应用商店下载，比 WSL 更新包更稳定），等待安装完成后，按提示设置 Ubuntu 的用户名和密码（随意设置，如用户名chuhe，密码自定义）。

验证 WSL2 安装成功

执行以下命令，输出 “默认版本：2” 且能看到 Ubuntu 子系统，即成功：

# 查看WSL状态
wsl --status
# 查看已安装的Linux子系统(分发)【简写：wsl -l -v】
wsl --list --verbose

正常输出示例：

默认版本：2
  NAME                   STATE           VERSION
* Ubuntu                 Running         2

四、安装 Docker Desktop

1、下载Docker Desktop

下载地址：Docker Desktop 官方下载（Windows 版）

2、安装Docker Deskto

双击下载的安装文件，安装向导中（关键勾选项

✅ Use the WSL 2 based engine（适配你的 WSL2 环境）
✅ Add shortcut to desktop（桌面快捷方式，方便启动）

一路点击「OK」「Install」，等待安装完成（约 2-3 分钟），安装后会提示重启电脑，点击「Close and restart」

3、如何检查 Docker Desktop 是否启用了 WSL 2 引擎

方法1、通过 Docker Desktop 设置界面直接查看

启动 Docker Desktop：从 Windows开始菜单或任务栏托盘图标启动
打开设置：右键点击托盘区的 Docker 鲸鱼图标，选择 "Settings"（设置）
检查选项：在打开的设置窗口中，导航到 "General"（常规）选项卡，查看 "Use the WSL 2 based engine" 是否被勾选

方法2、通过命令行验证（间接确认）

打开 PowerShell 或命令提示符
运行以下命令： docker run --rm hello-world
观察输出：
- 若成功输出 "Hello from Docker!" 等信息，并在输出中包含 "WSL 2" 相关字样，说明 WSL 2 引擎已启用
- 若输出显示 "正在从 Docker 守护进程接收信息..." 但无 WSL 提示，或显示 "无法连接到 Docker daemon"，则可能未启用 WSL 2

方法3、检查 Docker 与 WSL 集成状态

在 Docker 设置窗口中，导航到 "Resources > WSL Integration"
确认您的 WSL 发行版（如 Ubuntu-22.04）是否被勾选 "Enable integration"（启用集成）

注意：为什么这个设置很重要？

性能差异：WSL 2 引擎比传统 Hyper-V 引擎性能更好，容器启动更快，资源占用更低
WSL 集成：启用后，您可以在 WSL 终端中直接使用docker命令，无需额外配置
兼容性：许多现代 Docker 功能（如文件共享、GPU 加速）需要 WSL 2 支持
如果未勾选，如何启用？
1. 在 Docker 设置的 "General" 选项卡中勾选 "Use the WSL 2 based engine"
2. 点击 "Apply & Restart"（应用并重启）保存更改
3. 重启后，再次检查确认已生效

4、验证Docker Desktop启动成功

重启后，双击桌面「Docker Desktop」图标，等待右下角托盘图标显示 “Docker is running”（无红色叉号），说明启动成功。

5、配置 Docker 国内镜像（避免 GitLab 镜像下载慢）

打开 Docker Desktop → 设置（Settings）→ Docker Engine；
在 JSON 配置中添加阿里云镜像源，修改后如下： json { "registry-mirrors": [ "mirror.ccs.tencentyun.com", "hub-mirror.c.163.com", "mirror.aliyuncs.com" ], "experimental": false, "features": { "buildkit": true } }
点击 “Apply & Restart” 保存并重启 Docker。

五、部署GitLab

GitLab 官方没有 Windows 原生安装包（GitLab 底层依赖大量 Linux 系统组件），因此 Windows 下最稳定的部署方式是：通过 Docker Desktop for Windows（基于 WSL2）部署 GitLab 容器

步骤一、本地部署带 “公司（后续都用chuhe代替）” 前缀的 GitLab

1. 创建 chuhe 专属目录（Windows 路径）

在C盘根目录创建分层目录（避免权限问题，建议用英文路径）

打开文件资源管理器，新建文件夹：C:\chuhe-gitlab；
在chuhe-gitlab内再创建 4 个子文件夹：config、data、logs、ssh。

2. 编写 Docker Compose 配置文件（适配 Windows）

打开编辑器，粘贴以下内容（带 “chuhe” 前缀，适配 Windows 路径），保存为docker-compose.yml，放到C:\chuhe-gitlab目录下： services: gitlab-chuhe: image: gitlab/gitlab-ce:latest container_name: gitlab-chuhe restart: always privileged: true environment: GITLAB_OMNIBUS_CONFIG: | external_url 'http://localhost:8929/chuhe' gitlab_rails['gitlab_shell_ssh_port'] = 2222 ports: - "8929:8929" # Web访问端口：本地[前面8080] → 容器[后面8080] - "443:443" - "2222:22" # SSH端口：本地2222 → 容器22 volumes: # Windows路径写法：//c/chuhe-gitlab/xxx 或 C:/chuhe-gitlab/xxx - //c/chuhe-gitlab/config:/etc/gitlab - //c/chuhe-gitlab/data:/var/opt/gitlab - //c/chuhe-gitlab/logs:/var/log/gitlab - //c/chuhe-gitlab/ssh:/etc/ssh shm_size: '512m'
保存后，C:\chuhe-gitlab目录下会有docker-compose.yml和 4 个子文件夹。

3. 启动 GitLab（Windows PowerShell 操作）

按下Win+X，选择 “Windows PowerShell (管理员)”；
切换到 chuhe-gitlab 目录： cd C:\chuhe-gitlab
启动 GitLab 容器（首次启动的时候会比较慢，拉取镜像需要时间，建议搭梯子）： docker-compose up -d
查看容器状态（显示 Up 即启动成功）： docker-compose ps
监控启动日志： docker-compose logs -f gitlab-chuhe 看到GitLab instance ready.即初始化完成（按Ctrl+C退出）

步骤二、初始化 Windows 本地的 chuhe-GitLab

1. 获取初始 root 密码

在 PowerShell 中执行： docker exec -it gitlab-chuhe cat /etc/gitlab/initial_root_password
复制输出的随机密码（一串字符，24 小时内有效）。

2. 访问并配置 GitLab

浏览器打开：http://localhost:8929/chuhe；
用户名输入root，密码粘贴上面复制的初始密码，点击登录；
首次登录会提示修改密码，设置强密码后保存；
创建 chuhe 公司专属组织：
- 顶部菜单栏「Groups」→「New group」；
- 「Group name」填chuhe，「Group path」填chuhe；
- 「Visibility level」选「Private」，点击「Create group」

3. 配置 SSH 密钥（Windows 本地免密访问）

打开 PowerShell（普通用户），生成 chuhe 专属 SSH 密钥： ssh-keygen -t ed25519 -C "邮箱@xxx.com" 连续按 3 次回车（无需设置密码）；
查看并复制公钥： cat C:\Users\你的用户名.ssh\id_ed25519.pub
登录 GitLab → 头像→「Edit profile」→「SSH Keys」，粘贴公钥，标题填chuhe-gitlab-windows，点击「Add key」；
验证 SSH 连接： ssh -T -p 2222 git@localhost 输出Welcome to GitLab, @root!即成功。

注意：Windows 下 GitLab 常见问题排查

1. 8080 端口被占用（无法访问）

查看端口占用： netstat -ano | findstr :8080
结束占用进程（替换 PID 为实际数字）： taskkill /F /PID 1234
修改docker-compose.yml中的端口（如8081:80），
同步修改external_url为http://localhost:8081/chuhe，
重启容器： docker-compose restart

2. 目录权限错误（日志中提示 Permission denied）

Windows 下给C:\chuhe-gitlab目录赋予完全控制权限：右键文件夹→属性→安全→编辑→添加 “Everyone”，权限勾选 “完全控制”

六、安装并注册 GitLab Runner（Docker 方式）

GitLab Runner是执行 CI/CD 任务的代理，我们同样用Docker部署，与 GitLab 关联。

1 获取 GitLab Runner 注册令牌

登录 GitLab，进入项目(如：test-ci-cd) > 设置 > CI/CD > Runner`（展开 “Runner” 部分）。
复制 “项目令牌”（Project registration token）和 GitLab 实例 URL（如http://<你的WSL_IP>:8929/）。

2 部署并注册 GitLab Runner

创建 Runner 工作目录： mkdir -p ~/gitlab-runner/config cd ~/gitlab-runner
注册 Runner（核心步骤）：运行 docker run --rm -it -v $(pwd)/config:/etc/gitlab-runner gitlab/gitlab-runner:latest register 执行后按提示输入以下信息：
- Enter the GitLab instance URL: 输入 GitLab 地址（如http://172.17.0.2:8929/）
- Enter the registration token: 粘贴步骤 4.1 复制的项目令牌
- Enter a description for the runner: 输入描述（如docker-runner-for-test）
- Enter tags for the runner (comma separated): 输入标签（如wsl,ubuntu,docker，后续 CI/CD 会用到）
- Enter executor: 输入docker（表示用 Docker 作为执行器，符合 “镜像方式” 要求）
- Enter default Docker image: 输入基础镜像（如alpine:latest）
启动/注册 Runner 容器： docker run -d --name gitlab-runner --restart always
-v $(pwd)/config:/etc/gitlab-runner
-v /var/run/docker.sock:/var/run/docker.sock
gitlab/gitlab-runner:latest
验证 Runner 状态：
- 回到 GitLab 的CI/CD > Runner页面，能看到 Runner 状态为 “在线（Online）” 即注册成功。
- 终端执行docker logs gitlab-runner，无报错即运行正常。

七、阿里云服务器准备（部署环境）

步骤一、阿里云 ECS 基础配置

登录阿里云 ECS 控制台，确保服务器安装了 Docker（参考命令）： # CentOS系统安装Docker yum install -y docker systemctl start docker systemctl enable docker
```
# Ubuntu系统安装Docker
apt update && apt install -y docker.io
systemctl start docker
systemctl enable docker
```
开放端口：在阿里云安全组中开放 80/443/22 端口（根据项目需求调整）。
配置免密登录（让 Runner 能免密部署到阿里云）：
- 在 Windows WSL 终端生成 SSH 密钥：
```
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
# 一路回车，默认生成~/.ssh/id_rsa（私钥）和id_rsa.pub（公钥）
```
- 将公钥复制到阿里云 ECS： ssh-copy-id root@<阿里云ECS公网IP> // 输入ECS密码，完成公钥上传
- 验证免密登录：ssh root@<阿里云ECS公网IP>，无需密码即可登录即成功。

步骤二、配置阿里云容器镜像服务 ACR（可选）

若需要将构建好的镜像推送到阿里云 ACR（避免本地镜像传输问题）：

登录阿里云容器镜像服务控制台，创建命名空间（如test-namespace）和镜像仓库（如test-app）。

注意： 如果开启了自动创建仓库，可以在仓库不存在的情况下直接推送镜像，系统会自动创建对应的仓库。

在 WSL 终端登录 ACR： docker login --username=<阿里云账号> registry.cn-hangzhou.aliyuncs.com # 输入ACR密码（需在控制台生成访问凭证）

八、CI/CD

编写 CI/CD 配置文件（.gitlab-ci.yml）

在 GitLab 的test-ci-cd项目中，新建.gitlab-ci.yml文件（核心 CI/CD 逻辑），以下是 “构建镜像→推送镜像→部署到阿里云” 的完整示例：

# 定义阶段：构建→推送→部署
stages:
  - build
  - push
  - deploy

# 全局变量
variables:
  # 镜像名称（替换为你的ACR地址/本地镜像名）
  IMAGE_NAME: registry.cn-hangzhou.aliyuncs.com/test-namespace/test-app:latest
  # 阿里云ECS公网IP
  ALIYUN_IP: <你的阿里云ECS公网IP>

# 阶段1：构建Docker镜像
build_image:
  stage: build
  tags:
    - docker  # 匹配Runner的标签
  script:
    # 假设项目根目录有Dockerfile，构建镜像
    - docker build -t $IMAGE_NAME .
  only:
    - main  # 仅main分支触发

# 阶段2：推送镜像到阿里云ACR
push_image:
  stage: push
  tags:
    - docker
  script:
    - docker push $IMAGE_NAME
  only:
    - main
  dependencies:
    - build_image  # 依赖build阶段

# 阶段3：部署到阿里云ECS
deploy_to_aliyun:
  stage: deploy
  tags:
    - docker
  script:
    # 免密登录阿里云，拉取镜像并启动容器
    - ssh root@$ALIYUN_IP "docker pull $IMAGE_NAME"
    - ssh root@$ALIYUN_IP "docker stop test-app || true"  # 停止旧容器（不存在则忽略）
    - ssh root@$ALIYUN_IP "docker rm test-app || true"    # 删除旧容器
    - ssh root@$ALIYUN_IP "docker run -d --name test-app -p 80:80 $IMAGE_NAME"
  only:
    - main
  dependencies:
    - push_image

关键说明：

tags：必须匹配 Runner 注册时的标签，否则 Runner 不会执行任务；
Dockerfile：需在项目根目录编写（如简单的 Nginx 测试镜像），示例： FROM nginx:alpine COPY index.html /usr/share/nginx/html/
index.html：新建测试页面，内容任意（如<h1>CI/CD Test Success!</h1>）。

九、测试 CI/CD 流程

将.gitlab-ci.yml、Dockerfile、index.html提交到 GitLab 的 main 分支： # 在本地项目目录执行 git add . git commit -m "Add CI/CD config" git push origin main
登录 GitLab，进入项目CI/CD > 流水线，查看任务执行状态：
- 若所有阶段（build/push/deploy）都显示 “成功（green）”，则 CI/CD 流程完成；
- 若失败，点击对应阶段查看日志（常见问题：Runner 离线、SSH 免密失败、镜像推送失败）。
验证部署结果：打开浏览器访问http://<阿里云ECS公网IP>，能看到index.html的内容即部署成功。

十、常见问题排查

GitLab 启动慢 / 无法访问：
- 检查 WSL 内存分配（推荐给 Ubuntu 分配 4G 以上）；
- 确认端口未被占用（netstat -tulpn | grep 8929）。
Runner 注册失败：
- 检查 GitLab 地址是否正确（需用 WSL 的 IP，而非localhost）；
- 确认 Runner 容器能访问 GitLab（ping <WSL_IP>）。
部署阶段 SSH 失败：
- 检查阿里云 ECS 安全组是否开放 22 端口；
- 验证 WSL 的 SSH 公钥是否已上传到 ECS。

总结

核心成果：WSL 和虚拟机平台已成功启用，这是 Docker Desktop 运行的基础；
关键配置：通过wsl --set-default-version 2将 WSL 默认版本设为 2，确保 Docker 兼容；
验证标准：wsl --list --verbose显示 Ubuntu 的 VERSION 为 2，即 WSL2 环境配置完成；
后续操作：安装 Docker Desktop 后，即可按教程部署带 “chuhe” 前缀的 GitLab，流程和之前一致。
核心环境依赖：Windows WSL2 + Docker Desktop 是基础，需确保 WSL 与 Docker 的集成配置正确；
CI/CD 核心文件：.gitlab-ci.yml定义了 “构建 - 推送 - 部署” 全流程，tags需匹配 Runner 标签才能执行；
阿里云关键配置：免密 SSH 登录是部署的核心，ACR 用于镜像托管（可选但提升稳定性）；
资源注意：GitLab 对内存要求高，本机需分配足够资源，否则会启动失败或卡顿。

通过这套流程，你可以实现从本地代码提交到阿里云自动部署的完整 CI/CD 闭环，后续可根据实际项目需求扩展.gitlab-ci.yml（如增加测试阶段、多环境部署等）。

另外Docker Hub服务器在国外，即使是配置国内官方镜像加速源，有时候也会拉取失败，建议搭个梯子~