Gitea 自托管一站式 Git 开发平台：定位、源码构建与运行全解析（中文 README 深度解读）

本文基于 Gitea 仓库的官方繁体中文 README（README.zh-tw.md）展开，系统讲解 Gitea 的项目定位、平台支持、从源码构建（make build 的 frontend/backend 双目标流水线）、./gitea web 启动方式及可用的命令行参数、仓库代码结构、贡献流程与许可证等核心内容，并结合 Makefile、go.mod、main.go 与 cmd/web.go 等源码佐证，帮助读者完成从"读懂 README"到"本地编译并运行一个 Gitea 实例"的完整闭环。

一、项目定位：最简单、最快速、最无痛的自托管 Git 服务

中文 README 对项目的核心目标给出了明确表述："這個項目的目標是提供最簡單、最快速、最無痛的方式來設置自託管的 Git 服務。" 结合 README.md 中更完整的表述，Gitea 定位为"all-in-one"（一体化）软件开发服务，包含 Git 托管、代码管理、代码审查、Issue 跟踪、项目看板、Wiki、团队协作、包注册中心和可复用 GitHub Actions 的 CI/CD 能力。

几个可验证的基本事实：

• 单二进制、Go 编写：由于 Gitea 用 Go 语言编写，它可以运行在 Go 支持的所有平台和架构上。README.zh-tw 明确提到 Linux、macOS 和 Windows 的 x86、amd64、ARM 和 PowerPC 架构；英文版进一步补充了 FreeBSD/OpenBSD 与 RISC-V 64。
• 历史悠久：该项目自 2016 年 11 月从 Gogs 分叉而来，经过多年独立演进已形成庞大代码库。
• 在线入口：README 提供了在线演示（demo.gitea.com）、免费托管服务（gitea.com）与云部署试用（cloud.gitea.com）三类入口，方便读者在本地部署前先行体验。

从仓库体量也能印证其"一体化"定位：routers/ 承载 Web 与 API 路由，services/ 实现业务逻辑，models/ 定义数据模型，web_src/ 存放前端源码，modelmigration/ 则是跨度从 v1_6 到 v28 的完整数据库迁移历史。

二、从源码构建：make build 背后的双目标流水线

README.zh-tw 给出的构建入口命令是：

TAGS="bindata" make build

并说明 build 目标分为两个子目标。对照 Makefile 可以精确还原这条流水线：

build: frontend backend ## build everything

frontend: $(FRONTEND_DEST) ## build frontend files

backend: generate-backend $(EXECUTABLE) ## build backend files

2.1 backend 目标：Go 后端与二进制产出

• Go 版本要求：make backend 需要 Go Stable，所需版本在 go.mod 中定义——当前仓库声明为 go 1.27（toolchain go1.27.0），即构建后端需要安装相应版本或更高版本的 Go。
• 构建动作：backend 依赖 generate-backend（先执行 go generate 生成代码，如 modules/charset/ 下的生成文件），再编译出名为 gitea 的可执行文件。Makefile 中对应的编译命令为：

$(EXECUTABLE): $(GO_SOURCES) $(TAGS_PREREQ)
	CGO_ENABLED="$(CGO_ENABLED)" CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) build -v $(EXTRA_GOFLAGS) -tags '$(TAGS)' -ldflags '-s -w $(LDFLAGS)' -o $@

其中 -ldflags '-s -w ...' 会裁剪符号表以减小体积，而 LDFLAGS 中的 -X "main.Version=..." 会在编译期把版本号注入 main.go 里声明的 Version 全局变量——这也是 gitea --version 能显示正确版本号的原理。

• CGO 与构建标签：Makefile 定义了 CGO_TAGS := sqlite_mattn pam。默认 CGO_ENABLED=0（纯静态编译），只有当 TAGS 中包含 sqlite_mattn 或 pam 时才会自动开启 CGO。这意味着默认构建产物不依赖 CGO，便于跨平台交叉编译；若需要纯 Go 的 sqlite 驱动或 PAM 认证，则需显式传入对应标签。
• SQLite 变量数上限：Makefile 在 CGO 模式下还会注入 -DSQLITE_MAX_VARIABLE_NUMBER=32766，解除 SQLite 默认的 999 个绑定变量限制——对 Gitea 这类多条件查询的 Web 应用是必要的。

