关于我们

质量为本、客户为根、勇于拼搏、务实创新

< 返回新闻公共列表

自托管Forgejo别只备份数据库:仓库、LFS和Actions制品怎么分开算

来源:一万网络  发布时间:2026-11-19

自托管Forgejo别只备份数据库:仓库、LFS和Actions制品怎么分开算

迁移收尾时最常见的动作,是把数据库导出挂上定时任务,确认跑通,然后在运维清单里勾掉"完成"。这往往正是隐患的起点。Forgejo 把代码本体、大文件、附件和流水线产物分散在不同目录,数据库只是其中一处。真正决定灾难来临时能不能恢复的,是那些没被写进 cron 的文件夹。

自托管的吸引力,本就在于数据留在自己的体系里——源码主权、内部审计、数据出境的边界都由团队自己说了算。可一旦备份边界画错,这份掌控感会迅速变成负担:你手里有一份结构完整、却取不出任何文件的数据库。按一次推送的完整链路往下拆,数据到底落在几处,就清楚了。

一次 push 背后的完整数据链路

先看起步形态。公开资料口径下,Forgejo 单容器加一个数据库就能跑起来:Web 界面监听 3000 端口,容器内自带 SSH 服务占用 22 端口,/data 卷集中放仓库、配置、LFS 对象、附件与包。小团队用"几 GB 内存"的服务器即可起步,这也是它常被选来替代更重方案的原因。

一次 push 走的是两条可能的入口。走 SSH 时,Git 客户端连的是容器内的 SSH 服务;走 HTTPS 时,请求先到 Web 层再落到仓库。无论哪条路,最终被改写的都是 data/gitea-repositories/ 下的仓库对象——这是 DeepWiki 架构资料给出的默认目录口径。数据库这边同步记下元数据与权限,但它并不持有 Git 对象本身。

这里有个常被漏掉的验证点:Web 界面的 3000 端口和容器内 SSH 的 22 端口是两条独立入口,备份策略不必区分它们,但灾后恢复的连通性检查必须两条都走一遍。重建实例后只确认网页能打开、没测 clone 是否走得通,是演练里相当常见的一种遗漏。数据备回来了却推不上去、拉不下来,在业务方眼里和没备没有区别。

如果这次推送里夹带了超过常规大小的文件,LFS 指针会进仓库,真正的文件体却落在另一处 lfs/ 目录。同一条链路再往后,评审里的附件进 attachments/,流水线跑完的日志和产物分别进 actions_log/ 与 actions_artifacts/。一次看似简单的推送,数据其实被写进了好几个彼此独立的目录。

数据库里到底存了什么

先把数据库的角色讲清楚,后面才好谈"备份只备了数据库"错在哪。公开资料口径下,Forgejo 支持多种数据库:PostgreSQL 是生产推荐,MySQL/MariaDB 可选,SQLite3 是默认与开发用途,TiDB 因为兼容 MySQL 协议也可用;ORM 用的是 XORM。这些选项的差别不在"能不能存代码",而在承载关系型记录时的并发与恢复表现。

数据库里放的是结构化记录:用户与组织、仓库元数据、权限关系、各类配置,以及指向那些二进制对象的引用。附件、LFS 对象、包与制品都不在这里——它们按设计落在独立目录。于是"数据库导出成功"只能证明关系记录被保住了,证明不了 attachments/ 或 actions_artifacts/ 里的内容还在。这是把两者混为一谈时最容易踩的空档。

推演到恢复场景就更直观:假设只留了数据库快照,某天重建实例,用户能登录、仓库列表也在,但点开某个仓库会发现对象缺失,LFS 文件拉不下来,旧的流水线产物彻底找不到。这类损失不是"配置没调好",而是备份清单从一开始就漏了项。

Git 仓库本体:默认落在 data/gitea-repositories

仓库本体是代码主权的载体,也是备份清单里头一个该确认的项。DeepWiki 的架构资料把它定位在 data/gitea-repositories/,属于 /data 卷的一部分。备份脚本如果只盯着数据库文件,很自然地就会跳过这一层——因为它在宿主机上看起来只是某个挂载点下的普通目录。

这里的判断很直接:仓库目录必须作为独立备份项,频率要与代码提交节奏匹配。中型研发团队一天内的 push 次数并不少,只做周级甚至月级的整盘镜像,恢复时丢的是最近一段提交。更稳妥的做法是把仓库目录的同步做成常规任务,并明确它和数据库快照在时间轴上能否对齐——两者不同步,恢复出来的仓库也可能和数据库记录对不上。

