Windows 10上自建Git服务器：Gogs部署全流程与踩坑指南

如果你的主力机器是 Windows 10，又想给自己或小团队搞一个私有代码仓库，不想把代码放在公共平台上，其实有比共享文件夹、裸 Git 仓库更清爽的解法：部署一个轻量级的自托管 Git 服务器。我在 Win10 上折腾了两周，最后稳定跑起来的就是 Gogs，整个部署过程从“一头雾水”到“三分钟能重装一遍”，所有坑基本都踩遍了。这篇就把我验证过的完整流程、关键配置项、服务化常驻和备份策略全部写下来，给想在 Windows 上自建 Git 服务器的人一个可以直接照做的手册。

Gogs 是一个用 Go 语言写的轻量级 Git 服务端程序，单文件、低内存占用，特别适合内网个人仓库或几个人协作的团队。相比 GitLab 动辄要几 GB 内存、需要一堆依赖组件，Gogs 在 Win10 上的部署几乎就是“解压、配个文件、跑起来”三个动作。它能提供完整的 Web 界面、用户管理、仓库权限、Issue 管理、Webhook 通知，个人开发者拿来存代码，小团队拿来替代 SaaS 仓库，都够用。如果你不想每笔提交都推到受第三方平台约束的云端，这篇指南正好适合你。

1. 为什么是 Gogs，而不是裸仓库、GitLab 或 Gitea

1.1 这三个方案我都试过，区别在运维成本

先说我踩过的其他两条路。

第一种是 Windows 共享文件夹 + 裸 Git 仓库。操作很简单，在一台 Win10 上装好 Git for Windows，建一个文件夹并执行git init --bare，然后把共享文件夹分配给团队成员，大家直接映射网络驱动器。小团队、代码量不大、且所有成员都在同一内网时，这条路真的能跑。但问题也很明显：没有 Web 界面，看不到提交历史图、分支结构和代码 diff，代码评审基本全靠命令行；权限只能靠 NTFS 目录权限控制，想给 A 只读、给 B 读写，配置起来非常痛苦；多人同时 push 时还会出现文件锁冲突，代码量一大就很容易出现“明明提交成功但远端仓库状态不对”的诡异问题。

第二种是自建 GitLab。功能确实强，但它是为 Linux 服务器和高并发团队设计的，在 Win10 上部署要装 Ruby、PostgreSQL、Redis 一整套组件。我试过一次，光环境依赖就装了一个下午，启动后内存直接吃掉几个 GB，一台日常还得干别的机器根本扛不住。如果你的是小团队，GitLab 属于典型的“杀鸡用牛刀”，升级维护成本极高，而且 Windows 上并不是官方主推平台，遇到兼容问题的概率比 Linux 大得多。

第三种就是 Gogs。单文件、全平台支持、自带轻量 Web 界面，内存占用大概就在 100MB 以内，配置文件的逻辑非常直白。我在 Win10 上从下载到页面初始化，大概花了十分钟。

1.2 Gogs 和 Gitea 的差异，选型时怎么判断

很多人会问：Gogs 和 Gitea 不是同源吗，为什么选 Gogs 而不是 Gitea？两个项目确实同源，Gitea 是社区从 Gogs 分叉出去的，功能上有一些增强，比如更频繁的发布、更多的合并请求审查功能。但对大多数个人开发者和小团队来说，Gogs 的功能边界已经绰绰有余，更重要的是它更新节奏更慢、更保守，反而没有频繁升级带来的适配烦恼。在 Win10 这种“非主流服务器系统”上，我宁可要一个包里没有太多变化、行为可预测的程序。

选型结论很明确：如果你追求“最低运维成本、快速跑通内网 Git 服务、不带数据库依赖”，Gogs 是 Win10 上的最优解。如果你需要超细粒度的 CI/CD 集成、大规模组织管理，那应该直接上专业服务器系统 + GitLab，而不是在 Windows 上硬撑。

2. 部署前准备：宁可多花十分钟，也别当众翻车

2.1 Git for Windows 的安装选项别选错

