从 Gogs 平滑迁移到 Gitea：完整教程

前言

Gogs 是一款轻量级的自托管 Git 服务，但项目已经很久没有更新了（最后版本 0.13.0 停留在 2023 年），存在不少已知 Bug，比如：

• HTTP 方式 push 大仓库时返回 HTML 错误页
• SSH 推送到组织仓库报 "Repository owner does not exist"
• API 接口不完善，缺少 Fork、Deploy Key 等功能

Gitea 是 Gogs 的社区 Fork，完全兼容 Gogs 数据，持续活跃维护，推荐所有 Gogs 用户迁移。本文记录从 Gogs 平滑迁移到 Gitea 的完整过程。

环境信息

• 操作系统：OpenCloudOS / CentOS
• Gogs 部署路径：/app/gogs/
• 数据目录：/data/git/
• 配置文件：/app/gogs/custom/conf/app.ini

注意：如果 Gogs 使用 Docker 部署，SSH 端口通常映射为 10022（而非默认的 22），请在迁移前确认实际端口：

# 查看 Docker 端口映射
docker ps | grep gogs

# 测试 SSH 端口连通性
ssh -T -p 10022 git@git.cnbugs.com

第一步：备份数据

这一步非常重要！请务必完整备份后再操作。

# 备份 Gogs 程序和配置
cp -r /app/gogs /app/gogs.bak

# 备份 Git 数据仓库
cp -r /data/git /data/git.bak

# 备份数据库（根据你使用的数据库类型选择）

# SQLite 方式
cp /data/gogs.db /data/gogs.db.bak

# MySQL 方式
mysqldump -u root -p gogs > /data/gogs.sql.bak

第二步：下载 Gitea

前往 Gitea 下载页 获取最新版本，或直接执行：

# 下载最新版 Gitea（以 1.23.5 为例，请替换为最新版本号）
cd /tmp
wget -O gitea https://dl.gitea.io/gitea/1.23.5/gitea-1.23.5-linux-amd64
chmod +x gitea

# 验证下载
./gitea --version

第三步：停止 Gogs 服务

# 如果使用 systemd
systemctl stop gogs

# 如果使用 Docker
docker stop gogs

# 如果直接运行，找到进程并终止
ps aux | grep gogs
kill <PID>

第四步：放置 Gitea 并迁移配置

Gitea 可以直接读取 Gogs 的配置文件和数据库，无需额外转换。

# 将 Gitea 放到 Gogs 目录下
cp /tmp/gitea /app/gogs/gitea

# 查看现有 Gogs 配置（确认数据库类型和路径）
cat /app/gogs/custom/conf/app.ini

配置文件示例（Gogs 和 Gitea 格式兼容）：

[database]
TYPE  = sqlite3
PATH  = /data/gogs.db

[repository]
ROOT = /data/git/gogs-repositories

[server]
DOMAIN       = git.cnbugs.com
ROOT_URL     = https://git.cnbugs.com/
HTTP_PORT    = 3000
SSH_PORT     = 10022

第五步：启动 Gitea

首次启动使用 Gogs 的配置文件，Gitea 会自动检测并兼容：

# 使用 Gogs 的配置文件启动 Gitea
/app/gogs/gitea web -c /app/gogs/custom/conf/app.ini

启动后访问 http://你的IP:3000，如果能看到 Gitea 页面并且仓库都在，说明迁移成功！

第六步：创建 systemd 服务

确认 Gitea 正常运行后，创建系统服务实现开机自启：

cat > /etc/systemd/system/gitea.service << 'EOF'
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[Service]
Type=simple
User=git
WorkingDirectory=/app/gogs
ExecStart=/app/gogs/gitea web -c /app/gogs/custom/conf/app.ini
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF

# 重载并启动
systemctl daemon-reload
systemctl enable gitea
systemctl start gitea

# 检查状态
systemctl status gitea

注意：如果之前 Gogs 是以 root 用户运行的，将 User=git 改为 User=root，或者确保 git 用户有权限访问相关目录。

第七步：Nginx 反向代理配置

如果你使用 Nginx 反向代理，无需修改，Gitea 监听相同的端口，Nginx 配置保持不变：

server {
    listen 443 ssl;
    server_name git.cnbugs.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

第八步：SSH 密钥处理

Gitea 启动后会自动管理 authorized_keys 文件。建议登录管理员账号后：

• 进入 管理面板 → 操作 → 重新生成 authorized_keys
• 让所有用户重新确认 SSH 密钥是否正常

# 测试 SSH 连接
ssh -T git@git.cnbugs.com

# 正常返回：
# Hi username! You've successfully authenticated, but Gitea does not provide shell access.

第九步：验证迁移结果

逐项检查以下功能是否正常：

• ✅ 网页能正常访问，仓库列表完整
• ✅ 用户账号、组织、团队权限保留
• ✅ HTTP 方式 clone / push 正常
• ✅ SSH 方式 clone / push 正常
• ✅ 组织仓库 SSH push 正常（Gogs 的老 Bug 已修复）
• ✅ Webhook、Issue、Wiki 数据完整

回滚方案

如果迁移后发现问题，可以快速回滚到 Gogs：

# 停止 Gitea
systemctl stop gitea

# 恢复备份（如果数据库没有被 Gitea 修改）
systemctl start gogs

# 如果数据库已被 Gitea 升级，需要恢复数据库备份
cp /data/gogs.db.bak /data/gogs.db
# 或
mysql -u root -p gogs < /data/gogs.sql.bak

Gitea vs Gogs 新特性

迁移到 Gitea 后，你将获得以下额外功能：

• 🎨 更现代的 Web UI 界面
• 🔄 支持 Pull Request 和代码审查
• 📦 内置包管理器（Packages）：支持 npm、Docker、Maven 等
• 🔐 支持 OAuth2、OpenID Connect 登录
• 🤖 更完善的 API 接口
• 📱 更好的移动端适配
• 🐛 修复了 Gogs 所有已知的 SSH 和 HTTP 问题

常见问题

Q: 数据库会被修改吗？

Gitea 首次启动时会自动检测 Gogs 数据库并进行兼容性升级（新增部分字段），建议先备份数据库再启动。

Q: Docker 部署的 Gogs 如何迁移？

原理相同。将 Gitea 容器挂载相同的 volume（配置、数据、数据库），修改 docker-compose.yml 中的镜像为 gitea/gitea:latest 即可。

Q: 迁移后 Git 仓库的 URL 会变吗？

不会。HTTP 和 SSH 的 clone/push URL 完全不变，团队成员无需修改任何配置。

总结

Gogs 到 Gitea 的迁移过程非常简单，核心就是 备份数据 → 下载 Gitea → 用 Gogs 配置启动 三步。Gitea 作为 Gogs 的社区继承者，修复了大量 Bug 并持续更新，强烈建议所有 Gogs 用户迁移。

cnbugsai

打赏 海报 链接