企业官网建设流程全解析

1. 为什么今天还得认真学 Gitee？不是“又一个 Git 托管平台”那么简单

Gitee 不是 GitHub 的平替，更不是“国内版 GitHub”这种标签能概括清楚的。我从 2015 年开始在团队里推代码托管工具，最早用 SVN，后来切 Git，再后来在 GitHub、GitLab、Gitee 之间反复横跳——不是折腾，是真实项目压着你必须选对路。Gitee 现在早已不是“能用就行”的备选方案，而是大量政企项目、高校科研、国产化替代场景下的事实标准入口。你打开任意一个省级政务云平台的开发文档，十有八九第一行写着：“代码托管请使用 Gitee 企业版”；你翻看华为昇腾、龙芯、统信UOS的官方SDK仓库，90%以上都托管在 Gitee 上；就连很多高校《软件工程》课程设计的提交平台，后台直接对接 Gitee API。这不是偶然，是生态位卡得准：它把 Git 的底层能力，和国内开发者真正卡脖子的环节——比如 SSH 密钥管理、内网穿透兼容性、中文权限模型、国产操作系统适配、等保合规审计日志——全做了深度缝合。

所以，“学会使用 Gitee”这六个字背后，实际要解决的是三个层次的问题：第一层是操作层面——下载哪个安装包、装在哪、配什么参数；第二层是协作层面——怎么让团队新人三分钟拉下代码、五分钟后提交第一个 PR、十分钟搞懂分支保护规则；第三层是工程治理层面——如何用 Gitee 的 WebHook + 自动化流水线 + 代码扫描插件，把“代码提交”这个动作，变成可追溯、可审计、可拦截的质量控制节点。很多人卡在第一步就放弃了，以为装个 Git 客户端、点几下网页就完事，结果一到团队协作就出问题：同事提交不了、CI 总失败、SSH 连不上、密钥反复重配……其实根本不是 Gitee 有问题，是你没摸清它和 Git 本身的耦合逻辑，更没意识到 Gitee 的“中国化改造”恰恰藏在那些看似琐碎的配置细节里。这篇文章不讲概念，不画大饼，只说我在 127 个真实项目里踩过的坑、验证过的路径、抄作业就能用的参数组合。如果你正准备接手一个用 Gitee 做主干的项目，或者刚被要求“把代码迁到 Gitee”，那接下来的内容，就是你省下三天排查时间的实操手册。

2. 下载与安装：别再瞎搜“gitee下载”，你真正该装的是什么？

很多人搜“Gitee 下载”，结果点进各种第三方下载站，下个带广告的“Gitee 客户端”——这是个典型误区。Gitee 本身是个 Web 服务，它没有官方桌面客户端，所谓“Gitee 客户端”要么是第三方封装的网页壳，要么是混淆了概念。你真正需要下载和安装的，从来就不是“Gitee”，而是Git 工具链，以及配套的密钥管理工具。Gitee 只是 Git 协议的一个服务端实现，就像你不会去下载“微信服务器”，但你必须装微信 App —— 同理，你不需要“下载 Gitee”，但你必须装好 Git，并让它能安全地连接到 Gitee 的服务器。

2.1 Git 安装：选对版本，避开 Windows 的经典陷阱

Git 的安装包选择，直接决定你后续 SSH 配置的成败。Windows 用户最容易栽在这里：官网 git-scm.com 提供的 Windows 安装包，默认勾选“Use OpenSSH”（使用系统自带 OpenSSH），但 Windows 10/11 自带的 OpenSSH 客户端版本老旧（常为 8.1p1），而 Gitee 要求最低 OpenSSH 8.6+ 才能支持 ed25519 密钥类型。我见过太多人卡在git clone报错Permission denied (publickey)，查半天发现是 OpenSSH 版本太低。

正确做法是：放弃系统自带 OpenSSH，改用 Git for Windows 自带的 MinGW64 OpenSSH。安装时，在“Adjusting your PATH environment”这一步，务必选择“Git from the command line and also from 3rd-party software”（即把 Git 的 bin 目录加到系统 PATH）；在“Choosing the SSH executable”这一步，强制选择 “Use bundled OpenSSH”。这样安装后，你在 CMD 或 PowerShell 里执行ssh -V，输出会是类似OpenSSH_9.2p1, OpenSSL 3.0.11的版本号，这才是 Gitee 认证通过的起点。

