企业官网建设流程全解析

简介：这份资源围绕 Gitee、GitHub 与 GitLab 三大主流代码托管平台展开，面向刚接触 Git 版本控制、需要把本地项目推送到远端仓库的开发者与运维初学者。内容以 Gitee 为主线，覆盖仓库注册与新建、本地仓库上传、git clone 拉取、SSH 免密 push 等常见操作场景，帮助读者打通从本地提交到远端托管的完整链路。资源包共 1 个 docx 文档，约 5.29MB，以图文笔记形式整理命令与执行结果，便于对照练习和查阅。文档中保留了 git add、git commit、git remote add、git push 等关键命令的实际输出，以及 ssh-keygen 生成密钥对、复制公钥、验证连接等步骤的终端回显，可作为排错时的参考依据。目前已有 74 人学习，适合需要快速上手 Git 托管平台、补齐远端协作基础操作的读者。

1. 三个代码托管平台，到底该把代码放哪

很多团队都经历过这种场面：本地git push一切正常，换台机器git clone就卡在认证；或者代码在 Gitee 上跑得好好的，一迁到 GitLab 自建实例，CI 流水线全红。Gitee、GitHub、GitLab 这三个名字天天一起出现，但它们解决的问题并不一样。Gitee 是国内访问速度友好的托管平台，GitHub 是全球开源生态的中心，GitLab 则是能整套搬进内网的自建 DevOps 平台。选错了不是不能用，而是后面每一步都在还债。

这篇笔记面向三类人：刚学 git、纠结第一个远程仓库放哪的新手；要把公司代码从公有平台迁到自建 GitLab 的运维；以及被「GitLab 版本太老登录失败」「SSH 认证失败」这类报错卡住的开发者。我会把三者的定位差异、账号与密钥配置、仓库迁移、CI 接入、以及一堆血泪踩坑按顺序讲清楚，让你看完能直接动手，而不是停在「知道有这么个东西」。

2. 先分清定位：Gitee、GitHub、GitLab 各自解决什么问题

2.1 从托管模式看三者的本质差异

理解这三个平台，最有效的切入点是「代码存在谁的机器上、谁来运维」。GitHub 和 Gitee 本质是托管服务（SaaS），你注册账号、建仓库，底层服务器、备份、可用性都由平台负责，你只关心代码和协作。GitLab 有两种形态：官方也提供 SaaS，但真正让它出圈的是自建（Self-Managed）——你可以把整套 GitLab 装在自己的服务器或内网，代码不出门。

这个差异直接决定了选型。个人练手、开源项目、想蹭全球生态，GitHub 是默认答案；国内团队在意访问速度和合规备案，Gitee 更顺手；公司有内网隔离要求、要自己掌控 CI/CD 和权限审计，GitLab 自建几乎是标配。很多人把三者当成「同类竞品」，其实 GitHub/Gitee 更像「代码社交 + 托管」，GitLab 更像「一整套研发流水线」。

从协议层面看，三者都基于 git，所以本地命令完全通用，差异集中在认证方式、Web 功能、CI 语法和访问网络上。这意味着你学会一套 git 操作，换平台只需要改 remote 地址和认证配置，不用重学。

2.2 一张表看清选型维度

选型时我一般按这个顺序问自己：代码能不能出内网？团队在不在国内？要不要自己写 CI？三个问题答完，平台基本就定了。别一上来纠结功能列表，先看约束条件。

2.3 本地 git 环境的最小可用配置

不管最后选哪个平台，本地 git 得先配好。安装 git 后，第一件事是配身份，否则提交记录里的作者是乱的。

# 配置全局用户名和邮箱，会写进每次 commit 的作者信息 git config --global user.name "your-name" git config --global user.email "you@example.com" # 查看当前所有配置，确认写进去了 git config --global --list # 建议把默认分支名统一成 main，避免和平台默认不一致 git config --global init.defaultBranch main

