Windows 下 GitLab 完整使用指南

本文覆盖Git 客户端安装、SSH 配置、GitLab 账号 / 仓库操作、Git 命令实战、GitLab Runner 部署、常见问题，附可直接复制的命令与权威博文链接，适合从入门到日常开发使用。

一、Windows 上 GitLab 的两种使用场景

1. 作为开发者（连接远程 GitLab 仓库，最常用）

• 安装 Git 客户端，通过 Git Bash / Git GUI 操作本地仓库，推送 / 拉取代码到公司 / 个人 GitLab 服务器（gitlab.com 或自建 GitLab）。
• 无需在 Windows 本地搭建 GitLab 服务，仅需客户端工具。

2. 作为管理员（在 Windows 本地搭建 GitLab 服务）

• GitLab 官方不支持原生 Windows 安装 ，仅支持 Linux 系统。Windows 搭建需通过 Docker Desktop 运行 Linux 容器部署 GitLab 服务。

---

二、场景一：Windows 开发者使用 GitLab（核心流程）

（一）安装 Git 客户端（必备）

1. 下载 Git

• 官网：https://git-scm.com/download/win
• 选择 64-bit 版本（Windows 10/11 主流），下载安装包。

2. 安装配置（关键步骤）

1. 双击安装包，一路 Next ，关键配置：
   • Choosing the default editor used by Git ：推荐选 Visual Studio Code（或 Notepad++），方便编辑提交信息。
   • Adjusting your PATH environment ：选 Git from the command line and also from 3rd-party software（让 Git 命令在 CMD、PowerShell、Git Bash 都可用）。
   • Configuring the line ending conversions ：选 Checkout Windows-style, commit Unix-style line endings（适配跨平台换行）。
   • 最后一步勾选 Launch Git Bash，安装完成后自动打开 Git Bash。

3. 验证安装

打开 Git Bash，输入命令：

git --version

显示版本号（如 git version 2.45.1.windows.1）即安装成功。

4. 初始配置（全局用户名 / 邮箱，与 GitLab 账号一致）

git config --global user.name "你的GitLab用户名"
git config --global user.email "你的GitLab注册邮箱"
# 查看配置
git config --global --list

（二）配置 SSH 密钥（免密登录 GitLab，推荐）

1. 生成 SSH 密钥

打开 Git Bash，执行命令（一路回车，无需设置密码）：

ssh-keygen -t ed25519 -C "你的GitLab邮箱"

• 密钥默认存储路径：C:\Users\你的用户名\.ssh\
• 生成两个文件：id_ed25519（私钥，保密）、id_ed25519.pub（公钥，上传 GitLab）。

2. 复制公钥内容

cat ~/.ssh/id_ed25519.pub
# 或直接打开文件复制全部内容

3. 上传公钥到 GitLab

1. 登录 GitLab 网页（https://gitlab.com 或公司自建地址）。
2. 点击右上角头像 → Settings → SSH Keys。
3. 在 Key 输入框粘贴公钥，Title 填标识（如 "Windows 办公电脑"），点击 Add key。

4. 验证 SSH 连接

# 替换为你的GitLab域名（公司自建则填公司地址）
ssh -T git@gitlab.com

出现 Welcome to GitLab, @你的用户名! 即成功。

（三）GitLab 网页端基础操作（账号 / 仓库）

1. 注册 / 登录 GitLab

• 官网注册：https://gitlab.com/users/sign_up
• 公司自建 GitLab：联系管理员获取账号。

2. 创建远程仓库

1. 登录后点击右上角 New project。
2. 填写：Project name （仓库名）、Visibility Level（Private 私有 / Internal 内部 / Public 公开）。
3. 点击 Create project，完成创建。

3. 仓库基本信息（获取仓库地址）

创建后，在仓库首页点击 Clone ，复制 SSH 地址 （如 git@gitlab.com:username/project.git）。

（四）Git 命令实战（本地 ↔ GitLab 远程仓库）

1. 克隆远程仓库到本地（首次操作）

# 进入目标目录（如 D:\Projects）
cd /d/Projects
# 克隆仓库（替换为你的SSH地址）
git clone git@gitlab.com:username/project.git
# 进入仓库目录
cd project