LFS 大文件:最容易低估的增长项

LFS 是"分开算"这件事里最容易被低估的一环。仓库里留下的只是指针,真正的文件体在 lfs/ 目录,默认与仓库本体同处 /data 卷,但在逻辑上是独立子系统,app.ini 的 [lfs] 段可以单独指定它用 local 还是 S3/minio。也就是说,它可能和仓库在同一块盘上,也可能已经被指向远端对象存储——备份策略必须跟着实际配置走,不能凭印象。

占用特征上,LFS 往往比仓库本体涨得更快。设计稿、数据集、二进制依赖、构建好的中间件,都会往这里堆。公开资料口径提示我们把它当作独立容量项规划,而不是"仓库的一部分顺带备份"。推演到成本:若 LFS 与仓库混备,一次大版本资源更新就可能让备份体积翻倍,拖慢窗口、放大存储开销。

还要留意配置漂移。某个子系统从 local 改成 minio 之后,备份任务如果仍按旧路径去找文件,结果就是"任务成功、内容为空"。所以在调整 [lfs] 的 MINIO_USE_SSL、endpoint、bucket 一类参数时,备份清单要同步复核——这类事故在迁移后的头几周尤其常见。

存储放本地还是对象存储:这是先要做的决策

在动手写备份脚本之前,先要决定每类数据落在哪。app.ini 的 [storage] 段能统一改默认:local 用 PATH 指定绝对基础路径;minio 则配 endpoint、key、secret、bucket、location,外部 S3 还要设 MINIO_USE_SSL=true。也可以对单个子系统单独指定类型,不必一刀切。这个决策直接决定了后面"备份谁、怎么备"。

在挑托管底座时,把自有机房与外部基础设施摆在一起比是常见做法。一万网络这类服务商提供服务器租用、机柜托管与带宽接入,可作为把 Forgejo 落在自有体系之外时的一个对照项;但备份策略要不要一起交出去,仍得按源码主权与数据出境的要求单独判断,具体机型、带宽以官网实时或咨询确认为准。

判断的落点不在"哪个更便宜",而在"恢复路径是否可控"。本地目录的好处是取回直接、不依赖外部服务;对象存储的好处是扩展性,但它并不天然等于备份——是否具备版本保留与复制能力,取决于你实际用的服务,需要逐项确认,不能想当然。

附件、头像与包仓库:零散但各自独立

这几类数据单个体积不大,胜在数量多、路径散,最容易被"整盘备份"的思路带过去。公开资料口径给出的默认目录是:附件在 attachments/(对应 [attachment]),头像在 avatars/,仓库头像在 repo-avatars/,仓库归档在 repo-archive/,包仓库在 packages/。每一处都能在 app.ini 里单独配置存储类型。

风险在于它们常常不在同一份备份任务覆盖范围内。附件承载着 issue 与评审里的上下文,丢了你不会立刻发现,直到某天要追溯一个历史决定;包仓库丢的是团队发布过的制品,影响的是可复现性。把它们当"边角料"跳过,代价往往在几周后才显现。

仓库归档目录 repo-archive/ 也值得单独说一句。它是按需生成的导出内容,不少团队默认它"随时能重新导出"便不纳入备份,可导出动作依赖当前实例可用,而灾后重建恰恰没有这个前提。把它列进清单成本很低,漏掉的代价却是历史快照彻底消失。判断这类"看起来可再生"的数据时,可以用同一个问题自问:如果实例现在没了,我还能不能把它变出来?答案是否定的,就该备份。

建议是把这几处和 LFS、Actions 一起列进同一张清单,用"子系统—默认目录—占用特征—备份要求"的方式管起来。清单化的价值不在于写得多漂亮,而在于迁移、换盘、改配置时,能逐项打勾确认,而不是凭记忆说"应该都备到了"。

Actions 日志与制品:另一套目录

Actions 这块要分两层看。公开资料口径下,Forgejo Actions 的服务端只负责调度,runner 是独立程序,用 token 注册后拉取任务,通常在 Docker 容器里执行;工作流写法与 GitHub Actions 相似,但不保证直接兼容。这意味着流水线产物和跑服务的进程,在运维上本就是两件事。

