Gitea 自托管 Git 服务：从源码构建到 `gitea web` 启动的实战与源码解析

本文基于 Gitea 仓库的官方中文说明文档，完整覆盖项目定位、从源码构建（make build 的 backend/frontend 双目标）、./gitea web 启动方式、配置文件路径解析原理、贡献与翻译流程以及官方生态。读完本文，你可以独立完成 Gitea 的源码构建与部署运行，并理解其 CLI 参数与路径配置背后的源码实现逻辑。

项目定位：最无痛的自托管一体化开发服务

Gitea 的目标是提供最简单、最快速、最无痛的方式来搭建自托管的 Git 服务。作为一个"一体化"（all-in-one）软件开发生态，它涵盖 Git 托管、代码管理、代码评审、Issue 跟踪、项目看板、Wiki、团队协作、包注册中心，以及可以复用 GitHub Actions 语法的 CI/CD 能力（见英文版 README.md 中的 Purpose 描述）。

由于 Gitea 使用 Go 语言编写，它可以运行在 Go 支持的所有平台和架构上，包括 Linux、macOS 和 Windows 的 x86、amd64、ARM 和 PowerPC 架构；英文版文档进一步提到 FreeBSD/OpenBSD 与 RISC-V 64 也在支持范围内。这个项目自 2016 年 11 月从 Gogs 分叉而来，此后经历了大量演进。当前仓库的 Go 模块名为 gitea.dev，要求 Go 1.27（见 go.mod）。

项目提供在线演示环境，也有带仓库数量限制的免费托管服务供体验；对于希望快速部署专用实例的用户，Gitea 官方提供了云服务试用与官方 Docker 镜像两条路径。

文档入口

官方完整文档（安装、管理、使用、开发、贡献指南）托管在独立的文档站点上，文档内容本身也存放于单独的文档仓库中。本仓库内同时提供了几份面向开发者的指导文档，可直接作为补充阅读：

• docs/development.md：本地开发环境搭建；
• docs/testing.md：测试指南；
• docs/guidelines-backend.md 与 docs/guidelines-frontend.md：前后端开发规范。

从源码构建

从源代码树的根目录执行构建：

TAGS="bindata" make build

build 目标分为两个子目标（见 Makefile）：

build: frontend backend ## build everything

frontend: $(FRONTEND_DEST) ## build frontend files

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

• make backend：需要 Go Stable 版本，所需版本定义在 go.mod 中（当前为 go 1.27，并锁定 toolchain go1.27.0）。它先执行 go generate（generate-backend 目标），再编译出可执行文件；
• make frontend：需要 Node.js LTS 或更高版本以及 pnpm 包管理器，用于构建前端静态资源。

构建时需要互联网连接来下载 Go 和 npm 模块。一个重要的实践细节是：从官方发布的源代码压缩包构建时，压缩包内已包含预构建好的前端文件，因此不会触发 frontend 目标——这意味着在没有 Node.js 环境的机器上也能完成构建。

构建细节的源码佐证

结合 Makefile 与入口源码，可以确认构建过程的几个关键点：

1. 产物名称与平台差异：EXECUTABLE 在 Windows 下默认为 gitea.exe，其余平台为 gitea（Makefile）。最终通过 go build -tags '$(TAGS)' -ldflags '-s -w $(LDFLAGS)' -o $@ 生成（Makefile），-s -w 会剥离调试信息以减小体积。

2. 版本信息的注入机制：构建时 LDFLAGS 通过 -X 将 main.Version 与 main.Tags 写入二进制（Makefile），对应入口 main.go 中默认值为 "development" 的两个包级变量：

   // these flags will be set by the build flags
   var (
       Version = "development" // program version for this build
       Tags    = ""           // the Golang build tags
   )
   

   这解释了为什么源码直接构建出的版本会显示为 "development"，而发布版会显示正式版本号与构建标签。

3. bindata 标签的作用：TAGS="bindata" 用于将模板、公共静态资源、迁移脚本与 options 等文件以 bindata 形式嵌入二进制（Makefile 中 BINDATA_DEST_WILDCARD 列出了 modules/migration/bindata.*、modules/public/bindata.*、modules/options/bindata.*、modules/templates/bindata.* 等目标文件）。采用 bindata 构建的发行版在部署时不需要在运行目录旁再携带这些资源文件。

运行 Gitea

构建完成后，源代码树的根目录会生成名为 gitea 的二进制文件。启动 Web 服务的命令是：

./gitea web

注意：如果你对使用 Gitea 的 API 感兴趣，官方提供了（实验性的）API 支持，接口文档随文档站点发布。

默认行为：不写子命令就是启动 Web 服务

从 cmd/main.go 的源码结构看，web 命令是主应用的默认命令（app.DefaultCommand = webCmd.Name），且源码注释中明确说明：不指定子命令时直接启动 Web 服务器；同时保留默认命令还有一个现实原因——避免破坏过去在 Windows 上双击 EXE 直接运行的用户习惯。

web 命令自身的参数定义在 cmd/web.go：

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

此外还有三个全局标志，作用于所有依赖配置文件的子命令（见 cmd/main.go）：

参数	别名	默认值	说明
--work-path	-w	二进制所在目录	设置 Gitea 的工作路径
--config	-c	{WorkPath}/custom/conf/app.ini	指定自定义配置文件
--custom-path	-C	{WorkPath}/custom	设置自定义目录路径

