87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# GitLab Migration Tool
|
||
|
||
这是一个用于在两个 GitLab 实例之间迁移数据的自动化工具。它支持从旧版本 GitLab（如 v12.x）迁移到新版本（如 v18.x），涵盖用户、群组、项目、成员权限及 CI/CD 变量。
|
||
|
||
## 🚀 功能特性
|
||
|
||
- **全量迁移**：支持用户、群组、项目（含代码库）、成员关系、CI/CD 变量的迁移。
|
||
- **Web 可视化界面**：提供直观的 Web 界面进行配置、连接测试和实时日志监控。
|
||
- **高性能**：
|
||
- 项目迁移采用多进程并发执行。
|
||
- 支持 Git Mirror 镜像克隆与推送，保留完整提交历史、分支和标签。
|
||
- **幂等性设计**：支持断点续传。已迁移的对象（通过 ID 映射文件记录）会自动跳过，仅处理失败或新增的数据。
|
||
- **安全性**：对源 GitLab 环境强制只读，确保原始数据安全。
|
||
- **自动修正**：自动处理不合规的群组/项目路径（Path）和名称（Name），以适配新版 GitLab 的严格验证规则。
|
||
|
||
## 🛠️ 快速开始 (Docker 部署)
|
||
|
||
推荐使用 Docker Compose 快速启动服务。
|
||
|
||
### 1. 启动服务
|
||
|
||
```bash
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
### 2. 访问 Web 界面
|
||
|
||
打开浏览器访问：[http://localhost:5555](http://localhost:5555)
|
||
|
||
### 3. 开始迁移
|
||
|
||
1. 在界面中输入 **源 GitLab** 和 **目标 GitLab** 的 URL 及 Access Token。
|
||
2. 点击 **"检查连接"** 确保双方网络和 Token 有效。
|
||
3. 选择迁移模式（默认 "全部迁移"），点击 **"开始迁移"**。
|
||
4. 在下方日志窗口实时查看迁移进度。
|
||
|
||
---
|
||
|
||
## 💻 命令行使用 (高级)
|
||
|
||
如果你更喜欢在终端操作，可以直接运行 Shell 脚本。
|
||
|
||
### 前置要求
|
||
|
||
- Linux/macOS 环境
|
||
- 已安装工具：`curl`, `jq`, `git`
|
||
|
||
### 运行脚本
|
||
|
||
```bash
|
||
# 设置环境变量 (可选，也可以直接修改脚本头部默认值)
|
||
export OLD_GITLAB_URL="http://old-gitlab.example.com"
|
||
export OLD_TOKEN="your-old-token"
|
||
export NEW_GITLAB_URL="http://new-gitlab.example.com"
|
||
export NEW_TOKEN="your-new-token"
|
||
|
||
# 运行迁移
|
||
# 模式可选: all, users, groups, projects, members, variables
|
||
./gitlab_migration.sh all
|
||
```
|
||
|
||
## ⚙️ 配置项说明
|
||
|
||
| 环境变量 | 说明 | 默认值 |
|
||
| :--- | :--- | :--- |
|
||
| `OLD_GITLAB_URL` | 源 GitLab 地址 | (需配置) |
|
||
| `OLD_TOKEN` | 源 GitLab 管理员 Token (Read API/Repo) | (需配置) |
|
||
| `NEW_GITLAB_URL` | 目标 GitLab 地址 | (需配置) |
|
||
| `NEW_TOKEN` | 目标 GitLab 管理员 Token (Full API) | (需配置) |
|
||
| `DEFAULT_PASSWORD` | 新建用户的默认密码 | `Password123!@#` |
|
||
| `MAX_JOBS` | 项目迁移并发进程数 | `5` |
|
||
| `SKIP_EXISTING_REPO` | 是否跳过已完成 Git 同步的项目 | `true` |
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **管理员权限**：建议使用 Admin 账号生成的 Access Token，以确保能获取所有用户、群组和项目信息。
|
||
2. **用户密码**：由于 GitLab 安全机制，无法迁移用户原始密码。所有新迁移用户的初始密码将被设置为 `DEFAULT_PASSWORD` 配置的值（默认为 `Password123!@#`），并设置为“首次登录需修改密码”。
|
||
3. **数据映射**：迁移过程中会在 `migration_data/state` 目录下生成 ID 映射文件 (`.map`)。**请勿删除这些文件**，它们用于记录新旧 ID 的对应关系，是断点续传和成员权限恢复的基础。
|
||
4. **Git LFS**：脚本使用 `git clone --mirror`，理论上支持 LFS 对象，但取决于网络环境和 LFS 存储配置。
|
||
|
||
## 📂 目录结构
|
||
|
||
- `app.py`: Flask Web 应用后端。
|
||
- `gitlab_migration.sh`: 核心迁移逻辑脚本。
|
||
- `templates/` & `static/`: 前端界面资源。
|
||
- `migration_data/`: 存放迁移状态文件和临时数据（Docker 卷挂载）。
|