简介：面向Git初学者的托管平台操作指南，围绕Gitee、GitHub和GitLab三大主流代码托管平台展开，重点讲解Gitee的注册、远端仓库创建、本地仓库上传、git clone下载以及基于SSH的免密push配置。内容以图文笔记形式呈现，共1个docx文档，大小5.29MB，文字示例与命令输出完整清晰，适合刚接触Git版本控制的开发者按步骤对照练习。目前已有73人浏览学习，文档结构简洁，从基础操作到进阶的密钥配置均有覆盖。读者可从中掌握日常开发中最常用的Git远程协作命令，理解公钥与私钥在免密登录中的作用，避免因权限问题而中断提交流程。对于需要快速上手代码托管平台、解决远程仓库同步问题的用户来说，这份资料能提供直接可参考的操作路径。

1. 三平台并存才是常态：GitHub、Gitee 与 GitLab 到底解决什么问题

一线团队里，三个代码托管平台并存不是选择题，而是默认状态：GitHub 承担开源协作和前沿技术跟踪，Gitee 提供国内网络的稳定访问体验，GitLab 则常以私有化部署的形式出现在公司内网或交付环境中。不少从业者的真实状态是三个平台都在用，却把大量时间耗在“换个平台就不会操作”上，明明是同一套 Git 命令，换了个网页按钮就发怵。这篇笔记把 Gitee、GitHub 和 GitLab 串成统一的操作心智：如何选型、如何配 SSH、如何建仓库推拉代码、高频坑在哪，以及如何用 Docker 自托管一个 GitLab 社区版。适合刚接手团队仓库的新人，也适合准备迁移或自建仓库的熟手。

2. 按团队与网络环境选型：三平台定位差异和迁移成本判断

三个平台底层都是 Git，差异不在命令，而在“默认给你什么样的协作环境”。先把定位看清楚，后面的操作才有依据。

2.1 三个平台的出身与默认场景

GitHub 是全球开源协作的中心，默认场景是找开源项目、读源码、参与 Issue 讨论、给别人的仓库提 PR。它的公开仓库生态无可替代，私有仓库虽然免费，但很多企业功能是按席位收费的。Gitee 是国内团队最常用的替代者，面向国内网络做了访问优化，注册即用、仓库操作响应快，默认场景是国内团队协作、个人代码备份、开源项目的中文镜像。GitLab 则是开箱即用的 DevSecOps 平台，默认场景是企业私有化部署，代码托管、CI/CD、制品库、安全扫描都集成在一个产品里，对保密要求高的团队来说，“代码不出内网”是一个硬需求。

这里要澄清一个常见误区：GitHub Pages 和 Gitee Pages 都适合挂静态站点，但这和仓库协作本身没有关系，不要因为某个平台有 Pages 就把它当成选型的主要理由。Pages 解决的是“部署一个静态网页”的问题，而仓库选型解决的是“代码放在哪、谁有权改、构建怎么跑”的问题，两者不在一个维度。

2.2 选型的一线判断标准

我的判断标准就三个问题：给谁用、代码放哪、谁运维。

给谁用决定协作模式。目标是参与全球开源社区，GitHub 是唯一合理选择；目标是国内团队内部协作，Gitee 的访问速度和中文界面能省掉大量沟通成本；目标是公司资产、需要审计和权限管控，GitLab 自托管最常见。

代码放哪决定合规边界。GitLab 云版虽然也能用，但国内团队一般选择本地部署 GitLab，数据落自己的服务器，备份策略自己定。GitHub 访问不稳定时，一线团队最常见的对策不是绕路，而是把高频访问的仓库同步到 Gitee 或公司自建 GitLab 上，日常开发走国内平台，开源发布保留 GitHub。这个策略最省心，也最符合实际网络环境。

谁运维决定成本。GitHub 和 Gitee 都是托管服务，不用管服务器，注册就能用；GitLab 自托管意味着你要持续维护一个至少 4G 内存的节点，还要处理版本升级和高危漏洞。没有专职运维的团队，我一般建议先用托管平台，等团队超过十人、对 CI/CD 集成有强需求时再考虑私有化。

2.3 迁移成本：动手之前先看这三点

很多团队不是从零选型，而是从 GitHub 迁到 Gitee，或从 Gitee 迁到公司 GitLab。迁移本身不复杂，复杂的是迁移前没算清成本。