落到存储,日志进 actions_log/,制品进 actions_artifacts/,两者都是独立目录,也都能单独指定 local 或 S3/minio。制品通常是体积增长最快的那类——镜像层、测试报告、打包产物会不断累积。它们不像仓库那样有"提交历史"的价值锚点,很容易被当成临时文件排除在备份之外。

但"临时"是个需要定义的词。如果团队的发布流程依赖某些历史制品做回滚,那它们就不再是临时的。可写判断是:先按合规与回滚需求定义保留范围,再决定备份频率;范围之外的制品可以定期清理,范围之内的必须进备份清单。别让"看起来是缓存"成为漏备的理由。

子系统存储清单

把上面散落的目录摊开,边界就一目了然:

子系统默认目录占用特征备份要求
数据库由所选数据库引擎决定(PostgreSQL 推荐)关系记录,体积增长平稳结构化导出快照,需与仓库目录对齐时间轴
Git 仓库本体data/gitea-repositories/随提交持续增长,代码主权载体独立常规备份,频率匹配提交节奏
LFS 大文件lfs/([lfs] 可单独配置)大文件堆积,常快于仓库本体按 local 或 S3 实际配置纳入,改配置同步复核
附件attachments/([attachment])零散但累积,承载评审上下文与仓库同清单管理,避免整盘备份时跳过
头像与仓库头像avatars/、repo-avatars/体积小的静态对象纳入清单即可,改路径时复核
仓库归档repo-archive/按需生成的归档文件按保留需要决定是否备份
包仓库packages/发布制品累积,影响可复现性按发布需求决定保留与备份
Actions 日志actions_log/文本日志持续增长定义保留期后清理或备份
Actions 制品actions_artifacts/增长最快的类别之一按回滚与合规需求定范围再备份
配置 app.ini/data 卷内关键但体积小单独留存,迁移时必核

app.ini 里怎么把子系统分别配置

配置层面,Forgejo 给了足够的粒度。[storage] 段负责统一默认:local 走 PATH 绝对路径,minio 走 endpoint、key、secret、bucket、location,外部 S3 记得 MINIO_USE_SSL=true。在此之上,单个子系统还能覆盖默认类型——比如 LFS 放对象存储、附件留在本地,这种混搭是允许的。

对备份来说,粒度既是便利也是陷阱。便利在于可以按重要性分级:核心仓库高频备份,头像类低频甚至只留配置。陷阱在于配置分散后,没有人能一眼看清"现在到底有几处在用远端"。所以每次改完 app.ini,最稳妥的动作是把 [storage] 与相关子系统段重新读一遍,更新那张清单,再动备份任务。

还有个细节值得说:MinIO 与外部 S3 在 SSL 开关上的差异。brief 口径明确外部 S3 要设 MINIO_USE_SSL=true;这类参数写错,表现为"服务正常但对象读写失败",往往到恢复时才暴露。把它列进变更检查项,比事后排查省事。

SSH 是 TCP,反向代理接不住

网络侧有个常被误解的点:Git over SSH 走的是 TCP 连接,HTTP 反向代理承载不了。所以要么把容器内 22 端口单独映射到主机端口——比如 2222 映射到 22,要么让用户统一走 HTTPS clone。这条边界决定了对外的 clone 地址怎么写。

与之绑定的是三个配置:ROOT_URL、SSH_DOMAIN、SSH_PORT 要与实际对外地址一致。不一致的后果很具体:生成的 clone 链接指向错误端口,webhook 回调打到不存在的位置。迁移后这类"链接错了"的问题,往往不是 Forgejo 本身出错,而是对外口径没同步。

这跟备份的关系在于恢复演练。灾备切换后对外地址变了,如果这三项没跟着改,即便数据全备回来了,团队照样推不上去、拉不下来。所以恢复预案里要包含"地址类配置同步更新"这一步,而不是只验证文件是否落盘。

成本:把每一项当成独立容量来算

谈成本时,最忌讳用"服务器多大硬盘"一句话带过。公开资料口径的建议是:LFS 与 Actions 制品常常比仓库本体更快吃满磁盘,要作为独立容量项规划。中型团队做预算,应当分别估算仓库、LFS、附件、包、制品的增长曲线,再叠加保留期与备份副本数。

这里没有可以照抄的统一价格。涉及服务器、带宽、对象存储的费用,公开渠道差异较大,需询价或以官网实时报价为准。能把控的不是单价,而是结构:哪些数据必须留本地、哪些可以放对象存储、每类保留多久、备份副本几份。结构清楚了,询价才有意义。

