企业官网建设流程全解析

前阵子整理名下开源仓库的时候，我盯着某个小工具在Gitee上的最后一次提交记录愣了半天——2023年11月，距今已经过去两年。代码明明一直在GitHub上正常更新，release、issue、CI全都在跑，Gitee这边却像被按下了暂停键。我一开始以为是同步脚本崩了，逐个排查之后发现，这根本不是我一个人的问题。不少我关注的项目，在Gitee上的主线版本都停在一个较早的时间点，有的甚至干脆就冻结在2023年。“Gitee上的代码，仿佛冻结在了2023年”这句话在技术社区里越来越多见，背后其实是开源项目多平台发布策略、镜像同步机制和平台规则三者共同作用的结果。这篇文章就把我这两年的踩坑经历和排查思路完整梳理一遍，给同样被多平台同步折腾过的开发者一个参考。

1. “冻结在2023年”到底是怎么回事

1.1 先看现象：主线持续更新，Gitee却停在原地

先说我那个小工具的情况。它是一个给命令行终端用的格式化输出库，代码量不大，但迭代挺勤快。GitHub上几乎每个月都有新提交，issue和PR虽然不多，但一直有反馈进来。按照最初的设想，GitHub是主仓库，每次push之后自动同步一份到Gitee，方便国内开发者下载和浏览。

但某天我点开Gitee仓库页面，发现最近一次提交还停留在两年前的某次重构。点进去看提交记录，连commit message都和GitHub上的对不上——不是缺了后面几十个commit，而是整个仓库的提交历史都跟GitHub不再连贯。我查了一下同步日志，发现从某个时间点开始，自动同步任务就处于“失败但没人发现”的状态。

这不是孤例。我翻了几个经常逛的项目的Gitee镜像，有的停在同一个月，有的中途断断续续更新过几次，然后又停了。有些项目的README里还挂着Gitee的“同步中”图标，但实际内容早就落后主仓库几个大版本。时间线高度集中在2023年，说明那年之后，整个同步生态经历了一波集体性变化。

1.2 一句话说清本质：主仓库与镜像仓库的角色分工

要理解这种“冻结”现象，得先分清主仓库和镜像仓库的定位差异。

绝大多数项目采用的模式是：GitHub作为唯一主仓库，所有代码、issue、PR、release、CI都围绕它运转。Gitee仓库只是GitHub的一个远端镜像，作用有两个：一是给国内访问者提供一个更稳定的下载入口，二是在GitHub出现不可用情况时留一份备份。

这种模式本身没问题，问题出在“镜像”这两个字上。镜像仓库天然是次要的，维护者在设计流程时，通常只会给它分配最低优先级的自动化任务，比如定时同步、webhook触发同步。可一旦这个自动化链路出了故障，镜像仓库就会陷入无人管理的状态。代码还是那份代码，但更新已经断了。

所以“冻结在2023年”最核心的现象就是：主仓库在持续演进，镜像仓库却因为同步链路失效，停留在了某个历史快照。这不是代码没人写，而是同步没人管。

2. 代码为什么停在两年前：四个关键推手

2.1 镜像同步机制本身就不够可靠

先说最直接的技术原因。Gitee官方提供的仓库镜像功能，本质上是把远端仓库拉取到本地。触发方式一般有两种：手动点击界面上的“同步”按钮，或者配置定时同步。手动同步意味着你得记得去点，这个动作放在日常迭代里，几乎注定会被遗忘。定时同步虽然自动化了，但频率、时间窗口往往受平台限制，更新及时性很难保证。

用GitHub Actions推流到Gitee是另一种常见做法，但GitHub Actions本身也有自己的问题。workflow的cron定时任务不保证精确执行，可能延迟十几分钟甚至更久，在高负载时段还会跳过。push事件触发的workflow偶尔也会因为API抖动而丢失事件。最头疼的是，这类同步任务一旦失败，默认情况下GitHub不会给你弹通知，日志躺在Actions页面里，你不主动打开根本看不到。

我统计过自己那个项目的同步记录，连续三周内，有一周的定时任务被跳过，还有两次push事件触发的workflow在“Checkout”阶段就失败了。整个过程静默无声，仓库首页照样显示“同步成功”之类的状态标识，但实际内容已经落后一个版本。这种不确定性叠加起来，就是“看起来一直在同步，实际上早就断了”的典型状态。

2.2 授权与凭证失效，自动化链路说断就断