第一点是远端地址。GitHub 的 clone 地址是git@github.com:组织名/仓库名.git，Gitee 是git@gitee.com:用户名/仓库名.git，GitLab 还带着自定义域名和端口。地址全换不意味着代码要重传，一个 bare 仓库加 mirror 推送就能完成迁移：

# 用 bare 克隆方式拿到完整历史，包括所有分支和标签 git clone --bare git@github.com:your-org/your-repo.git cd your-repo.git # 把整个仓库镜像推送到新平台，远端仓库会自动补齐所有分支 git push --mirror git@gitee.com:your-name/your-repo.git

--bare意味着克隆出来的是没有工作区的纯仓库，专门用于迁移；--mirror会把本地所有分支、标签、远端引用一并推过去，比逐分支推送可靠得多。迁移完成后，本地开发目录只需改一行配置即可切换远端：git remote set-url origin 新地址。

第二点是大文件历史。GitHub 和 Gitee 对单文件都有 100MB 左右的硬限制，GitLab 社区版限制相对宽松，但历史里的超限文件会让 clone 变得极慢。迁移前用git rev-list --objects --all扫一遍大文件，该清的历史清掉，比迁移之后被新平台拒绝推送要省事。

第三点是许可证与可见性。公开仓库迁到私有仓库或反向操作时，开源许可证必须重新确认。Gitee 新建仓库时会让你选许可证，MIT、Apache-2.0、GPL-3.0 是最常见的三个选项：个人作品用 MIT 最省事；用了别人 GPL 代码的项目必须继续用 GPL；拿不准时宁可先选保留所有权利，不要默认乱选。许可证一旦定错，后续被合规问询时改起来很被动。

3. 一份 SSH 密钥管三个平台：生成、config 配置与三端验证

密钥配置是托管平台使用里最值得一次做对的事。配好 SSH 后，日常 push 和 pull 全程免密，不受令牌过期影响，换电脑也只需要转移密钥目录。

3.1 为什么优先 SSH 而不是 HTTPS

HTTPS 方式每次推送都要输用户名和密码，现在三个平台都已经把密码登录改为令牌登录，令牌有过期时间，过期后第一次推送就会报Authentication failed。在团队里经常看到这样的场景：同事的令牌三个月前过期，某天连着推十次代码，十次全部失败，还以为是网络问题。

SSH 是密钥对机制，私钥留在本机，公钥上传到平台，配一次之后长期有效。它还有一个额外好处：可以针对不同平台配置不同的私钥，避免公司 GitLab 的私钥和个人 GitHub 账号混用。换行符处理也是考虑因素，Windows 用户如果使用 HTTPS 克隆，Git 的 autocrlf 设置偶尔会搞乱脚本文件；SSH 协议下这个问题虽然也存在，但排查链路更短。

3.2 生成多平台隔离的密钥对与 config 文件

常见做法是为三个平台各生成一把独立的 ed25519 密钥，而不是一把钥匙走天下。生成方法如下：

# 生成三份密钥，文件名区分平台，避免互相覆盖 ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_gitee ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_gitlab # 查看公钥内容，分别粘贴到三个平台的 SSH 配置页 cat ~/.ssh/id_ed25519_github.pub cat ~/.ssh/id_ed25519_gitee.pub cat ~/.ssh/id_ed25519_gitlab.pub

-t ed25519指定密钥类型，目前比 RSA 更安全且长度更短；-C是注释，一般写邮箱，方便在平台上识别是哪台机器；-f指定输出文件路径，不加这个参数会默认覆盖id_ed25519。公钥上传位置三个平台不同：GitHub 在 Settings 里的 SSH and GPG keys，Gitee 在设置里的 SSH 公钥，GitLab 在个人偏好设置里的 SSH Keys。

生成完只是第一步，要让 SSH 知道“哪个域名用哪把钥匙”，必须写~/.ssh/config：

Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee Host gitlab.yourcompany.com HostName gitlab.yourcompany.com User git Port 2222 IdentityFile ~/.ssh/id_ed25519_gitlab

这段配置的作用是把域名和私钥文件绑定。Port 2222很关键，公司自建 GitLab 如果宿主机 22 端口被占，通常会映射到 2222，不写这一行，SSH 会默认走 22 端口，连接就会失败。有些团队还会遇到“能连 Gitee 却连不上公司 GitLab”的怪象，九成是 config 里少了 Port 或 HostName 写错。

