# https://github.com/go-gitea/gitea 项目说明书

生成时间：2026-07-06 18:26:51 UTC

## 目录

- [Gitea 概览与系统架构](#page-1)
- [核心功能：Git 仓库、Issue、PR、包管理与认证](#page-2)
- [Actions / CI/CD 系统深度解析](#page-3)
- [部署、配置、扩展与运维](#page-4)

<a id='page-1'></a>

## Gitea 概览与系统架构

### 相关页面

相关主题：[核心功能：Git 仓库、Issue、PR、包管理与认证](#page-2), [部署、配置、扩展与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.go](https://github.com/go-gitea/gitea/blob/main/main.go)
- [cmd/web.go](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)
- [cmd/serve.go](https://github.com/go-gitea/gitea/blob/main/cmd/serve.go)
- [cmd/doctor.go](https://github.com/go-gitea/gitea/blob/main/cmd/doctor.go)
- [routers/init.go](https://github.com/go-gitea/gitea/blob/main/routers/init.go)
- [modules/setting/setting.go](https://github.com/go-gitea/gitea/blob/main/modules/setting/setting.go)
- [modules/graceful/manager.go](https://github.com/go-gitea/gitea/blob/main/modules/graceful/manager.go)
- [modules/web/middleware.go](https://github.com/go-gitea/gitea/blob/main/modules/web/middleware.go)
- [modules/web/router.go](https://github.com/go-gitea/gitea/blob/main/modules/web/router.go)
</details>

# Gitea 概览与系统架构

## 一、项目定位与核心能力

Gitea 是一个使用 Go 语言编写的开源、自托管 Git 服务，提供代码托管、问题跟踪、代码审查、Wiki、包镜像、CI/CD（基于兼容 GitHub Actions 的工作流语法）以及 OAuth/LDAP/SAML 鉴权等企业级能力，目标是让用户能够在自己的基础设施上运行一个轻量级的 "GitHub 替代品"。当前主干版本位于 v1.27.0-rc0 阶段，数据库支持 PostgreSQL、MySQL/MariaDB 与 SQLite 三种后端，并可在 Linux、Windows、macOS 等多平台上以单二进制方式部署。

社区中长期关注的方向（参见 #1029 "Gitea hosted Gitea"、#13539 "Internal CI/CD system"、#1872 "Subgroups"、#1612 "Federation"）决定了 Gitea 在 v1.x 中必须补齐：组织子组、内建 Actions 运行时、可复用的工作流（已在 v1.27 强化）、跨实例联邦（[modules/setting/setting.go:150-220]() 中以独立配置块暴露）、以及内建 Pastebin/片段分享（#693）等能力。这些都对当前进程模型与目录分层提出了更清晰的边界要求。

资料来源：[main.go:1-60]()、[modules/setting/setting.go:150-220]()

## 二、进程与启动模型

入口二进制 `gitea` 在 `main.go` 中通过 `urfave/cli` 框架声明全部子命令，涵盖 `web`、`serve`、`cli`、`admin`、`doctor`、`dump`、`restore` 等多模式运行形态（[main.go:20-80]()）。

- **web 模式**：`cmd/web.go` 通过 `routes.AppRoutes` 构造 HTTP 路由器，注册中间件、模板与静态资源，然后交给 `RunHTTP` 监听 TCP（[cmd/web.go:50-180]()）。
- **serve 模式**：`cmd/serve.go` 同时承担 HTTP（部分）和 SSH 智能协议（git-receive-pack / git-upload-pack），启动内建 SSH 守护并将其注册到 `graceful` 管理器，使 `ssh://` 与 `git://` 协议复用同一套鉴权管线（[cmd/serve.go:1-120]()）。
- **doctor 模式**：`cmd/doctor.go` 对数据库、存储、索引、LFS、SSH 配置等进行一致性检查（[cmd/doctor.go:1-90]()）。

整个进程严格依赖 `modules/graceful/manager.go` 提供的优雅关停语义：`Start` 后由 Manager 接管 context 取消、信号捕获、连接排空，确保正在进行的 HTTP 请求、SSH 会话和后台队列在终止时不中断（[modules/graceful/manager.go:80-260]()）。

资料来源：[main.go:20-80]()、[cmd/web.go:50-180]()、[cmd/serve.go:1-120]()、[modules/graceful/manager.go:80-260]()

## 三、请求处理与中间件链

请求生命周期由 `routers/init.go` 中的 `RoutersInit` 统一装配：在该函数内，`InitWebInstallRoutes`、`InitWebRoutes`、`InitAPIRoutes`、`InitInternalRoutes` 被依次调用，分别覆盖安装向导、用户态 Web、RESTful API 与内部 RPC（[routers/init.go:30-200]()）。

路由层基于 `modules/web/router.go` 与 `modules/web/middleware.go` 封装的高阶中间件链实现，包括会话恢复（Session）、CSRF、Recovery、RequestID、AuthToken、Locale、CORS、CacheControl 等横切关注点（[modules/web/middleware.go:1-180]()、[modules/web/router.go:1-120]()）。`web.go` 中 `Midware` 列表的顺序即响应进入应用的顺序，便于在不同路径上定制策略。

API 路由位于 `routers/api/v1`，按 `user`、`repo`、`admin`、`orgs`、`issues`、`actions` 等业务命名空间聚合到同一棵 URL 树下；每个端点都使用 `contexter.APIContext` 提供一致的用户、仓库、权限上下文。对应处理函数调用 `services/` 完成业务计算，再通过 `models/` 持久化。

资料来源：[routers/init.go:30-200]()、[modules/web/middleware.go:1-180]()、[modules/web/router.go:1-120]()

## 四、模块化分层结构

Gitea 在仓库内采用按职责横向分层、纵向按功能切包的策略：

```mermaid
flowchart TD
  CLI[cmd/* 子命令] --> Boot[routers/init.go 总装配]
  Boot --> Web[routers/web 用户态]
  Boot --> API[routers/api/v1 REST]
  Boot --> Int[routers/internal 内部 RPC]
  Web --> Svc[services/* 业务服务]
  API --> Svc
  Svc --> Model[(models/* ORM & 数据库)]
  Svc --> Git[modules/git git 协议封装]
  Svc --> Cfg[modules/setting 配置]
  Svc --> Grace[modules/graceful 生命周期]
```

- **cmd/**：进程入口与 CLI 编排，只负责解析参数和绑定到运行时装配，不承载业务。
- **routers/**：HTTP/SSH 入口装配层；唯一职责是参数绑定、上下文构造、错误码转换。
- **services/**：业务规则层（仓库迁移、Issue、Actions、通知、存储等），是后续 Actions 与 CI/CD（呼应 #13539）扩展的核心入口。
- **models/**：基于 XORM 的 ORM 与数据库模型，是所有读写通道的底线。
- **modules/**：可独立复用的子包——`setting`、`git`、`graceful`、`web`、`queue`、`notification`、`auth` 等，为上层提供基础设施。
- **templates/** + **webapp/**：Go `html/template` 与 Frontend ESBuild 产物，统一由 `custom` 目录与 `CUSTOM_PATH` 覆盖（[modules/setting/setting.go:300-420]()）。

这种分层保证了子组（#1872）、联邦（#1612）等大型特性改造不必穿透到 `cmd/` 与 `routers/`，主要工作落在 `models/` 与 `services/` 之内即可完成。

资料来源：[routers/init.go:30-200]()、[modules/setting/setting.go:300-420]()、[modules/graceful/manager.go:80-260]()

---

<a id='page-2'></a>

## 核心功能：Git 仓库、Issue、PR、包管理与认证

### 相关页面

相关主题：[Gitea 概览与系统架构](#page-1), [Actions / CI/CD 系统深度解析](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [models/repo/repo.go](https://github.com/go-gitea/gitea/blob/main/models/repo/repo.go)
- [models/repo/collaboration.go](https://github.com/go-gitea/gitea/blob/main/models/repo/collaboration.go)
- [models/issues/issue.go](https://github.com/go-gitea/gitea/blob/main/models/issues/issue.go)
- [models/issues/pull.go](https://github.com/go-gitea/gitea/blob/main/models/issues/pull.go)
- [models/packages/package_version.go](https://github.com/go-gitea/gitea/blob/main/models/packages/package_version.go)
- [models/user/user.go](https://github.com/go-gitea/gitea/blob/main/models/user/user.go)
- [models/perm/access_mode.go](https://github.com/go-gitea/gitea/blob/main/models/perm/access_mode.go)
- [services/auth/basic.go](https://github.com/go-gitea/gitea/blob/main/services/auth/basic.go)
- [services/pull/merge.go](https://github.com/go-gitea/gitea/blob/main/services/pull/merge.go)
- [routers/web/repo/issue.go](https://github.com/go-gitea/gitea/blob/main/routers/web/repo/issue.go)
- [modules/packages/container/oci.go](https://github.com/go-gitea/gitea/blob/main/modules/packages/container/oci.go)
</details>

# 核心功能：Git 仓库、Issue、PR、包管理与认证

Gitea 作为自托管的 DevOps 平台，其核心能力围绕四大支柱展开：Git 仓库托管、Issue 与 Pull Request 协作、包注册中心以及多模式的身份认证。本页基于源码梳理这些模块的设计边界与关键路径。

## 一、Git 仓库模型与协作

仓库（`Repository`）是 Gitea 几乎所有交互的根实体。其结构在 `models/repo/repo.go` 中定义，包含所有者（`OwnerUID`）、默认分支（`DefaultBranch`）、可见性（`IsPrivate`/`IsFork`/`IsMirror`）以及大小、Stars 数、Forks 数等元数据 资料来源：[models/repo/repo.go:38-120]()。

| 字段类别 | 代表字段 | 含义 |
| --- | --- | --- |
| 所有权 | `OwnerID`, `OwnerUID` | 指向 `user` 或 `organization` |
| 派生关系 | `ForkID`, `IsFork` | 区分上游与下游仓库 |
| 同步 | `IsMirror`, `MirrorID` | 标记镜像拉取配置 |
| 协作 | `IsPrivate`, `TrustModel` | 决定读/写权限的范围 |

仓库的协作者权限通过 `Collaboration` 模型维护，区分读、写、管理三类角色 资料来源：[models/repo/collaboration.go:1-80]()。`models/perm/access_mode.go` 定义的 `AccessMode`（None / Read / Write / Admin）被路由中间件与 Git 协议层共用，是授权决策的统一枚举 资料来源：[models/perm/access_mode.go:18-60]()。

社区讨论中关于"子组（Subgroups）"的需求（#1872）反映出现有 `OwnerUID` 体系仅支持单层归属，向组织层级结构演进需要扩展该模型。

## 二、Issue 与 Pull Request 协作流

`Issue` 模型在 `models/issues/issue.go` 中同时承载了普通议题和拉取请求的统一结构，例如字段 `IsPull`、`PullRequest` 指针用于区分对象类型。议题通过标签（`Label`）、里程碑（`Milestone`）、受理人（`Assignee`）以及引用（`IssueReference`）建立关系网 资料来源：[models/issues/issue.go:60-150]()。

`models/issues/pull.go` 定义 `PullRequest`，关键字段包括 `BaseBranch`、`HeadBranch`、`MergeBase`、`HasMerged`、`Status`（open/closed/merged/all）。合并流程在 `services/pull/merge.go` 中实现 `Merge` / `Rebase` / `Squash` / `Manual Merge` 四种策略，分别对应核心方法 `rawMerge` 与 `getMergeCommit` 资料来源：[services/pull/merge.go:120-260]()。

Web 路由层入口在 `routers/web/repo/issue.go`，通过 `MustEnableIssues` 等断言函数保证私有模式下议题被禁用 资料来源：[routers/web/repo/issue.go:90-180]()。

```mermaid
flowchart LR
  A[Push / Fork] --> B[创建 PR]
  B --> C{CI 检查}
  C -- 通过 --> D[services/pull/merge.go]
  C -- 失败 --> E[状态回写]
  D --> F[合并到 BaseBranch]
  F --> G[关闭关联 Issue]
```

## 三、包注册中心

Gitea 通过 `models/packages/package_version.go` 提供统一的包元数据抽象。`Package` 与 `PackageVersion` 分别表示包与版本快照，字段 `LowerVersion`、`SemanticVersion`、`Metadata` 用于跨格式比对与查询 资料来源：[models/packages/package_version.go:30-95]()。

底层格式适配位于 `modules/packages/` 目录，例如 `container/oci.go` 处理 OCI 镜像推送、清单解析与层下载 资料来源：[modules/packages/container/oci.go:1-120]()。当前支持 Container、Maven、npm、PyPI、Conan、Generic 等多协议上传，各协议共享同一组 `PackageBlob` 持久化层。

社区在 #1029「Gitea hosted Gitea」中提到的自托管链路同样依赖包注册中心稳定运行，因为发布流水线通常消费 Gitea 镜像仓库。

## 四、身份认证与授权

`User` 模型在 `models/user/user.go` 中定义登录凭据、密码哈希（`PasswdHash`）、Salt、双因素密钥（`TotpSecret`）以及多邮箱配置 资料来源：[models/user/user.go:50-140]()。认证入口由 `services/auth/` 提供，包括 HTTP Basic、Session、Reverse Proxy、OAuth2、LDAP 等多源适配。

`services/auth/basic.go` 中的 `Basic` 认证结构同时处理 Git HTTP Smart 协议与普通登录请求，通过 `Verify` 方法执行凭据校验与 `AccessMode` 解析，最终封装为 `auth_model.User` 上下文 资料来源：[services/auth/basic.go:60-160]()。授权层面 `models/perm/` 提供 `GetUserRepoPermission` 等方法，把单元（unit）粒度的能力（Code、Issues、Packages、Wiki 等）映射为最终 `Permission`。

## 五、贯穿的安全设计

- **CSP nonce**：v1.27.0-rc0 起对所有脚本注入使用 `Content-Security-Policy: script nonce`（PR #37232），减轻 XSS 风险。
- **依赖治理**：`go-git/go-git/v5` 已升级至 v5.19.1（PR #37786），规避已知的协议层安全漏洞。
- **OAuth 强化**：v1.27.0-rc0 限制了 introspection 调用必须与 token client 一致（PR #38042）。
- **私有信息泄露防护**：v1.27.0-rc0 修复了通过 `public_members` 暴露私有组织成员关系的接口（PR #38145）。

这些变更均与认证、Issue/PR 协作链路交叉，是部署方升级时必须审计的关键点。

## 小结

Gitea 的四大核心功能在代码层面以清晰的分层协同：`models/*` 定义实体与权限枚举，`services/*` 执行业务编排，`modules/packages` 与 `routers/web/repo` 分别承担格式适配与 HTTP 入口。社区提案（Subgroups、CI/CD、联邦化）大多落在这套模型的边界上，理解现有字段与权限流是评估后续演进方案的基础。

---

<a id='page-3'></a>

## Actions / CI/CD 系统深度解析

### 相关页面

相关主题：[核心功能：Git 仓库、Issue、PR、包管理与认证](#page-2), [部署、配置、扩展与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [models/actions/run.go](https://github.com/go-gitea/gitea/blob/main/models/actions/run.go)
- [models/actions/run_job.go](https://github.com/go-gitea/gitea/blob/main/models/actions/run_job.go)
- [models/actions/task.go](https://github.com/go-gitea/gitea/blob/main/models/actions/task.go)
- [models/actions/runner.go](https://github.com/go-gitea/gitea/blob/main/models/actions/runner.go)
- [models/actions/schedule.go](https://github.com/go-gitea/gitea/blob/main/models/actions/schedule.go)
- [models/actions/scoped_workflow.go](https://github.com/go-gitea/gitea/blob/main/models/actions/scoped_workflow.go)
</details>

# Actions / CI/CD 系统深度解析

Gitea Actions 是 Gitea 内置的 CI/CD 系统，兼容 GitHub Actions 的工作流 YAML 语法与 Action 插件生态，自 v1.19 起正式启用。该系统在仓库中检测 `.gitea/workflows/*.yml` 工作流文件，由 Gitea Server 触发任务并分发到注册的 Runner 上执行，构建出一个从「事件触发 → 工作流编排 → Runner 执行」完整闭环的持续集成流水线。社区对内置 CI/CD 的呼声长期居高不下（参见 Issue #13539「An internal CI/CD system compatible with Github actions workflow yaml syntax」），Gitea Actions 正是对该诉求的直接回应。

## 1. 核心数据模型

### 1.1 ActionRun：工作流运行实例
`ActionRun` 是工作流每次触发后生成的顶层聚合实体，记录触发源（事件类型、commit SHA、计划任务 ID 等）、状态、耗时与汇总结果。它负责与 `ActionRunJob` 形成一对多关系，并为前端展示与 API 输出提供统一的数据视图。

资料来源：[models/actions/run.go:1-50]()

### 1.2 ActionRunJob：作业调度单元
`ActionRunJob` 代表工作流中的一个独立 Job，是 Runner 实际调度的最小单位。它承载 Job 级别配置（Runner 标签、需要 `needs` 的依赖集合）、状态机推进（pending → waiting → running → success/failure/cancelled），并通过聚合 `ActionTask` 的状态计算汇总结果。

资料来源：[models/actions/run_job.go:1-80]()

### 1.3 ActionTask：Runner 执行步进
`ActionTask` 是 Runner 真正处理的步进对象，按 Step 序列化为待执行指令载荷，Runner 执行完成后回写日志与退出码，再由 Server 汇总为 Job 的最终状态。该模型是 Server–Runner 协议的关键契约。

资料来源：[models/actions/task.go:1-60]()

## 2. Runner 注册与调度

`ActionRunner` 模型描述了系统中注册的 Runner 资源，包含 Owner（仓库级或全局级）、标签（用于 Job 匹配）、在线状态、最后心跳时间与版本信息。Server 通过轮询与心跳机制维护 Runner 在线列表，并在 Job 进入 `waiting` 状态时按标签匹配算法选取合适的 Runner 下发任务。

资料来源：[models/actions/runner.go:1-90]()

Runner 与 Server 之间采用基于 HTTP 的轮询与回写协议：Runner 定期拉取待执行任务，执行完毕后将日志分块上传，由 Server 持久化到对象存储或本地文件系统。这种设计避免了长连接复杂度，便于跨网络环境部署。

## 3. 定时触发与作用域控制

### 3.1 ScheduleSpec：定时调度
`ActionSchedule` 模型定义了工作流的定时触发规则，支持基于 Cron 表达式的周期性执行，并记录上一次与下一次执行时间。Server 在调度器中扫描到期的计划任务后，会自动生成对应的 `ActionRun`，实现无人值守的定时流水线。

资料来源：[models/actions/schedule.go:1-70]()

### 3.2 ScopedWorkflow：最小权限访问
`ScopedAccessToken` 与作用域机制确保工作流只能申请其声明范围内的令牌（如读取仓库内容、写入包），降低了在 CI 场景下滥用长期凭证的风险。该模型是 Gitea 在安全设计上区别于早期自托管 Runner 的关键演进。

资料来源：[models/actions/scoped_workflow.go:1-60]()

## 4. 整体架构与数据流

下表汇总了主要模型在一次工作流执行中的协作关系：

| 模型 | 角色 | 数量关系 | 触发方 |
|------|------|----------|--------|
| ActionRun | 工作流运行 | 1 : N ActionRunJob | 事件 / 计划 / 手动 |
| ActionRunJob | 作业 | 1 : N ActionTask | 由 Run 派生 |
| ActionTask | 步进 | N : 1 RunJob | 由 Runner 取走执行 |
| ActionRunner | 执行节点 | 1 : N ActionTask | Server 调度 |
| ActionSchedule | 定时源 | 1 : N ActionRun | 调度器扫描 |
| ScopedAccessToken | 凭证 | N : 1 ActionRun | Job 启动时签发 |

资料来源：[models/actions/run.go:30-60]()、[models/actions/run_job.go:20-50]()、[models/actions/task.go:15-45]()、[models/actions/runner.go:25-70]()、[models/actions/schedule.go:10-40]()、[models/actions/scoped_workflow.go:10-35]()

Gitea Actions 通过上述模型的有机协作，在保留 GitHub Actions 兼容性的同时，提供了自托管友好的 CI/CD 体验，并与 Gitea 的组织/权限体系深度集成。最新 v1.27.0-rc0 中关于「improve support for reusable workflows」的改进（PR #37478）进一步强化了可复用工作流的能力，使多仓库、多团队的流水线共享成为可能。

---

<a id='page-4'></a>

## 部署、配置、扩展与运维

### 相关页面

相关主题：[Gitea 概览与系统架构](#page-1), [Actions / CI/CD 系统深度解析](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [custom/conf/app.example.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
- [Dockerfile](https://github.com/go-gitea/gitea/blob/main/Dockerfile)
- [Dockerfile.rootless](https://github.com/go-gitea/gitea/blob/main/Dockerfile.rootless)
- [docker/README.md](https://github.com/go-gitea/gitea/blob/main/docker/README.md)
- [Makefile](https://github.com/go-gitea/gitea/blob/main/Makefile)
- [modules/queue/manager.go](https://github.com/go-gitea/gitea/blob/main/modules/queue/manager.go)
- [routers/install/install.go](https://github.com/go-gitea/gitea/blob/main/routers/install/install.go)
- [modules/setting/setting.go](https://github.com/go-gitea/gitea/blob/main/modules/setting/setting.go)
</details>

# 部署、配置、扩展与运维

## 概述

Gitea 以单一可执行文件 `gitea` 与 INI 配置文件 `app.ini` 为中心，构建出部署、配置、扩展、运维四条主线。配置文件模板位于 `custom/conf/app.example.ini`，是管理员了解全部可调参数的主入口；运行时配置加载、默认值合并与校验逻辑位于 `modules/setting/setting.go`。资料来源：[custom/conf/app.example.ini:1-30]()、资料来源：[modules/setting/setting.go:1-80]()。

## 配置体系：app.ini 分段结构

`app.ini` 由多个 `[section]` 组成，每个段落下使用 `KEY = VALUE`。常用段落如下表所示。

| 段落 | 作用 | 关键项示例 |
|------|------|-----------|
| `[server]` | HTTP 监听与域名 | `DOMAIN`、`ROOT_URL`、`HTTP_PORT`、`SSH_DOMAIN`、`LFS_JWT_SECRET` |
| `[database]` | 数据库后端 | `DB_TYPE`（sqlite3/mysql/postgres/mssql）、`PATH`、`HOST`、`NAME`、`USER`、`PASSWD` |
| `[security]` | 安全与登录 | `SECRET_KEY`、`INTERNAL_TOKEN`、`COOKIE_TIMEOUT` |
| `[oauth2]` | OAuth2 提供方 | `ENABLED`、`JWT_SECRET` |
| `[webhook]` | Webhook 出站策略 | `ALLOWED_HOST_LIST`、`SKIP_TLS_VERIFY`、`PAYLOAD_SIZE` |
| `[queue]` / `[queue.*]` | 后台任务队列 | `TYPE`（channel/redis/dummy）、`LENGTH`、`CONN_STR`、`WORKERS` |
| `[mailer]` | SMTP 邮件 | `ENABLED`、`HOST`、`USER`、`PASSWD`、`FROM` |
| `[cache]` | 缓存适配 | `ADAPTER`（memory/redis）、`ITEM_TTL`、`ITEM_MAX_SIZE` |
| `[log]` | 日志输出 | `MODE`（console/file/...）、`LEVEL`、`ROOT_PATH` |
| `[service]` | 业务开关 | `REGISTER_MANUAL_CONFIRM`、`DISABLE_REGISTRATION`、`ENABLE_NOTIFY_MAIL`、`MAINTENANCE_MODE` |

资料来源：[custom/conf/app.example.ini:30-200]()。启动时，Gitea 会把内置默认配置与用户 `app.ini` 合并；若未配置数据库则跳转至 `routers/install/install.go` 实现的安装向导，引导管理员通过浏览器写入初始 INI 并创建管理员账号。资料来源：[routers/install/install.go:1-80]()。

## 部署方式

### 二进制部署

通过根目录 `Makefile` 一键编译并发布单一可执行文件 `gitea`：

```
make build
./gitea web
```

`Makefile` 中通过 `TAGS` 注入 sqlite/pam/bindata 等可选后端；`make install` 可将产物安装到 `$(DESTDIR)`。资料来源：[Makefile:1-60]()。

### Docker 镜像

仓库提供两份 Dockerfile，分别面向常规与加固环境：

- `Dockerfile`：基于 `golang:*-alpine*` 多阶段构建，最终镜像基于 `alpine:*`，以 root 运行并默认监听 22/3000。
- `Dockerfile.rootless`：以非 root 用户（UID 1000）运行，规避容器逃逸风险，更适合受信的多租户环境。

资料来源：[Dockerfile:1-30]()、资料来源：[Dockerfile.rootless:1-30]()。容器内 `/data/gitea` 作为工作目录，包含 `conf`、`db`、`git`、`avatars`、`attachments`、`repositories`、`lfs` 等子目录，建议通过命名卷持久化并以 `/data/gitea/conf/app.ini` 形式挂载配置。资料来源：[docker/README.md:1-80]()。

## 扩展机制

### 自定义目录

Gitea 启动时读取 `$GITEA_WORK_DIR`（默认与 `gitea` 二进制同级的 `custom/`）下的内容：

- `custom/conf/app.ini`：覆盖默认配置。
- `custom/templates/`：覆盖内置 Go template。
- `custom/public/`：追加静态资源（CSS、JS、图片、Logo）。

通过该机制无需修改源码即可完成品牌、邮件模板等深度定制。资料来源：[custom/conf/app.example.ini:1-30]()。

### OAuth2、Webhook 与 Actions

- OAuth2：`[oauth2]` 段落注册 GitHub、Google、GitLab 等提供方，由 `services/auth/source/oauth2` 处理登录流。
- Webhook：仓库级与系统级支持出站 HTTP POST；`[webhook].ALLOWED_HOST_LIST` 用于 SSRF 防护。
- Actions：与社区 #13539 提议的 GitHub Actions 兼容工作流一致，执行器由独立仓库 `gitea/act_runner` 部署并通过 JWT 与主实例通信。

### 队列与数据库适配器

数据库驱动通过编译 tag 注入；`[database]` 与 `[queue]` 共同决定后端拓扑。例如将队列切换到 Redis 可显著提升吞吐：

```
[queue]
TYPE = redis
CONN_STR = redis://127.0.0.1:6379/0
WORKERS = 4
```

所有 worker 由 `modules/queue/manager.go` 中的 `Manager` 统一注册、启动并在收到 `SIGTERM` 时通过 `Manager.Shutdown` 按 context 超时排空任务，保证平滑退出。资料来源：[modules/queue/manager.go:1-80]()。

## 运维要点

### 升级

Gitea 升级仅替换二进制与静态资源，数据库结构变更由 `models/migrations` 自动迁移；容器升级只需拉取新镜像并重启。建议在迁移前临时开启 `[service].MAINTENANCE_MODE = true`，减少写并发。资料来源：[modules/setting/setting.go:1-80]()。

### 备份与还原

官方内置备份命令将 `app.ini`、仓库目录、SQL 快照与附件统一打包：

```
gitea dump -c /data/gitea/conf/app.ini -t /tmp -w /tmp
```

生成的 zip 适用于跨实例迁移，配合 `gitea restore` 完成还原。

### 安全加固

v1.27 在默认安全策略上持续加强（与社区 #1612 等隐私议题呼应）：

- `go-git` 升级至 v5.19.1 修复 CVE。
- OAuth2 令牌内省（RFC 7662）被限制于签发客户端。
- 私有组织的成员关系不再通过 `public_members` 接口泄漏。

### 日志与监控

`[log]` 段落可输出至 console、file、syslog，并按级别过滤；`/api/v1` 暴露 Prometheus 指标，可对接外部监控完成告警与容量规划。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：go-gitea/gitea

摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：LDAP Group Team Map in gitea CLI or API。

## 1. 安全/权限坑 · 来源证据：LDAP Group Team Map in gitea CLI or API

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LDAP Group Team Map in gitea CLI or API
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/20716 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/37531 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/go-gitea/gitea | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 来源证据：Multiple sub repos

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Multiple sub repos
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/4842 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

## 5. 维护坑 · 来源证据：When a closed issue is reopened, a new blank comment will be generated.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When a closed issue is reopened, a new blank comment will be generated.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/37128 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/go-gitea/gitea | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/go-gitea/gitea | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/go-gitea/gitea | no_demo; severity=medium

## 9. 安全/权限坑 · 来源证据：Improve MS Teams Webhook notification for Pull Request Review Requests

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Improve MS Teams Webhook notification for Pull Request Review Requests
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/38270 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 10. 安全/权限坑 · 来源证据：Wrong default for [server].SSH_ROOT_PATH

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Wrong default for [server].SSH_ROOT_PATH
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/36792 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 安全/权限坑 · 来源证据：[1.18.0] SQL warnings on start-up, XORM bug

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[1.18.0] SQL warnings on start-up, XORM bug
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/22275 | 来源类型 github_issue 暴露的待验证使用条件。

## 12. 安全/权限坑 · 来源证据：[EDITED] Changing sync time in a mirror repo from Github, disrupt syncing

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[EDITED] Changing sync time in a mirror repo from Github, disrupt syncing
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/27468 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 安全/权限坑 · 来源证据：openssh s6 service enters tight infinite restart loop causing 600%+ CPU when /data/ssh keys have wrong ownership

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：openssh s6 service enters tight infinite restart loop causing 600%+ CPU when /data/ssh keys have wrong ownership
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/go-gitea/gitea/issues/36755 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 14. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/go-gitea/gitea | issue_or_pr_quality=unknown

## 15. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/go-gitea/gitea | release_recency=unknown

<!-- canonical_name: go-gitea/gitea; human_manual_source: deepwiki_human_wiki -->