跳到主内容

Gitea 部署的 3 个必改参数,改错一个就白跑:单文件实测从 122MB 到 0.39 秒备份

凌晨的 Windows 测试机上,一个 122 MB 的 exe、一份手写的 app.ini、一次被文件锁挡住的备份——这是我把 Gitea 28.3.0 装起来又做成半自动流水线的一晚。先给结论:Gitea 单文件部署本身只要三步,真正让你白跑的是三个配置参数和一处备份锁,改对之后,备份命令 0.39 秒跑完,重启探活、API 建仓都能交给脚本。这篇文章把手工流程、每步耗时、哪些能自动化、哪些不能、失败长什么样,全部按实测拆给你看。

Gitea 是一个用 Go 写的自托管 Git 服务,仓库在 github.com/go-gitea/gitea,MIT 协议,GitHub API 实测 59,007 星、7,385 fork(2026-11-10)。它把 Git 托管、代码评审、issue、包仓库和 Actions CI 塞进一个二进制。注意版本号:1.27 之后官方把「1.」前缀去掉了,1.27.3 下一版直接叫 28.0.0,我这次装的是 28.3.0——2026 年 11 月 1 日发布的 28 系列第三个维护版,官方博客一口气列了 8 个 CVE 修复,其中 5 个和 token 权限范围有关,所以别拿旧版凑合,装就装 28.3.0。

先看清手工流程长什么样

动手之前,先把要做的动作列全。在 Windows 上不碰 Docker 的手工流程是六步:下载二进制、校验哈希、解压、建目录写 app.ini、启动服务、验证页面和 API。听着简单,我第一次走完花了四十多分钟——主要时间耗在两个地方:下载,和第一次启动后的等待。

先挑文件。官方下载页 dl.gitea.com/gitea/28.3.0/ 下面,同一个版本给你两个大文件:gitea-28.3.0-windows-amd64.exe,122,948,608 字节;gitea-28.3.0-windows-amd64.exe.xz,42,581,040 字节。压缩版只有原版的三分之一,但解压它需要 xz 工具。Git Bash 里没有 xz 命令,我第一反应是用 tar 解——Windows 自带的 tar 能认 xz 包,但提取到一半给了我一个 0 字节的文件,静默失败,没有任何报错。最后是用 Python 内置的 lzma 模块解开的,一次成功。这一步的教训先记下:别假设环境里有解压工具,选 exe 还是 exe.xz,取决于你手上有没有靠谱的解压手段。

再核哈希。每个文件旁边都有对应的 .sha256 文件。我下载的 exe.xz 算出来是 0e8ec8c6ca826c6e1e3875214061653b3fdb620b227d8550dd36865a08b31b79,和官方 sha256 文件一字不差;解压出的 exe 也对上了 4003c068ef0a7d8145ef8c85b8aab052bf1bbf9226f2d0058572f013e096ee06。两道校验花不了一分钟,跳过它等于把供应链安全交给运气。另外从 1.27 起官方还用 sigstore 签名所有二进制,有 cosign 环境的可以做第三道验证,命令在官方文档 installation/install-from-binary 页面里写得很全。

环境依赖只有一条硬的:Git。Gitea 自己不做版本控制,所有仓库操作都调本机 Git,官方文档写的要求是 Git 2.0 以上。但这里有个口径打架的地方,后面第五节细说。验证动作很简单:装完先跑 gitea.exe --version,我机器上输出「gitea version 28.3.0 built with go1.27.3」——这个 go1.27.3 不是巧合,官方博客说 28.3.0 就是因为 Go 1.27.3 不再信任某批中间证书而紧急发的。

做完这一步的验收标准:手里有一个哈希核对过的二进制,版本号输出 28.3.0,本机 git --version 不低于 2.0。三个都满足再往下走,任何一个不满足,后面全是空中楼阁。