提示：私钥文件不要复制到 U 盘或网盘，公司电脑如果启用了 BitLocker 或文件加密，直接放在用户目录即可；换电脑时重新生成一对密钥，比冒险拷贝私钥安全得多。

3.3 三端验证与失败输出

配置完成后，用三个命令分别验证：

ssh -T git@github.com ssh -T git@gitee.com ssh -T git@gitlab.yourcompany.com

验证输出的内容各有不同但含义一致：GitHub 返回Hi yourname! You've successfully authenticated，Gitee 返回Hi 你的名字! You've successfully authenticated，GitLab 返回Welcome to GitLab。看到这些就说明密钥链路已经通了。

如果看到Permission denied (publickey)，优先检查 config 文件的权限和格式，.ssh目录权限太开放会在 Linux 上直接导致 SSH 拒绝读取私钥；其次确认公钥确实粘贴到了对应平台。如果提示Host key verification failed，说明这台机器之前连过同域名但指纹变了，需要删除~/.ssh/known_hosts里的旧记录重新连接，常见于公司 GitLab 重装或域名复用。

4. 从建仓库到拉取项目：三端共用的最小命令集与参数说明

网页上“新建仓库”的按钮位置各不相同，但创建完成后你手里的东西是一样的：一个空仓库地址。这一章把三端共用的命令串一遍，覆盖从初始化到日常推拉的完整闭环。

4.1 网页建仓库与本地初始化的衔接

三个平台的网页流程几乎一致：New repository → 填名字 → 选可见性 → 选许可证或 README → 复制 SSH 地址。GitLab 的“新增项目”按钮和 GitHub/Gitee 略有差别，还提供 Import Project 入口，但从命令行迁移比网页导入更通用、更可控。

一个常见反模式是：本地已有代码，网页上又勾选了“初始化 README”，结果本地仓库和远端产生了无谓的合并。正确的做法是本地目录直接初始化，然后关联远端：

mkdir demo && cd demo git init # 关联远端仓库，地址用 SSH 方式，不需要输密码 git remote add origin git@gitee.com:your-name/demo.git git add . git commit -m "init project" # -u 参数把本地 main 分支和远端 main 分支绑定，后续可以直接 git push git push -u origin main

git remote add origin中的 origin 只是远端别名，可以任意命名，但行业内默认用 origin，不要标新立异。-u是--set-upstream的简写，建立本地分支和远端分支的跟踪关系，只推送一次，之后直接敲git push就能推到正确的远端分支。如果平台默认分支名是 master，而本地是 main，推送前执行git branch -M main统一分支名，否则会多出一个远端分支。

4.2 日常推拉的核心参数：pull --rebase 与 push 的安全姿势

日常开发中用到最多的三个命令是 pull、push 和 log，参数上的差别决定了提交历史是否干净。

# 从远端拉取最新代码，并把本地提交垫到远端提交之后，避免产生合并节点 git pull --rebase origin main # 推送当前分支到远端，origin 后不写分支名时，推的是跟踪分支 git push origin feature/login # 查看最近五条提交，确认 rebase 后历史是线性的 git log --oneline -5 # 查看本地绑定的所有远端地址，防止串到别的平台 git remote -v

git pull --rebase是团队协作里最重要的一个参数。默认的git pull等价于 fetch 加 merge，多人提交频繁时会留下一堆Merge branch 'xxx' into xxx的节点，历史图最终乱成一团。rebase 会把本地未推送的提交摘下来，垫到远端最新提交之后，历史保持线性。但 rebase 有一个使用边界：如果本地提交已经被别人 clone 过去，不要 rebase，否则对方下次 pull 会冲突到怀疑人生。

git remote -v检查是我每次切换平台后的习惯动作。本地仓库同时关联了 GitHub 和 Gitee 时，稍不注意就把代码推到了错误的平台，尤其是公司同时用两个平台做内外网隔离的场景，这一条命令能避免很多尴尬。

4.3 命令行之外的两条入口：IDEA 连接 Gitee/GitLab 与 SourceTree 配置私有 GitLab

团队里总有同事不习惯命令行，IDE 和图形化工具的配置也值得写清楚。