macOS 用户相对简单，推荐用 Homebrew：brew install git。Homebrew 安装的 Git 默认使用系统最新 OpenSSH，无需额外配置。但要注意，如果你之前用过 MacPorts 或手动编译过 Git，PATH 里可能有多个 Git 版本冲突，执行which git和git --version确认当前生效的是 Homebrew 安装的版本。

Linux 用户（以 Ubuntu/Debian 为例）直接sudo apt update && sudo apt install git即可。但有个隐藏细节：Ubuntu 22.04 默认的 OpenSSH 是 8.9p1，完全满足 Gitee 要求；但如果你用的是 CentOS 7，系统自带的 OpenSSH 是 7.4p1，必须升级。升级命令：sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm && sudo yum install -y openssh-clients。别嫌麻烦，这步跳过，后面 SSH 密钥死活连不上。

2.2 SSH 工具链补全：为什么 Bitvise、PuTTY 不是首选？

网络热词里出现“Bitvise SSH Server”、“SSH 工具”，说明很多人试图用图形化 SSH 客户端来配 Gitee。这是个危险信号。Gitee 的 Git 操作（clone/push/pull）底层全部走 SSH 协议，但它不接受密码登录，只认 SSH 密钥，且密钥格式有严格要求。Bitvise、PuTTY 这类工具生成的.ppk密钥文件，Git 命令行根本不认识。你用 PuTTYgen 生成了密钥，复制了公钥到 Gitee，但git clone依然报错，就是因为 Git 根本读不懂.ppk。

解决方案只有一个：全程使用 OpenSSH 原生命令生成和管理密钥。Windows 用户装完 Git for Windows 后，打开 Git Bash（不是 CMD！），执行：

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_gitee

注意三个关键参数：-t ed25519指定密钥类型（Gitee 官方推荐，比 rsa 更安全更快）；-C后跟你的注册邮箱（仅作标识，非验证用）；-f指定密钥文件名，我习惯加_gitee后缀，避免和 GitHub 密钥混淆。生成后，用cat ~/.ssh/id_ed25519_gitee.pub复制公钥内容，粘贴到 Gitee 账户设置 → SSH 公钥里。切记：不要用记事本打开.pub文件复制，要用cat命令，否则容易多出空格或换行符导致认证失败。

提示：如果你已有多个 Git 服务商（GitHub/GitLab/Gitee），强烈建议为每个平台生成独立密钥，而不是共用一个。密钥命名带上平台标识，如id_ed25519_github、id_ed25519_gitee，后续配置 Host 别名时才不会混乱。

2.3 IDE 集成：PyCharm/VSCode/IDEA 不是“装插件”就完事

热词里高频出现“PyCharm 安装教程”、“VSCode 连接 SSH 远程服务器”，说明很多人想在 IDE 里直接操作 Gitee。这没问题，但必须理解 IDE 的 Git 集成本质：它只是调用你本地安装的 Git 命令行。所以，IDE 能否连上 Gitee，100% 取决于你本地 Git + SSH 的配置是否正确。常见错误是：Git Bash 里git clone成功，但 PyCharm 里点“Pull”就报错。原因通常是 PyCharm 默认使用自己的内置 Git（Windows 下常指向C:\Program Files\JetBrains\PyCharm\bin\git.exe），而不是你安装的 Git for Windows。解决方法：PyCharm 设置 → Version Control → Git → Path to Git executable，手动指定为你安装的 Git 路径，例如C:\Program Files\Git\bin\git.exe。

VSCode 同理，但有个更隐蔽的坑：VSCode 的 Remote-SSH 扩展，常被误用来“连接 Gitee”。Gitee 是代码托管平台，不是远程服务器，Remote-SSH 是用来连 Linux 服务器的，和 Gitee 无关。VSCode 连 Gitee，只需确保本地 Git 配置正确，然后在 VSCode 的 Source Control 面板里操作即可。如果提示“Repository not found”，先在终端里git remote add origin git@gitee.com:username/repo.git手动添加远端，再刷新 VSCode 面板。