第二个推手是凭证问题。自动化同步本质上就是一次git push操作，而git push需要认证。放在Gitee场景里，常见的方式是使用平台的私人令牌，把这个令牌存到GitHub仓库的Secrets里，workflow运行时用令牌去推送。

问题在于，令牌是会过期的。有些平台支持设置长期有效的令牌，但很多开发者为了安全会设置较短的有效期，我自己就干过这种事。有效期到了之后，Actions里的同步任务会开始报“Authentication failed”之类的错误。这个错误足够明确，但它只躺在日志里，不会主动通知你。Gitee端那边，仓库可能显示为“最后同步时间：2023年某月某日”，但为什么没更新，页面上一句话都没有。

更隐蔽的一种情况是令牌权限变更。比如你在Gitee后台重新生成了令牌，但忘了更新GitHub Secrets里的旧值；或者新令牌生成时少勾了projects相关的写权限。这两种情况都会让你在排查时花掉大量时间，因为报错信息可能完全一样，但权限问题更难察觉。

2.3 平台内容巡检带来的同步中断

第三个推手，也是2023年之后集中爆发的因素，是国内平台的内容合规流程。Gitee作为面向国内用户的服务，对仓库内容有巡检机制。仓库一旦命中了某些规则，状态会变成异常，轻则提醒整改，重则进入只读状态。

这个机制对同步链路的影响是决定性的：镜像仓库处于异常状态时，平台会拒绝接收新的推送。我在一次排查中发现，某个项目的README里夹带了一个测试用域名，因为历史原因一直躺在文档里，结果巡检判定为推广内容，仓库状态被标记为异常。从那一刻起，所有来自GitHub的同步push都被平台拒收，而GitHub那边的Actions还在傻乎乎地定时执行、正常退出，因为git push的返回码被吞掉了。

这类问题跟代码质量没有任何关系，纯粹是平台规则适配问题。处理方式要走平台的申诉流程，提交人工审核，等待周期从几小时到几天不等。在申诉期间，Gitee上的代码就维持着异常前的最新状态——看起来就像是被冻结了。

2.4 维护者精力有限，多端发布被战略性放弃

第四个推手最朴素：维护者的精力不够了。

开源项目的维护者绝大多数是个人开发者或者两三个人的小团队。他们的核心时间要花在功能开发、bug修复、issue回复、PR评审上。Gitee同步这件事，价值在于服务国内用户，但代价是需要持续投入人力盯着。一旦项目进入维护倦怠期，或者维护者换了工作、项目不再活跃，第一个被砍掉的东西往往就是“保证Gitee同步及时”这条。

我认识的一位开发者，维护着一个Java工具库，GitHub上有几百star，Gitee上也有不少fork。他后来换了个方向，主仓库都改成低频更新了，Gitee自然不会有人再去管。他跟我说得很直白：“不是不想同步，是真的没时间，而且Gitee上的issue和PR我根本没精力处理，同步过去反而多一份维护负担。”

所以你会发现，很多项目的Gitee仓库停更时间，跟它的GitHub主仓库开始降频更新的时间点高度重合。不是平台问题，也不是技术问题，就是维护者做了一个理性的取舍：多端同步的边际收益，已经不足以抵消维护成本。

3. 三套让Gitee“解冻”的实战同步方案

我自己试过三种比较成熟的同步方案，踩了不少坑才找到合适组合。下面把这三种方案的配置过程完整写出来，你可以根据自己的基础设施条件选一种。

3.1 方案A：直接用Gitee仓库镜像管理

最省事的方案，适用场景是“不用太频繁，能同步就行”。

操作路径大致如下：登录Gitee账号，进入目标仓库页面，找到“管理”入口，进入仓库设置，找到“仓库镜像管理”这个选项。点击“添加镜像仓库”，填入GitHub上的仓库地址，按照提示完成授权。之后在镜像管理页面，你可以选择手动触发同步，或者配置定时同步。

这个方案的优点是零代码，不需要写workflow，不需要本地环境。缺点是时效性差，手动触发容易忘，定时同步的间隔一般不会太短，而且Gitee主动拉取GitHub的稳定性并不算好，偶尔需要手动重试。

我建议把“手动同步”这个动作固化到你的发版清单里。比如每次打tag发release的时候，顺手去Gitee点一下同步，10秒钟的事，但能保证每个正式版本都同步过去了。日常的零碎提交不同步关系不大，版本快照跟上就行。

3.2 方案B：GitHub Actions自动推流（推荐）