IDEA 连接 Gitee 远程仓库的标准路径是：File → New → Project from Version Control，粘贴 SSH 地址，IDEA 会自动读取~/.ssh/config里的配置。连接后首次推送会让选择远端分支，之后右下角的 Git 面板就能完成 commit、push、pull 全部操作。IDEA 连接 GitLab 时需要额外配置 Personal Access Token：Settings → Version Control → GitLab，填入带write_repository权限的 token，不要用账号密码登录。

SourceTree 连接私有 GitLab 有一个前提：SourceTree 自带的 Git 版本可能较旧，对 ed25519 密钥支持不完全。遇到认证失败，先到 Tools → Options → Git 里把 Git 版本切换为 System Git，再在 Authentication 里用 HTTPS token 方式添加 GitLab 账号，或者直接 clone 时使用git@gitlab.yourcompany.com:组名/仓库名.git格式的 SSH 地址。SourceTree 会读取系统~/.ssh/config，所以第 3 章配置好的密钥在这里依然生效。

5. 高频翻车现场：推送被拒、验证码异常与 GitLab 启动不了的排查实录

这一章是血泪经验合集。三平台的操作命令几乎一样，翻车点也高度重合，把这四条排查思路刻进脑子里，能省掉一半的折腾时间。

5.1 push 被拒：远端领先、分支保护和 Token 失效的三种表现

现象：git push报! [rejected] non-fast-forward，或者remote: GitLab: You are not allowed to push code，再或者fatal: Authentication failed。

原因要分三种看。non-fast-forward是远端有新提交而本地没有拉取，Git 为了保护远端历史拒绝覆盖；You are not allowed to push code是分支保护策略在起作用，常见于 GitLab 的 main 分支被设置为 Protected；Authentication failed则是令牌过期或者令牌权限不足。

解决方式对应也很直接：

# 场景一：远端领先，先 rebase 再推送 git pull --rebase origin main && git push # 场景二：分支保护，需要找管理员开通 Maintainer 权限 # 或者在 GitLab 项目设置里把当前分支的 Protected 属性去掉 # 场景三：令牌失效，重新生成 Personal Access Token # 生成时勾选 write_repository / api 权限，替换到 IDE 或命令行缓存里

一个非常典型的报错是login failed. check api token or gitlab version，常见于 IDEA 连接公司自建 GitLab。原因通常是 GitLab 版本较旧，新生成的 token 格式不被旧版本识别，或者 token 没勾选 api 权限。解决方式是登录 GitLab 后台确认版本号，重新生成 token 时至少勾选api和write_repository两个权限，再清掉 IDE 里缓存的旧凭据重试。

5.2 验证码与登录态：Gitee issue 验证码错误和浏览器旧缓存

现象：Gitee 上创建 Issue 时，验证码肉眼看着没输错，提交却反复提示“验证码错误”。

原因多数不在账号，而在浏览器状态。浏览器扩展拦截了验证码请求、旧缓存携带了过期会话、多标签页共享了失效的验证码 token，这三种情况都会导致提交失败。这个问题很玄学，因为换个时间再试可能就好了，容易让人以为是自己账号被限制。

解决方式按顺序操作：换无痕窗口重试、清理该站点的 Cookie、关闭浏览器验证码相关扩展后刷新页面。如果是在公司网络环境里反复出现，也可能是出口 IP 被风控，换到手机热点再试一次，基本能定位是网络层还是浏览器层的问题。

5.3 单文件超过 100MB：该上 LFS 还是一刀切拆分

现象：push 时报文件超过单文件大小限制，GitHub 和 Gitee 的单文件上限都在 100MB 左右；或者仓库整体超过 1GB 后，clone 超时、网页加载卡顿。

原因几乎都是误提交了二进制构建产物、安装包、模型文件或数据集。Git 本身不擅长管理大文件，每次修改都会把整个文件的新版本存进对象库，仓库体积会快速膨胀。

解决方式有两个方向。如果大文件是偶尔更新的资源，用 Git LFS 管理：

# 跟踪指定类型的大文件，LFS 会把文件内容存到独立存储，仓库里只保留指针 git lfs track "*.zip" "*.tar.gz" "*.bin" git add .gitattributes git commit -m "track large files with lfs" git push origin main