2.2 frontend 目标：Node.js / pnpm 前端产物

• make frontend 需要 Node.js LTS 或更高版本以及 pnpm。前端产物目标文件是 public/assets/.vite/manifest.json（见 Makefile 的 FRONTEND_DEST 定义），Vite 构建完成即认为前端就绪。
• 一个重要细节：README.zh-tw 特别指出，"需要互联网连接来下载 go 和 npm 模塊。從包含預構建前端文件的官方源代碼壓縮包構建時，不會觸發 frontend 目標，因此可以在沒有 Node.js 的情況下構建。" 从 Makefile 逻辑看这正是依赖文件戳的常规机制：官方源码压缩包中已预置 public/assets/ 下的前端产物，目标文件已存在，make 便跳过 frontend 目标。因此生产环境离线构建时，推荐使用官方源码压缩包而非 git clone 的裸仓库。

2.3 版本注入与发布构建

除了本地 build，Makefile 还实现了完整的发布版本体系：根据 GITHUB_REF_TYPE（tag/branch）计算 VERSION 与 GITEA_VERSION，main 分支会追加 -nightly 后缀。release 目标（Makefile）会依次执行前端构建、二进制交叉编译（release-binaries）、源码打包、校验等步骤；Makefile 中 release-linux、release-darwin、release-windows、release-freebsd 等目标印证了前文所述的多平台支持。

三、运行实例：./gitea web 与它的命令行参数

README.zh-tw 说明构建完成后，默认会在源码树根目录生成名为 gitea 的二进制文件，启动方式为：

./gitea web

web 命令是 Gitea 唯一必须运行的入口——从 cmd/web.go 中该命令的描述可见："Gitea web server is the only thing you need to run, and it takes care of all the other things for you"。源码同时揭示了 gitea web 支持的四个启动参数，这是 README 未列出、但实操中很有用的补充：

参数	别名	默认值	作用
--port	-p	3000	临时端口号，用于防止端口冲突
--install-port	—	3000	首次安装页使用的临时端口
--pid	-P	/run/gitea.pid	自定义 PID 文件路径
--quiet	-q	关	日志系统就绪前只显示 Fatal 级错误
--verbose	—	关	日志系统就绪前将初始日志级别设为 TRACE

首次运行时，如果尚未初始化，Gitea 会先进入 Web 安装向导（由 routers/install/ 提供），完成数据库、管理员账号等配置后才会正式启动服务。运行过程中，main.go 还会负责在进程退出前 flush 队列中的日志（log.GetManager().Close()），避免日志丢失。

此外，./gitea help 可以查看全部可用命令。仓库 cmd/ 目录下的文件即对应各子命令：admin（管理员操作）、doctor（诊断与数据修复）、dump/restore（仓库备份恢复）、serv（Git 后台服务，供 SSH/HTTP 推送拉取使用）、migrate（数据库迁移）等。

四、配置文件与数据库

• 配置入口：完整的配置项参考 custom/conf/app.example.ini，该文件逐节注释了 Server、Database、Repository、OAuth2、Actions 等全部配置段。README 中文版将更细粒度的配置文档指向官方文档站点（docs.gitea.com），仓库内的 docs/ 目录则提供了开发规范（docs/guidelines-backend.md、docs/guidelines-frontend.md）与测试指南（docs/testing.md）。
• 数据库：Makefile 显示本地测试默认使用 SQLite（GITEA_TEST_DATABASE ?= sqlite，且仅在非 CI 环境生效），集成测试还支持 MySQL、PostgreSQL、MSSQL，对应 tests/ 目录下的 mysql.ini.tmpl、pgsql.ini.tmpl、mssql.ini.tmpl、sqlite.ini.tmpl 四个模板。
• 数据库迁移体系：modelmigration/ 目录按版本划分为 v1_6 至 v28 共 20 个版本子目录，累计 300 余个迁移文件（如 modelmigration/v1_27/v331.go），并配有 fixtures/ 目录下的 YAML 测试夹具用于验证迁移正确性。升级 Gitea 实例时，gitea migrate 命令会依据这套体系把旧库结构平滑演进到当前版本。

