1. 需求拆解为什么偏偏要在 Windows 上自建 Gitea1.1 三类最典型的落地场景先把话说在前头Gitea 在 Windows 平台上的安装绝对不是什么玩具级操作它是我见过在中小团队里性价比最高的私有代码托管方案之一。很多人一听到自建代码仓库脑子里第一反应是 Linux 服务器加一堆命令行其实 Windows 在这件事上完全没有短板反而因为图形化程度高、运维门槛低特别适合下面这三类人。第一类是小团队内网开发。三五个人写代码公司不方便把源码放到外部托管平台上又不愿意为了一个 Git 服务专门去买云服务器、学 Linux 运维。这时候在办公室某台常开的 Windows 机器上装一个 Gitea局域网内所有人git clone就能用成本几乎为零。第二类是个人开发者做代码归档。你手上可能有几十个写了一半的项目、脚本、配置文件、笔记仓库散落在各个硬盘里。与其用 U 盘拷来拷去不如自己搭一个 Git 服务定期推上去顺带还能把 Issue 当待办清单用。Gitea 的界面轻、启动快、资源占用小一台老笔记本就能长期跑着。第三类是学习和练手环境。你想搞明白 Git 服务端到底是怎么工作的——仓库目录结构长什么样、SSH 是怎么对接的、钩子脚本在哪触发、权限模型怎么设计的。用 Gitea 在 Windows 上搭一套所有目录你都能直接打开看比在云端黑盒里点按钮学到的多得多。我一直觉得工具选型的核心不是哪个最强而是哪个能让你今晚就把事做完。Gitea 在 Windows 上的安装熟练的话二十分钟能跑起来这个门槛低到值得每个写代码的人都试一次。1.2 为什么是 Gitea而不是别的方案先做个横向对比把选型逻辑讲清楚后面装起来你才知道每一步在干什么。方案资源占用安装难度功能完整度适合场景裸 Git SSH极低中只有仓库无 Web 界面单人、纯命令行Gitea低单进程约 100-200MB 内存低仓库、Issue、PR、Wiki、Actions小团队、个人GitLab CE高建议 4GB 内存起步高全功能 DevOps 平台中大型团队云托管平台无本地占用极低全功能公开项目、无隐私要求Gitea 是用 Go 写的这个技术选型直接决定了它在 Windows 上的体验编译出来就是一个 exe 文件没有任何运行时依赖。你不需要装 Java、不需要装 Node、不需要配 Python 虚拟环境——虽然你机器上大概率为了别的项目已经装了 Python 和 Anaconda但 Gitea 完全不依赖它们。这一点太关键了Windows 上最烦的就是各种运行时装了一半、版本冲突、环境变量没配好。对比 GitLabGitLab 官方基本不推荐在 Windows 上原生部署社区版本在 Windows 上跑起来坑非常多。而 Gitea 官方直接提供 Windows 的 amd64 二进制包双击就能跑这就是差距。还有一点容易被忽略Gitea 的配置文件是一个纯文本的app.ini所有参数看得见摸得着。出问题的时候你不需要去翻十几层 Docker 配置或者 Helm Chart打开 ini 文件对照官方文档改一行重启就行。对于刚接触服务端部署的人来说这种所见即所得的透明度比任何花哨的功能都值钱。1.3 部署方式怎么选二进制、Docker 还是 Windows 子系统Gitea 在 Windows 上主要有三条路我把各自的取舍说明白。第一条是原生二进制也就是直接下载 exe 运行。这是我最推荐的入门方式路径清晰、日志直接写在文件里、服务注册简单、升级就是替换一个 exe。缺点是 Windows 上跑服务需要额外做一步注册成系统服务否则关掉命令行窗口进程就没了。第二条是 Docker Desktop。如果你的机器上已经有 Docker 环境用容器跑 Gitea 确实很省事一条docker run就完事数据用 volume 挂出来。但 Windows 上的 Docker Desktop 本身就要占不少内存还涉及 WSL2 后端对配置一般的机器不太友好。而且一旦出问题你得同时排查容器网络、卷挂载、端口映射三层排查链条变长了对新手不算友好。第三条是通过 Windows 子系统里的 Linux 环境来跑。这条路技术上完全可行也有不少人这么干但本质上你已经不是在Windows 平台部署了而是绕回了 Linux。对于想搞清楚 Windows 原生部署细节的人来说反而多了一层干扰。我的建议很明确第一次装走原生二进制路线。等这套跑顺了理解了 Gitea 的目录结构和配置项再考虑要不要迁到容器里。顺序反了的话你会在容器里遇到问题时完全不知道底层发生了什么。2. 安装前的环境准备与依赖梳理2.1 系统版本与硬件的最低门槛Gitea 对 Windows 版本的要求其实很宽松Windows 10、Windows 11、Windows Server 2016 及以上都能跑。需要注意的是 Windows 7 和 Server 2008 这类老系统新版本的 Gitea 已经不再提供支持硬上的话可能在 TLS 握手或者某些系统调用上出问题不建议折腾。硬件方面我给一个实测的参考值项目最低可跑舒适区间说明内存512MB 可用2GB 以上单进程本身占用很小磁盘1GB视仓库大小Git 仓库是增量存储比想象中省CPU双核四核日常操作几乎不吃 CPU系统盘任意建议数据放非系统盘方便备份和迁移这里有个经验千万别把仓库数据放在 C 盘的用户目录下。我见过太多人装完之后data、repositories、log全在C:\Users\xxx\里面结果系统重装或者用户配置损坏几年的仓库全没了。规划的时候就统一放一个独立目录比如D:\gitea\所有东西都塞进去备份直接整个目录打包干净利落。目录结构我习惯这样规划你也可以照抄D:\gitea\ ├── gitea.exe # 主程序 ├── custom\ │ └── conf\app.ini # 配置文件 ├── data\ # 附件、头像、会话等 ├── log\ # 日志 ├── repositories\ # 所有 Git 仓库 └── backup\ # 手动备份输出目录把gitea.exe放在根目录下是为了让它的工作目录Working Directory就是这个文件夹Gitea 默认会在当前目录下找custom、data、log这几个文件夹路径关系一目了然。2.2 Git 的安装与那几行必须改的全局配置Gitea 本身不包含 Git 的实现它需要调用系统的git命令来完成仓库的底层操作。所以第一步是先把 Git for Windows 装上。去 Git 官网下载 Windows 版安装包一路默认安装就行唯一需要注意的是在Adjusting your PATH environment这一步选Git from the command line and also from 3rd-party software这样git会被写进系统 PATHGitea 才能找到它。装完之后打开新的命令行窗口敲git --version git version 2.43.0.windows.1能输出版本号就说明装好了。如果你敲出来提示不是内部或外部命令那就是 PATH 没生效检查一下是不是没重开命令行窗口或者安装时选错了选项。接下来是几个全局配置不配的话后面会踩坑git config --global user.name 你的名字 git config --global user.email youexample.com git config --global core.autocrlf true git config --global core.quotepath false git config --global init.defaultBranch maincore.autocrlf true这一条是 Windows 上必须设的。原因在于 Windows 的换行符是CRLF而 Linux 和 macOS 是LF如果不做转换一个团队里混用不同系统的人会不停地产生整个文件都被改了的假 diffreview 的时候一片红非常难受。设成true之后提交时自动转成LF检出时自动转成CRLF各平台相安无事。core.quotepath false是让 Git 在输出中文文件名的时候不要转义成\344\275\240这种八进制码中文项目必备。init.defaultBranch main是把默认分支从master改成main跟主流托管平台保持一致省得每次都要手动改。提示这几条配置是跟当前 Windows 用户绑定的写在C:\Users\你的用户名\.gitconfig里。如果 Gitea 是用系统服务的方式跑起来的而服务账户是SYSTEM或者LocalService这类账户那么它读到的.gitconfig可能跟你命令行的不是同一份。这一点在排查命令行能提交、网页端操作报错这类问题时非常关键。2.3 数据库选型SQLite 和 MySQL 到底选哪个Gitea 支持 SQLite、MySQL、PostgreSQL、MSSQL 四种数据库。在 Windows 上绝大多数人的选择集中在 SQLite 和 MySQL 之间。SQLite 的优势是零配置。不需要单独装数据库服务不需要建库建用户Gitea 直接在data目录下生成一个gitea.db文件所有数据都在里面。备份的时候把这个文件复制走就完了简单到令人发指。缺点是并发写入性能有限多个用户同时推送大仓库的时候可能出现锁等待。MySQL 的优势是稳定和可迁移。数据量和并发上来之后不会成为瓶颈将来想把 Gitea 迁到别的机器或者别的平台只要把数据库导出再导入就行。缺点是你要额外装一个 MySQL 服务多一层维护成本。怎么选我的判断标准很简单使用者不超过 5 个人仓库数量几十个以内日常就是提交、拉取选SQLite别给自己找事。团队规模十人以上或者有 CI 频繁读写、有大量 Issue/PR 操作选MySQL。如果你选了 MySQL创建数据库的时候有几个细节必须注意。启动 MySQL 命令行执行CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER gitealocalhost IDENTIFIED BY 你自己设的强密码; GRANT ALL PRIVILEGES ON gitea.* TO gitealocalhost; FLUSH PRIVILEGES;字符集必须是utf8mb4不是utf8。MySQL 里的utf8其实是个残缺的实现最多只能存三个字节的字符存不了 emoji 和部分生僻汉字。如果你用了utf8将来在 Issue 里打个表情符号数据库直接报错。还有一个坑我必须单独拎出来说。MySQL 8.0 之后的默认认证插件是caching_sha2_password而 Gitea 使用的数据库驱动在部分版本下不支持这个插件表现就是初始化的时候一直提示Access denied或者连接超时密码明明是对的。解决办法是把这个用户改成传统的认证方式ALTER USER gitealocalhost IDENTIFIED WITH mysql_native_password BY 你自己设的强密码; FLUSH PRIVILEGES;注意这条命令执行完要重新连一次数据库验证。我在一台机器上曾经卡在这个问题上快一个小时一直在怀疑密码写错了、防火墙拦了、端口不对最后发现就是认证插件的问题。这个坑记住能省你半条命。3. Gitea 二进制版安装实操全过程3.1 下载文件与目录初始化的细节打开 Gitea 的官方下载页找到 Windows 版本的压缩包或者独立 exe。文件名一般长这样gitea-1.22.0-windows-4.0-amd64.exe。这个命名规则里的4.0指的是 Go 的 Windows API 版本不是 Gitea 版本别被绕晕。下载完之后把它重命名为gitea.exe放进你规划好的D:\gitea\目录。为什么要重命名因为后面注册 Windows 服务、写启动脚本的时候路径里有版本号会非常麻烦每次升级都要改路径。统一成gitea.exe之后升级就变成了停服务、覆盖 exe、启服务三步。接下来一步很多人会漏掉把D:\gitea加到系统的 PATH 里。这样你在任何目录下打开命令行输入gitea都能直接调用它的管理命令比如gitea dump、gitea admin。加 PATH 的方式是此电脑右键 → 属性 → 高级系统设置 → 环境变量 → 在系统变量里找到 Path → 编辑 → 新建 → 填入D:\gitea。第一次启动进入D:\gitea目录直接执行cd /d D:\gitea gitea web这时候你会看到一屏的日志输出最后几行大概是这样[INFO] Listen: http://0.0.0.0:3000 [INFO] AppURL: http://localhost:3000/看到Listen这一行就说明服务起来了。打开浏览器访问http://localhost:3000你会看到安装向导页面。但先别急着点我们先把配置文件搞明白。3.2 app.ini 关键参数逐条解读第一次运行gitea web之后程序会在D:\gitea\custom\conf\下自动生成一个app.ini。这个文件是 Gitea 的大脑所有行为都由它控制。格式化一下之后我挑几个真正需要关注的说。[server]段落[server] PROTOCOL http DOMAIN 192.168.1.100 HTTP_PORT 3000 ROOT_URL http://192.168.1.100:3000/ DISABLE_SSH false SSH_PORT 2222 SSH_LISTEN_PORT 2222 LFS_START_SERVER true OFFLINE_MODE true APP_DATA_PATH D:/gitea/dataDOMAIN和ROOT_URL这两项是最容易配错、配错之后症状最诡异的地方。DOMAIN要填局域网里其他机器能访问到的地址比如这台机器的内网 IP192.168.1.100。如果你填的是localhost那么别人从自己电脑打开页面时网页里生成的克隆地址会变成http://localhost:3000/xxx.git而那个 localhost 指向的是他自己的机器永远克隆不下来。SSH_PORT填 2222 是我强烈推荐的。Windows 10 和 Windows 11 默认可能已经安装了 OpenSSH Server占用了 22 端口。如果你让 Gitea 也用 22结果就是内置的 SSH 服务起不来日志里会说bind: address already in use。改成 2222 之后两边互不干扰克隆的时候写ssh://git192.168.1.100:2222/user/repo.git就行。LFS_START_SERVER建议开成 true用来支持大文件存储。哪天你的项目里要放设计稿、模型文件、数据集没有 LFS 的话 Git 仓库会迅速膨胀到几个 GB克隆一次要等半天。OFFLINE_MODE开成 true让 Gitea 不去外部拉取头像和字体资源。内网环境里这个必须开否则页面加载会卡在几个外链请求上转圈。[database]段落以 SQLite 为例[database] DB_TYPE sqlite3 PATH D:/gitea/data/gitea.db路径里的斜杠用正斜杠/最稳反斜杠在某些配置解析场景下会被当成转义字符导致路径识别错误。这是很多人配完发现数据跑到了奇怪地方的原因。[repository]段落[repository] ROOT D:/gitea/repositories这个路径决定了所有 Git 仓库的物理存放位置。注意这是仓库的裸库目录你去里面看会看到一堆以.git结尾的文件夹每个对应一个仓库。不要手动去改这里的文件所有操作都通过 Gitea 的界面或者 Git 命令完成直接改文件会让元数据不一致。[service]和[log]段落[service] DISABLE_REGISTRATION true REGISTER_EMAIL_CONFIRM false ENABLE_NOTIFY_MAIL false [log] MODE file LEVEL Info ROOT_PATH D:/gitea/logDISABLE_REGISTRATION true这一条只要你的实例是给特定团队用的就应该打开。默认情况下任何人都能访问你的首页注册账号如果你把服务暴露到公网又没关注册很快就会有一堆机器人账号注册进来。关掉之后新用户只能由管理员在后台手动创建。[log]的LEVEL平时设成Info就够了排查疑难问题的时候临时改成Trace能打出非常详细的 SQL 和 HTTP 请求日志。Trace模式日志量巨大一天能涨到几百 MB排查完记得改回来。提示改完app.ini必须重启 Gitea 才生效。Gitea 不会热加载配置文件这一点和 Nginx 那种reload不一样别指望改完自动生效。3.3 把 Gitea 注册成 Windows 服务前面用gitea web跑起来的方式一旦你关掉那个命令行窗口服务就停了。这不是一个可以长期运行的方式。要让它开机自启、后台常驻需要注册成 Windows 服务。Windows 上做这件事我更倾向用 NSSM 这个小工具原因是 Gitea 需要一个工作目录而 Windows 自带的sc create命令没有直接指定工作目录的参数处理起来比较别扭。NSSM 可以可视化地设置工作目录、启动参数、日志重定向对新手友好得多。装好 NSSM 之后在命令行执行nssm install Gitea会弹出一个图形窗口三处关键填写PathD:\gitea\gitea.exeStartup directoryD:\giteaArgumentsweb --config D:\gitea\custom\conf\app.ini切到 I/O 标签页把 Stdout 和 Stderr 都重定向到D:\gitea\log\service.log这样即使 Gitea 在初始化阶段就崩了、还没开始写自己的日志文件你也能从 service.log 里看到错误信息。这一步是我踩过坑之后加的Gitea 偶尔会在读配置阶段就失败退出这时候它自己的日志文件是空的只有进程级日志才有线索。填完之后点安装然后用命令启动nssm start Gitea验证服务状态nssm status Gitea SERVICE_RUNNING如果你想用系统自带的sc命令也不是不行只是引号处理要注意sc create Gitea binPath \D:\gitea\gitea.exe\ web --config \D:\gitea\custom\conf\app.ini\ start auto sc description Gitea Gitea Git Service sc start Gitea注意binPath后面必须有一个空格这是sc命令的一个古怪语法要求漏了空格会直接报参数错误。这也是我更推荐 NSSM 的原因之一。服务跑起来之后还有最后一步放行防火墙端口。netsh advfirewall firewall add rule nameGitea HTTP dirin actionallow protocolTCP localport3000 netsh advfirewall firewall add rule nameGitea SSH dirin actionallow protocolTCP localport2222不加这两条规则本机访问一切正常局域网里其他机器就是连不上很多人会在这上面怀疑人生很久以为服务没起来其实是被防火墙默默丢包了。4. 初始化向导与账号安全设置4.1 安装向导每一项该怎么填服务跑起来、防火墙放行之后打开浏览器访问http://你的内网IP:3000就进入安装向导了。如果你已经把app.ini里的数据库和路径配好了向导页面上大部分字段会自动填好你只需要确认几项。数据库设置部分如果你用的是 SQLite直接把DB_TYPE选成 SQLite3路径填绝对路径。如果用 MySQL就填主机127.0.0.1:3306、用户名gitea、密码、数据库名gitea。这里有个坑主机名写localhost在某些环境下会走 socket 连接而不是 TCP在 Windows 上可能直接失败建议统一写127.0.0.1:3306。应用基本设置部分最关键的是这三项仓库根目录确认是D:\gitea\repositoriesGit 用户保持默认的git管理员账号这是第一个管理员用户名建议用admin或者你自己的名字密码一定要强管理员账号密码这里我要多说两句。Gitea 默认不限制密码复杂度你可以设成123456它也不会拦你。但如果你打算把这个实例暴露到公网哪怕只是通过端口映射弱密码意味着别人可以直接拿走你所有源码。建议用密码管理器生成一个 16 位以上的随机串存起来日常登录靠浏览器记住。可选设置部分邮件配置如果内网没有 SMTP 服务直接跳过不影响使用只是收不到通知邮件而已。开启禁止用户自助注册这一项跟前面app.ini里的DISABLE_REGISTRATION是同一个开关两边保持一致就行。点下立即安装之后Gitea 会执行数据库迁移创建所有表结构然后在repositories目录下初始化一些系统仓库。这个过程在 SQLite 上大概两三秒MySQL 上稍慢一点。看到登录页面就说明成了。5. 日常使用从建仓到 SSH 免密推送5.1 创建第一个仓库并完成首次推送登录进去之后点右上角的加号创建仓库。填仓库名、描述、选公开还是私有勾选初始化仓库的话会自动生成一个 README 和.gitignore。这一步跟别的托管平台没区别没什么好说的。真正值得讲的是推送时的路径选择。仓库创建完之后页面上会给出两个克隆地址一个 HTTPS 的一个 SSH 的http://192.168.1.100:3000/admin/demo.git ssh://git192.168.1.100:2222/admin/demo.git这里有个新手极容易踩的坑Gitea 页面默认显示的 SSH 地址通常是git192.168.1.100:admin/demo.git这种简写形式端口是隐含的 22。但我们的 SSH 端口改成了 2222所以必须用带ssh://前缀的完整写法端口才能正确带上。如果你直接复制简写形式Git 会去连 22 端口然后卡在那里直到超时。这个小细节能让你少困惑半小时。HTTPS 方式的首次推送会要求输入用户名和密码注意这里的密码不是你的登录密码而是需要在设置 → 应用 → 管理访问令牌里生成一个 Token用 Token 当密码。这是为了防止你把主密码泄露到命令行历史或配置文件里。5.2 SSH 密钥配置一次配好长期省事用 HTTPS 每次推送都要输 Token久了很烦。SSH 方式配好之后推送拉取完全无感。先在本地生成密钥对如果还没有的话ssh-keygen -t ed25519 -C your_emailexample.com一路回车默认存在C:\Users\你的用户名\.ssh\id_ed25519。这里我推荐用ed25519而不是老的rsa密钥更短、安全性更好、握手更快。然后把公钥内容id_ed25519.pub那个文件里的全部文本复制出来粘贴到 Gitea 里设置 → SSH/GPG 密钥 → 增加密钥。最后一步在本地配置 SSH 的端口。因为 Gitea 的 SSH 端口不是默认的 22你需要在C:\Users\你的用户名\.ssh\config文件里加一段Host gitea HostName 192.168.1.100 Port 2222 User git IdentityFile ~/.ssh/id_ed25519配好之后你克隆的时候可以直接写git clone gitea:admin/demo.gitGit 会自动去读这个配置把 hostname、端口、用户、密钥全都补上。这个技巧在任何非标准 SSH 端口的 Git 服务上都通用用熟了之后效率提升非常明显。验证连接ssh -T gitea Hi there, admin! Youve successfully authenticated...看到这句话就成了。如果报Permission denied (publickey)按顺序排查三件事公钥有没有粘贴完整首尾不能有换行或空格、config文件里的 Port 写对没有、私钥文件权限是不是过宽。5.3 团队协作中的权限与工作流设置仓库建好之后如果是多人协作需要把成员加进来。Gitea 的仓库权限分几档只读、写入、管理、所有者。日常加人给写入就够了能推代码、能开 Issue、能发 PR但改不了仓库设置。组织Organization这个功能很值得用。你可以按项目组或者部门建组织然后在组织下面建仓库成员按团队授权。这样新来一个同事把他加进组织所有仓库的权限一次到位比一个个仓库去加人省事太多。分支保护规则是另一个必须配的东西。进仓库设置 → 分支保护把main或者master保护起来勾上禁止直接推送和合并前必须通过 Pull Request。配完之后任何人包括你自己都不能直接往主分支推代码只能走 PR 流程。这个规则在团队里能挡掉大量的低级事故——比如某人手一抖把没测过的代码直接推到主分支导致所有人都拉到了坏代码。还有一个跟 Windows 环境特别相关的问题换行符的统一。建议在仓库根目录放一个.gitattributes文件* textauto *.sh text eollf *.bat text eolcrlf *.png binary *.jpg binary* textauto让 Git 自动判断文本文件并做规范化*.sh强制用 LF因为 shell 脚本在 Linux 上执行时如果有 CRLF 会直接报错*.bat保持 CRLFWindows 批处理必须二进制文件明确标记不转换。这一份文件放进仓库跨平台团队里的换行符问题基本就绝迹了。6. 反向代理与 HTTPS让地址干净起来6.1 为什么建议加一层反向代理直接用http://192.168.1.100:3000访问能跑但有几个不体面的地方端口号难看没法用域名而且明文传输密码和 Token。如果你有内网域名解析比如想让同事访问git.company.local而不是一串 IP 加端口就需要反向代理。Windows 上做反向代理最省事的是 Caddy它的配置文件短到离谱git.company.local { reverse_proxy 127.0.0.1:3000 }Caddy 会自动申请和续期证书如果是内网域名没有公网 DNS它会用本地自签证书浏览器会提示不安全但连接是加密的。如果你想要更正式一点用 Nginx for Windows 也可以server { listen 80; server_name git.company.local; client_max_body_size 512m; 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; } }client_max_body_size这一项必须调大默认的 1MB 会导致大仓库推送时返回 413 错误。调到 512MB 之后一般的项目都够用了。加了代理之后记得回头改app.ini[server] ROOT_URL http://git.company.local/不改的话网页上的克隆地址还是带 3000 端口的旧地址同事照着复制一样连不上。6.2 代理场景下必须知道的两个坑第一个坑是真实 IP 丢失。加了代理之后Gitea 看到的访问来源全都是127.0.0.1因为请求是代理转发的。这会导致安全日志、登录失败记录、审计功能全部失效——你根本看不出是谁在什么时候从哪个 IP 登录的。解决办法是在app.ini里告诉 Gitea 信任代理传来的头部[server] REVERSE_PROXY_TRUSTED_PROXIES 127.0.0.1配好之后Gitea 会从X-Forwarded-For里取真实 IP。这个在排查谁一直在尝试暴力登录的时候特别有用。第二个坑是WebSocket 断连。Gitea 的页面有一些实时更新功能比如通知红点、任务进度这些走 WebSocket。Nginx 做代理时如果没开 HTTP/1.1 和 Upgrade 头部透传这些功能会静默失效——页面不报错就是数据永远不刷新。在location里补上proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;这类问题最折磨人因为它不报错你只会觉得这功能好像有点迟钝很难联想到代理配置上。7. 常见故障排查与长期运维经验7.1 启动类问题的排查顺序表Gitea 跑不起来的时候别慌按下面的顺序一项项排基本能覆盖九成的情况。症状大概率原因排查动作命令行闪退看不到任何输出配置路径错误用gitea web --config 完整路径手动指定配置端口已被占用3000 或 22 被别的程序占了netstat -ano | findstr :3000查进程 PID网页能开但样式全丢OFFLINE_MODE没开改成 true 后重启局域网访问不了防火墙未放行netsh加规则或用高级防火墙界面数据库连接失败认证插件不兼容改成mysql_native_password日志文件是空的启动阶段就失败了检查服务重定向的 stdout 日志网页 502反向代理指向了错误的端口确认 proxy_pass 的端口和HTTP_PORT一致命令行闪退这个问题在 Windows 上特别常见本质是进程启动了但立刻因为错误退出而错误信息在你还没看清之前窗口就关了。解决办法是不要双击 exe而是在命令行里执行或者在批处理文件末尾加一句pause让窗口停住。7.2 备份唯一真正重要的运维动作我把这句话放在这里没做备份的 Git 服务等于没搭。硬盘会坏、误删会发生、升级会出意外唯一能救你的就是备份。Gitea 自带一个备份命令这是官方提供的最省心的方式cd /d D:\gitea gitea dump -c D:\gitea\custom\conf\app.ini -f D:\gitea\backup\gitea-dump-%date%.zip这个命令会把数据库、所有仓库、附件、配置、日志打包成一个 zip。注意它默认不带 LFS 文件如果你用了 LFS要加--include-lfs参数。备份策略我建议分两层。数据库层每天备一次用 Windows 的任务计划程序建一个每日任务跑gitea dump输出到一个带日期的目录保留最近 30 天。文件层每周全量备一次直接把整个D:\gitea目录复制到另一块硬盘或者网络存储上。两层的区别在于dump 出来的包便于整机恢复目录复制便于捞回某个误删的文件。注意gitea dump在导出 MySQL 数据的时候会调用mysqldump如果这个命令不在 PATH 里备份会失败但可能只是打一行警告容易被忽略。备份任务跑完一定要去确认文件大小正常几百 KB 的备份包基本可以判定是失败的。7.3 升级三步操作但别跳大版本Gitea 的升级在 Windows 上其实很简单因为不需要编译、不需要跑一堆迁移脚本。流程就是停服务nssm stop Gitea备份先跑一次gitea dump确认备份包没问题替换 exe把新的gitea.exe覆盖旧的然后nssm start Gitea启动的时候 Gitea 会自动检测数据库版本并执行迁移你会在日志里看到一串[INFO] Migration:开头的输出。迁移完成后页面正常打开就升级成功了。有几个经验必须说。**第一不要跨太多版本升级。**比如从 1.19 直接跳到 1.22中间可能涉及数据结构的大改动迁移脚本执行顺序出问题的话数据库会进入一个半迁移的中间状态非常难修。稳妥的做法是每次只升一到两个小版本升完验证几天再继续。**第二升级前一定要看清版本说明里的破坏性变更。**Gitea 的 Release Notes 里会有专门的 Breaking Changes 段落比如某些配置项改名了、某个默认值变了、某个 API 废弃了。这些不看你就会在升级后遇到服务起不来、某个功能突然失效的问题。**第三app.ini是跨版本保留的。**升级的时候千万不要用新版本的默认配置覆盖旧配置那样你所有的自定义参数都会丢。Gitea 在启动时会自动往app.ini里补上新增的默认配置项你不需要手动加。反过来说如果你发现有新的配置项那说明这个版本引入了新功能可以去了解一下。7.4 我在实际使用中攒下的几条心得服务跑久了会积累一些只可意会的经验我挑几条写在最后。**日志目录要定期清理。**如果把日志级别开到Info并且不轮转半年下来log目录能涨到几个 GB尤其是被扫描器扫过的时候失败登录日志会刷得飞快。建议在[log]里加上MAX_DAYS 30让 Gitea 自动清理老日志。**别把 Gitea 和 MySQL 装在同一块老机械硬盘上。**这两者都是随机读写比较频繁的服务机械盘上同时跑页面响应会明显发涩。如果条件允许仓库数据和数据库文件放在 SSD 上体验差别很大。**给管理员账号开二次验证。**Gitea 支持 TOTP配好之后每次登录要输一个动态码。管理员权限能改所有仓库、能删所有数据这个账号被人拿到等于整个实例沦陷。开二次验证的成本是每次登录多输六位数字收益是不用再担心密码泄露。**定期看一眼任务管理器里的资源占用曲线。**Gitea 正常运行时内存占用应该是稳定的如果发现内存持续缓慢上涨、几天不重启就能翻一倍那可能是某个仓库太大或者有异常请求在堆积。这种慢性问题不会立刻出事但会在某个时刻突然变成服务不可用。**内网部署也别关掉审计。**有时候会出现仓库莫名其妙多了一个分支、某个 tag 不见了的情况如果没有日志记录谁在什么时候做了什么操作你只能靠猜。Gitea 的审计日志在管理员后台可以查到记得留着。说到底自建 Gitea 这件事的价值不在于省了多少钱而在于你对代码资产的完全掌控——数据在你自己的硬盘上备份策略你自己定迁移升级你说了算。Windows 平台跑这套东西门槛比很多人想象的低得多二十分钟就能跑起来剩下的时间都花在用熟它上面。