user.name和user.email是提交元数据，和登录账号无关，但很多平台靠邮箱把提交关联到你的账号，所以邮箱最好和平台注册邮箱一致。init.defaultBranch决定git init后的默认分支名，GitHub 早已默认 main，本地也统一能少一次改名。配完可以用git config --global --list核对，别配完就不管。

3. 账号、密钥与认证：把「登录失败」挡在门外

3.1 SSH 密钥的生成与三平台配置

HTTPS 每次要输密码，SSH 一次配置长期省心。生成密钥对是通用步骤，三个平台都能用同一套公钥。

# 生成 ed25519 密钥，-C 后面是注释，一般写邮箱方便识别 ssh-keygen -t ed25519 -C "you@example.com" # 一路回车，默认存到 ~/.ssh/id_ed25519 # 查看公钥内容，复制它去平台粘贴 cat ~/.ssh/id_ed25519.pub

-t ed25519指定算法，比老的 RSA 更短更安全；-C只是注释，不影响功能。生成后私钥留在本地，公钥（.pub结尾）贴到平台的 SSH Keys 设置里。Gitee 在「设置 → SSH 公钥」，GitHub 在「Settings → SSH and GPG keys」，GitLab 在「Preferences → SSH Keys」。贴完用下面命令验证：

# 测试与各平台的 SSH 连通性，-T 表示不分配终端 ssh -T git@gitee.com ssh -T git@github.com ssh -T git@your-gitlab-host

看到带用户名的欢迎语就说明通了。如果提示Permission denied (publickey)，八成是公钥没贴对或 ssh-agent 没加载私钥，先ssh-add ~/.ssh/id_ed25519再试。

3.2 个人访问令牌：GitLab 和 GitHub 的必答题

现在 GitHub 和 GitLab 用 HTTPS 推送时，密码位置要填的是个人访问令牌（Personal Access Token），不是登录密码。这是新手最容易翻车的点——明明密码没错，就是Authentication failed。

GitLab 在「Preferences → Access Tokens」创建，勾选read_repository、write_repository等 scope；GitHub 在「Settings → Developer settings → Personal access tokens」创建。令牌生成后只显示一次，务必当场存好。用的时候：

# 把令牌当密码用，用户名填你的账号名 git clone https://your-gitlab-host/group/repo.git # 提示 Password 时粘贴令牌，而不是登录密码

令牌可以设过期时间，也能随时吊销，比密码安全。团队里如果多人共用一台构建机，建议给 CI 单独建一个令牌，别用个人账号的，出问题好定位也好回收。

3.3 认证方式怎么选：SSH 还是令牌

简单说：个人开发机用 SSH，省事；CI/脚本环境用令牌，好管理。SSH 密钥一旦泄露影响面大，令牌可以限权限、限时间、随时吊销。我一般本地配 SSH，服务器和流水线里全用令牌。两者不冲突，同一个仓库可以同时配。

提示：私钥文件权限必须是 600，权限过宽 SSH 会直接拒绝使用。chmod 600 ~/.ssh/id_ed25519能解决一大类「密钥明明对却连不上」的玄学问题。

4. 仓库迁移与日常操作：从 Gitee 拉到 IDEA、从 GitHub 迁到 GitLab

4.1 用镜像克隆把仓库整体搬到另一个平台

迁移仓库最稳的方式是「裸克隆 + 镜像推送」，能保留全部分支和提交历史。

# 1. 裸克隆源仓库，--mirror 会带上所有分支和标签 git clone --mirror https://gitee.com/user/repo.git # 2. 进入裸仓库目录 cd repo.git # 3. 把推送地址改成目标平台的新仓库 git remote set-url --push origin https://your-gitlab-host/group/repo.git # 4. 镜像推送，把所有 refs 推过去 git push --mirror

--mirror克隆的是裸仓库，包含所有引用；push --mirror会把分支、标签、甚至删除操作都同步过去，适合一次性搬迁。注意目标仓库要先在平台上建好（可以是空仓库），否则推不上去。迁完记得在本地重新 clone 一份正常仓库来开发，别在裸仓库里改代码。