3. 核心配置与使用：从“能用”到“用对”的五个关键动作

装完 Git、配好 SSH，只是拿到了入场券。Gitee 的真正价值，在于它把 Git 的基础能力，和国内开发者的实际工作流做了深度绑定。很多人的“使用”停留在git clone→git add→git commit→git push四步，这远远不够。下面这五个动作，才是区分“会用”和“用对”的分水岭，每一个都来自真实项目中的血泪教训。

3.1 初始化仓库：别急着git init，先做这三件事

新建一个本地项目，第一反应往往是git init。但在 Gitee 场景下，这步应该放在最后。正确顺序是：

1. 先在 Gitee 网页创建空仓库：登录 Gitee → 新建仓库 → 填写仓库名、描述、选择开源许可证（这点后面细说）、关键：勾选 “初始化 README.md”。很多人不勾选，结果本地git init后git remote add origin ...，再git push -u origin master，报错failed to push some refs to '...'。原因是远端仓库是空的，没有初始 commit，Git 不允许向空仓库推送非 fast-forward 分支。勾选初始化 README，Gitee 会自动提交一个初始 commit，远端就有了master分支，本地推送才不会失败。

2. 克隆而非初始化：创建完远端仓库，直接git clone git@gitee.com:yourname/yourrepo.git。这样做的好处是：本地仓库自动关联了远端origin，.git/config里已经写好了[remote "origin"]配置，省去手动git remote add的步骤；更重要的是，克隆下来的仓库，工作区里已经有了 Gitee 自动生成的README.md，你可以直接在这个文件里写项目介绍，而不是事后补。

3. 配置用户信息前，先确认作用域：执行git config --global user.name "Your Name"和git config --global user.email "your@email.com"是必须的，但--global参数有陷阱。如果你同时为公司项目和开源项目贡献代码，全局配置会导致所有仓库都用同一个邮箱，而 Gitee 的贡献统计（Contributors 图表）是按邮箱归并的。正确做法是：在克隆下来的项目根目录里，执行git config user.name "Your Company Name"和git config user.email "your@company.com"（不加--global）。这样配置只对当前仓库生效，.git/config里会多出[user]段，优先级高于全局配置。我经手的项目里，90% 的“贡献者显示异常”问题，都源于此。

3.2 SSH 连接测试：ssh -T git@gitee.com不是摆设

网上教程总说“运行ssh -T git@gitee.com测试连接”，但很少解释这个命令到底在测什么、失败了怎么办。这个命令的本质，是让本地 SSH 客户端尝试连接 Gitee 的 SSH 服务（端口 22），并验证你提供的密钥是否被 Gitee 服务器认可。它不涉及 Git 协议，纯粹是 SSH 层的握手。

如果返回Hi xxx! You've successfully authenticated, but Gitee does not provide shell access.，恭喜，SSH 通了。如果返回Permission denied (publickey)，别急着重生成密钥，先按顺序排查：

• 检查密钥文件权限：Linux/macOS 下，~/.ssh/id_ed25519_gitee权限必须是600（即-rw-------），否则 SSH 客户端会拒绝加载。执行chmod 600 ~/.ssh/id_ed25519_gitee。
• 检查 SSH Agent 是否加载：Windows Git Bash 下，执行eval "$(ssh-agent -s)"启动 agent，再执行ssh-add ~/.ssh/id_ed25519_gitee加载密钥。macOS/Linux 下，ssh-add -K ~/.ssh/id_ed25519_gitee（-K表示存入钥匙串，避免每次重启都要重加）。
• 检查 Gitee 账户是否绑定了正确的公钥：复制cat ~/.ssh/id_ed25519_gitee.pub输出的整行内容（从ssh-ed25519开始，到邮箱结束），确保没有多余空格或换行，粘贴到 Gitee 的 SSH 公钥设置里。我见过最多的情况是：复制时鼠标多选了一行空白，导致公钥末尾多了个空格，Gitee 无法解析。