gitea 的二进制并不只是一个 Web 服务，它还内置了多个运维子命令。从 cmd/main.go 的结构看，需要读取配置文件的子命令包括：web、serv（Git 服务）、hook（Git Hook 处理）、keys、dump、admin、migrate、doctor、manager、embedded、migrate-storage、dump-repository、restore-repository、actions 等；而 config、cert、generate、docs 等子命令则完全独立，不依赖配置文件或运行环境。运行 ./gitea help 可以查看完整的命令清单。

工作路径与配置文件的解析原理

--work-path、-c 等参数最终如何生效？答案在 modules/setting/path.go 中。InitWorkPathAndCommonConfig 函数按以下优先级确定工作路径（Work Path）、自定义路径（Custom Path）和配置文件（Custom Conf）：

1. 内置默认值：工作路径默认为二进制所在目录，Custom 目录默认为 custom，配置文件默认为 conf/app.ini（path.go）；
2. 环境变量：GITEA_WORK_DIR 与 GITEA_CUSTOM（两者都要求绝对路径，否则直接 fatal 退出，见 path.go）；
3. 命令行标志：--work-path、--custom-path、--config，优先级高于环境变量（path.go）；
4. 配置文件中的 WORK_PATH：如果 app.ini 顶层设置了 WORK_PATH，它会最终覆盖工作路径，且必须是绝对路径；当环境变量或命令行指定的路径与配置中的路径不一致时，代码会标记 AppWorkPathMismatch 供后续检查（path.go）。

最终生效的配置文件路径组合规则是 {WorkPath}/{CustomPath}/conf/app.ini，即默认情况下的 {WorkPath}/custom/conf/app.ini。这也解释了 cmd/main.go 中 help 打印器为何会在帮助输出末尾附上 "DEFAULT CONFIGURATION"（AppPath / WorkPath / CustomPath / ConfigFile）——它调用的正是 prepareWorkPathAndCustomConf（cmd/main.go），方便运维人员确认实际读取的是哪个配置文件。

配置文件：app.ini

Gitea 的核心配置全部集中在 app.ini 中。仓库内提供了完整的示例配置 custom/conf/app.example.ini，其中包含大量逐节注释，是理解各配置项的最佳起点。几个典型配置节如下：

[server]
; HTTP 监听与端口等服务器级设置

[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306 ; can use socket e.g. /var/run/mysqld/mysqld.sock
NAME = gitea
USER = root

[security]
INSTALL_LOCK = false
SECRET_KEY =
INTERNAL_TOKEN =

[log]
MODE = console
LEVEL = Info

（以上截取自 custom/conf/app.example.ini，其中 [server] 位于第 58 行、[database] 位于第 353 行、[service] 位于第 788 行附近。）

配置项可分为两类管理方式：

• 动态配置：可以在管理面板的配置区域直接修改，立即生效；
• 静态配置：需要编辑 app.ini 文件后重启实例才能生效。

INSTALL_LOCK 这一项与源码直接相关：modules/setting/path.go 中，InitWorkPathAndCfgProvider 会检查 HasInstallLock，如果实例已完成安装锁定，则清除环境变量中的配置键，避免环境变量被传递到子进程。

贡献流程

预期工作流是：Fork → Patch → Push → Pull Request。

• 在开始进行 Pull Request 之前，必须先阅读 贡献者指南；
• 如果在项目中发现了安全漏洞，请勿公开提交，应私下发送邮件至 [e-mail]。

翻译工作通过 Crowdin 平台进行。如果想翻译成新的语言，需在 Crowdin 项目中请管理员添加；也可以直接创建 issue、或在 Discord 的 #translation 频道中询问。对于一般性的翻译问题，官方文档中有专门章节（目前仍在持续补充）。仓库内的 options/locale/TRANSLATORS 文件记录了各语言贡献者的名单，options/locale/ 目录下存放着各语言的翻译资源（共 28 个语言文件）。

官方与第三方生态

Gitea 官方提供了三个配套项目：

1. go-sdk：Go 语言的官方 SDK；
2. tea：官方 CLI 工具；
3. Gitea Action runner：用于运行 Gitea Actions 的 runner，这也是 Gitea 能够"复用 GitHub Actions 语法"的落地组件——当前仓库中 services/actions/、modules/actions/ 与 models/actions/ 目录即为 Actions 功能的后端实现，gitea 主命令下的 actions 子命令（见 cmd/main.go）也与之配套。

更多的第三方项目（SDK、插件、主题等）收录在官方维护的 awesome-gitea 列表中。社区交流主要通过 Discord 服务器与官方 discourse 论坛进行。

常见问题

Gitea 怎么发音？ Gitea 的发音是 /ɡɪ'ti:/，读作 "gi-tea"，g 发硬音。

为什么这个项目没有托管在 Gitea 实例上？ 官方正在推进迁移工作，相关进展可在代码仓库的 issue 跟踪（issue 编号 1029）。

在哪里可以找到安全补丁？ 在发布日志或 变更日志 中搜索关键词 SECURITY 即可定位安全补丁条目。

许可证

Gitea 根据 MIT 许可证授权，完整的许可证文本见仓库根目录的 LICENSE 文件。

小结

Gitea 的部署模型可以概括为一条清晰的主线：一条 TAGS="bindata" make build 命令产出单二进制（backend 由 Go 1.27 编译并注入版本信息，frontend 由 Node.js LTS + pnpm 构建且可被预构建产物跳过），./gitea web 启动服务（web 即默认命令，端口与 PID 等参数在 cmd/web.go 中定义），而 app.ini 的查找遵循"内置默认 → 环境变量 → 命令行标志 → 配置文件"的确定性优先级（modules/setting/path.go）。理解了这条主线，再结合 custom/conf/app.example.ini 中的分节注释，就能从容完成从构建、启动到配置调优的完整自托管流程。