Gogs 虽然自带 Git 仓库管理能力，但它本质上是调用系统里的 Git 可执行文件来执行相关操作的，所以第一步是先装好 Git for Windows。安装时有一个关键选择：调整 PATH 环境变量。这里我建议选第二项“从命令行使用 Git”，而不是“仅使用 Git Bash”。原因是后续无论你在 PowerShell、CMD 里执行git命令，还是排查 Gogs 报错，都需要在系统 PATH 里直接能找到git.exe。只选 Git Bash 会在某些自动化脚本里找不到 git，报错还特别难排查。

装完之后在 CMD 里执行git --version确认版本号能正常打印，再继续下一步。这个验证往往被省略，但很多后续"莫名其妙"的失败，根源就是 Git 没装好。

2.2 下载 Gogs 与合理的目录规划

去 Gogs 官方发布页下载 Windows 对应版本，我选的是windows amd64的 zip 包，而不是带mws的那个变体。mws 是内置了部分运维组件的版本，对于我们的场景没必要，标准 zip 包就够了。

下载完成后，不要图省事解压到桌面或下载目录。建议按下面的结构规划：

C:\gogs\ ← 程序目录，放解压后的全部文件 C:\gogs\custom\ ← 配置与自定义文件目录 D:\git-data\ ← 数据目录，放仓库和数据库 D:\git-data\repositories\ ← 实际 Git 仓库存储位置 D:\git-data\data\ ← Gogs 数据库、附件、日志

这里有个很重要的思路：程序目录和数据目录分离。Gogs 程序本身就是一个绿色软件，升级时只需要下载新版本压缩包、覆盖程序目录、保留custom和D:\git-data，你的所有仓库、用户、配置都在。如果不做分离，每次升级都把repositories和data覆盖一遍，数据损坏风险很高。

另外要设置一个环境变量：GOGS_WORK_DIR。把它指向D:\git-data，这样 Gogs 就会把所有动态数据写入数据目录，而不是程序目录。在 Windows 系统设置里选择“编辑系统环境变量”，新建一个用户变量即可。这一步不设置也能运行，但强烈建议做，因为后续所有备份、迁移都会变得非常简单。

2.3 数据库怎么选：SQLite 够用，什么时候换外部数据库

Gogs 支持 SQLite、MySQL、PostgreSQL。首次安装页会问你用哪种。先给结论：个人或十人以下团队，直接选 SQLite。

SQLite 是一个文件型数据库，Gogs 所有数据会落到data\gogs.db这个单文件里。好处是零依赖、备份只需要拷贝这一个文件、升级迁移完全不用关心数据库版本兼容。坏处是并发写入能力有限，但对于 Git 服务器来说，提交操作本身并不密集，真正承载大流量的是 Git 仓库文件而不是数据库，所以 SQLite 在上百人的团队里也未必是瓶颈。

以下几种情况才考虑 MySQL 或 PostgreSQL：团队人数多、有需求把数据库纳入统一的备份监控体系、或者已经有成熟的 MySQL 运维经验。如果只是“不想太折腾”，SQLite 完全够用。下面这个表是我自己的选型参考：

如果你在 Win10 上已经装了 MySQL，需要注意字符集和时区配置。保证数据库服务能正常运行即可，Gogs 安装页会和数据库建立连接，连接成功后会继续下一步。

3. 首次启动与初始化配置

3.1 第一份 app.ini 怎么生成

在 CMD 或 PowerShell 里进入C:\gogs目录，执行：

gogs.exe web

第一次启动时，Gogs 会自己生成一份默认配置文件C:\gogs\custom\conf\app.ini。这就是整个服务端的核心配置。启动之后如果终端没有报错，一般会显示监听端口，默认是3000。此时浏览器访问http://localhost:3000，就会进入安装页面。

注意，第一次启动只是临时前台运行，Ctrl+C 就会停掉。后面的章节里我会讲怎么注册成 Windows 服务，让它开机自启。现在先保持前台状态，目的是完成第一次初始化配置。

打开app.ini看一眼，核心配置项大概长这样：