还有两个二进制选型的边角料,顺手记在这里。官方文档提到一个 gogit-windows 变体,是专为部分 Windows 老系统上的性能问题出的(对应 PR #15482),官方原话是遇到性能问题再考虑换它——我的测试机上标准版没有出现性能异常,就不引入额外变量了。另外 126 个 release 资产里还有 darwin、freebsd、386、arm64 等一堆平台组合,下载脚本别写死 amd64,把平台后缀也做成变量,这样同一套脚本换台机器还能用。

把流程拆开,每一步记下耗时

自动化之前先量时长,不然你不知道脚本到底帮你省了什么。下面是我 2026-11-11 凌晨实测的数字,机器是一台普通 Windows 云主机,网络走国内直连。

步骤用的命令/动作实测耗时产出
下载 exe.xzcurl 从 dl.gitea.com 下载约 124 秒(实测约 344 KB/s)42,581,040 字节压缩包
哈希校验sha256sum 对照官方 .sha256约 3 秒哈希一致
解压Python lzma(Git Bash 无 xz,tar 静默失败)约 20 秒122,948,608 字节 exe
写 app.ini手工写入 custom/conf/app.ini约 5 分钟(第一次)配置文件
启动服务gitea.exe web启动命令秒回,服务就绪约 20 秒127.0.0.1:3300 可访问
验证curl 探活 + API 查版本约 10 秒{"version":"28.3.0"}

两个数字值得多说一句。下载速度 344 KB/s 是 dl.gitea.com 的直连实测——注意,GitHub 的 releases 下载在这台机器上是超时的(此前实测过多次 400 秒拿不到 50 MB 级文件),但 dl.gitea.com 反而顺畅。同一个项目、同一份文件,两个下载源速度差出一个数量级,这就是为什么脚本里要把下载源写成参数而不是写死。第二是启动时间:启动命令本身立刻返回,但第一次探测(12 秒时)拿到的是连接失败,到约 20 秒后 200 才稳定。原因写在启动日志里:Gitea 启动时会扫一遍本机 Git 版本、初始化存储层,我日志里能看到「Git version: 2.55.0」被识别,然后才开始监听端口。你的探活脚本如果只试一次就放弃,会误报启动失败。

对比一下其他开源服务的部署节奏,这条流水线不算慢:站内那篇 memos 部署搭建教程记录的是一条 docker 命令起步、重点在数据落盘;开源监控告警系统搭建:HertzBeat 从一条命令到生产部署拆的是从能跑到能上线的距离;而 Spring Boot 加 Vue3 的 mall 开发环境那种前后端分离项目,光环境搭建就能吃掉一个下午。Gitea 单文件的部署面明显短,短的原因是没有依赖树——代价是所有环境决策都压在那份 app.ini 上。

验收标准:把上面这张表里的每一列都填上你自己的数字。填不出来,说明你还没有资格谈自动化。

分清哪些步骤能自动、哪些必须人来

不是所有步骤都值得脚本化。判断标准只有一条:步骤的输入是不是确定的。输入确定的步骤——下载、校验、解压、启动、探活、建仓——全部能自动;输入含决策的步骤,脚本化只会把决策藏进脚本里,出问题更难查。

第一次启动前必须人来定的东西,就是配置文件里那三个安全参数。官方文档写得很明确:如果你不想让安装向导写配置,就要手工设 INSTALL_LOCK = true,并保证 SECRET_KEY 和 INTERNAL_TOKEN 已经设置好——这三个少一个,要么装到一半卡住,要么服务起不来。我实测就是这么过的:预先写好 app.ini,把 INSTALL_LOCK 置 true,启动后直接进系统,没有走过安装向导。

参数作用不设/设错会怎样
INSTALL_LOCK锁定安装向导,防止部署后配置被网页端改写false 时任何能访问页面的人都能重写你的数据库配置,等于把后台开放给全网
SECRET_KEY会话与加密相关的根密钥,官方提供 gitea generate secret 生成缺失时服务可能拒绝启动;沿用示例值等于没有密钥
INTERNAL_TOKEN服务内部组件互信的令牌缺失或不合法时部分内部调用失败,日志里表现成莫名 500
HTTP_PORT监听端口,默认 3000被占用时启动日志报 bind: address already in use,官方文档给的修法是 web -p 换端口
DISABLE_SSH关闭内置 SSH 通道不关且环境没有 SSH 服务时,克隆提示里的 SSH 地址全是摆设
RUN_MODE运行模式,prod 为生产设成 dev 时日志冗长、部分行为按开发路径走,带慢跑不必要开销
ROOT仓库根目录,所有裸仓库落在这里写错路径时新建仓库看似成功、文件落在意料之外的位置,迁移时找不到数据

除了这三件必答题,还有一类「决策型步骤」容易被低估:数据库选型。SQLite 内置、零配置,单人和小团队够用;MySQL、PostgreSQL 要自己准备实例。站内讲开源后台系统自测的那篇自测法写过一条规律:体积越大、依赖越多,环境搭建这一步就越容易把人卡住。Gitea 好就好在默认路径没有依赖树,你要主动选择引入依赖,而不是被迫接受它们。

数据库之外的另一个决策点是路径规划。官方文档推荐的结构是 custom、data、log 三个目录加一个 app.ini,Linux 上还配了权限(/var/lib/gitea 750、/etc/gitea 640)。Windows 上没有这套权限语义,但目录分离还是要照做——因为备份命令和升级流程都按这个结构找文件,你把配置和数据混放,后面 dump 出来的包就说不清哪部分能删。

给你留一个五分钟自测法,验证 app.ini 写没写对。第一问:访问 /api/v1/version 返回的是不是你的目标版本号?返回报错说明服务没起来或端口不对。第二问:访问 /api/healthz 里 database:ping 是不是 pass?不是 pass 说明数据库段落写错。第三问:新建一个测试仓库后,仓库根目录(ROOT 指向的位置)下有没有出现同名裸目录?没有出现说明 ROOT 配错了,文件落在了别处。三问全过,配置这一关才算真过,不然每一条都会在备份或迁移时变成一颗雷。

验收标准:列一张两栏清单,左边写「脚本可接管」,右边写「必须人拍板」。右栏里凡是还能再拆的,拆到底层确定性输入后挪到左边;挪不动的,就是你要长期守着的地方。

把三个参数和探活写成自动化节点

决策做完,剩下的就是把这些动作串成节点。这一节给四个能直接搬的节点实现,每个都实测过。

节点一:下载与校验。一个脚本三行:curl 拉文件、curl 拉 .sha256、sha256sum -c 比对。关键点是把版本号和下载源做成变量。我在两次下载里观察到真实差异:第一次在 100 秒超时点拿到 34.4 MB(约 344 KB/s),第二次用同样命令 150 秒内完整拿到 42,581,040 字节——同源不同时刻速度也在漂,所以校验哈希不是仪式,是必需。顺带一提,中断续传在这台机器上没走通:服务器对 Range 请求直接回了 200 全量重发,脚本要按「下载可能整包重来」来设计超时。

节点二:启动与探活。不要用「sleep 30 然后访问首页」这种写死时间的探活,用带重试循环的探健康检查接口。Gitea 提供 /api/healthz,我重启后第一次探测就拿到了 200,返回体里是三个 pass:

{"status":"pass","checks":{"database:ping":[{"status":"pass"}],"cache:ping":[{"status":"pass"}]}}

这个接口比访问首页强在它验的是数据库连通和缓存连通,首页 200 只能说明 HTTP 层活着。探活循环设五次、间隔五秒,覆盖我实测的约 20 秒启动窗口。

节点三:建仓与验证。管理员建好之后,建仓走 API:curl -u tester:密码 -X POST /api/v1/user/repos -d '{"name":"demo","auto_init":true}'。实测整条命令 3.888 秒返回,仓库默认分支是 main,auto_init 生效。这一步同时验证了三件事:API 通了、管理员账号有效、Git 初始化在服务端能跑——因为 auto_init 要真正执行一次 git init 加首次提交。以后所有自动化流程都可以拿「能否 API 建仓并默认分支为 main」当冒烟测试。

节点四:备份与升级。备份命令是 gitea dump,升级按官方文档是「停服务、换二进制、重启」三步,文档特别强调升级时不要改二进制文件名,原因第五节的报错会解释。备份节点有一个 Windows 特有的坑,也是整条流水线里我唯一没绕过去的约束,放到下一节单独讲。

验收标准:四个节点各自有一条幂等性验证——同一脚本连续跑两遍,第二遍不报错、不产生脏数据。跑不出幂等,说明节点里混着状态依赖。

给异常和失败留好人工兜底

只讲顺利跑通的自动化不可信。这一节是我这次部署里三个真实失败,每个都附报错原文和当时的排查路径。

失败一:dump 的 -t 参数目录必须预先存在。我第一次跑 gitea.exe dump --skip-repository -f backup-test.zip -t /tmp/gitea-run/tmpdump,0.278 秒后直接 fatal,报错原文是「Path does not exist: C:/Users/CLOUD_~1/AppData/Local/Temp/gitea-run/tmpdump」。注意两个细节:第一,-t 指定的临时目录要自己先建,工具不会代劳;第二,Git Bash 把 /tmp 路径自动换算成了 Windows 8.3 短路径(CLOUD_~1),日志里那段短路径容易让人以为自己传错了地方。mkdir 之后重跑,报错消失。

失败二:服务运行中备份,被文件锁挡死。这是我踩得最深的一坑。我以为 dump 是只读操作,可以热备,结果 0.313 秒后 fatal:「Failed to include data directory: writing file 23: LOCK: open ...data\queues\common\LOCK: The process cannot access the file because it is being used by another process.」。运行中的 Gitea 在 Windows 上握着队列目录的锁文件,dump 打包数据目录时直接撞上。结论要写进脚本注释里:Windows 上 dump 前必须先停服务。Linux 上官方文档同样推荐停机备份,只是文件锁的表现形式不同。停服之后实测完整 dump(含仓库、数据库、配置、data 目录)只用了 0.389 秒,产出 51,679 字节的 zip——空库当然小,但速度说明备份的成本瓶颈不在 dump 本身,而在「要不要停服」这个决策。

失败三:探活太早,误判启动失败。前面提过:12 秒时 curl 拿到 000,20 秒后 200。第一次遇到时我以为是配置错了,回头翻启动日志才发现一切正常,只是初始化还没完成。这类「慢而不是死」的失败,兜底方式就是探活循环,不是重装。

还有一个跨来源矛盾要处理:Git 版本要求。官方安装文档写「Git 2.0 以上」,但 ComputingForGeeks 2026 年 11 月的实测文章明确写「Git 2.25 minimum: older Git is refused at startup」(老 Git 启动时被拒)。两份来源打架时我的处理办法:以更接近实测的 2.25 为准做规划,以官方文档为准做引用,正文两处都写明出处。本机 Git 2.55.0 启动正常,不受影响。

验收标准:把每个报错原文抄进你的运维文档,旁边写两行——触发条件和处置动作。下次再见到同一条报错,你查文档的时间应该从十分钟降到十秒。

把跑起来之后的实际数据摊开

先交代数据口径:这套流水线我在本机连续跑了两天窗口,不是七天,所以这一节除了自己的数据,还引入一份别人跑了更久的实测做对照。

我自己的数据:两次完整部署(下载、校验、解压、配置、启动),三次启动到探活通过(每次 15 到 20 秒),三次备份尝试(两次失败一次成功),一次停服重启后仓库数据完好(API 查回 tester/demo,默认分支 main 未变),healthz 每次都返回 database:ping 和 cache:ping 双 pass。

对照数据来自 ComputingForGeeks 同月发表的 Ubuntu 26.04 实测,他们测的是 1.25.5 升级到 28.3.0:迁移执行了 35 次、systemctl start 后 8 秒端口就绪、二进制从 114.3 MB 涨到 119.9 MB、空载常驻内存从 174 MiB 涨到 199 MiB。这些数字和我 Windows 上的单文件路径互相印证了一件事:Gitea 的资源占用在小规模场景下非常轻,官方口径「2 核 1 GB 内存够小团队用」没有夸大。

那篇文章还有两个值得抄走的发现:一是 gitea doctor 默认检查项为 0——命令打印 All done (checks: 0) 看着像全过,实际一项都没查,要 --all 才跑 13 项;二是全新安装和升级安装的自注册口径不同,新装默认关注册、升级装沿用旧配置。这类「静默差异」是最容易在自动化里埋雷的,因为脚本看起来都执行成功了。

规模不同,流水线的取舍也不同,我把三种规模对应的参数和代价列成表:

规模关键参数/组件代价与注意点
单人/练手SQLite + 单文件 + 本机 cron 式定时备份零依赖起步;备份要停服,停机窗口自己扛;迁移到 MySQL 时数据要重新导
中小团队MySQL/PostgreSQL + 反向代理 + systemd/NSSM 托管数据库要有独立备份链路;28 系列的 WebSocket 通知(/-/ws)要求反代转发 Upgrade 头,不转发则退化为轮询
规模化加 Gitea Actions Runner、对象存储放 LFS 与制品注意 [actions] RUN_RETENTION_DAYS 默认 400 天,到期制品夜间任务清理;28 系列出站流量(迁移、镜像、webhook)走内部代理,EGRESS_MODE 默认 lax,私有目标要显式加白名单

验收标准:你的规模对应哪一行,参数都设了、代价都写进文档了,这一节才算读完。

补一句数据该怎么用:我的两天窗口数据只能证明「流水线在当前规模下成立」,ComputingForGeeks 的升级数据补的是「跨版本迁移长什么样」,两份合起来覆盖部署和升级两个场景。你抄这套流水线时,第一周的每一天都该记一行自己的数——启动耗时、备份体积、失败次数——第二周开始拿自己的基线对比异常,而不是拿别人的数字硬套。

算清楚这套流水线省下来的时间

自动化值不值,算账就知道了。手工全流程按第二节那张表合计:下载约 124 秒、校验 3 秒、解压 20 秒、配置 5 分钟、启动加验证约 30 秒,第一次全套约 9 分钟——前提是你没踩坑。我第一次实际花了四十多分钟,多出来的三十多分钟全是失败一和失败二:tar 静默失败来回试、dump 撞锁重来。这就是手工流程的真实成本:不是步骤贵,是失败贵。

脚本化之后呢?重装一遍变成:脚本拉起,下载加校验加解压约两分半,配置文件是现成的(三个安全参数一次性人工决策),启动加探活约 20 秒,全流程 3 分钟以内,全程无人值守。省下的不是那 6 分钟,是每次重装时的注意力:你不用盯着进度条,不用记参数,不用怕漏了哈希校验。

备份这笔账更典型。没有流水线时,备份靠「想起来才做」,频率约等于心情;有流水线后,停服-备份-重启三段脚本可以定在业务低峰执行,每次 1 分钟以内(dump 本体 0.389 秒,大头是停服和等探活)。站内写 DataGear 升级到 6.1 那篇有句话说得很准:省掉的运维成本,最后都从数据目录里找回来。反过来说,现在花一小时把备份脚本写对,就是在给未来的数据目录还债。

但别把账算过头。有些环节脚本化收益是负的——比如数据库选型、EGRESS_MODE 这类一年改一次的决策,写进脚本不会更快,只会让半年后的你更难看懂当时为什么这么配。算账的口径是「每次执行省的分钟数 × 执行频率」,频率低的决策型步骤,留给人。

验收标准:给你自己的流水线写一行账:手工 X 分钟 × 每月 N 次,脚本 Y 分钟 × 每月 N 次。Y 乘出来不比 X 小一半,就先别自动化,先把失败率打下来。

标出这套流水线的脆弱点

最后泼一盆冷水。这条流水线有四个明确的脆弱点,都在我这次部署里显形过。

脆弱点一:Windows 文件锁决定备份必须停机。备份节点的前置条件是服务已停,这意味着你的停机窗口等于备份窗口加两次探活窗口,实际约 1 分钟。如果哪天数据目录涨到几十 GB,这个窗口会线性放大,流水线的「低峰停机」假设就崩了。缓解办法只有换备份粒度:数据库层备份(mysqldump 之类)可以热备,文件层的 dump 放慢频。

脆弱点二:下载源的网络路径。这台机器 GitHub releases 大文件下载超时、dl.gitea.com 却有 344 KB/s——反过来在别的网络环境可能完全倒置。脚本里下载源写成数组、逐个尝试加哈希校验兜底,才算把这条脆弱点关进笼子。

脆弱点三:升级改二进制名会让所有仓库的 hooks 失效。官方 troubleshooting 写得很直白:更新时如果改了二进制文件名,已有仓库的 Git hooks 还指着旧路径,push 时报「./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory」。修法是进管理后台跑一遍「Resynchronize pre-receive, update and post-receive hooks of all repositories」任务——注意它会覆盖包括自定义在内的所有 hooks。这个坑脚本防不住,只能靠纪律:二进制永远叫 gitea,不带版本号。

脆弱点四:引用的数字会漂。同一周内,ITHub 目录页记 Gitea 58,933 星(11-07 更新),GitHub API 实测 59,007 星(11-10)——四天差了 74。写文档引用这类数字必须带日期,否则三个月后你的报告和现实对不上。这个习惯比任何工具都便宜。

验收标准:给每个脆弱点写一句触发条件和一句缓解措施,贴在流水线脚本头部。做到这一步,这条流水线才算从「能跑」变成「敢托付」。

常见问题

Q1:没有公网服务器,能先在自己 Windows 电脑上练手吗?能,我这次就是全程 127.0.0.1 练的。单文件加 SQLite 在本地跑没有任何外部依赖,app.ini 里把 HTTP_ADDR 写成 127.0.0.1 就不会暴露到局域网。练手顺序照抄本文:下载校验解压、写配置、启动探活、API 建仓、停服备份。练完你会对三个安全参数和探活节奏有手感,这些手感搬到 Linux 上原样可用——除了文件锁那条,Windows 特有。

Q2:单文件二进制和 Docker 部署怎么选?本机没有 Docker 环境,容器路线我未实跑,只能按官方文档静态核对:官方镜像在 docker.gitea.com/gitea,compose 模板默认带 SQLite,文档特别提醒卷目录属主要和配置的 UID/GID 对齐,rootless 变体有单独指引。单文件路线的优势是路径透明、备份就是拷目录、升级就是换文件;容器的优势是隔离和回滚干净。我的判断口径:单机练手和低配 VPS 选单文件,已有容器运维体系的团队选容器,两条路的 app.ini 参数几乎通用,以后换路线迁移成本不大。

Q3:备份多久做一次,dump 和直接拷数据目录哪个对?频率看仓库活跃度:代码每天都在推的团队按天备,个人自用按周备即可。手段上两者不对立——dump 的价值是产出带数据库、配置、仓库的完整包,适合整站迁移和升级前快照(官方文档要求升级前先备份);直接拷 data 目录适合纯文件兜底,但要小心运行中拷贝撞上和 dump 一样的文件锁问题。我的组合是:升级前必做 dump,平时低频 dump、高频数据库备份。

Q4:老的 1.27 系列能直接换 28.3.0 的二进制吗?能换,但换完回不去。ComputingForGeeks 实测 1.25.5 升 28.3.0 执行了 35 次数据库迁移,作者特别标注:迁移后的数据库老版本二进制打不开,所以升级前必须备份,且升级是单行道。另外两点别忘了:二进制文件名别改成带版本号的样子(hooks 会失效),升级装会沿用旧配置里的自注册开关,装完检查一眼注册入口是开是关。

Q5:28.3.0 一次修了 8 个 CVE,跟我这种小自用有关系吗?有关系,而且关系最大的恰好是低配用户的场景。8 个 CVE 里 5 个是 token 权限范围(public-only token)没被严格执行:管理端 API 可以列全站邮箱、组织主的 token 能删私有仓库、归档仓库的 release 能被改写。自用场景常常「反正只有我一个管理员」就发了全权限 token,这正好是这批漏洞的命门。官方博客对此的原话是「We strongly recommend that all users upgrade as soon as possible」,我的做法是直接从 28.3.0 起步,一步到位。

Q6:探活为什么不直接访问首页?首页 200 只证明 HTTP 进程活着,不证明数据库和缓存连通。/api/healthz 返回的是逐项检查结果(我实测是 status pass 加 database:ping、cache:ping 两个子项),任何一项挂了你能从返回体直接定位到是哪层的问题,而不是看到一个 500 再去翻日志。探活脚本的写法也简单:五次循环、五秒间隔、任一次拿到 200 就算就绪,覆盖启动初期的慢初始化窗口。

相关阅读

分享到:

本文链接:https://www.biyeyuanma.cn/post/420.html

服务热线

加我微信

加我微信