2. 本地开发 + 提交到 GitLab

# 1. 查看文件状态
git status
# 2. 添加文件到暂存区（. 代表所有文件）
git add .
# 3. 提交到本地仓库（填写提交信息）
git commit -m "feat: 新增功能模块"
# 4. 推送到GitLab远程仓库（默认main分支）
git push origin main

3. 拉取远程最新代码（多人协作必备）

git pull origin main

4. 分支操作（GitLab 开发核心）

# 查看所有分支
git branch -a
# 创建并切换到新分支
git checkout -b feature/login
# 推送新分支到GitLab
git push origin feature/login
# 合并分支（如合并到main）
git checkout main
git merge feature/login
# 删除本地分支
git branch -d feature/login
# 删除远程分支
git push origin --delete feature/login

5. 提交历史与回退

# 查看提交日志
git log --oneline
# 回退到指定版本（保留修改）
git reset --soft 提交哈希值
# 回退到指定版本（丢弃修改，谨慎使用）
git reset --hard 提交哈希值

（五）GitLab 高级操作（Merge Request、Issue、CI/CD）

1. Merge Request（MR，代码合并）

1. 本地开发完成后，推送分支到 GitLab。
2. 进入 GitLab 仓库 → Merge Requests → New merge request。
3. 选择源分支 （你的开发分支）和目标分支 （main），填写标题与描述，点击 Create merge request。
4. 等待代码 review，通过后点击 Merge 合并代码。

2. Issue（任务管理）

• 仓库 → Issues → New issue，创建任务、分配负责人、设置截止时间，关联 MR 实现任务闭环。

3. CI/CD（GitLab Runner，Windows 部署）

GitLab Runner 是执行 CI/CD 任务的代理，Windows 部署步骤GitLab：

1. 创建目录：C:\GitLab-Runner。

2. 下载 64 位 Runner 二进制：https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe，重命名为 gitlab-runner.exe 放入目录。

3. 以管理员身份打开 PowerShell，执行： powershell

   cd C:\GitLab-Runner
   # 注册Runner（替换为你的GitLab地址、token）
   .\gitlab-runner.exe register --url https://gitlab.com --registration-token 你的项目token
   # 安装为系统服务
   .\gitlab-runner.exe install
   # 启动服务
   .\gitlab-runner.exe start

4. 仓库根目录创建 .gitlab-ci.yml，配置 CI/CD 流程（如构建、测试、部署）。

---

三、场景二：Windows 本地搭建 GitLab 服务（Docker 方式）

1. 安装 Docker Desktop

• 官网下载：https://www.docker.com/products/docker-desktop/
• 安装后启动，切换为 Linux 容器模式（右下角 Docker 图标右键切换）。

2. 拉取并运行 GitLab 容器

打开 PowerShell，执行命令：

# 创建持久化存储卷
docker volume create gitlab-config
docker volume create gitlab-logs
docker volume create gitlab-data
# 启动GitLab容器（替换hostname为你的域名/IP）
docker run --detach `
--hostname gitlab.local `
--publish 443:443 --publish 80:80 --publish 22:22 `
--name gitlab `
--restart always `
--volume gitlab-config:/etc/gitlab `
--volume gitlab-logs:/var/log/gitlab `
--volume gitlab-data:/var/opt/gitlab `
gitlab/gitlab-ce:latest

3. 访问与初始登录

1. 等待容器启动（约 5-10 分钟），浏览器访问 http://localhost。

2. 初始管理员账号：root，密码查看命令：

   docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

3. 登录后立即修改初始密码。

---

四、Windows 下 GitLab 常见问题与解决

1. SSH 连接失败：检查公钥是否正确上传、Git Bash 路径是否正确、防火墙是否放行 22 端口。
2. git push 报错 Permission denied：确认 SSH 密钥配置正确，或使用 HTTPS 地址（输入 GitLab 账号密码）。
3. Docker 启动 GitLab 报 502 Bad Gateway：等待容器完全启动，或增加内存分配（Docker 设置 → Resources → Memory 调至 4GB 以上）。
4. Git Bash 中文乱码 ：Git Bash 右键 → Options → Text → 字符集选 UTF-8。