xWork/README.md

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. 启动服务

docker-compose up -d --build

2. 访问 Web 界面

打开浏览器访问：http://localhost:5555

3. 开始迁移

1. 在界面中输入 源 GitLab 和 目标 GitLab 的 URL 及 Access Token。
2. 点击 "检查连接" 确保双方网络和 Token 有效。
3. 选择迁移模式（默认 "全部迁移"），点击 "开始迁移"。
4. 在下方日志窗口实时查看迁移进度。

---

💻 命令行使用 (高级)

如果你更喜欢在终端操作，可以直接运行 Shell 脚本。

前置要求

• Linux/macOS 环境
• 已安装工具：curl, jq, git

运行脚本

# 设置环境变量 (可选，也可以直接修改脚本头部默认值)
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 卷挂载）。