企业官网建设流程全解析

如果你坐在新配的电脑前，刚把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上设true，Linux服务器上不设置，保持默认。

安装完成后，打开终端执行：

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.17，GitLab已经升级到较新的版本，结果某次push时直接报协议错误，排查了半天才定位到是客户端版本太旧。

1.3 装好之后的第一件事：配置身份信息

这里有个新手特别容易忽略的操作：Git装好后，第一件事不是急着clone，而是先设置全局身份。因为每一次commit都会记录作者信息，如果这步偷懒，GitLab提交历史里就会出现一堆没有归属的提交记录，后期追溯问题非常痛苦。

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

注意，这个邮箱不需要和GitLab注册邮箱完全一致，它只是一个提交记录的标识字段。但如果公司有代码审计需求，还是建议统一用企业邮箱，保持一致。

2. 装完Git别急着用：SSH密钥、免密登录与认证细节

2.1 为什么我优先选SSH而不是HTTPS

Git连接远端有两种常用方式：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目录权限，私钥文件权限建议600，Windows上则确认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 reconfigure

GitLab社区版首次启动后会生成一个初始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 git@gitlab.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 git@gitlab.example.com:username/project.git

后续同步远端更新：

git pull origin master

clone和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 --since="2024-01-01" --until="2024-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和IdentityFile：

Host gitlab.example.com HostName gitlab.example.com Port 2222 User git IdentityFile ~/.ssh/id_ed25519

第三，服务器端没登记公钥，检查方式还是那句：ssh -T git@gitlab域名，看返回信息。

排查时我习惯按三层来走：先测端口通不通，再确认公钥在不在远端，最后看本地私钥匹配不匹配。按这个顺序走，基本十次能解决八次。

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通道、端口映射、权限、版本兼容这四件事想清楚，很多问题自己就能排查掉一大半。这篇文章里的内容，基本就是我在一台全新设备上从零走到日常协作时真正用到的全部环节，希望你能少绕几次弯路。