五、代码结构与核心模块导览

理解 Gitea 的代码组织，有助于按 README 所述功能定位到实现：

目录	职责
cmd/	CLI 子命令实现（web、admin、doctor、serv、dump 等）
routers/api/	RESTful API v1 实现（README 注明 API 为"实验性支援"，配套官方文档）
routers/web/	Web 页面路由
services/	业务服务层：邮件通知、Webhook、Pull 合并、CI/CD Actions 等
models/	数据模型与数据库访问：issues、repo、user、actions、packages 等
modules/	与业务解耦的基础设施库：setting、log、git、queue、storage、indexer 等
modelmigration/	数据库版本迁移（v1_6 起的全量历史）
templates/	服务端模板（Go 模板）
web_src/	前端源码（TypeScript / Vue / CSS，由 Vite 构建）
options/locale/	各语言翻译文件（约 28 种语言 JSON）

六、生态：官方与第三方项目

README.zh-tw 列出了 Gitea 的官方配套项目，这些是围绕核心实例扩展能力的关键组件：

1. go-sdk：官方 Go 语言 SDK，用于以编程方式操作 Gitea API；
2. tea：官方命令行工具，便于在终端管理仓库、Issue、Release 等；
3. action runner：Gitea Actions 的执行器，使 Gitea 能够复用 GitHub Actions 的 workflow 生态；
4. awesome-gitea：社区维护的第三方项目清单，涵盖更多 SDK、插件与主题。

七、贡献、翻译与沟通

• 贡献流程：README 明确了预期工作流为 Fork → Patch → Push → Pull Request，并强调发起 PR 前必须阅读 CONTRIBUTING.md；发现安全漏洞时应私下发送邮件至 [e-mail]。
• 翻译：翻译通过 Crowdin 进行。若需新增语言，可在 Crowdin 项目中请求管理员添加，或创建 issue / 在 Discord #translation 频道询问。翻译贡献者名单记录在 options/locale/TRANSLATORS。
• 沟通渠道：Discord 服务器与 discourse 论坛是文档之外问题的官方沟通渠道。

八、FAQ 与许可证

README.zh-tw 保留了三个值得注意的 FAQ 条目：

• 发音：Gitea 读作 /ɡɪˈti:/，即 "gi-tea"，g 发硬音。
• 安全补丁：在发布日志或 CHANGELOG.md 中搜索关键词 SECURITY 即可定位所有安全补丁对应的版本，这是排查是否需要升级的安全基线动作。
• 许可证：项目基于 MIT 许可证授权，完整文本见 LICENSE。MIT 协议对自托管二次分发非常友好，这也是 Gitea 在企业内网私有化部署中被广泛采用的法律基础之一。

九、快速上手清单

综合以上各节，一个从零开始的本地部署可以浓缩为以下步骤：

1. 准备工具链：安装 go.mod 声明的 Go 版本（当前为 go 1.27）、Node.js LTS 与 pnpm（若使用官方预构建源码包可省略后两者）；
2. 构建：在仓库根目录执行 TAGS="bindata" make build（需要联网下载 go/npm 模块）；
3. 启动：运行 ./gitea web，浏览器访问 http://localhost:3000 完成首次安装向导；
4. 深入：用 ./gitea help 查看全部子命令，用 custom/conf/app.example.ini 作为配置基线，配合 CHANGELOG.md 跟踪版本与安全更新。

Gitea 通过"单二进制 + 可选构建标签 + Web 化安装向导"的设计，把自托管 Git 平台的运维成本压缩到接近最低；而本文梳理的 Makefile 构建链路、gitea web 参数与 modelmigration 迁移体系，正是这一设计理念在代码层面的直接体现。