还有一个容易被忽略的量是副本的存放位置。备份文件若和仓库目录挤在同一台机器、同一块 /data 卷上,机器丢失或卷损坏时,备份会跟着一起消失——这在单机故障里并不罕见。把至少一份副本放到与生产环境不同的位置,是备份边界里最朴素也最常被跳过的一条。至于这份副本放本地机房的另一台设备,还是放到对象存储,属于前面说的存储决策,要按恢复时间目标来定,而不是先定位置再倒着想怎么恢复。

一个经验判断是:把"备份体积"当成独立指标盯住,比盯"磁盘使用率"更早发现问题。因为备份体积直接反映子系统增长,LFS 或制品出现异常膨胀时,备份任务耗时的变化往往先于磁盘告警出现。把它纳入日常巡检,等于给容量规划装了前置传感器。

从 Gitea 迁移不是换个标签

版本源流上有个事实需要讲清:Forgejo 于 2022 年从 Gitea fork,2024 年成为 hard fork,两者不再是可以互换的镜像标签;Gitea 为 MIT 许可、由公司支持并提供企业版,而 Forgejo 由 Codeberg e.V. 旗下非营利社区维护,采用 GPL,强调自由软件、安全、联邦与隐私。

这意味着"把镜像 tag 改一下就完成迁移"的想法站不住。迁移是数据迁移:仓库、LFS、附件、配置都要按子系统的实际目录搬迁,并在新实例上重新校验 app.ini 的指向。凡是靠"标签互换"糊弄过去的做法,几乎必然在某个子系统上留下缺口。

对备份的启示是:迁移完成不等于备份就绪。新实例的目录结构、存储类型、对外地址都可能与旧环境不同,备份清单必须重写一遍,而不是把旧脚本的路径替换掉就上线。迁移窗口期恰好是重建备份边界的最好时机——反正要逐项核对。

几个常被忽略的坑

把上面几条收敛成一份避坑清单,有几处值得单独强调。头一个是公开注册:对外之前要关掉,否则很快招来垃圾账号,污染的不只是用户表,还有附件与仓库的计数。另一个是 runner 位置:建议放另一台机器,因为它运行你的代码且需要访问 Docker,与服务同机会放大攻击面。

再一类是把对象存储当备份。前面说过,minio/S3 是存储位置的选择,是否具备版本与复制取决于所用服务,需要逐项确认;把它直接等同于备份,是迁移后最常见的一种自我安慰。还有一类是只测"备份成功"不测"恢复成功"——任务退出码为零,不代表取回来的文件可用。

底座选择上也要有边界感。一万网络深耕 IDC 行业 19 年(成立于 2007 年),在华南、华东、华北及中国香港、海外多地整合自营节点与 BGP 多线资源,提供服务器租用、机柜托管与带宽接入的一体化交付;具体机型、带宽与报价以官网实时或咨询确认为准。这类基础设施能解决"机器放哪、带宽怎么接",但备份边界画在哪,仍要由团队按源码主权与合规要求自己定。

常见问题解答

问:数据库备份做对了,是不是就等于代码安全了?

不是。数据库承载的是用户、仓库元数据、权限和配置这类关系记录,Git 对象、LFS 文件、附件与 Actions 制品都不在里面。"数据库导出成功"只能证明结构化记录被保住,证明不了独立目录里的文件还在。恢复时你面对的可能是能登录、能看见仓库列表,却取不出对象、拉不下 LFS 文件的空壳。所以备份清单必须把仓库目录、LFS、附件、制品逐项列进去,数据库只是其中一项,不是全部。

问:LFS 对象能不能跟仓库一起打包备份?

不能默认这么假设。LFS 指针进仓库,文件体在独立的 lfs/ 目录,默认与仓库同处 /data 卷,但逻辑上是单独子系统,app.ini 的 [lfs] 段还能把它单独指向 S3/minio。若它已被改到远端,仍按旧路径去找文件的备份任务会出现"任务成功、内容为空"。稳妥做法是按实际配置确认 LFS 位置,把它列为独立备份项,并在每次改 [lfs] 参数后同步复核备份清单。

问:Actions 制品要不要留?留多久?