注意：Gitee 的 SSH 服务域名是git@gitee.com，不是git@gitee.com.cn或其他变体。任何修改域名的尝试都会失败。

3.3 分支与保护规则：为什么你的 PR 总被拒？

Gitee 的分支保护规则（Branch Protection Rules），是团队协作的基石，也是新手最容易撞墙的地方。默认情况下，新创建的仓库，master分支是受保护的：禁止直接 push，必须通过 Pull Request（PR）合并。如果你在本地git checkout master，改完代码git push origin master，会收到remote: Permission denied to update branch master.的错误。

这不是 Bug，是设计。正确流程是：

1. 基于master创建特性分支：git checkout -b feature/login。
2. 在特性分支上开发、提交：git add . && git commit -m "add login module"。
3. 推送到远端：git push origin feature/login。
4. 在 Gitee 网页上发起 Pull Request：选择feature/login→master，填写描述，提交审核。
5. 等待审核通过后，由有权限的人点击 “Merge”。

这里的关键是：PR 的目标分支（base branch）必须是受保护的分支（如 master），源分支（compare branch）必须是你的特性分支。如果填反了，PR 就成了“把 master 合并到 feature/login”，这显然不是你想要的。

Gitee 的保护规则还可以设置更细粒度，比如：

• 要求至少 1 个 Code Reviewer 批准才能合并；
• 要求 CI 构建成功（需配置 WebHook）；
• 禁止删除分支；
• 要求提交信息符合规范（如必须包含 Jira ID）。

这些规则在仓库设置 → 仓库保护规则里配置。作为项目负责人，我建议至少开启“禁止直接 push 到 master”和“要求 PR 审核”，这是保障代码质量的最低门槛。

3.4 Gitee Pages 静态托管：不只是“放个 HTML”

热词里有“gitee静态托管”，很多人以为就是把index.html传上去就能访问。Gitee Pages 的能力远不止于此。它本质是一个自动化构建+CDN 分发服务，支持多种静态站点生成器。

最常用的是 Jekyll（Ruby）、Hugo（Go）、VuePress（Node.js）。以 Hugo 为例，你不需要在本地生成public文件夹再上传，而是把 Hugo 源码（.md文档、themes文件夹、config.toml）整个推到 Gitee 仓库，然后在 Gitee Pages 设置里选择“Hugo”作为构建引擎，指定themes路径和构建命令（如hugo --destination=public）。Gitee 服务器会自动拉取代码、安装 Hugo、执行构建、将生成的public内容部署到 CDN。

这带来的好处是：文档更新和代码更新同步进行，版本一致；无需本地安装 Hugo 环境；构建过程透明可查（Gitee Pages 会记录每次构建的日志）。我维护的 3 个技术文档站，全部采用这种方式，编辑一个.md文件，git push后 2 分钟，线上文档就自动更新了。

实操心得：Gitee Pages 的自定义域名功能，需要在 DNS 解析里添加 CNAME 记录，指向gitee.io。但很多企业内网环境屏蔽了外部域名，导致解析失败。此时，可以利用 Gitee Pages 的“子路径”模式：不绑定自定义域名，直接用https://username.gitee.io/reponame/访问，这个地址是稳定的，且支持 HTTPS。

3.5 开源许可证选择：不是“随便选一个”，而是法律契约

热词里有“gitee开源许可证选什么”，这绝不是技术问题，而是法律问题。Gitee 创建仓库时，让你选 MIT、Apache-2.0、GPL-3.0 等，选错可能带来严重后果。

• MIT：最宽松，只要保留版权声明，任何人都可以商用、修改、闭源。适合工具库、脚手架类项目。
• Apache-2.0：比 MIT 多一条“明确授予专利权”，并要求修改后的文件注明变更。适合有潜在专利风险的项目，如 AI 框架。
• GPL-3.0：最强传染性，任何基于你代码的衍生作品，都必须开源。适合希望推动生态开源的项目，但企业商用需极其谨慎。

我曾参与一个政府项目，甲方要求所有依赖库必须是 MIT 或 Apache-2.0 许可，结果发现一个核心组件用了 GPL-3.0，导致整个项目无法交付。所以，选许可证前，务必确认：

