 完全指南】)
前言在 Windows 环境下搭建私有的 Git 代码托管服务Gogs是一个轻量级且易于部署的优秀选择。本文将详细介绍如何在 Windows 10 上安装 Gogs、配置为系统服务、进行数据迁移以及解决常见的权限与推送错误。一、环境准备与资源下载在开始之前请确保已准备好以下资源Gogs 安装包官网下载https://dl.gogs.io/GitHub 仓库https://github.com/gogs/gogs官方安装文档Install from BinaryNSSM (Non-Sucking Service Manager)用于将 Gogs 注册为 Windows 系统服务实现开机自启。下载地址https://nssm.cc/download参考教程若遇疑难可参考知乎、CSDN 或博客园的相关部署文章如“Windows下如何搭建属于自己的git服务器”。二、Gogs 安装与配置1. 解压与目录规划建议规划统一的工具目录例如D:\tools。将下载的gogs_0.13.0_windows_amd64.zip解压至D:\tools\gogs。将 NSSM 解压至D:\tools\nssm-2.24\win64。2. 配置环境变量为了方便命令行调用建议将 NSSM 的路径加入系统环境变量Path中添加路径D:\tools\nssm-2.24\win643. 注册为系统服务为了让 Gogs 在后台稳定运行并随系统启动需将其注册为服务。以管理员身份打开命令提示符CMD或 PowerShell。进入 Gogs 的脚本目录cd D:\tools\gogs\scripts\windows执行安装脚本install-as-service.bat注此脚本通常会自动调用 NSSM 进行服务注册。如果脚本执行失败也可手动使用nssm install gogs命令进行图形化配置。验证服务打开 Windows“服务”管理器查找名为gogs的服务确保其状态为“正在运行”。4. 初始化安装浏览器访问默认地址http://127.0.0.1:3000/install数据库设置初次安装可选择内置数据库SQLite3或连接外部数据库MySQL/PostgreSQL。应用设置基础 URL根据实际访问 IP 修改如http://192.168.1.100:3000/。SSH 端口默认是 22。如果 Windows 已开启 OpenSSH 服务建议修改为其他端口如2222以避免冲突。点击“立即安装”。5. 防火墙配置若需局域网内其他机器访问需在 Windows 防火墙中放行对应端口HTTP 端口默认3000若修改过请以实际为准。SSH 端口默认22或自定义的2222。注意如果修改了配置文件中的端口号必须重启 Gogs 服务才能生效。重启命令管理员权限net stop gogs net start gogs或者在“服务”管理器中右键重启。三、数据迁移方案当需要更换服务器或重装系统时数据迁移是关键步骤。1. 迁移方法对比官方备份命令推荐但需注意版本兼容性.\gogs backup # Windows ./gogs backup # Linux # 排除仓库文件仅备份配置和数据库 .\gogs backup --exclude-repos # 指定配置文件 .\gogs backup --configmy/custom/conf/app.ini直接拷贝法本文采用直接复制整个gogs安装目录包含conf,data,log等以及gogs-repositories仓库目录到新机器覆盖。2. 迁移后的常见问题与修复直接拷贝数据后常因文件所有者或数据库用户ID不匹配导致权限错误如页面显示 500 错误或无法推送代码。现象描述登录新服务器后发现原有仓库的拥有者显示异常或者新建仓库的拥有者是当前登录的管理员账号而非原始数据的归属者。解决方案修正数据库所有权需要通过直接操作 Gogs 的数据库通常是gogs.dbSQLite 文件或 MySQL 数据库来修正owner_id。步骤演示确认用户 ID登录 Gogs 网页查看目标用户的个人主页 URL或直接查询数据库user表。假设目标用户rady的 ID 为1新用户yf的 ID 为2。修正仓库所有者 (repository表)将特定仓库的所有者 ID 修改为正确的用户 ID。-- 示例将名为 demo 的仓库所有者设为 ID 为 1 的用户UPDATErepositorySETowner_id1,lower_namedemo,namedemo,descriptiondemo测试,is_bare0WHERElower_namedemo;修正关注关系 (watch表)确保关注记录的用户 ID 与仓库所有者一致。UPDATEwatchSETuser_id1WHERErepo_id(SELECTidFROMrepositoryWHERElower_namedemo);修正动态记录 (action表)修复时间线和动态反馈中的用户引用。UPDATEactionSETuser_id1,repo_user_nameradyWHERErepo_id(SELECTidFROMrepositoryWHERElower_namedemo);批量修复脚本示例如果有多个仓库需要迁移给新用户例如用户 ID7用户名op-- 修改仓库所有者UPDATErepositorySETowner_id7WHERElower_namebat-samples;-- 修改关注记录UPDATEwatchSETuser_id7WHERErepo_id(SELECTidFROMrepositoryWHERElower_namebat-samples);-- 修改动态记录UPDATEactionSETuser_id7,repo_user_nameopWHERErepo_id(SELECTidFROMrepositoryWHERElower_namebat-samples);添加协作者权限如果需要给用户赋予特定仓库的写入权限需同时在access和collaboration表中插入记录。-- 模式 2 代表写权限 (Write)模式 1 代表读权限 (Read)INSERTINTOaccess(user_id,repo_id,mode)VALUES(2,579,2);INSERTINTOcollaboration(user_id,repo_id,mode)VALUES(2,579,2);四、常见故障排查问题Git 推送失败 (Error 403 / Unexpected Disconnect)报错信息示例Compressing objects: 100% (34759/34759), done. error: RPC failed; HTTP 403 curl 22 The requested URL returned error: 403 send-pack: unexpected disconnect while reading sideband packet Writing objects: 100% (46516/46516), 2.38 GiB | 304.78 MiB/s, done. fatal: the remote end hung up unexpectedly可能原因及解决方法权限不足 (HTTP 403)原因当前使用的 Git 账号没有该仓库的写入权限或者密码/Token 认证失败。解决检查 Gogs 网页端该用户是否有仓库的“写”权限。如果是 HTTPS 推送尝试重新输入密码或使用 Personal Access Token。检查是否开启了双重验证2FA若开启必须使用 Token 而非密码。推送包过大导致超时原因一次性推送的文件过多或单个文件过大导致 Nginx/IIS/Gogs 内部超时限制。解决分批提交不要一次性推送大量历史提交尝试分多次推送。调整配置修改 Gogs 的app.ini配置文件增加上传限制和超时时间。[server] MAX_UPLOAD_SIZE 1024 ; 单位 MB [repository] DISABLE_HTTP_GIT false检查 Web 服务器如果前端使用了 Nginx 反向代理需同步调整client_max_body_size。SSH 密钥问题原因如果使用 SSH 协议推送本地公钥未正确添加到 Gogs 账户设置中。解决在 Gogs 网页端 - 设置 - SSH/GPG 密钥添加本地的id_rsa.pub内容。确保本地 SSH 客户端使用的是正确的私钥可通过ssh -T gityour-server-ip -p 2222测试连接。五、总结在 Windows 上部署 Gogs 是一种低成本构建私有代码库的有效方式。通过 NSSM 将其服务化可以保证稳定性而在进行数据迁移时理解底层的数据库结构特别是user,repository,access表之间的关系对于解决权限错乱问题至关重要。遇到推送错误时优先排查权限配置和网络超时设置。
【Win10 部署私有 Git 服务器 (Gogs) 完全指南】
发布时间：2026/7/14 17:13:08
前言在 Windows 环境下搭建私有的 Git 代码托管服务Gogs是一个轻量级且易于部署的优秀选择。本文将详细介绍如何在 Windows 10 上安装 Gogs、配置为系统服务、进行数据迁移以及解决常见的权限与推送错误。一、环境准备与资源下载在开始之前请确保已准备好以下资源Gogs 安装包官网下载https://dl.gogs.io/GitHub 仓库https://github.com/gogs/gogs官方安装文档Install from BinaryNSSM (Non-Sucking Service Manager)用于将 Gogs 注册为 Windows 系统服务实现开机自启。下载地址https://nssm.cc/download参考教程若遇疑难可参考知乎、CSDN 或博客园的相关部署文章如“Windows下如何搭建属于自己的git服务器”。二、Gogs 安装与配置1. 解压与目录规划建议规划统一的工具目录例如D:\tools。将下载的gogs_0.13.0_windows_amd64.zip解压至D:\tools\gogs。将 NSSM 解压至D:\tools\nssm-2.24\win64。2. 配置环境变量为了方便命令行调用建议将 NSSM 的路径加入系统环境变量Path中添加路径D:\tools\nssm-2.24\win643. 注册为系统服务为了让 Gogs 在后台稳定运行并随系统启动需将其注册为服务。以管理员身份打开命令提示符CMD或 PowerShell。进入 Gogs 的脚本目录cd D:\tools\gogs\scripts\windows执行安装脚本install-as-service.bat注此脚本通常会自动调用 NSSM 进行服务注册。如果脚本执行失败也可手动使用nssm install gogs命令进行图形化配置。验证服务打开 Windows“服务”管理器查找名为gogs的服务确保其状态为“正在运行”。4. 初始化安装浏览器访问默认地址http://127.0.0.1:3000/install数据库设置初次安装可选择内置数据库SQLite3或连接外部数据库MySQL/PostgreSQL。应用设置基础 URL根据实际访问 IP 修改如http://192.168.1.100:3000/。SSH 端口默认是 22。如果 Windows 已开启 OpenSSH 服务建议修改为其他端口如2222以避免冲突。点击“立即安装”。5. 防火墙配置若需局域网内其他机器访问需在 Windows 防火墙中放行对应端口HTTP 端口默认3000若修改过请以实际为准。SSH 端口默认22或自定义的2222。注意如果修改了配置文件中的端口号必须重启 Gogs 服务才能生效。重启命令管理员权限net stop gogs net start gogs或者在“服务”管理器中右键重启。三、数据迁移方案当需要更换服务器或重装系统时数据迁移是关键步骤。1. 迁移方法对比官方备份命令推荐但需注意版本兼容性.\gogs backup # Windows ./gogs backup # Linux # 排除仓库文件仅备份配置和数据库 .\gogs backup --exclude-repos # 指定配置文件 .\gogs backup --configmy/custom/conf/app.ini直接拷贝法本文采用直接复制整个gogs安装目录包含conf,data,log等以及gogs-repositories仓库目录到新机器覆盖。2. 迁移后的常见问题与修复直接拷贝数据后常因文件所有者或数据库用户ID不匹配导致权限错误如页面显示 500 错误或无法推送代码。现象描述登录新服务器后发现原有仓库的拥有者显示异常或者新建仓库的拥有者是当前登录的管理员账号而非原始数据的归属者。解决方案修正数据库所有权需要通过直接操作 Gogs 的数据库通常是gogs.dbSQLite 文件或 MySQL 数据库来修正owner_id。步骤演示确认用户 ID登录 Gogs 网页查看目标用户的个人主页 URL或直接查询数据库user表。假设目标用户rady的 ID 为1新用户yf的 ID 为2。修正仓库所有者 (repository表)将特定仓库的所有者 ID 修改为正确的用户 ID。-- 示例将名为 demo 的仓库所有者设为 ID 为 1 的用户UPDATErepositorySETowner_id1,lower_namedemo,namedemo,descriptiondemo测试,is_bare0WHERElower_namedemo;修正关注关系 (watch表)确保关注记录的用户 ID 与仓库所有者一致。UPDATEwatchSETuser_id1WHERErepo_id(SELECTidFROMrepositoryWHERElower_namedemo);修正动态记录 (action表)修复时间线和动态反馈中的用户引用。UPDATEactionSETuser_id1,repo_user_nameradyWHERErepo_id(SELECTidFROMrepositoryWHERElower_namedemo);批量修复脚本示例如果有多个仓库需要迁移给新用户例如用户 ID7用户名op-- 修改仓库所有者UPDATErepositorySETowner_id7WHERElower_namebat-samples;-- 修改关注记录UPDATEwatchSETuser_id7WHERErepo_id(SELECTidFROMrepositoryWHERElower_namebat-samples);-- 修改动态记录UPDATEactionSETuser_id7,repo_user_nameopWHERErepo_id(SELECTidFROMrepositoryWHERElower_namebat-samples);添加协作者权限如果需要给用户赋予特定仓库的写入权限需同时在access和collaboration表中插入记录。-- 模式 2 代表写权限 (Write)模式 1 代表读权限 (Read)INSERTINTOaccess(user_id,repo_id,mode)VALUES(2,579,2);INSERTINTOcollaboration(user_id,repo_id,mode)VALUES(2,579,2);四、常见故障排查问题Git 推送失败 (Error 403 / Unexpected Disconnect)报错信息示例Compressing objects: 100% (34759/34759), done. error: RPC failed; HTTP 403 curl 22 The requested URL returned error: 403 send-pack: unexpected disconnect while reading sideband packet Writing objects: 100% (46516/46516), 2.38 GiB | 304.78 MiB/s, done. fatal: the remote end hung up unexpectedly可能原因及解决方法权限不足 (HTTP 403)原因当前使用的 Git 账号没有该仓库的写入权限或者密码/Token 认证失败。解决检查 Gogs 网页端该用户是否有仓库的“写”权限。如果是 HTTPS 推送尝试重新输入密码或使用 Personal Access Token。检查是否开启了双重验证2FA若开启必须使用 Token 而非密码。推送包过大导致超时原因一次性推送的文件过多或单个文件过大导致 Nginx/IIS/Gogs 内部超时限制。解决分批提交不要一次性推送大量历史提交尝试分多次推送。调整配置修改 Gogs 的app.ini配置文件增加上传限制和超时时间。[server] MAX_UPLOAD_SIZE 1024 ; 单位 MB [repository] DISABLE_HTTP_GIT false检查 Web 服务器如果前端使用了 Nginx 反向代理需同步调整client_max_body_size。SSH 密钥问题原因如果使用 SSH 协议推送本地公钥未正确添加到 Gogs 账户设置中。解决在 Gogs 网页端 - 设置 - SSH/GPG 密钥添加本地的id_rsa.pub内容。确保本地 SSH 客户端使用的是正确的私钥可通过ssh -T gityour-server-ip -p 2222测试连接。五、总结在 Windows 上部署 Gogs 是一种低成本构建私有代码库的有效方式。通过 NSSM 将其服务化可以保证稳定性而在进行数据迁移时理解底层的数据库结构特别是user,repository,access表之间的关系对于解决权限错乱问题至关重要。遇到推送错误时优先排查权限配置和网络超时设置。
)
