开发者指南

相关源文件

• .changelog.yml
• .golangci.yml
• CHANGELOG-archived.md
• CHANGELOG.md
• Dockerfile
• Dockerfile.rootless
• Makefile
• docker/README.md
• docker/root/usr/bin/entrypoint
• docker/rootless/usr/local/bin/docker-entrypoint.sh
• flake.lock
• flake.nix
• models/db/install/db.go
• models/db/sql_postgres_with_schema.go
• models/migrations/base/tests.go
• models/migrations/v1_11/v112.go
• models/unittest/fixtures.go
• modules/log/color.go
• modules/queue/backoff.go
• modules/queue/workergroup.go
• modules/queue/workerqueue.go
• modules/queue/workerqueue_test.go
• modules/testlogger/testlogger.go
• modules/web/routing/logger_manager.go
• playwright.config.ts
• services/context/csrf.go
• snap/snapcraft.yaml
• tests/e2e/README.md
• tests/e2e/e2e_test.go
• tests/integration/README.md
• tests/integration/README_ZH.md
• tests/integration/attachment_test.go
• tests/integration/csrf_test.go
• tests/integration/integration_test.go
• tests/integration/repo_branch_test.go
• tests/integration/signout_test.go
• tests/test_utils.go
• vitest.config.ts

本指南为希望为 Gitea 代码库做出贡献的开发者提供了全面的信息。它涵盖了设置开发环境、构建应用程序、运行测试以及理解系统架构的关键组件。有关将 Gitea 用作最终用户的信息，请参阅用户指南。

开发环境设置

先决条件

要开发 Gitea，您需要安装以下工具

• Go 1.24+：Gitea 的后端是用 Go 编写的
• Node.js 22+：前端开发必需
• Git & Git LFS：用于版本控制和处理大文件
• Make：用于执行构建任务
• 数据库：SQLite 默认用于开发

来源：flake.nix15-36 Makefile21-39

设置开发环境

Gitea 提供了几种设置开发环境的方法

选项 1：使用 Nix Flake（推荐）

如果您已安装并启用了 Nix flakes

来源：flake.nix1-43

选项 2：手动设置

根据您的操作系统手动安装所需的依赖项，然后

开发工具

Gitea 使用多种工具来维护代码质量

工具	目的	命令
golangci-lint	Go 代码 linting	make lint-backend
eslint	JavaScript/Vue 代码 linting	make lint-frontend
gofumpt	Go 代码格式化	make fmt
stylelint	CSS linting	make lint-css
misspell	拼写检查	make lint-spell

来源：.golangci.yml1-173 Makefile300-382

项目架构

下图展示了 Gitea 的高层架构

来源：modules/web/routing/logger_manager.go1-144 routers/ models/db/install/db.go1-83 modules/queue/workerqueue.go1-197

构建 Gitea

基础构建命令

以下命令通常用于构建 Gitea

来源：Makefile686-724 Makefile398-404

构建标签

Gitea 可以使用不同的功能集通过构建标签进行构建

最常见的构建标签是

标签	目的
sqlite	启用 SQLite 数据库支持
sqlite_unlock_notify	SQLite 并发必需
mysql	启用 MySQL 数据库支持
postgres	启用 PostgreSQL 数据库支持
mssql	启用 MSSQL 数据库支持
bindata	将静态资源嵌入二进制文件
pam	启用 PAM 认证

来源：Makefile134-136 Makefile8-9

Docker 构建

使用 Docker 构建和运行 Gitea

Docker 构建过程在 Dockerfile 中定义，并创建一个包含所有依赖项的镜像。

来源：Dockerfile1-87 Dockerfile.rootless1-91 docker/README.md1-7

测试系统

Gitea 拥有一个全面的测试系统，包含多种测试类型

来源：tests/integration/integration_test.go1-452 tests/e2e/e2e_test.go1-115 tests/test_utils.go1-251 modules/testlogger/testlogger.go1-265

运行测试

您可以使用 Make 命令运行不同类型的测试

单元测试

集成测试

端到端测试

来源：tests/integration/README.md1-107 tests/e2e/README.md1-93 Makefile409-639

编写测试

在为 Gitea 编写测试时，请遵循以下模式

1. 单元测试：与被测试的代码放在一起，以 _test.go 后缀命名
2. 集成测试：添加到 tests/integration/ 目录
3. 端到端测试：添加到 tests/e2e/ 目录，并使用 .test.e2e.ts 扩展名

示例集成测试结构

来源：tests/integration/attachment_test.go1-135 tests/integration/repo_branch_test.go1-227 tests/integration/signout_test.go1-25

数据库迁移

Gitea 使用迁移系统来处理数据库模式更改

来源： models/migrations/base/tests.go1-141 models/migrations/v1_11/v112.go1-63 models/db/sql_postgres_with_schema.go1-75

创建新的迁移

要创建新的数据库迁移

1. 在 models/migrations/v<版本号>/ 目录中创建一个新文件
2. 使用 XORM 的 schema API 实现迁移逻辑
3. 在相应的文件中注册迁移

迁移示例

测试迁移

您可以使用以下命令测试迁移

来源： models/unittest/fixtures.go1-84 Makefile639-697

前端开发

前端架构结合了 Go HTML 模板和 Vue.js 组件

来源： vitest.config.ts1-22 Makefile848-883

构建前端资源

前端构建过程由 Webpack 处理

前端测试

前端测试使用 Vitest

测试文件应放置在与被测试代码相同的目录中，并带有 .test.ts 扩展名。

来源： Makefile417-419 vitest.config.ts1-22

结论

本开发指南提供了 Gitea 开发工作流程和架构的概述。有关特定主题，请参考以下资源

• 有关 API 文档，请参阅 API 文档
• 有关配置选项，请参阅 配置指南
• 有关数据库架构详细信息，请参阅 数据库系统

Gitea 项目欢迎贡献。在提交更改之前，请确保运行适当的测试和代码风格检查工具，以确保代码质量。

来源： CHANGELOG.md1-443 .golangci.yml1-173 Makefile1-923