[server] HTTP_PORT = 3000 ROOT_URL = http://192.168.x.x:3000/ SSH_PORT = 2222 DOMAIN = 192.168.x.x [database] DB_TYPE = sqlite3 PATH = D:/git-data/data/gogs.db [repository] ROOT = D:/git-data/repositories

有几个字段必须理解，不然后面会踩坑：

• ROOT_URL：这是唯一决定“其他人克隆仓库时拿到什么地址”的配置。如果你只是本机访问，写http://localhost:3000/没问题；但要让局域网里其他人也能克隆，就必须写成http://你的局域网IP:3000/，否则别人从网页上复制克隆地址时，拿到的全是localhost。
• SSH_PORT：默认是 22，但 Windows 10 的系统 OpenSSH 服务很可能已经占用了 22 端口。我的建议是改成2222，或者10022，避免冲突。
• [repository] ROOT：仓库数据实际存储路径，指向我们规划的D:\git-data\repositories。

3.2 网页安装页面上隐藏的几个关键设置

浏览器打开安装页面后，表单里有几个字段看起来很基础，但实际很关键：

• 数据库类型：选 SQLite，路径填D:\git-data\data\gogs.db。
• 站点名称：随便填一个，比如 “Internal Git Service”，这个会显示在网页标题和页面顶部。
• 仓库根目录：填D:\git-data\repositories。
• SSH 服务端口：填 2222（或你选定的端口）。
• 应用 URL：必须填http://局域网IP:3000/，这个值会写进ROOT_URL。如果这里填错了，后面改app.ini后重启服务也可以解决，但最好一开始就填对。
• 管理员账号：安装页会要求设置一个管理员用户名和密码，不要跳过。后面所有仓库创建、团队管理、系统配置都要靠这个账号登录。

提交安装表单后，Gogs 会写入配置并重启服务。然后就可以用管理员账号登录后台了。登录后第一件事，在“管理面板”里确认“服务配置”中显示的 SSH 端口和ROOT_URL是否和你填的一致。不一致就直接改app.ini，保存后重启服务。

3.3 创建第一个仓库前的自检

创建仓库前，建议先做一轮自检，省得后面排查起来抓瞎：

1. 浏览器访问http://localhost:3000，确认 Web 界面正常。
2. 在安装页同一台机器上执行git --version，确认 git 命令可用。
3. 检查防火墙：Win10 默认会拦截外部对 3000 端口和 2222 端口的访问，需要在“Windows Defender 防火墙”的“高级设置”里新建两条入站规则，放行 TCP 3000 和 TCP 2222。如果你只在局域网里用，这一步必须要做，否则其他机器连不上。
4. 用netstat -an | findstr 3000看一眼 3000 端口是否处于 LISTENING 状态。

然后就可以点击“创建仓库”，试着在本地初始化一个项目并 push 上去了。创建仓库的页面里有个“仓库可见性”选项，个人仓库建议选“私有”，只有你添加的协作者才能看到和访问。

4. 让 Gogs 真正“跑起来”：服务注册与开机自启

4.1 两种常驻方案，不用 CMD 窗口硬撑

如果每天开个 CMD 窗口手动执行gogs.exe web，机器重启一次就断了，显然不是正经做法。注册成 Windows 服务是唯一靠谱的方案，有两种方式。

第一种是使用 Gogs 自带的 service 命令。在管理员权限的 CMD 里执行：

C:\gogs\gogs.exe service install -n Gogs -description "Gogs Git Server" C:\gogs\gogs.exe service start -n Gogs

注意，执行 service 命令时必须保证当前目录是C:\gogs，因为 Gogs 默认以当前工作目录来定位程序和配置。如果你在别的目录执行，服务安装了也会因为找不到app.ini而启动失败，这是初学者最容易踩的坑之一。

第二种方式是使用第三方工具 NSSM。NSSM 的好处是配置图形化、日志重定向更直观。命令如下：

nssm install Gogs "C:\gogs\gogs.exe" web nssm set Gogs AppDirectory "C:\gogs" nssm start Gogs

无论用哪种方式，服务注册成功后，都要在“服务管理器”里确认 Gogs 服务的“启动类型”是“自动”，并且启动状态为“运行中”。

