如果你坐在新配的电脑前刚把Git和GitLab从零到一折腾了一遍应该能理解这篇东西想讲什么装好Git、配对SSH、部署一套能用的GitLab社区版再跑通本地项目和远端仓库之间那套日常操作。看起来是五六件小事串起来处处有坑。这篇文章就是我基于一次完整实操写出来的基本覆盖从git安装到gitlab使用的整条链路适合刚接触Git和GitLab的新手也适合准备在公司内网自己搭一套GitLab的运维同学参考。说明文章里的命令我都按“Windows下Git Bash Linux服务器”两条线来写命令部分可以直接复制调整路径和域名记得替换成自己的。1. 先把环境搞定Git安装的路线选择与版本细节1.1 Windows用户最容易翻车的其实是下载环节说句实在话Git在Windows上的安装向导本身没什么难度难的是很多人卡在下载这一步——官网直连速度不稳定下载到一半断掉的情况不少。我的做法是直接用国内镜像站下载安装包速度快也稳阿里云镜像、清华镜像都有和官方完全同步的版本。找到最新的64位exe下载完直接双击运行。运行安装向导时大部分选项保持默认就行但有三处我会手动确认。第一安装路径尽量不要带空格。虽然现代Git对路径兼容已经做得很好但某些IDE和脚本在解析带空格的路径时还是可能出幺蛾子为了省事我一般直接装到C:\Program Files\Git之外的自定义路径比如D:\software\Git。第二在“Adjusting your PATH environment”这一步强烈建议选“Git from the command line and also from 3rd-party software”。这样Windows Terminal、CMD、PowerShell里都能直接敲git命令不必每次都打开Git Bash。很多教程默认让你用Git Bash导致后续在vscode、IntelliJ IDEA里配置终端时找不到git命令根源就在PATH这一步。第三换行符转换策略。Windows和Linux混用的团队建议把core.autocrlf设为input或true避免每次切换平台后出现大量“整个文件都变了”的假差异。我个人的习惯是Windows上设trueLinux服务器上不设置保持默认。安装完成后打开终端执行git --version能看到版本号就说明安装成功了。如果输出的是“git不是内部或外部命令”那就回去检查PATH那一步是不是选错了。1.2 Linux服务器包管理器快但版本可能偏老服务器上装Git最常见的方式是走包管理器# Ubuntu/Debian sudo apt update sudo apt install git -y # CentOS/RHEL sudo yum install git -y这种方式的优点是快缺点是版本通常偏老。比如某些发行版默认源里Git版本停留在2.3x而新版本的GitLab对Git客户端版本有最低要求。如果后面遇到git push到GitLab一直提示协议或认证相关的诡异问题可以先检查本机Git版本再决定要不要升级。部署GitLab之前建议先看一眼官方文档里写的“最低Git版本要求”确保两头都不落后。我自己就踩过一回服务器上Git是2.17GitLab已经升级到较新的版本结果某次push时直接报协议错误排查了半天才定位到是客户端版本太旧。1.3 装好之后的第一件事配置身份信息这里有个新手特别容易忽略的操作Git装好后第一件事不是急着clone而是先设置全局身份。因为每一次commit都会记录作者信息如果这步偷懒GitLab提交历史里就会出现一堆没有归属的提交记录后期追溯问题非常痛苦。git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这个邮箱不需要和GitLab注册邮箱完全一致它只是一个提交记录的标识字段。但如果公司有代码审计需求还是建议统一用企业邮箱保持一致。2. 装完Git别急着用SSH密钥、免密登录与认证细节2.1 为什么我优先选SSH而不是HTTPSGit连接远端有两种常用方式HTTPS和SSH。HTTPS第一次push或pull时需要输入GitLab的用户名密码或访问令牌体验比较割裂。SSH则是用一对公钥和私钥完成认证配置好后push和pull全程不需要输密码也就是大家常说的“git免密”。团队协作场景里SSH还有一个好处权限控制更干净。管理员可以通过密钥管理严格控制谁能访问代码库而HTTPS的密码一旦泄露影响面往往更大。所以在任何长期使用的开发机上我默认配SSH。2.2 生成密钥并配置到GitLab生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱或备注一路回车即可会在用户主目录的.ssh文件夹下生成两个文件私钥id_ed25519和公钥id_ed25519.pub。私钥是绝密文件不能外传公钥可以放心提供给GitLab。然后在GitLab页面右上角头像 → Preferences → SSH Keys把公钥内容完整粘贴进去保存。不同平台GitLab、GitHub、Gitee的密钥配置逻辑是通用的所以“git配置gitee密钥”和配置GitLab的步骤完全一致配过一次就懂了。这里补充一句为什么用ed25519而不是传统的RSA因为GitLab较新版本对RSA密钥长度有更严格的要求2048位以下的RSA可能会被拒绝。ed25519是目前各平台兼容性最好、生成也快的算法新环境我无脑选它。2.3 验证免密是否生效配置完成后用终端验证ssh -T git你的gitlab域名看到类似“Welcome to GitLab, 用户名!”的输出就说明SSH通道已经通了。新手可能会困惑这条命令看起来像登录用户为什么没有输密码因为这里是通过git这个系统账号做握手验证实际认证靠公钥完成密码自然就不需要了。如果命令卡住不动或者报Permission denied按这三层排查端口通不通公司内网有时不用默认22端口需要看GitLab的SSH端口配置公钥在不在去GitLab确认一下公钥是否真的保存成功私钥对不对检查本地.ssh目录权限私钥文件权限建议600Windows上则确认OpenSSH读取的密钥目录是否正确。3. GitLab从哪里来Docker部署社区版的全流程3.1 为什么建议用Docker部署GitLab关于GitLab部署社区两种主流方式用Omnibus包直接装或者用Docker跑官方镜像。个人使用、内网小团队使用我偏向Docker。原因很实际Omnibus安装要对系统版本、依赖库做一堆前置准备而且GitLab版本对操作系统有明确限制。热词里“gitlab 19只支持ubuntu 24.04”这类情况就属于系统版本兼容问题直接用Docker能绕开大部分系统层面的坑——运行环境被镜像封装好了宿主机只要满足Docker运行条件即可。3.2 docker run部署的核心参数用一个最小化命令启动GitLab社区版sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8022:22 --publish 8080:80 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest几个参数逐个解释--hostname容器内GitLab对外识别的域名或IP。如果内网用IP访问直接填服务器内网IP。--publish端口映射。宿主机8080映射容器内80宿主机8022映射容器内22。为什么不做默认端口映射因为宿主机很可能已经占用了80和22。后面遇到“gitlab启动不了”的报错一半以上是端口冲突。--volume挂载目录。config、logs、data这三块必须持久化否则容器重建后数据全部丢失等于白干活。跑起来之后不能马上访问。GitLab首次初始化需要几分钟到十几分钟不等具体取决于服务器性能。用下面命令观察日志docker logs -f gitlab看到类似“GitLab is running”的日志服务才算真正就绪。首次访问时页面报502或503很常见别急多等一会儿再刷新。3.3 修改端口与读取root密码关于“ubuntu gitlab 更该端80口号”本质就是调整GitLab对外端口。Docker部署场景下最简单方式是把启动命令里的--publish主机端口改掉比如--publish 8090:80。如果是Omnibus方式部署则需要修改/etc/gitlab/gitlab.rb里的external_url和nginx端口改完执行sudo gitlab-ctl reconfigureGitLab社区版首次启动后会生成一个初始root密码存放在容器内/etc/gitlab/initial_root_password文件里docker exec -it gitlab cat /etc/gitlab/initial_root_password这个文件只在第一次初始化时存在。如果错过了可以在容器内执行gitlab-rake resets相关命令重置管理员密码。3.4 部署完先做几件安全的事GitLab部署完成后别急着建项目先把安全基线打好。第一调整对外端口并用防火墙限制访问范围不要把GitLab直接暴露到公网。第二进入管理后台在“Settings → General”里关闭公开注册避免陌生账号随意注册进来。第三关注GitLab官方安全公告。GitLab历史上有过几个比较知名的高危漏洞通用修复方案就是“升级到修复版本并检查相关配置项”。所以真正要记得的动作是建立版本更新关注渠道安全更新发布时及时升级别拖。4. GitLab上的项目流转新增、导入、拉取与上传4.1 新增项目的完整流程GitLab首页的“新建项目”入口很显眼填好项目名、描述选择可见性等级。我的习惯是公司内网一律私有或内部公开权限风险太高个人项目如果只是自己保管也选私有。项目建好后页面会给出两种仓库地址HTTPS和SSH。前文已经配好了SSH密钥这里直接复制SSH地址即可。4.2 外部项目导入GitLab的方式“gitlab导入项目”算是高频需求。GitLab原生支持从其他Git平台导入项目路径是“New Project → Import Project”。GitLab提供GitHub、Gitee等多个平台的导入选项导入时通过各平台生成的Token授权会把仓库、提交历史、分支等信息一并迁移过来。如果只是想把一个没有远端历史的项目导入GitLab还有个更直接的办法本地初始化Git仓库后推送到GitLab新建的空仓库下面一节详细写。4.3 本地已有项目上传到GitLab这是“本地项目上传到gitlab”场景的标准操作。在项目根目录执行git init git add . git commit -m 初始提交 git remote add origin gitgitlab.example.com:username/project.git git push -u origin master按顺序解释git init创建隐藏的.git目录这是整个仓库的核心git add .把当前目录所有文件加入暂存区git commit -m 初始提交生成第一个提交记录git remote add origin 地址和远端仓库建立关联git push -u origin master首次推送并指定默认上游分支。提醒一点很多人在push时遇到“fatal: not a git repository (or any of the parent directories): .git”原因就是没有先git init或者命令执行目录不是仓库根目录。如果你用IntelliJ IDEA操作路径是File → New → Project from Version Control粘贴GitLab仓库的SSH地址IDEA自动拉取。本地已有项目想传上去则用VCS → Import into Version Control → Share Project on GitLab。SourceTree这类图形化工具本质也是封装git remote add、git push这些操作在仓库设置里配置远端地址即可。4.4 从GitLab拉取代码到本地全新克隆git clone gitgitlab.example.com:username/project.git后续同步远端更新git pull origin masterclone和pull的区别clone是把整个仓库完整复制到本地只需要一次pull是在已有仓库基础上获取远端新增提交并合并到当前分支。本地有未提交改动时直接pull可能出现冲突或“无法合并”的提示稳妥做法是先提交或暂存git stash拉完再恢复。5. 日常开发上手最快的几个Git操作5.1 分支合并git merge的正确使用姿势团队协作里“git分支合并”绕不开。常规流程从master/main拉出功能分支开发完合并回去。git checkout -b feature/login # 开发一段时间后 git add . git commit -m 完成登录功能 git checkout master git pull origin master git merge feature/login经验之谈执行merge之前先git pull更新目标分支能解决大部分冲突。如果merge时报告冲突Git会列出冲突文件打开后能看到 HEAD和分隔标记手动保留需要的代码删掉标记再git add、git commit。我在项目里通常建议团队采用简单粗暴的主干开发加短期分支模式分支生命周期不要拖太长。分支拖得越久合并时冲突越难处理。5.2 git commit --amend怎么用热词里出现“git commit --amend怎么使用”说明很多人提交信息打错了字或者发现漏提交了一个文件时第一个想到的就是它。git commit --amend的作用是修改最近一条提交记录。两个高频用法修改提交信息git commit --amend -m 修正后的提交信息把漏掉的文件补进同一条提交git add 漏掉的文件 git commit --amend --no-edit--no-edit表示不修改提交信息只补充内容。注意--amend会改变提交的哈希值所以只适合提交还未推送到远端、或者只有你一个人使用该分支的场景。如果已经push到远端且别人已经拉取过再去amend会破坏双方历史一致性强行推送还得用git push --force-with-lease有覆盖他人提交的风险。共享项目里更稳妥的做法是保留原提交用一个新的commit来修正问题。5.3 查看提交历史与代码量统计日常最常用的查看命令是这些git status # 当前工作区状态 git log --oneline --graph --all # 查看分支合并图 git log --author你的名字 --oneline # 按作者筛选 git diff # 查看未暂存的改动 git diff --staged # 查看已暂存但未提交的改动如果Leader突然问你“gitlab 代码量怎么看”直接入口在GitLab项目页的“分析/仓库分析”功能按成员维度查看提交次数和代码行数变化趋势。想用命令行统计也可以git log --since2024-01-01 --until2024-12-31 --oneline | wc -l统计一段时期内的提交次数配合--author可以按人统计。6. 高频报错的完整排查链路6.1 fatal: not a git repository 系列问题这个报错翻译过来是当前目录不是一个Git仓库或者你执行命令的位置不对。排查很简单git rev-parse --show-toplevel这个命令会输出当前目录所属的仓库根目录。如果报错说明你在仓库之外如果输出了路径那说明命令执行位置有问题。还有一种特殊情况仓库的.git目录损坏或被人误删。这种只能从远端重新clone一份再手动把本地改动备份过去。6.2 SSH认证失败与超时问题“ssh认证失败 git”的场景我总结下来通常是三种原因第一私钥没被SSH agent加载或者路径不对。执行ssh-add -l查看已加载的密钥列表为空就执行ssh-add ~/.ssh/id_ed25519加载。第二GitLab的SSH端口不通。公司内网经常用非标准SSH端口这种情况需要在用户主目录.ssh/config里为GitLab主机单独指定Port和IdentityFileHost gitlab.example.com HostName gitlab.example.com Port 2222 User git IdentityFile ~/.ssh/id_ed25519第三服务器端没登记公钥检查方式还是那句ssh -T gitgitlab域名看返回信息。排查时我习惯按三层来走先测端口通不通再确认公钥在不在远端最后看本地私钥匹配不匹配。按这个顺序走基本十次能解决八次。6.3 login failed. check api token or gitlab version 是什么情况这个报错我在IDE和第三方客户端连接GitLab时遇到过。字面含义很清楚登录失败请检查API Token或GitLab版本。翻译成人话就是客户端和GitLab的API握手失败。常见原因有两个一是访问令牌Personal Access Token失效或权限不足重新生成一个并勾选对应的API scope即可二是GitLab版本和客户端版本不兼容。老版本的GitLab配新版客户端或反过来都可能出现这种提示。解决思路就是让两边的版本差距尽量小。GitLab版本太旧的建议升级客户端的插件或IDE也尽量保持更新。整体排查顺序先确认Token有效再确认版本兼容最后检查网络能否正常访问GitLab的API接口。6.4 GitLab启动不了的常见原因部署GitLab后最常遇到的“启动不了”分四种端口被占用这是最高频的。默认80、8080、22端口最容易冲突检查方式ss -lntp看端口占用情况把占用端口的进程停掉或者调整Docker映射端口。磁盘空间不足GitLab运行要写大量数据尤其数据库和仓库存储。启动前执行df -h确认根分区和挂载目录还有足够空间。内存不足GitLab社区版至少建议2GB内存低于这个配置在配置阶段和运行阶段都可能出问题。我实际测下来4GB会更稳如果机器只有1GB建议加配置或换轻量方案。权限问题挂载目录的所有者或权限不对容器内进程无法写入也会启动失败。Docker方式部署时挂载目录尽量不要放在有ACL限制或者加密的主目录下否则排查起来很折磨人。最后说一个和“gitlab ci”相关的体会。GitLab部署起来之后很多人会顺手启用CI/CD功能在项目根目录放一个.gitlab-ci.yml文件定义流水线阶段来跑测试、构建、部署。我的建议是先把基础操作弄扎实再碰CI。因为CI一旦跑起来就涉及Runner注册、Token配置、执行器选型是一整套新的知识体系前置的Git操作不稳CI排错时两种问题混在一起会非常头大。我自己实际用下来的感受是Git本身不复杂复杂的永远是“你和团队、你和服务器之间的边界问题”。把SSH通道、端口映射、权限、版本兼容这四件事想清楚很多问题自己就能排查掉一大半。这篇文章里的内容基本就是我在一台全新设备上从零走到日常协作时真正用到的全部环节希望你能少绕几次弯路。
Git与GitLab零到一实操：安装部署、SSH免密与代码上传指南
如果你坐在新配的电脑前刚把Git和GitLab从零到一折腾了一遍应该能理解这篇东西想讲什么装好Git、配对SSH、部署一套能用的GitLab社区版再跑通本地项目和远端仓库之间那套日常操作。看起来是五六件小事串起来处处有坑。这篇文章就是我基于一次完整实操写出来的基本覆盖从git安装到gitlab使用的整条链路适合刚接触Git和GitLab的新手也适合准备在公司内网自己搭一套GitLab的运维同学参考。说明文章里的命令我都按“Windows下Git Bash Linux服务器”两条线来写命令部分可以直接复制调整路径和域名记得替换成自己的。1. 先把环境搞定Git安装的路线选择与版本细节1.1 Windows用户最容易翻车的其实是下载环节说句实在话Git在Windows上的安装向导本身没什么难度难的是很多人卡在下载这一步——官网直连速度不稳定下载到一半断掉的情况不少。我的做法是直接用国内镜像站下载安装包速度快也稳阿里云镜像、清华镜像都有和官方完全同步的版本。找到最新的64位exe下载完直接双击运行。运行安装向导时大部分选项保持默认就行但有三处我会手动确认。第一安装路径尽量不要带空格。虽然现代Git对路径兼容已经做得很好但某些IDE和脚本在解析带空格的路径时还是可能出幺蛾子为了省事我一般直接装到C:\Program Files\Git之外的自定义路径比如D:\software\Git。第二在“Adjusting your PATH environment”这一步强烈建议选“Git from the command line and also from 3rd-party software”。这样Windows Terminal、CMD、PowerShell里都能直接敲git命令不必每次都打开Git Bash。很多教程默认让你用Git Bash导致后续在vscode、IntelliJ IDEA里配置终端时找不到git命令根源就在PATH这一步。第三换行符转换策略。Windows和Linux混用的团队建议把core.autocrlf设为input或true避免每次切换平台后出现大量“整个文件都变了”的假差异。我个人的习惯是Windows上设trueLinux服务器上不设置保持默认。安装完成后打开终端执行git --version能看到版本号就说明安装成功了。如果输出的是“git不是内部或外部命令”那就回去检查PATH那一步是不是选错了。1.2 Linux服务器包管理器快但版本可能偏老服务器上装Git最常见的方式是走包管理器# Ubuntu/Debian sudo apt update sudo apt install git -y # CentOS/RHEL sudo yum install git -y这种方式的优点是快缺点是版本通常偏老。比如某些发行版默认源里Git版本停留在2.3x而新版本的GitLab对Git客户端版本有最低要求。如果后面遇到git push到GitLab一直提示协议或认证相关的诡异问题可以先检查本机Git版本再决定要不要升级。部署GitLab之前建议先看一眼官方文档里写的“最低Git版本要求”确保两头都不落后。我自己就踩过一回服务器上Git是2.17GitLab已经升级到较新的版本结果某次push时直接报协议错误排查了半天才定位到是客户端版本太旧。1.3 装好之后的第一件事配置身份信息这里有个新手特别容易忽略的操作Git装好后第一件事不是急着clone而是先设置全局身份。因为每一次commit都会记录作者信息如果这步偷懒GitLab提交历史里就会出现一堆没有归属的提交记录后期追溯问题非常痛苦。git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这个邮箱不需要和GitLab注册邮箱完全一致它只是一个提交记录的标识字段。但如果公司有代码审计需求还是建议统一用企业邮箱保持一致。2. 装完Git别急着用SSH密钥、免密登录与认证细节2.1 为什么我优先选SSH而不是HTTPSGit连接远端有两种常用方式HTTPS和SSH。HTTPS第一次push或pull时需要输入GitLab的用户名密码或访问令牌体验比较割裂。SSH则是用一对公钥和私钥完成认证配置好后push和pull全程不需要输密码也就是大家常说的“git免密”。团队协作场景里SSH还有一个好处权限控制更干净。管理员可以通过密钥管理严格控制谁能访问代码库而HTTPS的密码一旦泄露影响面往往更大。所以在任何长期使用的开发机上我默认配SSH。2.2 生成密钥并配置到GitLab生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱或备注一路回车即可会在用户主目录的.ssh文件夹下生成两个文件私钥id_ed25519和公钥id_ed25519.pub。私钥是绝密文件不能外传公钥可以放心提供给GitLab。然后在GitLab页面右上角头像 → Preferences → SSH Keys把公钥内容完整粘贴进去保存。不同平台GitLab、GitHub、Gitee的密钥配置逻辑是通用的所以“git配置gitee密钥”和配置GitLab的步骤完全一致配过一次就懂了。这里补充一句为什么用ed25519而不是传统的RSA因为GitLab较新版本对RSA密钥长度有更严格的要求2048位以下的RSA可能会被拒绝。ed25519是目前各平台兼容性最好、生成也快的算法新环境我无脑选它。2.3 验证免密是否生效配置完成后用终端验证ssh -T git你的gitlab域名看到类似“Welcome to GitLab, 用户名!”的输出就说明SSH通道已经通了。新手可能会困惑这条命令看起来像登录用户为什么没有输密码因为这里是通过git这个系统账号做握手验证实际认证靠公钥完成密码自然就不需要了。如果命令卡住不动或者报Permission denied按这三层排查端口通不通公司内网有时不用默认22端口需要看GitLab的SSH端口配置公钥在不在去GitLab确认一下公钥是否真的保存成功私钥对不对检查本地.ssh目录权限私钥文件权限建议600Windows上则确认OpenSSH读取的密钥目录是否正确。3. GitLab从哪里来Docker部署社区版的全流程3.1 为什么建议用Docker部署GitLab关于GitLab部署社区两种主流方式用Omnibus包直接装或者用Docker跑官方镜像。个人使用、内网小团队使用我偏向Docker。原因很实际Omnibus安装要对系统版本、依赖库做一堆前置准备而且GitLab版本对操作系统有明确限制。热词里“gitlab 19只支持ubuntu 24.04”这类情况就属于系统版本兼容问题直接用Docker能绕开大部分系统层面的坑——运行环境被镜像封装好了宿主机只要满足Docker运行条件即可。3.2 docker run部署的核心参数用一个最小化命令启动GitLab社区版sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8022:22 --publish 8080:80 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest几个参数逐个解释--hostname容器内GitLab对外识别的域名或IP。如果内网用IP访问直接填服务器内网IP。--publish端口映射。宿主机8080映射容器内80宿主机8022映射容器内22。为什么不做默认端口映射因为宿主机很可能已经占用了80和22。后面遇到“gitlab启动不了”的报错一半以上是端口冲突。--volume挂载目录。config、logs、data这三块必须持久化否则容器重建后数据全部丢失等于白干活。跑起来之后不能马上访问。GitLab首次初始化需要几分钟到十几分钟不等具体取决于服务器性能。用下面命令观察日志docker logs -f gitlab看到类似“GitLab is running”的日志服务才算真正就绪。首次访问时页面报502或503很常见别急多等一会儿再刷新。3.3 修改端口与读取root密码关于“ubuntu gitlab 更该端80口号”本质就是调整GitLab对外端口。Docker部署场景下最简单方式是把启动命令里的--publish主机端口改掉比如--publish 8090:80。如果是Omnibus方式部署则需要修改/etc/gitlab/gitlab.rb里的external_url和nginx端口改完执行sudo gitlab-ctl reconfigureGitLab社区版首次启动后会生成一个初始root密码存放在容器内/etc/gitlab/initial_root_password文件里docker exec -it gitlab cat /etc/gitlab/initial_root_password这个文件只在第一次初始化时存在。如果错过了可以在容器内执行gitlab-rake resets相关命令重置管理员密码。3.4 部署完先做几件安全的事GitLab部署完成后别急着建项目先把安全基线打好。第一调整对外端口并用防火墙限制访问范围不要把GitLab直接暴露到公网。第二进入管理后台在“Settings → General”里关闭公开注册避免陌生账号随意注册进来。第三关注GitLab官方安全公告。GitLab历史上有过几个比较知名的高危漏洞通用修复方案就是“升级到修复版本并检查相关配置项”。所以真正要记得的动作是建立版本更新关注渠道安全更新发布时及时升级别拖。4. GitLab上的项目流转新增、导入、拉取与上传4.1 新增项目的完整流程GitLab首页的“新建项目”入口很显眼填好项目名、描述选择可见性等级。我的习惯是公司内网一律私有或内部公开权限风险太高个人项目如果只是自己保管也选私有。项目建好后页面会给出两种仓库地址HTTPS和SSH。前文已经配好了SSH密钥这里直接复制SSH地址即可。4.2 外部项目导入GitLab的方式“gitlab导入项目”算是高频需求。GitLab原生支持从其他Git平台导入项目路径是“New Project → Import Project”。GitLab提供GitHub、Gitee等多个平台的导入选项导入时通过各平台生成的Token授权会把仓库、提交历史、分支等信息一并迁移过来。如果只是想把一个没有远端历史的项目导入GitLab还有个更直接的办法本地初始化Git仓库后推送到GitLab新建的空仓库下面一节详细写。4.3 本地已有项目上传到GitLab这是“本地项目上传到gitlab”场景的标准操作。在项目根目录执行git init git add . git commit -m 初始提交 git remote add origin gitgitlab.example.com:username/project.git git push -u origin master按顺序解释git init创建隐藏的.git目录这是整个仓库的核心git add .把当前目录所有文件加入暂存区git commit -m 初始提交生成第一个提交记录git remote add origin 地址和远端仓库建立关联git push -u origin master首次推送并指定默认上游分支。提醒一点很多人在push时遇到“fatal: not a git repository (or any of the parent directories): .git”原因就是没有先git init或者命令执行目录不是仓库根目录。如果你用IntelliJ IDEA操作路径是File → New → Project from Version Control粘贴GitLab仓库的SSH地址IDEA自动拉取。本地已有项目想传上去则用VCS → Import into Version Control → Share Project on GitLab。SourceTree这类图形化工具本质也是封装git remote add、git push这些操作在仓库设置里配置远端地址即可。4.4 从GitLab拉取代码到本地全新克隆git clone gitgitlab.example.com:username/project.git后续同步远端更新git pull origin masterclone和pull的区别clone是把整个仓库完整复制到本地只需要一次pull是在已有仓库基础上获取远端新增提交并合并到当前分支。本地有未提交改动时直接pull可能出现冲突或“无法合并”的提示稳妥做法是先提交或暂存git stash拉完再恢复。5. 日常开发上手最快的几个Git操作5.1 分支合并git merge的正确使用姿势团队协作里“git分支合并”绕不开。常规流程从master/main拉出功能分支开发完合并回去。git checkout -b feature/login # 开发一段时间后 git add . git commit -m 完成登录功能 git checkout master git pull origin master git merge feature/login经验之谈执行merge之前先git pull更新目标分支能解决大部分冲突。如果merge时报告冲突Git会列出冲突文件打开后能看到 HEAD和分隔标记手动保留需要的代码删掉标记再git add、git commit。我在项目里通常建议团队采用简单粗暴的主干开发加短期分支模式分支生命周期不要拖太长。分支拖得越久合并时冲突越难处理。5.2 git commit --amend怎么用热词里出现“git commit --amend怎么使用”说明很多人提交信息打错了字或者发现漏提交了一个文件时第一个想到的就是它。git commit --amend的作用是修改最近一条提交记录。两个高频用法修改提交信息git commit --amend -m 修正后的提交信息把漏掉的文件补进同一条提交git add 漏掉的文件 git commit --amend --no-edit--no-edit表示不修改提交信息只补充内容。注意--amend会改变提交的哈希值所以只适合提交还未推送到远端、或者只有你一个人使用该分支的场景。如果已经push到远端且别人已经拉取过再去amend会破坏双方历史一致性强行推送还得用git push --force-with-lease有覆盖他人提交的风险。共享项目里更稳妥的做法是保留原提交用一个新的commit来修正问题。5.3 查看提交历史与代码量统计日常最常用的查看命令是这些git status # 当前工作区状态 git log --oneline --graph --all # 查看分支合并图 git log --author你的名字 --oneline # 按作者筛选 git diff # 查看未暂存的改动 git diff --staged # 查看已暂存但未提交的改动如果Leader突然问你“gitlab 代码量怎么看”直接入口在GitLab项目页的“分析/仓库分析”功能按成员维度查看提交次数和代码行数变化趋势。想用命令行统计也可以git log --since2024-01-01 --until2024-12-31 --oneline | wc -l统计一段时期内的提交次数配合--author可以按人统计。6. 高频报错的完整排查链路6.1 fatal: not a git repository 系列问题这个报错翻译过来是当前目录不是一个Git仓库或者你执行命令的位置不对。排查很简单git rev-parse --show-toplevel这个命令会输出当前目录所属的仓库根目录。如果报错说明你在仓库之外如果输出了路径那说明命令执行位置有问题。还有一种特殊情况仓库的.git目录损坏或被人误删。这种只能从远端重新clone一份再手动把本地改动备份过去。6.2 SSH认证失败与超时问题“ssh认证失败 git”的场景我总结下来通常是三种原因第一私钥没被SSH agent加载或者路径不对。执行ssh-add -l查看已加载的密钥列表为空就执行ssh-add ~/.ssh/id_ed25519加载。第二GitLab的SSH端口不通。公司内网经常用非标准SSH端口这种情况需要在用户主目录.ssh/config里为GitLab主机单独指定Port和IdentityFileHost gitlab.example.com HostName gitlab.example.com Port 2222 User git IdentityFile ~/.ssh/id_ed25519第三服务器端没登记公钥检查方式还是那句ssh -T gitgitlab域名看返回信息。排查时我习惯按三层来走先测端口通不通再确认公钥在不在远端最后看本地私钥匹配不匹配。按这个顺序走基本十次能解决八次。6.3 login failed. check api token or gitlab version 是什么情况这个报错我在IDE和第三方客户端连接GitLab时遇到过。字面含义很清楚登录失败请检查API Token或GitLab版本。翻译成人话就是客户端和GitLab的API握手失败。常见原因有两个一是访问令牌Personal Access Token失效或权限不足重新生成一个并勾选对应的API scope即可二是GitLab版本和客户端版本不兼容。老版本的GitLab配新版客户端或反过来都可能出现这种提示。解决思路就是让两边的版本差距尽量小。GitLab版本太旧的建议升级客户端的插件或IDE也尽量保持更新。整体排查顺序先确认Token有效再确认版本兼容最后检查网络能否正常访问GitLab的API接口。6.4 GitLab启动不了的常见原因部署GitLab后最常遇到的“启动不了”分四种端口被占用这是最高频的。默认80、8080、22端口最容易冲突检查方式ss -lntp看端口占用情况把占用端口的进程停掉或者调整Docker映射端口。磁盘空间不足GitLab运行要写大量数据尤其数据库和仓库存储。启动前执行df -h确认根分区和挂载目录还有足够空间。内存不足GitLab社区版至少建议2GB内存低于这个配置在配置阶段和运行阶段都可能出问题。我实际测下来4GB会更稳如果机器只有1GB建议加配置或换轻量方案。权限问题挂载目录的所有者或权限不对容器内进程无法写入也会启动失败。Docker方式部署时挂载目录尽量不要放在有ACL限制或者加密的主目录下否则排查起来很折磨人。最后说一个和“gitlab ci”相关的体会。GitLab部署起来之后很多人会顺手启用CI/CD功能在项目根目录放一个.gitlab-ci.yml文件定义流水线阶段来跑测试、构建、部署。我的建议是先把基础操作弄扎实再碰CI。因为CI一旦跑起来就涉及Runner注册、Token配置、执行器选型是一整套新的知识体系前置的Git操作不稳CI排错时两种问题混在一起会非常头大。我自己实际用下来的感受是Git本身不复杂复杂的永远是“你和团队、你和服务器之间的边界问题”。把SSH通道、端口映射、权限、版本兼容这四件事想清楚很多问题自己就能排查掉一大半。这篇文章里的内容基本就是我在一台全新设备上从零走到日常协作时真正用到的全部环节希望你能少绕几次弯路。
