简介面向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 集成有强需求时再考虑私有化。平台默认可见性私有仓库内置 CI/CD国内访问典型场景GitHub公开优先免费GitHub Actions不稳定开源协作、技术社区、个人作品集Gitee公开优先免费Gitee Go稳定国内团队协作、个人备份GitLab私有优先免费内置 GitLab CI取决于部署位置企业私有化、DevOps 一体化2.3 迁移成本动手之前先看这三点很多团队不是从零选型而是从 GitHub 迁到 Gitee或从 Gitee 迁到公司 GitLab。迁移本身不复杂复杂的是迁移前没算清成本。第一点是远端地址。GitHub 的 clone 地址是gitgithub.com:组织名/仓库名.gitGitee 是gitgitee.com:用户名/仓库名.gitGitLab 还带着自定义域名和端口。地址全换不意味着代码要重传一个 bare 仓库加 mirror 推送就能完成迁移# 用 bare 克隆方式拿到完整历史包括所有分支和标签 git clone --bare gitgithub.com:your-org/your-repo.git cd your-repo.git # 把整个仓库镜像推送到新平台远端仓库会自动补齐所有分支 git push --mirror gitgitee.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 而不是 HTTPSHTTPS 方式每次推送都要输用户名和密码现在三个平台都已经把密码登录改为令牌登录令牌有过期时间过期后第一次推送就会报Authentication failed。在团队里经常看到这样的场景同事的令牌三个月前过期某天连着推十次代码十次全部失败还以为是网络问题。SSH 是密钥对机制私钥留在本机公钥上传到平台配一次之后长期有效。它还有一个额外好处可以针对不同平台配置不同的私钥避免公司 GitLab 的私钥和个人 GitHub 账号混用。换行符处理也是考虑因素Windows 用户如果使用 HTTPS 克隆Git 的 autocrlf 设置偶尔会搞乱脚本文件SSH 协议下这个问题虽然也存在但排查链路更短。3.2 生成多平台隔离的密钥对与 config 文件常见做法是为三个平台各生成一把独立的 ed25519 密钥而不是一把钥匙走天下。生成方法如下# 生成三份密钥文件名区分平台避免互相覆盖 ssh-keygen -t ed25519 -C youexample.com -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C youexample.com -f ~/.ssh/id_ed25519_gitee ssh-keygen -t ed25519 -C youexample.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 keysGitee 在设置里的 SSH 公钥GitLab 在个人偏好设置里的 SSH Keys。生成完只是第一步要让 SSH 知道“哪个域名用哪把钥匙”必须写~/.ssh/configHost 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 gitgithub.com ssh -T gitgitee.com ssh -T gitgitlab.yourcompany.com验证输出的内容各有不同但含义一致GitHub 返回Hi yourname! Youve successfully authenticatedGitee 返回Hi 你的名字! Youve successfully authenticatedGitLab 返回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 gitgitee.com:your-name/demo.git git add . git commit -m init project # -u 参数把本地 main 分支和远端 main 分支绑定后续可以直接 git push git push -u origin maingit 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 -vgit 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 TokenSettings → Version Control → GitLab填入带write_repository权限的 token不要用账号密码登录。SourceTree 连接私有 GitLab 有一个前提SourceTree 自带的 Git 版本可能较旧对 ed25519 密钥支持不完全。遇到认证失败先到 Tools → Options → Git 里把 Git 版本切换为 System Git再在 Authentication 里用 HTTPS token 方式添加 GitLab 账号或者直接 clone 时使用gitgitlab.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 分支被设置为 ProtectedAuthentication 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不设置时默认只有 64mGitLab 内置 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 文件。这三个习惯帮我省掉了大量夜间紧急修复希望帮到你。本文还有配套的精品资源点击获取