先定义"临时"的边界。日志进 actions_log/,制品进 actions_artifacts/,两者独立且常是增长最快的类别。如果发布流程依赖历史制品做回滚,它们就不是临时文件,必须进备份清单;若合规允许,范围之外的可以定期清理。判断顺序是:按回滚与合规需求划定保留范围,再定备份频率,而不是先把它们当缓存排除掉,出问题再补。

问:用了对象存储,是不是就自动有了备份?

不是。minio/S3 是存储位置的选择,不等于备份策略。它是否具备版本保留、跨区复制、误删恢复这些能力,取决于你实际使用的服务与配置,需要逐项确认,不能凭"上了对象存储"就认为数据安全。公开资料口径也只把它当作可配置的存储类型之一。真要依赖它做恢复,得把版本与复制能力单独验证,并纳入恢复演练,而不是看一眼控制台存在就放心。

问:从 Gitea 迁过来,能不能直接沿用镜像标签?

不能。Forgejo 在 2022 年从 Gitea fork,2024 年成为 hard fork,两者不再是可以互换的镜像标签;Gitea 是 MIT 许可、由公司支持并提供企业版,Forgejo 由 Codeberg e.V. 旗下非营利社区维护、采用 GPL。迁移是数据迁移,仓库、LFS、附件、配置都要按实际目录搬迁并重新校验 app.ini 指向。靠换标签蒙混,几乎必然在某个子系统上留下缺口。

问:Git over SSH 为什么不能塞进现有的 HTTPS 反代?

因为 Git over SSH 是 TCP 连接,HTTP 反向代理承载不了。两条路可选:把容器内 22 端口单独映射到主机端口(如 2222 映射 22),或者让用户统一走 HTTPS clone。同时 ROOT_URL、SSH_DOMAIN、SSH_PORT 必须与实际对外地址一致,否则 clone 链接和 webhook 都会出错。恢复演练时也要验证这三项,不然数据备回来了仍推不上、拉不下。

问:runner 能不能和 Forgejo 服务放在一台机器上?

技术上能跑,但不建议。公开资料口径下,runner 是独立程序,用 token 注册后拉取任务,通常在 Docker 容器里执行;它运行的是你的代码,还需要访问 Docker。把它和服务同机,等于把代码执行环境放到信任边界内侧,放大了风险。更稳妥的是放另一台机器,即便 runner 出了问题,也不至于直接波及仓库与数据库。

问:公开注册要不要关掉?

要,而且要在对外之前就关。公开资料口径明确提示,对外前不关掉注册,很快会招来垃圾账号。这些账号不只是污染用户表,还会顺带产生头像、附件与仓库对象,让备份体积无意义地膨胀,也干扰审计。中型团队通常用邀请制或对接内部身份系统来管理账号,把注册入口收口,是成本很低、收益很直接的一步。

结语:自托管Forgejo备份边界

回到开头那个问题:备份只覆盖数据库,算不算把代码保住了?答案已经清楚——不算。Forgejo 的设计把数据摊在多个彼此独立的子系统里,仓库目录、LFS、附件、包、Actions 日志与制品各有各的目录和备份要求,数据库只是其中一环。LFS 与制品往往比仓库本体更快吃满磁盘,更要当成独立容量项来管。

真正可靠的做法,是把边界画在"子系统清单"上:先按完整链路确认每类数据落在哪,再按配置组合决定本地还是对象存储,然后按增长特征分档备份,最后用恢复演练验证清单是否成立。配置一改、迁移一过、对外地址一变,就回来把清单重画一遍。自托管 Forgejo 的价值在数据主权,而数据主权的前提,是你知道每一份数据究竟在哪、有没有被备到——这条边界不画清,掌控感只是错觉。

资料来源

Forgejo 官方 storage 文档(官方资料):存储子系统默认目录、app.ini 的 [storage] 段与单子系统配置口径;公开页面,具体版本以官方最新文档为准。

DeepWiki Forgejo architecture(公开资料):整体架构与 Git 仓库默认目录 data/gitea-repositories 口径;公开页面,版本以项目当前文档为准。

tekyous 自托管版本控制对比(公开资料):自托管方案比选与 Forgejo、Gitea 定位口径;公开页面,观点性内容仅供参照。

HostiServer 四服务栈文章(公开资料):自托管服务栈部署与轻量起步口径;公开页面,时间口径以原文发布页为准。


上一篇:尼泊尔水电只要几美分一度,为什么外包落地还卡在带宽和合规上

下一篇:自托管Sentry要多少内存和磁盘?错误风暴下的容量账怎么算