# 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 卷挂载）。