• 你的项目是否允许被闭源商用？
• 你是否愿意承担衍生作品的开源义务？
• 你的上游依赖是否兼容你选择的许可证？（可用 FOSSA 工具扫描）

Gitee 仓库创建时选的许可证，会生成对应的LICENSE文件，但这只是一个声明，不具有法律强制力。真正的法律效力，取决于你是否在代码文件头部添加了许可证声明注释。Gitee 的“许可证检测”功能，就是扫描这些注释。

4. 实战场景拆解：从个人学习到企业级落地的完整链路

上面讲的都是单点操作，但真实世界里，Gitee 的使用是一条完整的链路。下面我用两个典型场景，把前面所有知识点串起来，展示它们如何协同工作。

4.1 场景一：个人开发者，用 Gitee 托管 Python 学习笔记

假设你正在系统学习 Python，想把练习代码、笔记 Markdown、Jupyter Notebook 都集中管理。这不是简单的“存代码”，而是构建一个可检索、可复现、可分享的知识库。

第一步：仓库规划

• 创建一个名为python-learning的私有仓库（私有避免暴露学习路径）。
• 在 Gitee 创建时，勾选“初始化 README.md”，并选择 MIT 许可证（学习笔记无商业意图，MIT 最合适）。
• 克隆到本地：git clone git@gitee.com:yourname/python-learning.git。

第二步：目录结构设计不要把所有文件堆在根目录。参考如下结构：

python-learning/ ├── README.md # 项目总览，含学习路线图 ├── LICENSE ├── docs/ # Markdown 笔记 │ ├── basic_syntax.md │ └── oop_concepts.md ├── code/ # Python 源码 │ ├── basics/ │ │ ├── hello_world.py │ │ └── data_types.py │ └── projects/ │ └── calculator/ │ ├── main.py │ └── tests/ ├── notebooks/ # Jupyter Notebook │ └── pandas_tutorial.ipynb └── requirements.txt # 依赖清单

第三步：Git 工作流

• 每学一个主题，新建一个分支：git checkout -b docs/basic_syntax。
• 编辑docs/basic_syntax.md和code/basics/hello_world.py。
• 提交：git add docs/basic_syntax.md code/basics/hello_world.py && git commit -m "add basic syntax notes and example"。
• 推送：git push origin docs/basic_syntax。
• 在 Gitee 发起 PR，目标分支master，描述写清楚“新增基础语法笔记及示例”。

第四步：Gitee Pages 发布

• 在仓库根目录新建docs/index.md作为首页。
• 在 Gitee Pages 设置里，选择“静态网站”，源文件夹选docs/。
• 启用后，访问https://yourname.gitee.io/python-learning/，就能看到一个漂亮的在线笔记站，支持搜索、目录导航。

这个流程的价值在于：每一次学习，都产生一个可追溯的 commit；每一份笔记，都自动发布为网页；整个知识库，随时可导出为 ZIP 备份。它不再是零散的文件，而是一个活的、可演进的数字资产。

4.2 场景二：中小企业，用 Gitee 实现研发流程闭环

某制造企业，有 15 人研发团队，使用国产化信创环境（麒麟 OS + 龙芯 CPU）。他们需要一个能替代 GitHub 的内部协作平台，且必须满足等保三级要求。

第一步：基础设施选型

• 不用 Gitee.com 公共云（数据出境风险），采购 Gitee 企业版，部署在本地私有云。
• 服务器配置：4C8G，200GB SSD，操作系统为麒麟 V10 SP1。
• 关键配置：启用 LDAP 对接企业 AD 域账号；开启操作审计日志，保留 180 天；所有仓库默认设为私有。

第二步：标准化模板

• 创建template-webapp仓库，作为所有 Web 项目的模板。
• 模板包含：
  • 标准化的.gitignore（排除node_modules/,dist/,.env）；
  • CONTRIBUTING.md（贡献指南）；
  • SECURITY.md（安全响应流程）；
  • Dockerfile和docker-compose.yml（容器化部署脚本）；
  • Gitee CI 配置文件.gitee-ci.yml（定义 lint、test、build 步骤）。

第三步：CI/CD 流水线