如果你希望每次push都自动同步，GitHub Actions是最好的方式。原理很简单：checkout代码，然后添加Gitee作为remote，用Gitee私人令牌做认证，执行git push。顺序是反向的，是GitHub这边主动往Gitee推。

先配置Gitee私人令牌。进入Gitee个人设置，找到“私人令牌”页面，点击“生成新令牌”，勾选projects相关的写权限。生成之后马上复制保存，这是唯一一次能看到完整令牌的机会。

然后在GitHub仓库的Settings里，进入Secrets and variables，选择Actions，点击New repository secret，名字设为GITEE_TOKEN，值粘贴刚才的令牌。

接着在仓库根目录创建workflow文件，比如.github/workflows/sync-to-gitee.yml，内容如下：

name: Sync to Gitee on: push: branches: - main - master schedule: - cron: "0 2 * * *" workflow_dispatch: jobs: sync: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 - name: Push to Gitee env: GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }} run: | git remote add gitee https://oauth2:${GITEE_TOKEN}@gitee.com/yourname/yourrepo.git || true git push -f gitee main:main git push -f gitee master:master || true git push -f gitee --tags

我来解释一下这个workflow的设计思路。push事件监听main和master分支，保证常规提交实时同步。cron定时任务放在凌晨两点，作为兜底，处理那些push时间比较集中、可能被跳过的极端情况。最后一个workflow_dispatch是手动触发入口，方便你在紧急时刻主动跑一次。

注意push命令里我用了-f强推，这是有意的。因为镜像仓库不该有和主仓库分叉的历史，强推可以保证Gitee的代码永远和GitHub当前状态一致。代价是如果有人在Gitee上直接改了代码，强推会覆盖掉他们的提交。所以你在仓库说明里最好注明“Gitee为只读镜像，请到GitHub提交PR”，避免踩到协作冲突。

3.3 方案C：本地定时脚本同步

第三种方案适合那些不方便用GitHub Actions的场景，比如项目主仓库在自建服务器，或者你希望同步过程完全可控。

本地脚本的核心逻辑是：维护一个本地裸仓库，定期从GitHub拉取，再推送到Gitee。裸仓库是指只存git历史、不保留工作区的仓库，很适合做中转站。

脚本内容大致如下：

#!/bin/bash # sync_to_gitee.sh # 功能：将GitHub主仓库的代码同步到Gitee镜像仓库 MIRROR_DIR="/srv/git-mirror/yourrepo.git" cd "$MIRROR_DIR" # 拉取GitHub最新状态 git fetch origin --prune # 推送到Gitee，所有分支和tag一并推送 git push gitee --all -f git push gitee --tags -f echo "$(date '+%Y-%m-%d %H:%M:%S') sync finished"

然后在cron里配一条规则：

0 3 * * * /usr/local/bin/sync_to_gitee.sh >> /var/log/gitee-sync.log 2>&1

这个方案的优点是你可以在脚本里写各种失败通知逻辑，比如推送失败时调用企业微信机器人或者邮件发送报错。缺点是依赖本地服务器持续运行，而且需要提前配置好两个remote的认证，GitHub端一般用SSH key，Gitee端用令牌。

3.4 三种方案怎么选

如果你已经有GitHub Actions在跑CI，方案B几乎是无脑最优解，复用现有的基础设施，不用维护额外服务器。如果项目不在GitHub上，或者你对灰飞烟灭的失败日志极度敏感，方案C适合你。方案A适合那种更新频率低、主要以发版为主的项目，人力投入最少。

我自己的现状是方案B为主，方案A作为手动兜底。每次发版的时候，除了Actions自动推，我会顺手去Gitee后台看一眼同步状态，双保险。

4. 同步过程中的高频故障与排查记录

4.1 令牌过期导致的认证失败

这是出现频率最高的报错。表现形式是Actions日志里出现remote: Authentication failed或者fatal: Authentication failed for 'https://gitee.com/...'。

排查思路分两步：先检查secrets里的令牌是否和Gitee当前有效令牌一致；再检查令牌权限是否包含projects写入。很多时候问题并不是过期，而是重新生成令牌时忘了更新secrets。最快验证方式是在本地终端手动执行一次同样的push命令，如果本地成功而Actions失败，基本可以锁定是secrets配置问题。

提示：给Gitee令牌设置较长有效期时，建议在日历上设一个提醒。到期前主动更新，比等到失败日志堆了一周再去翻要省心得多。

4.2 强推带来的协作者分叉