如果大文件根本不需要进仓库，比如编译产物和依赖包，最稳的做法是删除历史中的大文件。用git filter-repo清理历史，操作前先备份仓库，清理后所有协作者都需要重新 clone。还有一种更纯粹的做法：一分为二，大文件挪到对象存储或内部网盘，仓库里只保留下载脚本。Gitee 的 LFS 免费额度有限，团队里最省心的方案往往是第三种，而不是在 LFS 配额边缘反复试探。

5.4 GitLab 容器反复退出：从日志到内存的定位顺序

现象：Docker 启动 GitLab 后容器几秒就退出，或者容器在跑但网页一直 502。

原因通常集中在四个方向：内存不足、挂载目录权限不对、端口冲突、shm 空间不足导致 Postgres 崩溃。GitLab 全家桶对内存要求很高，4G 内存的机器勉强能跑，2G 内存基本起不来。

定位顺序固定为看日志、看资源、看端口：

# 第一步：看容器日志，找到真正的退出原因 docker logs -f gitlab # 第二步：确认磁盘和内存，GitLab 至少需要 4G 可用内存 df -h free -m # 第三步：确认映射端口没有被占用 ss -ltnp | grep 8080

日志里如果出现Permission denied，检查/srv/gitlab三个挂载目录的所有者是否为 65532 或其他容器内用户；如果 postgres 相关日志频繁报错，把 compose 文件里加上shm_size: '256m'，这个参数在很多默认配置下没有设置，而 GitLab 内置的 PostgreSQL 对共享内存很敏感。端口冲突则直接换映射端口，比如把8080:80改成18080:80。

6. 自托管 GitLab 社区版：Docker Compose 部署、启动等待与维护习惯

团队跨过托管平台阶段、决定自建 GitLab 时，Docker Compose 是最容易落地的方式。它绕开了 GitLab 官方安装包对操作系统版本的严格限制——新版 Omnibus 对 Ubuntu 等系统的版本要求越来越严格，Docker 镜像自带全套依赖，反而省心。本地部署一台 GitLab 社区版，一个 compose 文件就能起步。

6.1 最小 Docker Compose 文件与三个必调参数

services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab restart: always hostname: gitlab.example.com environment: GITLAB_OMNIBUS_CONFIG: | external_url 'http://gitlab.example.com' gitlab_rails['time_zone'] = 'Asia/Shanghai' ports: - "8080:80" - "2222:22" volumes: - /srv/gitlab/config:/etc/gitlab - /srv/gitlab/logs:/var/log/gitlab - /srv/gitlab/data:/var/opt/gitlab shm_size: '256m'

三个必调参数：external_url决定访问地址和回调地址，写错会导致注册、推送回调全部异常；Port 2222:22用于避免宿主机 22 端口被占用，clone 地址里的端口从这里来；shm_size不设置时默认只有 64m，GitLab 内置 PostgreSQL 在并发稍高时会直接崩溃。三个卷必须持久化，容器删了重建数据还在，这是自托管最基本的后悔药。部署完成后还要单独起一个 GitLab Runner 容器，CI 任务才能跑起来。

6.2 启动慢的真相、代码量统计与升级之前先备份

GitLab 启动慢不是故障，是常态。容器起来后内部要执行几十个服务的初始化和 reconfigure，通常要等 3 到 5 分钟才能访问网页，期间打开域名看到 502 属于正常现象，不要急着重启容器。判断初始化完成的标志是docker logs -f gitlab中出现gitlab Reconfigured!或容器状态变为 healthy。

团队问“GitLab 代码量怎么看”时，不要去找代码行数统计按钮——那东西不存在。常见做法是看仓库大小：项目设置里的仓库信息直接显示体积；需要脚本化统计时，用 GitLab 自带的 GraphQL API 查询项目存储统计，比逐个翻网页可靠。代码量本身没有统一标准，提交次数、仓库体积、活跃开发者数量各代表不同维度，先想清楚要回答什么问题再去看哪个指标。

最后是老生常谈但必须做的一件事：升级。GitLab 高危漏洞修复方案只有一个，就是及时升到修复版本。升级前先备份/srv/gitlab下的三个卷再动，不要直接对正在运行的容器执行docker exec gitlab apt upgrade。我现在的习惯是：任何平台切换前先git remote -v确认地址，任何自托管升级前先备份卷，任何 SSH 连不上先看 config 文件。这三个习惯帮我省掉了大量夜间紧急修复，希望帮到你。

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