4.2 从 Gitee 拉项目到 IDEA 的完整流程

热词里「从 gitee 拉取项目到 idea」出现频率很高，步骤其实很固定。先在 Gitee 复制仓库地址（SSH 或 HTTPS），然后：

# 方式一：命令行先克隆，再用 IDEA 打开目录 git clone git@gitee.com:user/repo.git cd repo # 然后用 IDEA 的 File -> Open 选中这个目录

方式二：IDEA 内直接操作 File -> New -> Project from Version Control 粘贴仓库 URL，选择本地目录，点 Clone

克隆后 IDEA 会问是否信任项目、是否用 Maven/Gradle 导入，按项目实际选。如果拉下来依赖报红，先看 JDK 版本和构建工具配置，多半不是 git 的问题。SSH 方式要求 IDEA 能找到你的私钥，Windows 下有时需要在 Settings → Version Control → Git 里把 SSH executable 切成 Native。

4.3 分支合并与冲突处理的基本功

迁移和协作都绕不开分支合并。日常流程是：拉最新、切分支、改、提交、推、发合并请求。

# 拉取远程最新并合并到当前分支 git pull origin main # 新建并切换到功能分支 git checkout -b feature/login # 改完代码后暂存、提交、推送 git add . git commit -m "feat: add login" git push origin feature/login

推送后在平台上发起 Merge Request（GitLab）或 Pull Request（GitHub/Gitee），走评审再合并。冲突一般发生在git pull或合并时，git 会在文件里标出<<<<<<<冲突块，手动改完再git add和git commit。别怕冲突，怕的是不看就--force推，那才是真的后悔药都买不到。

注意：git push --force会覆盖远程历史，团队分支上慎用。真要用，先确认没人在这个分支上协作，或者改用--force-with-lease，它会在远程有新提交时拒绝推送。

5. 避坑与排查：那些让人抓狂的报错

5.1 GitLab 版本过旧导致 IDEA 登录失败

现象：IDEA 里登录 GitLab 报login failed. gitlab versions older than 14.0 are not supported。原因很明确——IDEA 的 GitLab 插件新版只支持 14.0 以上，你的自建 GitLab 太老。解决有两条路：一是升级 GitLab 到 14.0+，二是别用插件登录，改用「Log in via Git」，也就是走 git 命令行认证，IDEA 只负责拉代码。升级前务必备份，GitLab 跨大版本升级有严格路径要求，不能一步到位。

5.2 SSH 认证失败但公钥明明贴了

现象：ssh -T报Permission denied (publickey)。原因通常是三类：公钥贴错位置、私钥没被 ssh-agent 加载、或者私钥权限过宽。解决：先ssh -vT git@host看详细握手日志，确认用的是哪个私钥；再ssh-add -l看 agent 里有没有；最后chmod 600修权限。Windows 用户还要注意是不是被系统自带的 ssh 和 Git 自带的 ssh 搞混了。

5.3 GitLab 启动不了与端口冲突

现象：自建 GitLab 装完gitlab-ctl status显示组件 down，或者访问不了。常见原因是 80/8080 端口被占用，或者内存不足（GitLab 很吃内存，2G 以下基本跑不动）。解决：改/etc/gitlab/gitlab.rb里的external_url和 nginx 监听端口，然后gitlab-ctl reconfigure。内存不够就加 swap 或升配。用 Docker 装的话，注意端口映射和 volume 持久化，容器删了数据别跟着没。

5.4 权限角色搞不清，推不上 master

现象：能 clone 不能 push，或者提示 protected branch。原因是 GitLab 的 master/main 默认是受保护分支，Developer 角色不能直接推。解决：要么让 Maintainer 在「Settings → Repository → Protected branches」里放开，要么走合并请求流程。别想着改角色蒙混，权限设计就是为了防误操作，顺着流程走最省事。

