Windows上自托管Gitea：轻量级Git服务器部署全攻略

如果你稍微有点自托管癖好或者团队里就想弄个内网代码库又不想上 GitLab 那种大家伙Gitea 在 Windows 上其实是被很多人低估的方案。它是一个用 Go 写的轻量级 Git 托管服务整个程序就一个 exe 文件跑起来几十 MB 内存却把代码托管、Issue、PR、Wiki、WebHook 这些常用功能全给你备齐了。我身边不少朋友第一反应是 Windows 上跑 Git 服务有点别扭实际上按对的方式装完日常使用非常顺手。这篇文章我从零开始把我反复装的这套流程写全覆盖安装、配置、注册服务、建仓库、日常协作和常见坑适合个人开发者、小团队管理员也适合第一次接触自托管 Git 服务的人。1. 为什么在 Windows 上装 Gitea选型与思路1.1 Gitea 是什么解决什么问题用 Git 做版本管理是开发者的基本功但单打独斗和团队协作是两码事。只在本地git init别人想拉你的代码、提 Issue、做 Code Review 都没有统一入口搭 GitLab 又嫌太重尤其是 Windows 服务器上跑 GitLab那种折腾程度能把一个运维的耐心耗尽。Gitea 就是冲着这个空档来的轻量、单文件、跨平台。它和 GitLab 一样能建仓库、管用户、开合并请求但资源占用小很多一台 2 核 4G 的小主机或者 Windows 老机器都能带得动。从部署形态看Gitea 在 Windows 上就是运行一个原生可执行程序不依赖 Java 环境不依赖单独 Web 服务器默认用 SQLite 数据库也不用额外起数据库服务。日常维护成本很低。这也是我推荐它在 Windows 上用的主要原因没有一层又一层的依赖关系出问题好排查升级也简单。1.2 在 Windows 上部署 Gitea 的几种方式常见的部署方式有四种我按照推荐程度排一下直接跑二进制最轻量。下载 exe启动 web访问 3000 端口完成安装。单机内网首选适合先体验一下。注册为 Windows 服务在直接跑的基础上用sc或 NSSM 包一层实现开机自启、崩溃随系统拉起推荐正式环境这么做。Docker 方式如果 Windows 上已经装了 Docker Desktop可以用gitea/gitea镜像跑容器。缺点是 Docker Desktop 本身内存占用不小和 Gitea 轻量的初衷有点矛盾但好处是升级和数据迁移方便适合容器化管理经验丰富的团队。WSL 方式在 WSL 里按 Linux 方式跑 Gitea能获得与 Linux 一致的环境但网络和文件系统转发在部分版本上有坑普通用户没必要绕这一圈。后面我主要以“直接跑二进制 注册服务”为主线这也是 Windows 下最稳妥、最接近官网推荐的方式。2. 安装前的准备环境依赖与文件下载2.1 先装好 Git for WindowsGitea 虽然本体是 Go 写的但管理仓库时会在底层调用 git 命令所以 Windows 机器上必须装 Git。我建议你从 git-scm.com 下载官方版本安装时保持默认选项即可有一个细节要注意在“Adjusting your PATH environment”这一步建议选第二项“Git from the command line and also from 3rd-party software”。这样 PowerShell、CMD 以及其他软件才能直接找到 git。装完以后开一个 PowerShell 窗口验证一下git --version如果输出类似git version 2.46.0.windows.1说明 Git 已经进入 PATH后面 Gitea 调用不会出问题。很多同学 Gitea 启动失败日志里报git not found基本都是这一环没弄好。尤其是用服务方式运行时服务账户的 PATH 可能和当前用户不一致后面我会单独讲。2.2 下载 Gitea 的 Windows 版本Gitea 的下载地址是 dl.gitea.com也可以去 GitHub Releases 下载。Windows 平台要选文件名里带windows-4.0-amd64的那个比如gitea-1.21.11-windows-4.0-amd64.exe如果你的机器还是老爷级的 32 位系统选386版本但说实话现在几乎遇不到了。下载后建议核对一下 SHA256官方下载页同时提供了哈希值。你可以在 PowerShell 里计算Get-FileHash .\gitea-1.21.11-windows-4.0-amd64.exe -Algorithm SHA256哈希一致再往下走这一步能避免下载到损坏文件。然后把 exe 放到一个固定目录比如C:\Gitea\gitea.exe。请注意之后不管是手动启动还是注册服务都统一用这个绝对路径别今天放 C 盘明天又挪 D 盘否则配置路径全乱。2.3 数据库别想复杂先用 SQLiteGitea 支持 SQLite、MySQL、PostgreSQL 和 MSSQL。单机和几十人以内的小团队SQLite 完全够用它不需要安装不需要账号密码Gitea 第一次启动时会自动创建数据库文件存在数据目录里。只有当你预估并发量很大、需要独立数据库统一管理或者要跟现有数据库基础设施整合才考虑 MySQL、PostgreSQL 这些。Windows 下如果你没有专门的 DBA 角色第一套环境直接 SQLite能省掉一大半的安装问题。后面真的量大了Gitea 也提供从 SQLite 迁移到 MySQL 的方法不过迁移是另一个话题初期不用管。3. 一步一步在 Windows 上装好 Gitea3.1 规划目录结构先建好这么一个目录结构C:\Gitea\ ├─ custom\conf\ ├─ data\ ├─ log\ └─ gitea.execustom\conf目录放配置文件 app.inidata目录放 SQLite 数据库和仓库数据log目录放运行日志。没有的目录手动创建一下。Gitea 启动时会把当前工作目录当成根目录所以后面我们运行 exe 或者注册服务时工作目录要指定为C:\Gitea不然它找不到 custom 和 data。如果你是从压缩包解压的包里通常有custom、data等空目录直接用就可以。不管哪种方式目录权限建议给运行 Gitea 的账户完全控制权。如果后面注册服务用的是 Local System 账户这个问题不大但如果你用普通用户启动服务就得检查 ACL 权限很多诡异问题都是目录写不进去导致的。3.2 初始化 app.ini先跑一遍再改配置最快的方式是先把服务跑起来让它自动生成默认配置。在 PowerShell 里切换到C:\Gitea目录cd C:\Gitea .\gitea.exe web --port 3000看到类似Listen: http://0.0.0.0:3000的输出说明 Gitea 已经启动。这时打开浏览器访问http://localhost:3000第一次进会跳转到安装页面地址通常是/install。这里可以完成基础配置站点名称随意比如“Team Git Server”。仓库根目录建议填C:/Gitea/data/gitea-repositories。数据库类型选 SQLite数据库文件路径填C:/Gitea/data/gitea.db。管理员账号填一个自己记得住的管理员用户名、邮箱和密码。如果不填第一个注册用户会自动成为管理员。域名和 SSH 端口域名填你的机器 IP 或实际域名HTTP 端口填 3000。填完点“安装 Gitea”配置会写入custom/conf/app.ini然后自动重启服务。此时 Gitea 就已经能用了。3.3 手工调整 app.ini 的几个常用参数安装向导生成的配置足够日常用但有三个参数我建议你打开C:\Gitea\custom\conf\app.ini后手动确认[server] PROTOCOL http DOMAIN 192.168.1.10 HTTP_PORT 3000 ROOT_URL http://192.168.1.10:3000/ [repository] ROOT C:/Gitea/data/gitea-repositories [database] DB_TYPE sqlite3 PATH C:/Gitea/data/gitea.db这里的DOMAIN和ROOT_URL很关键。如果你改了机器 IP或者以后想用域名访问一定要同步修改这两个值否则浏览器里显示的仓库克隆地址还是旧 IP别人复制下来也没法直接拉代码。另外如果你打算通过反向代理用 HTTPS 访问这一段也要一并改[server] PROTOCOL http ROOT_URL https://git.example.com/反向代理层负责把外网 HTTPS 转成内网 HTTPGitea 自己仍然监听 HTTP 端口这样证书、加解密压力全部交给反向代理Gitea 保持简单。3.4 注册成 Windows 服务实现开机自启手动开一个窗口跑 Gitea人走关机或者窗口一关服务就断了。正式使用必须注册成 Windows 服务。最简单的方式用系统自带的sc命令以管理员身份打开 CMD不是 PowerShellPowerShell 对引号转义处理不同执行sc.exe create gitea start auto binPath \C:\Gitea\gitea.exe\ web --config \C:\Gitea\custom\conf\app.ini\ DisplayName Gitea Server注意start auto和binPath后面都有一个空格这是 sc 命令的老规矩等号后空格不能省略。创建完以后sc.exe start gitea如果启动失败检查C:\Gitea\log\gitea.log。成功的话服务会以本地系统账户运行开机自动启动。想删除服务就sc.exe delete gitea备选方案是使用 NSSMNSSM 对服务工作目录、日志重定向、崩溃自动重启控制更直观nssm install Gitea C:\Gitea\gitea.exe web --config C:\Gitea\custom\conf\app.ini然后在 NSSM 界面里设置 Startup directory 为C:\Gitea。我个人的习惯是用 NSSM因为它的日志管理比 sc 更方便能直接把 stdout、stderr 写到文件排查问题更舒服。注册好服务以后记得在 Windows 防火墙里放行 3000 端口否则局域网内其他机器访问不了 Gitea 页面。4. 日常使用建仓库、克隆推送、加权限4.1 创建组织、仓库和用户安装完成后先在网页右上角注册或登录管理员账号。点“”号可以新建仓库新建时可以选仓库所有者是你自己还是一个组织。如果你的团队有多个项目组建议先建组织再在组织下建仓库权限好统一管理。在“组织”页面创建组织后可以往组织里添加成员并按团队Team分配权限比如读权限、写权限、管理员权限。Gitea 的权限模型和 GitLab 基本一致仓库级别可以设置可见性公开、私有团队级别可以限制能访问哪些仓库、能做什么操作。小团队可以不用管那么细直接在仓库页面的“管理 - 合作者”里添加用户并勾选写权限就够了。4.2 HTTP 方式克隆和推送Windows 客户端要使用 clone 和 push同样需要先装好 Git。假设你的 Gitea 地址是http://192.168.1.10:3000用户名是user1仓库名是demo那么克隆地址就是git clone http://192.168.1.10:3000/user1/demo.git首次 push 时如果你用的是 HTTP/HTTPSGit 会弹出窗口让你输入 Gitea 账号密码如果不想每次输密码可以在仓库里执行一次git config --global credential.helper manager这是 Git for Windows 自带的 credential manager首次输入后会记住凭证。如果你更习惯用 SSH 密钥参考下一小节。4.3 SSH 方式公钥配置的正确打开方式Windows 客户端这边SSH 密钥生成和 Linux 没区别。在 PowerShell 或 CMD 里执行ssh-keygen -t ed25519 -C your_emailexample.com按三次回车生成密钥对然后把C:\Users\你的用户名\.ssh\id_ed25519.pub里的内容复制打开 Gitea 网页右上角头像 - 设置 - SSH/GPG 密钥 - 添加密钥粘贴进去。这里很多人会遇到问题密钥加好了但 SSH 克隆还是提示连接失败。原因在于 Gitea 服务端的 SSH 实现不是单纯靠网页里那把公钥就能跑起来的。Windows 版 Gitea 并不像 Linux 那样可以随意启用内置 SSH 服务器它需要依赖 Windows 自带的 OpenSSH Server并把 Git 的 shell 环境给 SSH 用户准备好配置过程稍显繁琐。所以在 Windows 上如果你只是自己用或者小团队用我建议先用 HTTP 克隆SSH 等确实有需求再折腾服务端。要是你已经在 Windows 上装好并启动了 OpenSSH ServerGitea 的配置项[server] SSH_PORT 22、SSH_USER 你给 ssh 服务的账户都要对应起来。4.4 备份和升级的实用做法备份 Gitea本质上只要备份三样东西custom/conf/app.ini、data目录、log目录其实 log 不备也行。最简单粗暴的办法是直接复制整个C:\Gitea目录但运行中的 SQLite 数据库文件直接复制可能不一致建议先停服务再复制或者用 Gitea 自带命令cd C:\Gitea .\gitea.exe dump -c custom/conf/app.inidump 会把配置文件、数据库和仓库打包成一个 zip然后你自己挪到备份盘就行。恢复时把 zip 解压回原目录重新启动服务即可。升级步骤也不复杂先备份然后停掉 Gitea 服务把新的 exe 覆盖旧的重新启动服务。Gitea 从旧版到新版一般会自动做数据库迁移启动日志里会看到迁移记录。需要注意的是跨大版本升级前一定看官方更新日志如果中间隔了很多版本最好逐级升不要一下从 1.18 跳到 1.21。5. 常见问题与排查技巧5.1 端口被占用3000 起不来怎么办Windows 上 3000 端口被其他程序占用很常见尤其是装了 Node 开发环境的机器。先用命令查netstat -ano | findstr :3000找到占用进程 PID 后在任务管理器里定位或直接问是否关闭。如果不想关其他程序改 Gitea 端口最省事编辑app.ini里的HTTP_PORT 3001然后重启服务。改完以后ROOT_URL里的端口也要同步改成 3001。5.2 中文文件名或者路径乱码Gitea 本身对中文仓库名、中文文件名支持没问题但 Windows 下 Git 默认可能对非 ASCII 路径转义。在客户端里执行git config --global core.quotepath false再查看git status时中文文件名就不会显示成一串转义数字。仓库名想用中文也没问题只是克隆地址里会带 URL 编码浏览器能自动解析不一定非要改。5.3 服务启动失败日志里看门道如果注册成服务后sc.exe start gitea启动失败不要干瞪眼。服务方式运行时 Gitea 会把日志写到C:\Gitea\log\gitea.log或者 Windows 事件查看器里也有记录。最常见的失败原因有三个一是binPath里配置路径错误检查引号有没有写对二是工作目录不对用 sc 创建服务时没指定工作目录Gitea 找不到 custom 和 data这时改用 NSSM 来设置 Startup directory 比较省心三是权限不足服务运行账户对数据目录没有写权限给服务账户加上完全控制权限即可。5.4 克隆仓库时提示“找不到 git”或后置钩子失败这通常是 Gitea 运行账户的 PATH 里没有 git.exe。如果服务是用 Local System 账户跑的而 Git for Windows 是装在管理员用户目录下的系统 PATH 里未必有 git。解决方法是把C:\Program Files\Git\cmd和C:\Program Files\Git\bin手动加到系统环境变量 PATH 里然后重启 Gitea 服务。另外安装 Git 时可以勾选“Use Git from the command line and also from 3rd-party software”这样最省事。5.5 小技巧用反向代理提供 HTTPS 访问如果不想裸用 IP 加端口访问Windows 上装个 Caddy 做反向代理非常省力。在 Caddyfile 里写git.example.com { reverse_proxy 127.0.0.1:3000 }Caddy 会自动申请和续期证书然后把外部 HTTPS 流量转发到 Gitea 的 HTTP 端口。再配合app.ini里的ROOT_URLhttps://git.example.com/克隆地址就是干净的 HTTPS 地址公网客户机访问也安全得多。没有公网域名的话也可以用自签证书但所有客户端都要信任那份证书维护成本偏高内网个人用可以接受。我个人在实际部署中最大的体会是Gitea 在 Windows 上的问题大部分不在 Gitea 本身而在环境Git 装没装、PATH 对不对、端口冲不冲突、服务账户有没有权限。把这四件事理顺后面基本就是一路顺畅。如果你只想在本机做个小仓库直接跑 exe 就够了如果是多人长期用一定第一时间注册成服务并且把备份脚本写进计划任务GitHub 出问题不心疼自己的代码丢了才是真麻烦。