跨平台Gitea数据迁移实战指南
1. 为什么需要跨平台Gitea数据迁移
最近在帮朋友处理一个Gitea服务器迁移的项目时，遇到了一个棘手的问题：他们原来的Gitea服务运行在Windows服务器上，现在需要迁移到Ubuntu系统。这让我意识到，很多团队在基础设施升级或架构调整时，都会面临类似的跨平台数据迁移需求。
Gitea作为轻量级的Git服务，确实给我们带来了很多便利。但当你需要把它从Windows搬到Linux，或者反过来操作时，事情就没那么简单了。我遇到过不少案例：有的团队迁移后仓库历史记录丢失了，有的用户权限全乱了，更惨的是数据库连接出问题导致整个服务起不来。
跨平台迁移最大的挑战在于系统环境的差异。Windows和Linux在文件路径、权限管理、服务运行方式上都有很大不同。比如Windows用反斜杠\作为路径分隔符，而Linux用正斜杠/；Windows对文件名大小写不敏感，Linux则严格区分。这些细节不注意，迁移后各种奇怪的问题就来了。
2. 迁移前的准备工作
2.1 制定详细的迁移计划
在开始实际迁移前，我强烈建议你先花点时间做个完整的迁移计划。根据我的经验，至少要包括以下内容：
- 停机时间窗口：评估业务影响，选择低峰期进行。Gitea迁移期间仓库是不可用的，要提前通知团队成员。
- 回滚方案：万一迁移失败，要能快速回退到原系统。我通常会保留原系统至少一周不删除。
- 验证清单：列出迁移后需要检查的所有项目，包括仓库完整性、用户权限、Issue和PR状态等。
2.2 环境检查清单
执行迁移前，先确认两边系统的环境是否匹配：
# 在Ubuntu上检查环境 lsb_release -a # 查看系统版本 mysql --version # 检查MySQL版本 git --version # 检查Git版本Windows上可以通过命令提示符执行类似检查：
systeminfo | findstr /B /C:"OS 名称" /C:"OS 版本" mysql --version git --version版本差异可能导致兼容性问题。我曾经遇到Windows上的MySQL 5.7迁移到Ubuntu的MySQL 8.0时，因为默认认证插件不同导致连接失败的情况。
3. Windows到Ubuntu的迁移实战
3.1 完整备份Windows端数据
在Windows上，我们需要备份三个关键部分：仓库文件、数据库和配置文件。
仓库文件备份： Gitea的仓库默认存放在C:\gitea\data\repositories。我习惯用7-Zip进行压缩备份，因为它支持保留NTFS权限信息：
# 使用PowerShell创建带时间戳的备份 $date = Get-Date -Format "yyyyMMdd" 7z a -tzip "C:\backups\gitea-repo-$date.zip" "C:\gitea\data\repositories\*"数据库备份： 对于MySQL数据库，除了基本的mysqldump，我还会加几个重要参数：
mysqldump -u root -p --single-transaction --routines --triggers --events gitea > C:\backups\gitea-db-$date.sql--single-transaction参数特别重要，它能确保备份时数据的一致性，不会锁表影响正在运行的服务。
配置文件备份： 不要小看app.ini这个配置文件，它包含了SMTP设置、OAuth配置等关键信息。我建议同时备份整个custom目录：
Copy-Item -Path "C:\gitea\custom" -Destination "C:\backups\gitea-custom-$date" -Recurse3.2 在Ubuntu上恢复数据
安装Gitea： 在Ubuntu上，我更喜欢用Docker方式部署Gitea，管理起来更方便：
# 创建数据目录 sudo mkdir -p /var/lib/gitea/data sudo chown -R 1000:1000 /var/lib/gitea # 使用Docker运行 docker run -d --name=gitea -p 3000:3000 -p 2222:22 \ -v /var/lib/gitea/data:/data \ -v /etc/timezone:/etc/timezone:ro \ -v /etc/localtime:/etc/localtime:ro \ gitea/gitea:latest恢复仓库文件： 把Windows备份的ZIP文件传到Ubuntu后：
# 安装unzip工具 sudo apt install unzip # 解压到临时目录检查 unzip gitea-repo-backup.zip -d /tmp/gitea-repo sudo chown -R git:git /tmp/gitea-repo/* sudo mv /tmp/gitea-repo/* /var/lib/gitea/data/gitea-repositories/这里有个坑要注意：Linux下文件权限比Windows严格得多。一定要确保所有仓库文件的owner是git用户（或者你运行Gitea的用户）。
数据库恢复： 先在Ubuntu上创建空数据库：
mysql -u root -p -e "CREATE DATABASE gitea CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';"然后导入数据：
mysql -u root -p gitea < gitea-db-backup.sql如果遇到"Unknown collation"错误，可能是字符集问题，可以尝试在导入前编辑SQL文件，把utf8mb4_0900_ai_ci替换为utf8mb4_unicode_ci。
4. Ubuntu到Windows的反向迁移
4.1 备份Ubuntu端数据
仓库备份： 在Linux上，我更喜欢用tar命令，它能更好地保留文件权限和符号链接：
sudo tar -czvf /backup/gitea-repo-$(date +%Y%m%d).tar.gz \ --exclude='*.lock' \ /var/lib/gitea/data/gitea-repositories--exclude='*.lock'参数可以避免备份时包含仓库锁文件，这些文件在迁移后不需要。
数据库备份： 对于大型数据库，可以加上压缩：
mysqldump -u root -p --single-transaction gitea | gzip > /backup/gitea-db-$(date +%Y%m%d).sql.gz4.2 在Windows上恢复
安装Gitea： Windows上推荐直接下载二进制包：
- 从Gitea官网下载最新版的windows-4.0-amd64.exe
- 重命名为gitea.exe，放到C:\gitea
- 运行一次生成默认配置
恢复仓库： 使用7-Zip解压备份的tar.gz文件：
# 安装7-Zip CLI工具 7z x gitea-repo-backup.tar.gz -oC:\temp 7z x C:\temp\gitea-repo-backup.tar -oC:\gitea\data\repositories数据库恢复： 如果备份是压缩的，先解压：
gzip -d gitea-db-backup.sql.gz然后在Windows命令提示符下导入：
mysql -u root -p gitea < C:\backup\gitea-db-backup.sql5. 迁移后的验证与排错
5.1 必做的验证步骤
迁移完成后，不要急着宣布成功，先做这些检查：
仓库完整性检查： 随机挑选几个仓库，执行git fsck检查：
cd /var/lib/gitea/data/gitea-repositories/user/repo.git git fsck --full用户权限验证： 用不同权限的测试账号登录，检查：
- 能否访问应该能访问的仓库
- 不能访问私有仓库
- 管理员功能是否正常
Webhook测试： 如果配置了Webhook，触发几次push操作，检查回调是否正常。
5.2 常见问题解决
问题1：页面显示500错误
- 检查
gitea.log日志文件 - 常见原因：数据库连接失败、文件权限错误
问题2：仓库可以看见但无法push
- 检查仓库目录的权限
- 检查SSH配置（如果是用SSH协议）
问题3：用户头像不显示
- 检查
custom/avatars目录是否迁移 - 检查文件权限
6. 高级迁移技巧
6.1 使用rsync进行增量迁移
对于大型仓库，可以先用rsync做一次预迁移，减少停机时间：
# 在Ubuntu上执行（从Windows拉取） rsync -azP --delete windows_user@windows_ip:/c/gitea/data/repositories/ \ /var/lib/gitea/data/gitea-repositories/6.2 数据库迁移的替代方案
除了mysqldump，还可以考虑：
- 使用MySQL主从复制：配置Windows为主，Ubuntu为从，然后切换。
- 导出为SQLite再转换：如果目标端想改用SQLite。
6.3 配置文件的跨平台调整
Windows和Linux的app.ini需要调整的地方：
[server] DOMAIN = localhost SSH_DOMAIN = linux-server # 从Windows改为Linux服务器地址 ROOT_URL = http://linux-server:3000/特别是路径相关的配置：
[repository] ROOT = /var/lib/gitea/data/gitea-repositories # Linux路径7. 自动化迁移脚本
为了简化流程，我整理了一个自动化迁移脚本的框架：
#!/bin/bash # 备份脚本示例（Ubuntu端） BACKUP_DIR="/backup/$(date +%Y%m%d)" mkdir -p $BACKUP_DIR # 备份仓库 tar -czvf $BACKUP_DIR/repositories.tar.gz \ --exclude='*.lock' \ /var/lib/gitea/data/gitea-repositories # 备份数据库 mysqldump -u root -p$DB_PASSWORD --single-transaction gitea | gzip > $BACKUP_DIR/gitea-db.sql.gz # 备份配置 cp /etc/gitea/app.ini $BACKUP_DIR/ cp -r /var/lib/gitea/custom $BACKUP_DIR/对应的Windows恢复脚本：
# Windows恢复脚本示例 $backupDate = "20230801" $backupDir = "C:\backup\$backupDate" # 恢复仓库 Expand-Archive -Path "$backupDir\repositories.zip" -DestinationPath "C:\gitea\data\" # 恢复数据库 mysql -u root -p gitea < "$backupDir\gitea-db.sql" # 恢复配置 Copy-Item -Path "$backupDir\app.ini" -Destination "C:\gitea\custom\conf\"