强推虽然保证了镜像仓库和主仓库完全一致，但副作用很明显：任何在Gitee上直接产生的提交都会被覆盖。我遇到过一位用户，直接在Gitee镜像仓库上提了个bug修复commit，还在issue区留言“已经修好了，麻烦合并”。结果下一次同步强推一跑，他的提交直接被抹掉，人家私信来问是不是被开除了。

这个问题的处置方式不是改用非强推，因为非强推在历史分叉的情况下会直接失败，更麻烦。正确做法是在README顶部明显位置标注“镜像只读，提交请前往GitHub”，并且在Gitee仓库的“通知”或“描述”区域也写上一句。如果经常被覆盖，可以考虑不给Gitee仓库开放直接push权限给普通用户，只保留维护者权限。

4.3 仓库状态异常导致同步被平台拒绝

这类问题最隐蔽，因为报错信息可能看起来像是认证失败，但实际上是仓库状态不允许更新。我在前文提到的那个README域名案例就是典型。

排查方式是登录Gitee后台，进入仓库管理页面，看仓库状态有没有异常标识，比如“内容待审核”“已停止公开访问”之类的提示。如果发现异常，先按照平台提示修正违规内容，然后走人工申诉或重新提交审核。

在状态恢复之前，同步任务会持续失败。这时候建议在工作流里加一个失败通知。方法是修改workflow，在push step后面加一个if条件判断，失败时通过API发一条通知到即时通讯工具。没有通知机制的，至少让失败邮件发到提交邮箱。

4.4 双端README与文档差异带来的体验割裂

这个问题的根源是：很多项目的README里会放GitHub专属的徽章图标、star历史图、issue状态标签，这些组件在Gitee上可能加载不出来，甚至显示成破损图片。另外，README里如果写了“欢迎star”链接到GitHub，访问Gitee的用户点了就会跳到外网，体验很割裂。

我的处理方式是在仓库根目录放两份说明文件，README.md作为通用介绍，README.gitee.md作为Gitee定制版，内容里去掉GitHub专属徽章，把star按钮和issue入口替换成Gitee站内链接。然后在Gitee仓库的后台设置里，手动指定默认展示README.gitee.md。

这个方案看起来很笨，但对国内用户来说，阅读体验提升非常明显。维护成本也不算高，通用改动了顺手同步一下两份文档即可。

5. 要不要让Gitee上的代码“解冻”：我的选择思路

5.1 动手之前先问自己三个问题

代码冻结在Gitee上，本身不是问题。真正的问题是：你还需要不需要这个镜像仓库的用户和流量。在决定要不要修复同步链路之前，先回答下面三个问题。

第一个问题，你的目标用户主要在哪里。如果项目定位是服务国内开发者，比如中文文档的库、国内开发环境的工具链，Gitee的入口价值就很高。如果项目面向全球，受众大多数在GitHub上活跃，Gitee镜像只是锦上添花，解冻优先级自然下降。

第二个问题，项目内容和平台内容规则的适配成本。如果你的项目涉及的领域比较敏感，比如爬虫、代理、网络探测类的工具，在Gitee上被标记的风险高，申诉周期又长，强行维护同步等于给自己找罪受。

第三个问题，你愿意为多端维护投入多少时间。这里的维护不只是同步代码，还包括处理Gitee上的issue、PR、私信。很多人把代码同步过去之后，却完全不回应Gitee上的反馈，这种半失踪状态其实对项目声誉伤害更大。

5.2 我的多端发布决策框架

基于上面三个问题，我给自己梳理了一个决策框架，你可以对照参考。

按照这个框架，我给自己名下几个项目做了分类。窄众的工具库，因为用户群确实有一部分在国内，保留了Gitee同步，但只要求发版时同步，不再追求实时。那几个内容边界模糊的探索性项目，直接放弃Gitee同步，只在GitHub上留底。这样分配下来，维护压力小了很多，内耗也少了。

我个人这两年的一个体会是，Gitee同步这件事，自动化只是手段，不应该是全部。代码冻结在2023年不可怕，可怕的是你根本不知道它已经冻结了。如果决定继续做多平台分发，就把同步、监控、失败通知这三件事一次性搭好，然后用“发版时检查一眼”这种低功耗方式长期维持。如果决定不做，那就爽快地删掉Gitee仓库，或者明确标注“本项目只维护GitHub主仓库”，别让访问者对着两年前的代码猜来猜去。最终要不要“解冻”，取决于你还想不想服务那群访问Gitee的人，想清楚了，方案自然而然就有了。