4.2 服务化之后最容易忽略的权限问题

Windows 服务默认以“本地系统账户”运行，这个权限很高，但有一个容易忽略的点：如果你在app.ini里把RUN_USER填成了一个具体的 Windows 用户名，就要保证该用户对C:\gogs和D:\git-data有完整的读写权限。我之前为了“看起来规范”填了个普通用户，结果服务启动后仓库目录写入失败，所有 push 操作都报权限错误，排查了半天才发现是目录权限没放给那个用户。

所以，最简单的做法是把RUN_USER留空，让服务以系统账户运行，然后确保D:\git-data目录对Everyone或服务账户开放读写。如果你们公司对安全要求严格，再按最小权限模型去收敛。

服务化配置完成后，强烈建议完整重启一次机器，验证 Gogs 是否真的“开机即起”。重启后如果服务没起来，就去“事件查看器-应用程序”里找 Gogs 的错误记录，常见原因是端口被占用或者工作目录不对。

5. 日常使用：仓库、权限与备份的实操

5.1 团队协作的权限模型

Gogs 的权限模型可以满足大多数小团队场景，核心是“仓库私有 + 组织管理”。

在仓库页面里，把仓库设为私有后，点击“设置 -> 协作者管理”，你可以按用户名添加协作者，并指定为读或写权限。读权限只能 clone 和查看，写权限可以 push。如果团队成员人数超过五个人，建议在“组织”里创建一个团队，把成员统一归入团队，再把这个仓库授权给整支团队。这样新员工加入时只需要加入组织，仓库权限自动生效，不用一个个手动配。

这个设计很像我用过的一些 SaaS 平台，企业这一层比较省事。个人部署场景下虽然不一定需要组织，但如果你要给外聘同事开账号，强烈建议一定配合私有仓库使用，避免代码被无关人员拉走。

5.2 备份策略：我在用的双保险

自建服务最怕的是数据丢失，Gogs 的数据分两部分：Git 仓库本体和数据库。备份策略比你想的还要简单。

第一种备份方式是直接复制目录。把D:\git-data整个目录复制到另一块磁盘，或者压缩打包丢到 NAS。这种方法最朴素，但也最可靠。执行复制前，最好先把 Gogs 服务停一下，保证gogs.db不会被写入到一半。如果你不想停服，就选择在深夜或团队不活跃的时间做，并用工具做差异同步。

第二种是 Gogs 自带的备份命令：

gogs.exe dump --config C:\gogs\custom\conf\app.ini

这个命令会把仓库目录、数据库、配置文件和附件打包成一个 zip。文件名会带时间戳。但注意，dump 命令执行时如果数据库正在被写入，备份的一致性无法保证，所以依然建议优先停服备份。

我现在日常采用的是“双保险”：每周日深夜停服十分钟，完整复制D:\git-data到另一块本地硬盘；每天中午用 dump 命令打一个带日期的 zip包，存到文件服务器。这样即使当天仓库数据损坏，最多也就丢半天提交记录，恢复成本很低。

5.3 和本地 Git 工作流的融合

Gogs 部署好后，它的身份就是一台远端 Git 服务器。所有人拉取代码的方式有两种：

HTTP 方式：在仓库页克隆地址那里会显示http://192.168.x.x:3000/username/repo.git，本地执行：

git clone http://192.168.x.x:3000/username/repo.git

SSH 方式：需要在 Gogs 个人设置里添加 SSH 公钥，然后本地用：

git clone ssh://git@192.168.x.x:2222/username/repo.git

我日常习惯用 SSH 方式，因为免密、传输走加密通道，在信任的内网环境里很顺手。注意端口是 2222，因为默认 22 冲突了，克隆地址里必须带上端口号。第一次 SSH 连接时，提示确认主机指纹，选择yes即可。对团队新同事，最省事的方式是把公钥集中维护，或者干脆都走 HTTP，用 Gogs 账号密码登录。

