4. 迁移前期评估与盘点

迁移项目最容易失败的地方，不是目标端装不起来，而是源端“没摸清”。在动手搭建新 GitLab 之前，必须先把现有环境当成一个待迁移的资产系统来盘点：它跑在什么版本、有哪些组件、数据量多大、谁在用、哪些仓库还活着、哪些集成一旦断掉就会影响交付。本节给出一套可落地的评估方法，并给出可直接填写的盘点表结构。

一、环境信息采集：先确定“迁移边界”

环境采集的目标是回答三个问题：源端是什么形态、依赖了哪些外部组件、迁移窗口内允许停机多久。建议从 GitLab 自身、宿主与存储、外部依赖三层采集。

GitLab 自身信息可通过 Rails 控制台或 API 获取，最直接的是版本与组件版本：

# 查看 GitLab 版本与各组件版本
sudo gitlab-rake gitlab:env:info

# 查看数据库、Redis、Gitaly 等组件版本
sudo gitlab-ctl status
gitlab-rails runner "puts Gitlab::VERSION"

# 通过 API 获取实例基础信息（需管理员 Token）
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/version"

宿主与存储层需要记录 CPU/内存、磁盘类型与剩余空间、Git 数据目录、对象存储（若启用）、备份策略与最近一次成功备份时间。外部依赖层要记录 LDAP/AD、OAuth/SSO、SMTP、外部 PostgreSQL、外部 Redis、对象存储、容器镜像仓库、制品库等。这里的关键判断依据是：凡是源端依赖、目标端未同步准备的外部系统，都会成为迁移后的“断点”。

二、仓库规模与活跃度分析：决定迁移批次与优先级

仓库盘点不能只看“有多少个”，而要看“多大、多活跃、多关键”。建议采集每个项目的：仓库大小（含 LFS）、最近一次推送时间、近 90 天提交数、分支与标签数量、是否归档、是否含大文件或子模块。

可通过 API 分页拉取项目列表并导出为 CSV，便于后续排序：

# 导出项目基础信息（示例：每页 100，按最后活动时间排序）
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/projects?per_page=100&order_by=last_activity_at&sort=desc" \
  > projects_page1.json

# 统计单个项目仓库大小（含 LFS）
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/projects/<id>?statistics=true"

拿到数据后，按“活跃度 × 规模”划分四类，作为迁移批次依据：

活跃度判断建议以“最近推送时间 + 近 90 天提交数 + 近 30 天访问量”三者结合，避免仅凭最后活动时间误判。例如某仓库最后活动是 80 天前，但近 30 天有大量克隆，说明仍被依赖，不能简单归为废弃。

三、用户与权限矩阵：迁移后“谁能看什么”必须一致

用户盘点的核心是身份来源与权限映射。先确认用户来自本地账号、LDAP/AD 还是 SAML/OIDC，再统计用户总数、活跃用户数、外部用户数、管理员数量。权限矩阵要覆盖群组、子群组、项目三层，记录每个用户/群组在每层的角色（Guest、Reporter、Developer、Maintainer、Owner）。

可通过 API 导出群组成员与项目成员：

# 导出某群组成员及权限
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/groups/<group_id>/members/all?per_page=100"

# 导出某项目成员及权限
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/projects/<project_id>/members/all?per_page=100"

迁移前必须重点核对三类风险：同名不同人（LDAP 与本地账号重名）、外部用户误入内部群组、Owner 权限过度集中。建议在目标端先建立与源端一致的群组层级，再按“群组继承优先、项目单独授权补充”的方式还原权限，减少逐项目手工配置。

四、集成与 CI/CD 资产清单：最容易被忽略的“隐形依赖”

CI/CD 资产包括：Runner（类型、标签、并发、执行器）、CI 变量（含受保护/掩码变量）、Schedules、Webhook、Deploy Keys、Deploy Tokens、Container Registry、Package Registry、Pages、外部集成（Jira、Slack、Jenkins、SonarQube 等）。这些资产一旦遗漏，迁移后表现为“仓库在、流水线红”。

建议按“资产类型—数量—是否含密钥—迁移方式—验证方式”建立清单。例如 Runner 需要记录：

# 查看 Runner 列表与标签
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/runners/all?per_page=100"

# 查看项目级 CI 变量（注意：值不会明文返回）
curl --header "PRIVATE-TOKEN: <admin_token>" \
  "https://gitlab.example.com/api/v4/projects/<project_id>/variables"

CI 变量中的密钥无法通过 API 取回明文，必须在源端仍有权限时导出或重新生成。Webhook 与 Deploy Token 同理，建议在迁移前统一登记并规划“重新签发”流程，而不是尝试复制旧密钥。

五、盘点成果如何转化为迁移计划

四类盘点完成后，应形成一份可执行的迁移计划，至少包含：迁移批次与时间窗、每批仓库清单、用户与权限映射表、CI/CD 资产迁移方式、密钥重签清单、回滚点与验证清单。判断迁移是否“评估到位”的标准不是文档厚度，而是：任意一个仓库、任意一个用户、任意一条流水线，都能在清单中找到它的迁移归属和验证方式。

最后提醒一个常见误区：把“仓库数量”当作迁移工作量。实际工作量往往由大仓库、LFS、子模块、受保护分支规则、CI 变量和 Runner 标签共同决定。评估阶段多花一天把清单做准，迁移窗口内就能少一次回滚。