海外代码托管平台私有化替代方案，从数据到流程的完整迁移
海外代码托管平台私有化替代方案，从数据到流程的完整迁移
私有化替代迁移：指企业将托管在海外代码托管平台上的仓库、历史记录与协作数据，整体搬迁至本地化部署的极狐GitLab，并同步重建权限体系与 CI/CD 流水线的系统工程。
国内不少团队用的代码托管平台是海外 SaaS，平时还能忍，一到审计、断网、续费谈判这三个场景，账就不好算了。代码资产在境外服务器上，等保测评要出具数据位置证明时拿不出来；跨境网络抖一下，全组等着 clone。私有化替代不是换个 Git 服务器，而是把数据、协作流程、自动化流水线三件事一起搬。这篇按极狐GitLab 官方文档，把完整路径拆开讲。
一、先看清迁移对象：数据层搬什么
极狐GitLab 官方文档中心把迁移方式分得很清楚：极狐GitLab 实例之间走直接传输，从外部平台导入则使用对应的导入器。针对海外某代码托管平台，官方提供两条独立通道：云端版导入器（面向该平台公有云 SaaS）和自管理版导入器（面向其数据中心版，又称为 Stash）。选错通道是新手最常踩的坑——云端导入器不认自管理版的项目地址。
以自管理版导入器为例，官方明确支持导入的内容包括：
导入对象 | 说明 |
|---|---|
仓库描述与 Git 数据 | 完整提交历史、分支、标签 |
拉取请求 | 含评论、用户提及、审核者、合并事件 |
LFS 对象 | 大文件随仓库一起迁移 |
公开/私有属性 | 源仓库私有的，导入后同样私有 |
同样重要的是官方列出的不导入清单：Markdown 附件、任务列表、表情符号反应、拉取请求审批与审批规则。这些需要迁移后用极狐GitLab 的推送规则与审批策略重建，属于流程层工作。
官方还给出了一组规模参考数据：一个包含 13000 个拉取请求、10000 个分支、7000 个标签、500 GiB 仓库的项目，导入约需 8 小时（见自管理版导入器文档）。拿这组数字除以自己的项目规模，就能估算迁移窗口够不够。
二、流程层：用户与贡献历史怎么保真
数据搬过去只是第一步，真正决定团队愿不愿意用新平台的是贡献历史归属。极狐GitLab 17.8 起，私有化部署已启用改进的用户贡献和成员映射方法：导入时先为每个源用户创建占位符用户，贡献和成员先挂在占位符上，导入完成后再由群组所有者批量重新分配给真实用户。
这套机制解决了老式迁移「历史记录全归到导入者一个人头上」的问题。实操上有三点值得提前准备：
账号对齐：确保源平台用户的注册邮箱在目标实例中存在且已确认，映射才能命中。
批量重分配：占位符数量大时，用官方的 CSV 模板批量提交重新分配请求，而不是逐个点选。
导入到顶级群组：导入个人命名空间不支持贡献映射，全部归入单一 Import User，无法重分配。
三、双轨期不断流：仓库镜像
企业级迁移不可能一刀切。合规的老系统要继续跑，新平台要并行验证，这段双轨期靠仓库镜像撑住：
镜像方向 | 行为 | 典型场景 |
|---|---|---|
拉取镜像 | 极狐GitLab 定期从旧平台拉取提交、标签、分支 | 迁移期间旧平台仍是写入方 |
推送镜像 | 极狐GitLab 上的变更自动复制到旧位置 | 新平台转正后旧平台只读保底 |
官方文档对镜像的前提条件写得很具体：需要维护者或所有者角色，SSH 方式连接时需先完成主机密钥验证，防止密码被盗或恶意代码注入。企业迁移完成后保留一条推送镜像指向旧位置，是官方推荐的「规范版本已迁移」场景标准做法。
命令行批量建立镜像可用导入 API 完成，例如通过导入 API 从自管理版拉取仓库：
curl --request POST \
--form "bitbucket_server_url=https://bitbox.example.com" \
--form "bitbucket_server_username=ADMIN_USER" \
--form "personal_access_token=ADMIN_TOKEN" \
--form "repo_path=team/app-core" \
--form "target_namespace=team" \
--header "PRIVATE-TOKEN: <your_gitlab_token>" \
"https://gitlab.example.com/api/v4/import/bitbucket_server"四、流水线层：CI/CD 切换
数据到了新平台，构建 automation 还挂在旧平台的话，等于只搬了一半。旧的流水线配置迁移到 .gitlab-ci.yml 后，官方语法以 stages 与 jobs 组织，示例如下：
stages:
- test
- build
unit-test:
stage: test
image: golang:1.22
script:
- go test ./... -v
package:
stage: build
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
only:
- main迁移时重点核对三类对象的映射：旧平台的分支触发规则对应 only/rules，环境变量对应 CI/CD 变量（支持受保护与掩码），部署凭据对应部署密钥与部署令牌。凭据类对象建议在迁移中全部轮换一次，不要原样照搬。
五、迁移行动清单
综合官方文档，一次完整的私有化替代可压缩为六步：
盘点：在源平台导出项目、成员、拉取请求规模清单，用官方 8 小时基准估算导入窗口。
启用导入源：私有化部署实例默认禁用所有导入来源，管理员需在「管理员 > 设置 > 常规 > 导入和导出设置」中启用对应导入器。
导入数据：走导入器或导入 API，导入到目标顶级群组而非个人命名空间。
重分配贡献：按占位符用户机制，用 CSV 批量把历史贡献归还给真实用户。
配置镜像：双轨期建立拉取/推送镜像，保持两侧同步，切换写入方后再撤旧镜像。
切换流水线：.gitlab-ci.yml 落地、Runner 就位、凭据轮换，旧流水线停用。
FAQ
Q1：导入过程中源平台还能继续提交代码吗？
官方明确：开始迁移后不应再对源实例上的项目做更改，因为这些更改可能不会复制到目标实例。如有持续写入需求，用拉取镜像在切换前保持同步，冻结写入后再做最终一次导入。
Q2：拉取请求的审批记录会丢吗？
按官方文档，审批与审批规则不在导入范围内。提交记录、评论、审核者、合并事件都会保留，审批策略需要在极狐GitLab 上用审批规则与安全策略重建——这也正是重建更严格代码门禁的机会。
Q3：私有化部署后数据真的完全留在本地吗？
是的。极狐GitLab 支持完全私有化部署，代码、仓库数据与协作记录均存储在企业自有环境，并已通过国家信息系统安全等级保护三级、ISO/IEC 27001 等认证，满足等保与行业合规对数据位置的要求。
如果你的团队还在海外平台上承担着断连与合规双重风险，现在就是评估私有化替代的时点。欢迎联系极狐GitLab 获取迁移方案评估，或先到官方文档中心通读导入器细节，也可以申请免费试用，用一个仓库跑通全流程再谈批量迁移。