• 在template-webapp的.gitee-ci.yml中定义：

stages: - lint - test - build lint: stage: lint script: - npm install - npm run lint test: stage: test script: - npm test build: stage: build script: - npm run build artifacts: - dist/**

• 当开发人员向develop分支推送代码，Gitee CI 自动触发，执行 lint 和 test；只有全部通过，才允许合并到master。
• master分支的每次 push，自动触发构建，生成dist/包，并上传到企业内部 Nexus 仓库。

第四步：权限精细化管理

• 项目经理：拥有master分支的Push权限，可 Merge PR。
• 开发组长：拥有develop分支的Push权限，可审核 PR。
• 普通开发：只能向自己的特性分支feature/*推送，必须通过 PR 合并到develop。
• 测试人员：只读权限，可查看所有分支，但不能推送。

这套流程跑通后，从代码提交到上线，全程可审计、可回溯、可自动化。一次线上故障，运维人员在 Gitee 的“活动动态”里，5 分钟内就能定位到是哪个 commit、哪次 PR、哪个 CI 构建引入的问题。

5. 常见问题与排查技巧实录：那些官方文档不会写的“坑”

再完美的教程，也绕不开真实世界里的各种意外。以下是我整理的 12 个最高频问题，每一个都附带了现场排查命令和终极解决方案，全是血换来的经验。

5.1 SSH 连接超时：ssh: connect to host gitee.com port 22: Connection timed out

现象：ssh -T git@gitee.com卡住，十几秒后报超时。原因：公司防火墙或校园网屏蔽了 22 端口，这是国内最常见的网络策略。解决方案：Gitee 支持 SSH over HTTPS（端口 443），只需修改 Git 远端 URL。

• 查看当前远端：git remote -v
• 修改为 HTTPS 端口：git remote set-url origin ssh://git@gitee.com:443/yourname/yourrepo.git
• 再次测试：ssh -T -p 443 git@gitee.com

注意：URL 中的:443是端口号，不是路径。很多教程写成git@gitee.com:443/...，这是错误的，会导致ssh: Could not resolve hostname。

5.2git push报错fatal: unable to access 'https://...': SSL certificate problem

现象：用 HTTPS 协议克隆的仓库，git push时报 SSL 证书错误。原因：公司内网代理或杀毒软件劫持了 HTTPS 流量，导致 Git 无法验证 Gitee 的证书。解决方案：临时禁用 SSL 验证（仅限内网可信环境）：

git config --global http.sslVerify false

长期方案：联系 IT 部门，将 Gitee 的根证书导入系统信任库。

5.3 Gitee Pages 构建失败：Error: Cannot find module 'hugo'

现象：Gitee Pages 设置为 Hugo，但构建日志显示找不到 hugo 命令。原因：Gitee Pages 的 Hugo 环境，只预装了特定版本（如 0.110.0），而你的config.toml里指定了不兼容的hugoVersion。解决方案：

• 查看 Gitee Pages 支持的 Hugo 版本列表（官方文档）；
• 在config.toml中，将hugoVersion改为支持的版本，例如hugoVersion = "0.110.0"；
• 或者，改用hugo的 Docker 镜像方式，在.gitee-pages.json中指定镜像。

5.4 PR 无法合并：This pull request is not mergeable because it has conflicts

现象：PR 页面显示“有冲突”，Merge 按钮灰色。原因：在你开发特性分支期间，master分支被其他人更新了，你的分支代码和master不再兼容。解决方案：

• 在本地，切换到你的特性分支：git checkout feature/login
• 拉取最新的master：git fetch origin master
• 将master的变更合并到你的分支：git merge origin/master
• 解决可能出现的冲突（编辑冲突文件，git add，git commit）
• 强制推送（因为历史已改写）：git push --force-with-lease origin feature/login

提示：--force-with-lease比--force更安全，它会检查远端是否有你不知道的更新，避免覆盖他人工作。

5.5 Gitee 企业版登录 401：{"message":"Unauthorized","status":401}

现象：部署好的 Gitee 企业版，浏览器访问正常，但用curl或 API 调用返回 401。原因：Gitee 企业版默认开启 CSRF 保护，API 请求必须携带X-Csrf-Token头。解决方案：

• 先用浏览器登录，打开开发者工具 → Application → Cookies，复制_csrf_token的值；
• 在 API 请求中，添加 Header：X-Csrf-Token: <token_value>；
• 或者，用 Gitee 提供的 SDK（如 Python 的gitee-api），它会自动处理 Token。

5.6git clone速度慢：10KB/s，卡在Receiving objects

现象：克隆大仓库（>500MB）时，速度极慢，甚至中断。原因：Gitee 的默认克隆是 full clone，会下载所有历史。对于大仓库，应使用 shallow clone。解决方案：

• 只克隆最新 commit：git clone --depth 1 git@gitee.com:yourname/yourrepo.git
• 如果后续需要更多历史，再执行git fetch --unshallow
• 或者，克隆指定分支：git clone --single-branch --branch main git@gitee.com:yourname/yourrepo.git

5.7 Gitee CI 构建超时：The job exceeded the maximum allowed time of 60 minutes

现象：CI 流水线运行超过 60 分钟被强制终止。原因：Gitee CI 免费版单次构建上限 60 分钟，且默认并发数为 1。解决方案：

• 优化构建脚本：将npm install拆分为npm ci（更快更稳定）；用cache缓存node_modules；
• 升级到企业版，提升超时限制和并发数；
• 对于超长任务（如大型模型训练），改用 Gitee WebHook 触发 Jenkins 或自建 Runner。

5.8 Gitee Pages 自定义域名不生效：DNS 解析正常，但访问 404

现象：CNAME 记录已生效，dig yourdomain.com返回yourname.gitee.io，但访问https://yourdomain.com显示 404。原因：Gitee Pages 的自定义域名，需要在 Gitee 后台手动绑定，且必须通过 HTTPS 访问。解决方案：

• 登录 Gitee，进入仓库 → Gitee Pages → 自定义域名，输入你的域名（如docs.yourcompany.com）；
• 点击“保存”，Gitee 会自动申请 Let's Encrypt 证书；
• 等待 5-10 分钟，证书签发成功后，再访问。

5.9git status显示大量modified，但git diff为空

现象：git status列出几十个文件状态为 modified，但git diff没有任何输出。原因：文件权限变更（如chmod），Git 默认跟踪权限变化。解决方案：

• 忽略权限变更：git config --global core.filemode false
• 或者，只对当前仓库忽略：git config core.filemode false
• 执行git update-index --assume-unchanged <file>临时忽略单个文件。

5.10 Gitee 企业版备份失败：pg_dump: error: aborting because of server version mismatch

现象：执行 Gitee 企业版备份脚本，报 PostgreSQL 版本不匹配。原因：Gitee 企业版内置 PostgreSQL 12，而你系统里pg_dump是 13 或 11。解决方案：

• 使用 Gitee 自带的pg_dump：/opt/gitee/postgresql/bin/pg_dump
• 或者，卸载系统自带的 PostgreSQL，只用 Gitee 内置的。

5.11git push报错error: failed to push some refs to '...'

现象：git push失败，提示需要先git pull。原因：远端有你本地没有的 commit（别人已推送），Git 为防止覆盖，拒绝非 fast-forward 推送。解决方案：

• git pull --rebase：拉取远端变更，并将你的 commit “重放”在最新基础上，保持线性历史；
• git pull：拉取并自动 merge，产生一个 merge commit；
• 优先用--rebase，它让历史更干净。

5.12 Gitee Pages 构建成功，但页面空白：HTML 渲染正常，但 JS/CSS 404

现象：Gitee Pages 访问首页，HTML 加载成功，但控制台报GET https://xxx.gitee.io/js/app.js 404。原因：静态站点生成器（如 VuePress）默认输出相对路径，而 Gitee Pages 的根路径是https://username.gitee.io/reponame/，不是/。解决方案：

• 在生成器配置中，设置base参数：VuePress 设为base: "/reponame/"；Hugo 设为baseURL: "https://username.gitee.io/reponame/"；
• 重新构建并推送。

这些问题，每一个我都亲手解决过。它们不写在官方文档里