Gogs 的 Webhook 功能也可以接上：在仓库设置里添加一个 webhook，push 事件发生后，Gogs 会向你的内部群机器人发送通知，或者在 CI 工具上触发自动构建。这个功能对于小团队来说，等于把“代码推送”和“构建通知”串成了一条简单的流水线。如果你正在把本地代码库往 Gogs 迁移，直接用git remote add origin换一下远端地址再git push -u origin master就行。

6. 我踩过的坑与排查思路

6.1 SSH 连接失败：端口被占和主机密钥不匹配

第一次在某台笔记本上配好 Gogs 后，我用 SSH 去 clone 仓库，终端报错connection refused。检查后发现，Win10 自带的 OpenSSH 服务占用了 22 端口，而我虽然把 Gogs 的 SSH 端口改成了 2222，但某些客户端配置里的地址还是老的ssh://git@192.168.x.x/username/repo.git，没带端口。SSH 默认走 22，自然连不上。

排查思路：在服务端执行netstat -an | findstr 2222，确认端口在监听。客户端执行ssh -p 2222 -T git@192.168.x.x，观察是否能识别出 Gogs 的 SSH 服务。另外还要注意C:\Users\用户名\.ssh\known_hosts里可能残留旧的主机指纹，如果 IP 被别的机器用过的 ssh 服务绑定过，报错会提示 host key mismatch，删除那一行即可。

6.2 克隆地址粘出来是 localhost，根本连不上

这个问题几乎每个新手都会遇到。网页仓库页显示的克隆地址是http://localhost:3000/username/repo.git，别人照这个地址 clone 当然连不到你的机器。根因就是我在前面反复强调的ROOT_URL没正确配置。

解决方式也不复杂，修改app.ini里的ROOT_URL = http://192.168.x.x:3000/，然后重启 Gogs 服务。要注意的是，仓库页面的克隆地址是在页面加载时根据 ROOT_URL 动态生成的，改完配置后记得强制刷新浏览器，或者重新打开仓库页。我见过有人配置改对了，但浏览器缓存着旧页面，误以为没生效，白白排查半个小时的。

6.3 版本升级时 SQLite 文件不可写

有一次我从旧版升级到新版本，发布了新程序文件后，执行gogs.exe web一直报错，错误日志指向unable to open database file。当时第一反应是文件损坏，后来发现是因为新版程序启动时，数据目录还没有正确设置，它偷偷在程序目录下新建了一个data文件夹，然后去里面找gogs.db，自然找不到。

这个问题就是典型的 GOGS_WORK_DIR 或app.ini里PATH配置没对齐导致。升级前如果重新解压过程序，一定要注意检查app.ini是否还指向原来的数据库路径D:\git-data\data\gogs.db。升级的完整流程我建议是：停服务 -> 备份整个数据目录 -> 删除或重命名旧程序目录 -> 解压新版 -> 把旧的custom文件夹复制回去 -> 启动服务。不要图省事直接把新版文件覆盖到旧目录，有些旧配置文件残留会造成不可预期的问题。

6.4 通用排查思路：日志是第一手线索

Gogs 的日志会写到D:\git-data\data\log\gogs.log。几乎所有的错误，无论是数据库连接、仓库创建失败、SSH 握手异常，都会日志里留下记录。我的排查习惯是：先把服务停下来，在前台模式下用gogs.exe web启动，日志会直接打到终端，比翻文件直观得多。前台模式下复现一遍操作，看到报错日志后，再回app.ini或防火墙设置里找答案。九成的部署问题，在日志出现的那一刻就已经能定位了。

如果你准备把 Gogs 长期作为日常协作基础设施，还有一个容易被忽略的点：Windows 时间同步。SSH 和 HTTPS 的某些操作对机器时间比较敏感，如果系统时间偏差过大，会出现证书或认证相关的奇怪错误。确保 Win10 开启了“自动设置时间”，并在 BIOS 层面保证机器时间不跳变，就能避免这类玄学问题。

我现在的习惯是：每个周六晚上导出一份 dump 备份，每个月底把D:\git-data整个打包到移动硬盘。升级版本前，永远先备份再操作，留一条退路。这些坑大部分都是我亲手踩出来的，记录在这里，希望能帮你少走点弯路。