5.5 平台访问慢或打不开时的应对

现象：GitHub 网页转圈、clone 卡住。原因是跨境网络波动。解决：优先用 SSH 而非 HTTPS（有时更稳），或者配置镜像站、用国内托管做中转。团队项目如果长期受影响，认真评估迁到 Gitee 或自建 GitLab。这不是技术问题，是网络环境问题，别在 git 配置里瞎折腾。

6. 把 CI 接上：GitLab CI 与 GitHub Actions 的最小可用流水线

6.1 GitLab CI 的 .gitlab-ci.yml 最小示例

GitLab 自建最大的价值之一是内置 CI。在仓库根目录放一个.gitlab-ci.yml，推代码就自动跑。

# 定义流水线阶段 stages: - build - test # 构建任务 build-job: stage: build script: - echo "building..." - ls -la # 测试任务，只在 main 分支跑 test-job: stage: test script: - echo "running tests..." only: - main

stages定义执行顺序，同名 stage 的任务并行；script是实际命令；only限定触发分支。GitLab 需要先注册 Runner（gitlab-runner register），否则任务会一直 pending。Runner 的 executor 选 docker 最通用，记得给它配好拉代码的权限。

6.2 GitHub Actions 的对应写法

GitHub 用.github/workflows/下的 YAML，概念类似但语法不同。

name: ci on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: run run: echo "building..."

on定义触发条件，jobs下的steps顺序执行，actions/checkout负责把代码拉进 runner。GitHub 的 runner 由平台提供，不用自己维护，这是托管平台相对自建 GitLab 的省心之处。

6.3 迁移后 CI 配置的适配要点

从 GitHub 迁到 GitLab，或反过来，CI 配置不能直接复制。要改的点包括：文件位置和名字、触发语法、变量注入方式、缓存和制品（artifacts）写法。我的习惯是迁移时先只保留「拉代码 + 跑测试」两条最小流水线，跑通再逐步加构建和部署，别一上来把整套搬过去，出错都不知道是哪一层。

提示：CI 里用的令牌和密钥一定放平台的「CI/CD Variables」里，别硬编码进 YAML。硬编码的密钥一旦推到仓库，等于公开，吊销都来不及。

7. 进阶技巧：用 git 别名和钩子把重复操作压到一行

写到这里，前面都是「怎么用」，最后说一个我自己每天都在用的提效习惯——git 别名。三个平台来回切，命令其实高度重复，把常用组合压成短命令，能省下大量敲键盘的时间。

# 用别名把常用操作缩短 git config --global alias.st "status -sb" git config --global alias.co "checkout" git config --global alias.br "branch -vv" git config --global alias.last "log -1 --stat" git config --global alias.sync "!git pull --rebase && git push" # 之后直接 git st、git co main、git sync 即可

alias.sync前面加!表示执行 shell 命令而不是 git 子命令，pull --rebase能让提交历史保持线性，减少无意义的合并节点。用--rebase的前提是本地没有别人依赖的提交，个人分支上很安全。

再进一步是 git 钩子。比如提交前自动跑格式检查，用pre-commit钩子：

# 在仓库 .git/hooks/pre-commit 写入（去掉 .sample 后缀） #!/bin/sh # 提交前跑一次 lint，失败就阻止提交 npm run lint || exit 1

钩子文件要可执行：chmod +x .git/hooks/pre-commit。注意.git/hooks不会随仓库分发，团队要统一钩子得用core.hooksPath指向仓库内的目录，或者用 husky 这类工具管理。

验证这些配置是否生效，最直接的办法是故意制造一次失败：改坏一个文件再提交，看钩子有没有拦住；或者跑一次git sync看历史是不是线性的。我踩过最深的坑是别名写错把push配成了push --force，结果差点覆盖远程分支，从那以后所有带--force的别名我都单独命名并加二次确认。工具是省事的，但省事的前提是你清楚它到底执行了什么。希望帮到你。

本文还有配套的精品资源，点击获取