nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-12 21:03:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add version v28 (#564)

Browse Source 
<!-- cloudflare-preview --> Preview: https://pr-564.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/564
Reviewed-by: bircni <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
This commit is contained in:
Lunny Xiao authored and bircni committed 2026-09-30 06:40:44 +00:00
1 parent deb2f068d4
commit ba60edbbda
338 files changed
+114455 -45
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Makefile
+13 -3
View File
@@ -12,20 +12,30 @@ create_dir:
clone_awesome: create_dir clone_awesome: create_dir
git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
# the contributing guide moved to the gitea repository, the readme of
# awesome-gitea still links to it with a relative path
AWESOME_CONTRIBUTING_URL := https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md
FIX_AWESOME_LINKS := sed 's|](contributing.md)|]($(AWESOME_CONTRIBUTING_URL))|'
.PHONY: prepare-awesome-latest .PHONY: prepare-awesome-latest
prepare-awesome-latest: clone_awesome prepare-awesome-latest: clone_awesome
cp .tmp/upstream-awesome/README.md docs/awesome.md $(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > docs/awesome.md
.PHONY: prepare-awesome\#% .PHONY: prepare-awesome\#%
prepare-awesome\#%: prepare-awesome\#%:
cp .tmp/upstream-awesome/README.md versioned_docs/version-1.$*/awesome.md $(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-1.$*/awesome.md
# versions numbered without the 1. prefix, like 28
.PHONY: prepare-awesome-v%
prepare-awesome-v%:
$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-$*/awesome.md
.PHONY: install .PHONY: install
install: install:
pnpm install pnpm install
.PHONY: prepare-docs .PHONY: prepare-docs
prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-awesome-v28
.PHONY: build .PHONY: build
build: build:
README.md
+2 -2
View File
@@ -7,8 +7,8 @@ The site covers three products, all served from this repository:
| Product | Content | Versions | Languages | | Product | Content | Versions | Languages |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 | | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English | | API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English | | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
The enterprise documentation is built and deployed from its own repository and The enterprise documentation is built and deployed from its own repository and
cloudflare/_redirects
+2 -2
View File
@@ -9,9 +9,9 @@
# The version served at the root of a product is also reachable under its # The version served at the root of a product is also reachable under its
# number, which is what the release notes and old links use. # number, which is what the release notes and old links use.
/api/1.27/* /api/:splat 301 /api/28/* /api/:splat 301
/runner/3/* /runner/:splat 301 /runner/3/* /runner/:splat 301
/1.27/* /:splat 301 /28/* /:splat 301
# The local search plugin had a results page of its own, algolia docsearch is a # The local search plugin had a results page of its own, algolia docsearch is a
# modal opened from any page. # modal opened from any page.
docs/installation/from-source.md
+2 -2
View File
@@ -23,7 +23,7 @@ version is @minNodeVersion@ and the latest LTS version is recommended.
:::note :::note
Go version @minGoVersion@ or higher is required. However, it is recommended to Go version @minGoVersion@ or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in obtain the same version as our continuous integration, see the advice given in
[Hacking on Gitea](development/hacking-on-gitea.md) [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
::: :::
## Download ## Download
@@ -73,7 +73,7 @@ To build from source, the following programs must be present on the system:
- `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/) - `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
- `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/) - `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](development/hacking-on-gitea.md#installing-make) - `make`, see [here](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md#make)
Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile) Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
are provided to keep the build process as simple as possible. are provided to keep the build process as simple as possible.
i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/from-source.md
+2 -2
View File
@@ -12,7 +12,7 @@ aliases:
接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。 **注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
## 下载 ## 下载
@@ -53,7 +53,7 @@ git checkout @sourceVersion@ # or git checkout pr-xyz
- `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/) - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/) - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](development/hacking-on-gitea.md) - `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.27/installation/from-source.md
+2 -2
View File
@@ -12,7 +12,7 @@ aliases:
接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。 **注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
## 下载 ## 下载
@@ -53,7 +53,7 @@ git checkout @sourceVersion@ # or git checkout pr-xyz
- `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/) - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/) - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](development/hacking-on-gitea.md) - `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28.json
+29
View File
@@ -0,0 +1,29 @@
{
"sidebar.docs.category.Installation": {
"message": "安装"
},
"sidebar.docs.category.Administration": {
"message": "管理"
},
"sidebar.docs.category.Usage": {
"message": "使用"
},
"sidebar.docs.category.actions": {
"message": "Actions"
},
"sidebar.docs.category.packages": {
"message": "软件包"
},
"sidebar.docs.category.Development": {
"message": "开发"
},
"sidebar.docs.category.Contributing": {
"message": "贡献"
},
"sidebar.docs.category.Help": {
"message": "帮助"
},
"sidebar.docs.doc.What is Gitea?": {
"message": "Gitea是什么?"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "运维",
"position": 30,
"link": {
"type": "generated-index",
"slug": "/administration",
"title": "运维"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/adding-legal-pages.md
+34
View File
@@ -0,0 +1,34 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: adding-legal-pages
sidebar_position: 110
aliases:
- /zh-cn/adding-legal-pages
---
# 添加法律页面
一些法域（例如欧盟）要求在网站上添加特定的法律页面（例如隐私政策）。按照以下步骤将它们添加到你的 Gitea 实例中。
## 获取页面
Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
```
wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
```
现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。
## 使其可见
创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中：
```go
<a class="item" href="{{AppSubUrl}}/assets/privacy.html">隐私政策</a>
```
重启 Gitea 以查看更改。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/authentication.md
+301
View File
@@ -0,0 +1,301 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "authentication"
sidebar_position: 10
aliases:
- /zh-cn/authentication
---
# 认证
## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP）
通过 BindDN 的 LDAP 和简单认证方式 LDAP 共享以下字段:
- 认证名称 **(必选)**
- 分配给新授权方法的名称。
- 主机名 **(必选)**
- LDAP 服务的主机地址.
- 例如:`mydomain.com`
- 端口号 **(必选)**
- LDAP 服务的端口号.
- 例如: LDAP `389`/ LDAPs `636`
- 安全协议 (可选)
- 连接 LDAP 服务器时是否使用 TLS 协议。
- 管理员过滤规则 (可选)
- 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
- 示例:`(objectClass=adminAccount)`
- 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
- 用户名属性（可选）
- 用户 LDAP 记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的 Gitea 账户用户名。若留空，则使用登录表单上提供的用户名。
- 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于 Gitea 账户名称，请参阅"用户过滤器"。
- 示例:uid
- 适用于 Microsoft Active Directory（AD）的示例:`sAMAccountName`
- 名字属性（可选）
- 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
- 示例:givenName
- 姓氏属性（可选）
- 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
- 示例:`sn`
- 电子邮件属性 **(必选)**
- 用户 LDAP 记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
- 示例:`mail`
### LDAP(via BindDN)
需要额外设置以下字段:
- 绑定 DN (可选)
- 搜索用户时绑定到 LDAP 服务器的 DN。这可以留空以执行匿名搜索。
- 示例: `cn=Search,dc=mydomain,dc=com`
- 绑定密码 (可选)
- 上述指定的 Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 具有尽可能少的权限。
- 用户搜索基准 **(必选)**
- 这是用于搜索用户帐户的 LDAP 基础路径.
- 示例: `ou=Users,dc=mydomain,dc=com`
- 用户过滤规则 **(必选)**
- LDAP 过滤器声明如何查找试图进行身份验证的用户记录
`%[1]s`匹配参数将替换为登录表单中给出的登录名
- 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
- 示例 for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。
- 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
- 启用用户同步
- 这个选项启用了一个周期性任务，用于将 Gitea 用户与 LDAP 服务器进行同步。默认的同步周期是每 24 小时，
但您可以在 app.ini 文件中进行更改。
有关此部分的详细说明，请参阅[sample
app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。
### LDAP(simple auth)
需要额外设置以下字段:
- 用户 DN **(必选)**
- 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。
- 示例: `cn=%s,ou=Users,dc=mydomain,dc=com`
- 示例: `uid=%s,ou=Users,dc=mydomain,dc=com`
- 用户搜索基准 (可选)
- 用户搜索基准声明哪些用户帐户将被搜索.
- 示例: `ou=Users,dc=mydomain,dc=com`
- 用户过滤规则 **(必选)**
- LDAP 过滤器声明何时允许用户登录
`%[1]s`匹配参数将替换为登录表单中给出的登录名。
- 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
- 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
### 使用 LDAP 验证分组成员
使用以下字段:
- 群组搜索基础 DN(可选)
- 组使用的 LDAP DN。
- 示例: `ou=group,dc=mydomain,dc=com`
- 组名过滤器 (可选)
- LDAP 过滤器，声明如何在上述 DN 中查找有效组。
- 示例: `(|(cn=gitea_users)(cn=admins))`
- 组中的用户属性 (可选)
- 组中列出了哪个用户的 LDAP 属性。
- 示例: `uid`
- 用户组属性 (可选)
- 哪个组的 LDAP 属性包含一个高于用户属性名称的数组。
- 示例: `memberUid`
## 可插拔式认证模块(Pluggable Authentication Module,PAM)
这个过程启用了 PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
PAM 提供了一种机制，通过对用户进行 PAM 认证来自动将其添加到当前数据库中。为了与普通的 Linux 密码一起使用，
运行 Gitea 的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
**注意**:如果用户已将 SSH 公钥添加到 Gitea 中，使用这些密钥可能会绕过登录检查系统。因此，
如果您希望禁用使用 PAM 进行身份验证的用户，应该在 Gitea 中手动禁用该账户，使用内置的用户管理功能。
1. 配置和安装准备.
- 建议您创建一个管理用户.
- 建议取消自动注册.
1. 一旦数据库已初始化完成，使用新创建的管理员账户登录.
1. 导航至用户设置（右上角的图标），然后选择
`Site Administration` -> `Authentication Sources`, 并选择
`Add Authentication Source`.
1. 填写字段如下:
- 认证类型:`PAM`。
- 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
- PAM 服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
- PAM 电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为 gituse 的用户，
并且将此字段设置为 mail.com，那么 Gitea 在验证一个 GIT 实例的用户时将期望 user emai 字段为gituser@mail.com[^2]。
**Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。
[^1]:
例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
[^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP)
此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:
- 身份验证名称 **(必选)**
- 分配给新授权方法的名称
- SMTP 验证类型 **(必选)**
- 用于连接 SMTP 主机的验证类型，plain 或 login
- 主机名 **(必选)**
- SMTP 服务的主机地址
- 例如:`smtp.mydomain.com`
- 端口号 **(必选)**
- SMTP 服务的端口号
- 例如: `587`
- 允许的域名
- 如果使用公共 SMTP 主机或有多个域的 SMTP 主机，限制哪些域可以登录
限制哪些域可以登录。
- 示例: `gitea.com,mydomain.com,mydomain2.com`
- 强制使用 SMTPS
- 默认情况下将使用 SMTPS 连接到端口 465.如果您希望将 smtp 用于其他端口，自行设置
- 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名
- 跳过 TLS 验证
- 禁用 TLS 验证身份.
- 该认证源处于激活状态
- 启用或禁用此身份验证源
## FreeIPA
- 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。
创建一个绑定帐户:
- 在 FreeIPA 服务器上创建一个 gitea.ldif 文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
```sh
dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
changetype: add
objectclass: account
objectclass: simplesecurityobject
uid: gitea
userPassword: secure password
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0
```
- 导入 LDIF 文件（如果需要，请将 localhost 更改为 IPA 服务器）。系统会提示您输入 Directory Manager 的密码。:
```sh
ldapmodify -h localhost -p 389 -x -D \
"cn=Directory Manager" -W -f gitea.ldif
```
- 为`gitea_users`添加 IPA 组:
```sh
ipa group-add --desc="Gitea Users" gitea_users
```
- **提示**:对于 IPA 凭证错误，运行' kinit admin '并提供域管理帐户密码.
- 以管理员身份登录 Gitea，点击 Admin Panel 下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
Gitea 支持通过 Windows 内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现 SPNEGO 单点登录认证（由 RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中工作，即当服务器和客户端都在 Windows 操作系统上运行时。
在激活 SSPI 单点登录认证（SSO）之前，您需要准备您的环境:
- 在 Active Directory 中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在 domain.local 域下创建一个名为 user 的账户:
- 为运行 gitea.exe 的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为 HTTP:
- 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。
- 运行下面的命令，将 host.domain.local 替换为 Web 应用程序将运行的服务器的完全限定域名（FQDN），将 domain\user 替换为在前一步中创建的账户名称:
```sh
setspn -A HTTP/host.domain.local domain\user
```
在遵循上述步骤之前，请确保您按照以下流程进行操作:
1. 用之前创建的用户登录（如果已经登录，请先注销）。
2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为 Web 应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
3. 启动 Web 服务器（运行 `gitea.exe web`）。
4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用 SSPI 认证。
5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。
6. 如果您使用 Chrome 或 Edge 浏览器，请将 Web 应用程序的 URL 添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
7. 启动 Chrome 或 Edge 浏览器，导航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
8. 在控制面板中点击“Sign In”按钮，然后选择 SSPI，将会自动使用当前登录到计算机的用户进行登录。
9. 如果无法正常工作，请确保:
- 您不是在运行`gitea.exe`的同一台服务器上运行 Web 浏览器。应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
- 主机上只有一个`HTTP/...`的 SPN。
- SPN 中只包含主机名，不包含端口号。
- 将 Web 应用程序的 URL 添加到"本地站点"。
- 服务器和客户端的时钟差异不超过 5 分钟（取决于组策略）。
- 在 Internet Explorer 中启用了"集成 Windows 身份验证"（在"高级设置"下）。
遵循这些步骤，您应该能够成功启用和使用 SSPI 单点登录认证（SSO）。
## 反向代理认证
Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
```
默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的 IP 地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
你可以通过以下配置为 API 启用此认证方法：
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
```
:::note
当此方法用于 API 时，反向代理负责处理 CSRF 保护。
:::
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/backup-and-restore.md
+146
View File
@@ -0,0 +1,146 @@
---
date: "2018-06-06T09:33:00+08:00"
slug: "backup-and-restore"
sidebar_position: 11
aliases:
- /zh-cn/backup-and-restore
---
# 备份与恢复
Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个 zip 压缩文件。该压缩文件可以被用来进行数据恢复。
## 备份一致性
为了确保 Gitea 实例的一致性，在备份期间必须关闭它。
Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都会发生变化。例如，当迁移正在进行时，在数据库中创建一个事务，而 Git 仓库正在被复制。如果备份发生在迁移的中间，Git 仓库可能是不完整的，尽管数据库声称它是完整的，因为它是在之后被转储的。避免这种竞争条件的唯一方法是在备份期间停止 Gitea 实例。
## 备份命令 (`dump`)
先转到 git 用户的权限: `su git`. 再 Gitea 目录运行 `./gitea dump`。一般会显示类似如下的输出：
```
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
2016/12/27 22:32:22 Dumping database...
2016/12/27 22:32:22 Packing dump files...
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
```
最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
- `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
- `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
- `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
- `repos/` - 仓库目录的完整副本。
- `gitea-db.sql` - 数据库 dump 出来的 SQL。
- `log/` - Logs 文件，如果用作迁移不是必须的。
中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
## 备份数据库
`gitea dump` 创建的 SQL 转储使用 XORM，Gitea 管理员可能更喜欢使用本地的 MySQL 和 PostgreSQL 转储工具。使用 XORM 转储数据库时仍然存在一些问题，可能会导致在尝试恢复时出现问题。
```sh
# mysql
mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
# postgres
pg_dump -U $USER $DATABASE > gitea-db.sql
```
### 使用 Docker （`dump`）
在使用 Docker 时，使用 `dump` 命令有一些注意事项。
必须以 `gitea/conf/app.ini` 中指定的 `RUN_USER = <OS_USERNAME>` 执行该命令；并且，为了让备份文件夹的压缩过程能够顺利执行，`docker exec` 命令必须在 `--tempdir` 内部执行。
示例：
```none
docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
```
\*注意：`--tempdir` 指的是 Gitea 使用的 Docker 环境的临时目录；如果您没有指定自定义的 `--tempdir`，那么 Gitea 将使用 `/tmp` 或 Docker 容器的 `TMPDIR` 环境变量。对于 `--tempdir`，请相应调整您的 `docker exec` 命令选项。
结果应该是一个文件，存储在指定的 `--tempdir` 中，类似于：`gitea-dump-1482906742.zip`
## 恢复命令 (`restore`)
当前还没有恢复命令，恢复需要人工进行。主要是把文件和数据库进行恢复。
例如：
```sh
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
mv app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
# mysql
mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
# sqlite3
sqlite3 $DATABASE_PATH <gitea-db.sql
# postgres
psql -U $USER -d $DATABASE < gitea-db.sql
service gitea restart
```
如果安装方式发生了变化（例如 二进制 -> Docker），或者 Gitea 安装到了与之前安装不同的目录，则需要重新生成仓库 Git 钩子。
在 Gitea 运行时，并从 Gitea 二进制文件所在的目录执行：`./gitea admin regenerate hooks`
这样可以确保仓库 Git 钩子中的应用程序和配置文件路径与当前安装一致。如果这些路径没有更新，仓库的 `push` 操作将失败。
### 使用 Docker (`restore`)
在基于 Docker 的 Gitea 实例中，也没有恢复命令的支持。恢复过程与前面描述的步骤相同，但路径不同。
示例：
```sh
# 在容器中打开 bash 会话
docker exec --user git -it 2a83b293548e bash
# 在容器内解压您的备份文件
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# 恢复 Gitea 数据
mv data/* /data/gitea
# 恢复仓库本身
mv repos/* /data/git/repositories/
# 调整文件权限
chown -R git:git /data
# 重新生成 Git 钩子
/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
```
Gitea 容器中的默认用户是 `git`（1000:1000）。请用您的 Gitea 容器 ID 或名称替换 `2a83b293548e`。
### 使用 Docker-rootless (`restore`)
在 Docker-rootless 容器中的恢复工作流程只是要使用的目录不同：
```sh
# 在容器中打开 bash 会话
docker exec --user git -it 2a83b293548e bash
# 在容器内解压您的备份文件
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# 恢复 app.ini
mv data/conf/app.ini /etc/gitea/app.ini
# 恢复 Gitea 数据
mv data/* /var/lib/gitea
# 恢复仓库本身
mv repos/* /var/lib/gitea/git/repositories
# 调整文件权限
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
# 重新生成 Git 钩子
/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/cmd-embedded.md
+93
View File
@@ -0,0 +1,93 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "cmd-embedded"
sidebar_position: 20
aliases:
- /zh-cn/cmd-embedded
---
# 嵌入资源提取工具
Gitea 的可执行文件包含了运行所需的所有资源：模板、图片、样式表和翻译文件。你可以通过在 `custom` 目录下的相应路径中放置替换文件来覆盖其中的任何资源（详见 [自定义 Gitea 配置](../administration/customizing-gitea.md)）。
要获取嵌入资源的副本以进行编辑，可以使用 CLI 中的 `embedded` 命令，通过操作系统的 shell 执行。
**注意：** 嵌入资源提取工具包含在 Gitea 1.12 及以上版本中。
## 资源列表
要列出嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
```sh
gitea embedded list [--include-vendored] [patterns...]
```
`--include-vendored` 标志使命令包括被供应的文件，这些文件通常被排除在外；即来自外部库的文件，这些文件是 Gitea 所需的（例如 [octicons](https://octicons.github.com/) 等）。
可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。以下是一些示例：
- 列出所有模板文件，无论在哪个虚拟目录下：`**.tmpl`
- 列出所有邮件模板文件：`templates/mail/**.tmpl`
列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
不要忘记为模式使用引号，因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。
如果未提供模式，则列出所有文件。
### 示例：列出所有嵌入文件
列出所有路径中包含 `openid` 的嵌入文件：
```sh
$ gitea embedded list '**openid**'
public/assets/img/auth/openid_connect.svg
public/assets/img/openid-16x16.png
templates/user/auth/finalize_openid.tmpl
templates/user/auth/signin_openid.tmpl
templates/user/auth/signup_openid_connect.tmpl
templates/user/auth/signup_openid_navbar.tmpl
templates/user/auth/signup_openid_register.tmpl
templates/user/settings/security_openid.tmpl
```
## 提取资源
要提取嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
```sh
gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
```
`--config` 选项用于告知 Gitea `app.ini` 配置文件的位置（如果不在默认位置）。此选项仅在使用 `--custom` 标志时使用。
`--destination` 选项用于指定提取文件的目标目录。默认为当前目录。
`--custom` 标志告知 Gitea 直接将文件提取到 `custom` 目录中。为使其正常工作，该命令需要知道 `app.ini` 配置文件的位置（通过 `--config` 指定），并且根据配置的不同，需要从 Gitea 通常启动的目录运行。有关详细信息，请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md)。
`--overwrite` 标志允许覆盖目标目录中的任何现有文件。
`--rename` 标志告知 Gitea 将目标目录中的任何现有文件重命名为 `filename.bak`。之前的 `.bak` 文件将被覆盖。
至少需要提供一个文件搜索模式；有关模式的语法和示例，请参阅上述 `list` 子命令。
### 重要提示
请确保**只提取需要自定义的文件**。位于 `custom` 目录中的文件不会受到 Gitea 的升级过程的影响。当 Gitea 升级到新版本（通过替换可执行文件）时，许多嵌入文件将发生变化。Gitea 将尊重并使用在 `custom` 目录中找到的任何文件，即使这些文件是旧的和不兼容的。
### 示例：提取邮件模板
将邮件模板提取到临时目录：
```sh
$ mkdir tempdir
$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
Extracting to tempdir:
tempdir/templates/mail/auth/activate.tmpl
tempdir/templates/mail/auth/activate_email.tmpl
tempdir/templates/mail/auth/register_notify.tmpl
tempdir/templates/mail/auth/reset_passwd.tmpl
tempdir/templates/mail/issue/assigned.tmpl
tempdir/templates/mail/issue/default.tmpl
tempdir/templates/mail/notify/collaborator.tmpl
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/command-line.md
+534
View File
File diff suppressed because it is too large. Load diff
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md
+1554
View File
File diff suppressed because it is too large. Load diff
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/customizing-gitea.md
+547
View File
File diff suppressed because it is too large. Load diff
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/email-setup.md
+77
View File
@@ -0,0 +1,77 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "email-setup"
sidebar_position: 12
aliases:
- /zh-cn/email-setup
---
# Email 设置
Gitea 具有邮件功能，用于发送事务性邮件（例如注册确认邮件）。它可以配置为使用 Sendmail（或兼容的 MTA，例如 Postfix 和 msmtp）或直接使用 SMTP 服务器。
## 使用 Sendmail
使用 `sendmail` 命令作为邮件传输代理（mailer）。
注意：对于在官方 Gitea Docker 镜像中使用，请使用 SMTP 版本进行配置（请参考下一节）。
注意：对于面向互联网的网站，请查阅您的 MTA 文档以了解通过 TLS 发送邮件的说明。同时设置 SPF、DMARC 和 DKIM DNS 记录，以使发送的邮件被各个电子邮件提供商接受为合法邮件。
```ini title="app.ini"
[mailer]
ENABLED = true
FROM = [email protected]
PROTOCOL = sendmail
SENDMAIL_PATH = /usr/sbin/sendmail
SENDMAIL_ARGS = "--" ; 大多数 "sendmail" 程序都接受选项，使用 "--" 将防止电子邮件地址被解释为选项。
```
## 使用 SMTP
直接使用 SMTP 服务器作为中继。如果您不想在实例上设置 MTA，但在电子邮件提供商那里有一个帐户，这个选项非常有用。
```ini title="app.ini"
[mailer]
ENABLED = true
FROM = [email protected]
PROTOCOL = smtps
SMTP_ADDR = mail.mydomain.com
SMTP_PORT = 587
USER = [email protected]
PASSWD = `password`
```
重启 Gitea 以使配置更改生效。
要发送测试邮件以验证设置，请转到 Gitea > 站点管理 > 配置 > SMTP 邮件配置。
有关所有选项的完整列表，请查看[配置速查表](../administration/config-cheat-sheet.md)。
请注意：只有在使用 TLS 或 `HOST=localhost` 加密 SMTP 服务器通信时才支持身份验证。TLS 加密可以通过以下方式进行：
- 通过端口 587 的 STARTTLS（也称为 Opportunistic TLS）。初始连接是明文的，但如果服务器支持，则可以升级为 TLS。
- 通过默认端口 465 的 SMTPS 连接。连接到服务器从一开始就使用 TLS。
- 使用 `PROTOCOL=smtps` 进行强制的 SMTPS 连接。（这两种方式都被称为 Implicit TLS）
这是由于 Go 内部库对 STRIPTLS 攻击的保护机制。
请注意，自 2018 年起，[RFC8314](https://tools.ietf.org/html/rfc8314#section-3) 推荐使用 Implicit TLS。
### Gmail
以下配置应该适用于 Gmail 的 SMTP 服务器：
```ini title="app.ini"
[mailer]
ENABLED = true
HOST = smtp.gmail.com:465 ; 对于 Gitea >= 1.18.0，删除此行
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 465
FROM = [email protected]
USER = example.user
PASSWD = `***`
PROTOCOL = smtps
```
请注意，您需要创建并使用一个 [应用密码](https://support.google.com/accounts/answer/185833?hl=en) 并在您的 Google 帐户上启用 2FA。您将无法直接使用您的 Google 帐户密码。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/environment-variables.md
+49
View File
@@ -0,0 +1,49 @@
---
date: "2017-04-08T11:34:00+02:00"
slug: "environment-variables"
sidebar_position: 10
aliases:
- /zh-cn/environment-variables
---
# 环境变量清单
这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
```
GITEA_CUSTOM=/home/gitea/custom ./gitea web
```
## Go 的配置
因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
- `GOOS`
- `GOARCH`
- [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)
您可以在[官方文档](https://go.dev/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。
## Gitea 的文件目录
- `GITEA_WORK_DIR`：工作目录的绝对路径
- `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 _custom_ 目录
- `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
- `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
## 操作系统配置
- `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
- `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
- `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
### 仅限于 Windows 的配置
- `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
- `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C 盘）
- `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
## Miscellaneous
- `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/external-renderers.md
+194
View File
@@ -0,0 +1,194 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "external-renderers"
sidebar_position: 60
aliases:
- /zh-cn/external-renderers
---
# 外部渲染器
Gitea 通过外部二进制文件支持自定义文件渲染（例如 Jupyter notebooks、asciidoc 等），只需要进行以下步骤：
- 安装外部二进制文件
- 在您的 `app.ini` 文件中添加一些配置
- 重新启动 Gitea 实例
此功能支持整个文件的渲染。如果您想要在 Markdown 中渲染代码块，您需要使用 JavaScript 进行一些操作。请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md) 页面上的一些示例。
## 安装外部二进制文件
为了通过外部二进制文件进行文件渲染，必须安装它们的关联软件包。
如果您正在使用 Docker 镜像，则您的 `Dockerfile` 应该包含以下内容：
```docker
FROM docker.gitea.com/gitea:@dockerVersion@
[...]
COPY custom/app.ini /data/gitea/conf/app.ini
[...]
RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
# 安装其他您需要的外部渲染器的软件包
RUN pipx install jupyter docutils --include-deps
# 在上面添加您需要安装的任何其他 Python 软件包
```
## `app.ini` 文件配置
在您的自定义 `app.ini` 文件中为每个外部渲染器添加一个 `[markup.XXXXX]` 部分：
```ini
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
; 输入不是标准输入而是文件
IS_INPUT_FILE = false
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
IS_INPUT_FILE = false
[markup.restructuredtext]
ENABLED = true
FILE_EXTENSIONS = .rst
RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
IS_INPUT_FILE = false
```
如果您的外部标记语言依赖于在生成的 HTML 元素上的额外类和属性，您可能需要启用自定义的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 包作为我们的 HTML 清理器。下面的示例可以用于支持从 [`pandoc`](https://pandoc.org/) 输出的服务器端 [KaTeX](https://katex.org/) 渲染结果。
```ini
[markup.sanitizer.TeX]
; Pandoc 渲染 TeX 段落为带有 "math" 类的 <span> 元素，根据上下文可能还带有 "inline" 或 "display" 类。
; - 请注意，这与我们的 Markdown 解析器中内置的数学支持不同，后者使用 <code> 元素。
ELEMENT = span
ALLOW_ATTR = class
REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
[markup.markdown]
ENABLED = true
FILE_EXTENSIONS = .md,.markdown
RENDER_COMMAND = pandoc -f markdown -t html --katex
```
您必须在每个部分中定义 `ELEMENT` 和 `ALLOW_ATTR`。
要定义多个条目，请添加唯一的字母数字后缀（例如，`[markup.sanitizer.1]` 和 `[markup.sanitizer.something]`）。
要仅为特定的外部渲染器应用清理规则，它们必须使用渲染器名称，例如 `[markup.sanitizer.asciidoc.rule-1]`、`[markup.sanitizer.<renderer>.rule-1]`。
**注意**：如果规则在渲染器 ini 部分之前定义，或者名称与渲染器不匹配，它将应用于所有渲染器。
完成配置更改后，请重新启动 Gitea 以使更改生效。
**注意**：在 Gitea 1.12 之前，存在一个名为 `markup.sanitiser` 的单个部分，其中的键被重新定义为多个规则，但是，这种配置方法存在重大问题，需要通过多个部分进行配置。
### 示例：HTML
直接渲染 HTML 文件：
```ini
[markup.html]
ENABLED = true
FILE_EXTENSIONS = .html,.htm
RENDER_COMMAND = cat
; 输入不是标准输入，而是文件
IS_INPUT_FILE = true
[markup.sanitizer.html.1]
ELEMENT = div
ALLOW_ATTR = class
[markup.sanitizer.html.2]
ELEMENT = a
ALLOW_ATTR = class
```
请注意：此示例中的配置将允许渲染 HTML 文件，并使用 `cat` 命令将文件内容输出为 HTML。此外，配置中的两个清理规则将允许 `<div>` 和 `<a>` 元素使用 `class` 属性。
在进行配置更改后，请重新启动 Gitea 以使更改生效。
### 示例：Office DOCX
使用 [`pandoc`](https://pandoc.org/) 显示 Office DOCX 文件：
```ini
[markup.docx]
ENABLED = true
FILE_EXTENSIONS = .docx
RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html"
[markup.sanitizer.docx.img]
ALLOW_DATA_URI_IMAGES = true
```
在此示例中，配置将允许显示 Office DOCX 文件，并使用 `pandoc` 命令将文件转换为 HTML 格式。同时，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
模板文件的内容如下：
```
$body$
```
### 示例：Jupyter Notebook
使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 显示 Jupyter Notebook 文件：
```ini
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
[markup.sanitizer.jupyter.img]
ALLOW_DATA_URI_IMAGES = true
```
在此示例中，配置将允许显示 Jupyter Notebook 文件，并使用 `nbconvert` 命令将文件转换为 HTML 格式。同样，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
在进行配置更改后，请重新启动 Gitea 以使更改生效。
## 自定义 CSS
在 `.ini` 文件中，可以使用 `[markup.XXXXX]` 的格式指定外部渲染器，并且由外部渲染器生成的 HTML 将被包装在一个带有 `markup` 和 `XXXXX` 类的 `<div>` 中。`markup` 类提供了预定义的样式（如果 `XXXXX` 是 `markdown`，则使用 `markdown` 类）。否则，您可以使用这些类来针对渲染的 HTML 内容进行定制样式。
因此，您可以编写一些 CSS 样式：
```css
.markup.XXXXX html {
font-size: 100%;
overflow-y: scroll;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
.markup.XXXXX body {
color: #444;
font-family: Georgia, Palatino, "Palatino Linotype", Times, "Times New Roman",
serif;
font-size: 12px;
line-height: 1.7;
padding: 1em;
margin: auto;
max-width: 42em;
background: #fefefe;
}
.markup.XXXXX p {
color: orangered;
}
```
将您的样式表添加到自定义目录中，例如 `custom/public/assets/css/my-style-XXXXX.css`，并使用自定义的头文件 `custom/templates/custom/header.tmpl` 进行导入：
```html
<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
```
通过以上步骤，您可以将自定义的 CSS 样式应用到特定的外部渲染器，使其具有所需的样式效果。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/fail2ban-setup.md
+86
View File
@@ -0,0 +1,86 @@
---
date: "2022-08-01T00:00:00+00:00"
slug: "fail2ban-setup"
sidebar_position: 16
aliases:
- /zh-cn/fail2ban-setup
---
# 设置 Fail2ban
**Fail2ban 检查客户端登录日志，将多次登录失败的客户端识别为攻击者并在一段时间内阻止其访问服务。如果你的实例是公开的，这一点尤其重要。请管理员仔细设置 fail2ban，错误的配置将导致防火墙阻止你访问自己的服务器。**
Gitea 会在日志文件 `log/gitea.log` 中记录登录失败的 CLI、SSH 或 HTTP 客户端 IP 地址，而你需要将 Gitea 的日志输出模式从默认的 `console` 更改为 `file`。这表示将日志输出到文件，使得 fail2ban 可以定期扫描日志内容。
当用户的身份验证失败时，日志中会记录此类信息：
```log
2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
```
```log
2020/10/15 16:08:44 [E] invalid credentials from xxx.xxx.xxx.xxx
```
## 配置规则
添加日志过滤器规则到配置文件 `/etc/fail2ban/filter.d/gitea.conf`:
```ini
[Definition]
failregex = .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
ignoreregex =
```
添加监狱规则到配置文件 `/etc/fail2ban/jail.d/gitea.conf`:
```ini
[gitea]
enabled = true
filter = gitea
logpath = /var/lib/gitea/log/gitea.log
maxretry = 10
findtime = 3600
bantime = 900
action = iptables-allports
```
如果你的 Gitea 实例运行在 Docker 容器中，并且直接将容器端口暴露到外部网络，
你还需要添加 `chain="FORWARD"` 到监狱规则配置文件 `/etc/fail2ban/jail.d/gitea-docker.conf`
以适应 Docker 的网络转发规则。但如果你在容器的宿主机上使用 Nginx 反向代理连接到 Gitea 则无需这样配置。
```ini
[gitea-docker]
enabled = true
filter = gitea
logpath = /var/lib/gitea/log/gitea.log
maxretry = 10
findtime = 3600
bantime = 900
action = iptables-allports[chain="FORWARD"]
```
最后，运行 `systemctl restart fail2ban` 即可应用更改。现在，你可以使用 `systemctl status fail2ban` 检查 fail2ban 运行状态。
上述规则规定客户端在 1 小时内，如果登录失败的次数达到 10 次，则通过 iptables 锁定该客户端 IP 地址 15 分钟。
## 设置反向代理
如果你使用 Nginx 反向代理到 Gitea 实例，你还需要设置 Nginx 的 HTTP 头部值 `X-Real-IP` 将真实的客户端 IP 地址传递给 Gitea。否则 Gitea 程序会将客户端地址错误解析为反向代理服务器的地址，例如回环地址 `127.0.0.1`。
```
proxy_set_header X-Real-IP $remote_addr;
```
额外注意，在 Gitea 的配置文件 `app.ini` 中存在下列默认值：
```
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128
```
`REVERSE_PROXY_LIMIT` 限制反向代理服务器的层数，设置为 `0` 表示不使用这些标头。
`REVERSE_PROXY_TRUSTED_PROXIES` 表示受信任的反向代理服务器网络地址，
经过该网络地址转发来的流量会经过解析 `X-Real-IP` 头部得到真实客户端地址。
（参考 [configuration cheat sheet](../administration/config-cheat-sheet.md#安全性)）
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/git-lfs-support.md
+24
View File
@@ -0,0 +1,24 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "git-lfs-setup"
sidebar_position: 12
aliases:
- /zh-cn/git-lfs-setup
---
# Git LFS 设置
要使用 Gitea 内置的 LFS 支持，您需要更新 `app.ini` 文件：
```ini
[server]
; 启用 git-lfs 支持。true 或 false，默认为 false。
LFS_START_SERVER = true
[lfs]
; 存放 LFS 文件的路径，默认为 data/lfs。
PATH = /home/gitea/data/lfs
```
**注意**：LFS 服务器支持需要服务器上安装 Git v2.1.2 以上版本。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/https-support.md
+89
View File
@@ -0,0 +1,89 @@
---
date: "2023-04-09T11:00:00+02:00"
slug: "https-setup"
sidebar_position: 12
---
# HTTPS配置
## 使用内置服务器
在启用HTTPS之前，确保您拥有有效的SSL/TLS证书。
建议在测试和评估情况下使用自签名证书，请运行 `gitea cert --host [HOST]` 以生成自签名证书
如果您在服务器上使用阿帕奇（Apache）或Nginx，建议参考 [反向代理指南](reverse-proxies.md)。
要使用Gitea内置HTTPS支持，您必须编辑`app.ini`文件。
```ini
[server]
PROTOCOL = https
ROOT_URL = https://git.example.com:3000/
HTTP_PORT = 3000
CERT_FILE = cert.pem
KEY_FILE = key.pem
```
请注意，如果您的证书由第三方证书颁发机构签名（即不是自签名的），则 cert.pem 应包含证书链。服务器证书必须是 cert.pem 中的第一个条目，后跟中介（如果有）。不必包含根证书，因为连接客户端必须已经拥有根证书才能建立信任关系。要了解有关配置值的更多信息，请查看 [配置备忘单](../administration/config-cheat-sheet#server-server)。
对于“CERT_FILE”或“KEY_FILE”字段，当文件路径是相对路径时，文件路径相对于“GITEA_CUSTOM”环境变量。它也可以是绝对路径。
### 设置HTTP重定向
Gitea服务器仅支持监听一个端口；要重定向HTTP请求致HTTPS端口，您需要启用HTTP重定向服务：
```ini
[server]
REDIRECT_OTHER_PORT = true
; Port the redirection service should listen on
PORT_TO_REDIRECT = 3080
```
如果您使用Docker，确保端口已配置在 `docker-compose.yml` 文件
## 使用 ACME (默认: Let's Encrypt)
[ACME](https://tools.ietf.org/html/rfc8555) 是一种证书颁发机构标准协议，允许您自动请求和续订 SSL/TLS 证书。[Let`s Encrypt](https://letsencrypt.org/) 是使用此标准的免费公开信任的证书颁发机构服务器。仅实施“HTTP-01”和“TLS-ALPN-01”挑战。为了使 ACME 质询通过并验证您的域所有权，“80”端口（“HTTP-01”）或“443”端口（“TLS-ALPN-01”）上 gitea 域的外部流量必须由 gitea 实例提供服务。可能需要设置 [HTTP 重定向](#设置http重定向) 和端口转发才能正确路由外部流量。否则，到端口“80”的正常流量将自动重定向到 HTTPS。**您必须同意**ACME提供商的服务条款（默认为Let's Encrypt的 [服务条款](https://letsencrypt.org/documents/LE-SA-v1.2-2017年11月15日.pdf)。
使用默认 Let's Encrypt 的最小配置如下：
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_DIRECTORY=https
;; Email can be omitted here and provided manually at first run, after which it is cached
ACME_EMAIL=[email protected]
```
小型配置请使用 [smallstep CA](https://github.com/smallstep/certificates), 点击 [教程](https://smallstep.com/docs/tutorials/acme-challenge) 了解更多信息。
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_URL=https://ca.example.com/acme/acme/directory
;; Can be omitted if using the system's trust is preferred
;ACME_CA_ROOT=/path/to/root_ca.crt
ACME_DIRECTORY=https
ACME_EMAIL=[email protected]
```
要了解关于配置, 请访问 [配置备忘单](../administration/config-cheat-sheet.md#server-server)获取更多信息
## 使用反向代理服务器
按照 [reverse proxy guide](reverse-proxies.md) 的规则设置你的反向代理服务器
然后，按照下面的向导启用 HTTPS：
- [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
- [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
- [caddy](https://caddyserver.com/docs/tls)
注意：仅在代理层启用 HTTPS 被称为 [TLS 终止代理](https://en.wikipedia.org/wiki/TLS_termination_proxy)。代理服务器接受传入的 TLS 连接，解密内容，然后将现在未加密的内容传递给 Gitea。只要代理和 Gitea 实例在同一台计算机上或在私有网络中的不同计算机上（代理暴露给外部网络），这通常是可以接受的。如果您的 Gitea 实例与代理隔离在公共网络上，或者如果您想要全端到端的加密，您还可以直接在 Gitea 中 [启用内置服务器的 HTTPS 支持](#使用内置服务器)，并将连接转发到 HTTPS 上。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/logging-config.md
+263
View File
@@ -0,0 +1,263 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "logging-config"
sidebar_position: 40
aliases:
- /zh-cn/logging-configuration
---
# 日志配置
Gitea 的日志配置主要由以下三种类型的组件组成：
- `[log]` 部分用于一般配置
- `[log.<mode-name>]` 部分用于配置不同的日志输出方式，也称为 "writer mode"，模式名称同时也作为 "writer name"
- `[log]` 部分还可以包含遵循 `logger.<logger-name>.<CONFIG-KEY>` 模式的子日志记录器的配置
默认情况下，已经有一个完全功能的日志输出，因此不需要重新定义。
## 收集日志以获取帮助
要收集日志以获取帮助和报告问题，请参阅 [需要帮助](help/support.md)。
## `[log]` 部分
在 Gitea 中，日志设施的配置在 `[log]` 部分及其子部分。
在顶层的 `[log]` 部分，可以放置以下配置项：
- `ROOT_PATH`：（默认值：**%(GITEA_WORK_DIR)/log**）：日志文件的基本路径。
- `MODE`：（默认值：**console**）：要用于默认日志记录器的日志输出列表。
- `LEVEL`：（默认值：**Info**）：要持久化的最严重的日志事件，不区分大小写。可能的值为：`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`。
- `STACKTRACE_LEVEL`：（默认值：**None**）：对于此类及更严重的事件，将在记录时打印堆栈跟踪。
它还可以包含以下子日志记录器：
- `logger.router.MODE`：（默认值：**,**）：用于路由器日志记录器的日志输出列表。
- `logger.access.MODE`：（默认值：**_empty_**）：用于访问日志记录器的日志输出列表。默认情况下，访问日志记录器被禁用。
- `logger.xorm.MODE`：（默认值：**,**）：用于 XORM 日志记录器的日志输出列表。
将子日志记录器的模式设置为逗号（`,`）表示使用默认的全局 `MODE`。
## 快速示例
### 默认（空）配置
空配置等同于默认配置：
```ini
[log]
ROOT_PATH = %(GITEA_WORK_DIR)/log
MODE = console
LEVEL = Info
STACKTRACE_LEVEL = None
logger.router.MODE = ,
logger.xorm.MODE = ,
logger.access.MODE =
; 这是“控制台”模式的配置选项（由上面的 MODE=console 使用）
[log.console]
MODE = console
FLAGS = stdflags
PREFIX =
COLORIZE = true
```
这等同于将所有日志发送到控制台，并将默认的 Golang 日志也发送到控制台日志中。
这只是一个示例，默认情况下不需要将其写入配置文件中。
### 禁用路由日志并将一些访问日志记录到文件中
禁用路由日志，将访问日志（>=Warn）记录到 `access.log` 中：
```ini
[log]
logger.router.MODE =
logger.access.MODE = access-file
[log.access-file]
MODE = file
LEVEL = Warn
FILE_NAME = access.log
```
### 为不同的模式设置不同的日志级别
将默认日志（>=Warn）记录到 `gitea.log` 中，将错误日志记录到 `file-error.log` 中：
```ini
[log]
LEVEL = Warn
MODE = file, file-error
; 默认情况下，"file" 模式会将日志记录到 %(log.ROOT_PATH)/gitea.log，因此我们不需要设置它
; [log.file]
[log.file-error]
LEVEL = Error
FILE_NAME = file-error.log
```
## 日志输出（模式和写入器）
Gitea 提供以下日志写入器：
- `console` - 输出日志到 `stdout`（或 `stderr`，如果已在配置中设置）
- `file` - 输出日志到文件
- `conn` - 输出日志到套接字（网络或 Unix 套接字）
### 公共配置
某些配置适用于所有日志输出模式：
- `MODE` 是日志输出写入器的模式。它将默认为 ini 部分的模式名称。因此，`[log.console]` 将默认为 `MODE = console`。
- `LEVEL` 是此输出将记录的最低日志级别。
- `STACKTRACE_LEVEL` 是此输出将打印堆栈跟踪的最低日志级别。
- `COLORIZE` 对于 `console`，默认为 `true`，否则默认为 `false`。
#### `EXPRESSION`
`EXPRESSION` 表示日志事件必须匹配才能被输出写入器记录的正则表达式。
日志消息（去除颜色）或 `longfilename:linenumber:functionname` 必须匹配其中之一。
注意：整个消息或字符串不需要完全匹配。
请注意，此表达式将在写入器的 goroutine 中运行，而不是在日志事件的 goroutine 中运行。
#### `FLAGS`
`FLAGS` 表示在每条消息之前打印的前置日志上下文信息。
它是一个逗号分隔的字符串集。值的顺序无关紧要。
默认值为 `stdflags`（= `date,time,medfile,shortfuncname,levelinitial`）。
可能的值为：
- `none` 或 `,` - 无标志。
- `date` - 当地时区的日期：`2009/01/23`。
- `time` - 当地时区的时间：`01:23:23`。
- `microseconds` - 微秒精度：`01:23:23.123123`。假定有时间。
- `longfile` - 完整的文件名和行号：`/a/b/c/d.go:23`。
- `shortfile` - 文件名的最后一个部分和行号：`d.go:23`。
- `funcname` - 调用者的函数名：`runtime.Caller()`。
- `shortfuncname` - 函数名的最后一部分。覆盖 `funcname`。
- `utc` - 如果设置了日期或时间，则使用 UTC 而不是本地时区。
- `levelinitial` - 提供的级别的初始字符，放在方括号内，例如 `[I]` 表示 info。
- `level` - 在方括号内的级别，例如 `[INFO]`。
- `gopid` - 上下文的 Goroutine-PID。
- `medfile` - 文件名的最后 20 个字符 - 相当于 `shortfile,longfile`。
- `stdflags` - 相当于 `date,time,medfile,shortfuncname,levelinitial`。
### Console 模式
在此模式下，日志记录器将将日志消息转发到 Gitea 进程附加的 stdout 和 stderr 流。
对于 console 模式的日志记录器，如果不在 Windows 上，或者 Windows 终端可以设置为 ANSI 模式，或者是 cygwin 或 Msys 管道，则 `COLORIZE` 默认为 `true`。
设置：
- `STDERR`：**false**：日志记录器是否应将日志打印到 `stderr` 而不是 `stdout`。
### File 模式
在此模式下，日志记录器将将日志消息保存到文件中。
设置：
- `FILE_NAME`：要将日志事件写入的文件，相对于 `ROOT_PATH`，默认为 `%(ROOT_PATH)/gitea.log`。异常情况：访问日志默认为 `%(ROOT_PATH)/access.log`。
- `MAX_SIZE_SHIFT`：**28**：单个文件的最大大小位移。28 表示 256Mb。详细信息见下文。
- `LOG_ROTATE` **true**：是否轮转日志文件。
- `DAILY_ROTATE`：**true**：是否每天旋转日志。
- `MAX_DAYS`：**7**：在此天数之后删除旋转的日志文件。
- `COMPRESS`：**true**：默认情况下是否使用 gzip 压缩旧的日志文件。
- `COMPRESSION_LEVEL`：**-1**：压缩级别。详细信息见下文。
`MAX_SIZE_SHIFT` 通过将给定次数左移 1 (`1 << x`) 来定义文件的最大大小。
在 v1.17.3 版本时的确切行为可以在[这里](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185)中查看。
`COMPRESSION_LEVEL` 的有用值范围从 1 到（包括）9，其中较高的数字表示更好的压缩。
请注意，更好的压缩可能会带来更高的资源使用。
必须在前面加上 `-` 符号。
### Conn 模式
在此模式下，日志记录器将通过网络套接字发送日志消息。
设置：
- `ADDR`：**:7020**：设置要连接的地址。
- `PROTOCOL`：**tcp**：设置协议，可以是 "tcp"、"unix" 或 "udp"。
- `RECONNECT`：**false**：在连接丢失时尝试重新连接。
- `RECONNECT_ON_MSG`：**false**：为每条消息重新连接主机。
### "Router" 日志记录器
当 Gitea 的路由处理程序工作时，Router 日志记录器记录以下消息类型：
- `started` 消息将以 TRACE 级别记录
- `polling`/`completed` 路由将以 INFO 级别记录。异常情况："/assets" 静态资源请求也会以 TRACE 级别记录。
- `slow` 路由将以 WARN 级别记录
- `failed` 路由将以 WARN 级别记录
### "XORM" 日志记录器
为了使 XORM 输出 SQL 日志，还应将 `[database]` 部分中的 `LOG_SQL` 设置为 `true`。
### "Access" 日志记录器
"Access" 日志记录器是自 Gitea 1.9 版本以来的新日志记录器。它提供了符合 NCSA Common Log 标准的日志格式。虽然它具有高度可配置性，但在更改其模板时应谨慎。此日志记录器的主要好处是，Gitea 现在可以使用标准日志格式记录访问日志，因此可以使用标准工具进行分析。
您可以通过使用 `logger.access.MODE = ...` 来启用此日志记录器。
如果需要，可以通过更改 `ACCESS_LOG_TEMPLATE` 的值来更改 "Access" 日志记录器的格式。
请注意，访问日志记录器将以 `INFO` 级别记录，将此日志记录器的 `LEVEL` 设置为 `WARN` 或更高级别将导致不记录访问日志。
#### ACCESS_LOG_TEMPLATE
此值表示一个 Go 模板。其默认值为
```tmpl
{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
```
模板接收以下选项：
- `Ctx` 是 `context.Context`
- `Identity` 是 `SignedUserName`，如果用户未登录，则为 "-"
- `Start` 是请求的开始时间
- `ResponseWriter` 是 `http.ResponseWriter`
更改此模板时必须小心，因为它在标准的 panic 恢复陷阱之外运行。此模板应该尽可能简单，因为它会为每个请求运行一次。
## 释放和重新打开、暂停和恢复日志记录
如果您在 Unix 上运行，您可能希望释放和重新打开日志以使用 `logrotate` 或其他工具。
可以通过向运行中的进程发送 `SIGUSR1` 信号或运行 `gitea manager logging release-and-reopen` 命令来强制 Gitea 释放并重新打开其日志文件和连接。
或者，您可能希望暂停和恢复日志记录 - 可以通过使用 `gitea manager logging pause` 和 `gitea manager logging resume` 命令来实现。请注意，当日志记录暂停时，低于 INFO 级别的日志事件将不会存储，并且只会存储有限数量的事件。在暂停时，日志记录可能会阻塞，尽管是暂时性的，但会大大减慢 Gitea 的运行速度，因此建议仅暂停很短的时间。
### 在 Gitea 运行时添加和删除日志记录
可以使用 `gitea manager logging add` 和 `remove` 子命令在 Gitea 运行时添加和删除日志记录。
此功能只能调整正在运行的日志系统，不能用于启动未初始化的访问或路由日志记录器。如果您希望启动这些系统，建议调整 app.ini 并（优雅地）重新启动 Gitea 服务。
这些命令的主要目的是在运行中的系统上轻松添加临时日志记录器，以便调查问题，因为重新启动可能会导致问题消失。
## 使用 `logrotate` 而不是内置的日志轮转
Gitea 包含内置的日志轮转功能，对于大多数部署来说应该已经足够了。但是，如果您想使用 `logrotate` 工具：
- 在 `app.ini` 中将 `LOG_ROTATE` 设置为 `false`，禁用内置的日志轮转。
- 安装 `logrotate`。
- 根据部署要求配置 `logrotate`，有关配置语法细节，请参阅 `man 8 logrotate`。
在 `postrotate/endscript` 块中通过 `kill -USR1` 或 `kill -10` 向 `gitea` 进程本身发送 `USR1` 信号，
或者运行 `gitea manager logging release-and-reopen`（使用适当的环境设置）。
确保配置适用于由 Gitea 日志记录器生成的所有文件，如上述部分所述。
- 始终使用 `logrotate /etc/logrotate.conf --debug` 来测试您的配置。
- 如果您正在使用 Docker 并从容器外部运行，您可以使用
`docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'`
或 `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'`，或直接向 Gitea 进程本身发送 `USR1` 信号。
下一个 `logrotate` 作业将包括您的配置，因此不需要重新启动。
您还可以立即使用 `logrotate /etc/logrotate.conf --force` 重新加载 `logrotate`。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/mail-templates.md
+254
View File
@@ -0,0 +1,254 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "mail-templates"
sidebar_position: 45
aliases:
- /zh-cn/mail-templates
---
# 邮件模板
为了定制特定操作的电子邮件主题和内容，可以使用模板来自定义 Gitea。这些功能的模板位于 [`custom` 目录](../administration/customizing-gitea.md) 下。
如果没有自定义的替代方案，Gitea 将使用内部模板作为默认模板。
自定义模板在 Gitea 启动时加载。对它们的更改在 Gitea 重新启动之前不会被识别。
## 支持模板的邮件通知
目前，以下通知事件使用模板：
| 操作名称 | 用途 |
| ---------- | ---------------------------------------------------------------------- |
| `new` | 创建了新的工单或合并请求。 |
| `comment` | 在现有工单或合并请求中创建了新的评论。 |
| `close` | 关闭了工单或合并请求。 |
| `reopen` | 重新打开了工单或合并请求。 |
| `review` | 在合并请求中进行审查的首要评论。 |
| `approve` | 对合并请求进行批准的首要评论。 |
| `reject` | 对合并请求提出更改请求的审查的首要评论。 |
| `code` | 关于合并请求的代码的单个评论。 |
| `assigned` | 用户被分配到工单或合并请求。 |
| `default` | 未包括在上述类别中的任何操作，或者当对应类别的模板不存在时使用的模板。 |
特定消息类型的模板路径为：
```sh
custom/templates/mail/{操作类型}/{操作名称}.tmpl
```
其中 `{操作类型}` 是 `issue` 或 `pull`（针对合并请求），`{操作名称}` 是上述列出的操作名称之一。
例如，有关合并请求中的评论的电子邮件的特定模板是：
```sh
custom/templates/mail/pull/comment.tmpl
```
然而，并不需要为每个操作类型/名称组合创建模板。
使用回退系统来选择适当的模板。在此列表中，将使用 _第一个存在的_ 模板：
- 所需**操作类型**和**操作名称**的特定模板。
- 操作类型为 `issue` 和所需**操作名称**的模板。
- 所需**操作类型**和操作名称为 `default` 的模板。
- 操作类型为` issue` 和操作名称为 `default` 的模板。
唯一必需的模板是操作类型为 `issue` 操作名称为 `default` 的模板，除非用户在 `custom` 目录中覆盖了它。
## 模板语法
邮件模板是 UTF-8 编码的文本文件，需要遵循以下格式之一：
```
用于主题行的文本和宏
------------
用于邮件正文的文本和宏
```
或者
```
用于邮件正文的文本和宏
```
指定 _主题_ 部分是可选的（因此也是虚线分隔符）。在使用时，_主题_ 和 _邮件正文_ 模板之间的分隔符需要至少三个虚线；分隔符行中不允许使用其他字符。
_主题_ 和 _邮件正文_ 由 [Golang 的模板引擎](https://go.dev/pkg/text/template/) 解析，并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素：
| 名称 | 类型 | 可用性 | 用途 |
| ------------------ | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.FallbackSubject` | string | 始终可用 | 默认主题行。参见下文。 |
| `.Subject` | string | 仅在正文中可用 | 解析后的 _主题_。 |
| `.Body` | string | 始终可用 | 工单、合并请求或评论的消息，从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。 |
| `.Link` | string | 始终可用 | 源工单、合并请求或评论的地址。 |
| `.Issue` | models.Issue | 始终可用 | 产生通知的工单（或合并请求）。要获取特定于合并请求的数据（例如 `HasMerged`），可以使用 `.Issue.PullRequest`，但需要注意，如果工单 _不是_ 合并请求，则该字段将为 `nil`。 |
| `.Comment` | models.Comment | 如果适用 | 如果通知是针对添加到工单或合并请求的评论，则其中包含有关评论的信息。 |
| `.IsPull` | bool | 始终可用 | 如果邮件通知与合并请求关联（即 `.Issue.PullRequest` 不为 `nil` ），则为 `true`。 |
| `.Repo` | string | 始终可用 | 仓库的名称，包括所有者名称（例如 `mike/stuff`） |
| `.User` | models.User | 始终可用 | 事件来源仓库的所有者。要获取用户名（例如 `mike`），可以使用 `.User.Name`。 |
| `.Doer` | models.User | 始终可用 | 执行触发通知事件的操作的用户。要获取用户名（例如 `rhonda`），可以使用 `.Doer.Name`。 |
| `.IsMention` | bool | 始终可用 | 如果此通知仅是因为在评论中提到了用户而生成的，并且收件人未订阅源，则为 `true`。如果收件人已订阅工单或仓库，则为 `false`。 |
| `.SubjectPrefix` | string | 始终可用 | 如果通知是关于除工单或合并请求创建之外的其他内容，则为 `Re：`；否则为空字符串。 |
| `.ActionType` | string | 始终可用 | `"issue"` 或 `"pull"`。它将与实际的 _操作类型_ 对应，与选择的模板无关。 |
| `.ActionName` | string | 始终可用 | 它将是上述操作类型之一（`new` ，`comment` 等），并与选择的模板对应。 |
| `.ReviewComments` | []models.Comment | 始终可用 | 审查中的代码评论列表。评论文本将在 `.RenderedContent` 中，引用的代码将在 `.Patch` 中。 |
所有名称区分大小写。
### 模板中的主题部分
用于邮件主题的模板引擎是 Golang 的 [`text/template`](https://go.dev/pkg/text/template/)。
有关语法的详细信息，请参阅链接的文档。
主题构建的步骤如下：
- 根据通知类型和可用的模板选择一个模板。
- 解析并解析模板（例如，将 `{{.Issue.Index}}` 转换为工单或合并请求的编号）。
- 将所有空格字符（例如 `TAB`，`LF` 等）转换为普通空格。
- 删除所有前导、尾随和多余的空格。
- 将字符串截断为前 256 个字母（字符）。
如果最终结果为空字符串，**或者**没有可用的主题模板（即所选模板不包含主题部分），将使用 Gitea 的**内部默认值**。
内部默认（回退）主题相当于：
```
{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
```
例如：`Re: [mike/stuff] New color palette (#38)`
即使存在有效的主题模板，Gitea 的默认主题也可以在模板的元数据中作为 `.FallbackSubject` 找到。
### 模板中的邮件正文部分
用于邮件正文的模板引擎是 Golang 的 [`html/template`](https://go.dev/pkg/html/template/)。
有关语法的详细信息，请参阅链接的文档。
邮件正文在邮件主题之后进行解析，因此还有一个额外的 _元数据_ 字段，即在考虑所有情况之后实际呈现的主题。
期望的结果是 HTML（包括结构元素，如`<html>`，`<body>`等）。可以通过 `<style>` 块、`class` 和 `style` 属性进行样式设置。但是，`html/template` 会进行一些 [自动转义](https://go.dev/pkg/html/template/#hdr-Contexts)，需要考虑这一点。
不支持附件（例如图像或外部样式表）。但是，也可以引用其他模板，例如以集中方式提供 `<style>` 元素的内容。外部模板必须放置在 `custom/mail` 下，并相对于该目录引用。例如，可以使用 `{{template styles/base}}` 包含 `custom/mail/styles/base.tmpl`。
邮件以 `Content-Type: multipart/alternative` 发送，因此正文以 HTML 和文本格式发送。通过剥离 HTML 标记来获取文本版本。
## 故障排除
邮件的呈现方式直接取决于邮件应用程序的功能。许多邮件客户端甚至不支持 HTML，因此显示生成邮件中包含的文本版本。
如果模板无法呈现，则只有在发送邮件时才会注意到。
如果主题模板失败，将使用默认主题，如果从 _邮件正文_ 中成功呈现了任何内容，则将使用该内容，忽略其他内容。
如果遇到问题，请检查 [Gitea 的日志](../administration/logging-config.md) 以获取错误消息。
## 示例
`custom/templates/mail/issue/default.tmpl`:
```html
[{{.Repo}}] @{{.Doer.Name}}
{{if eq .ActionName "new"}}
创建了
{{else if eq .ActionName "comment"}}
评论了
{{else if eq .ActionName "close"}}
关闭了
{{else if eq .ActionName "reopen"}}
重新打开了
{{else}}
更新了
{{end}}
{{if eq .ActionType "issue"}}
工单
{{else}}
合并请求
{{end}}
#{{.Issue.Index}}: {{.Issue.Title}}
------------
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>{{.Subject}}</title>
</head>
<body>
{{if .IsMention}}
<p>
您收到此邮件是因为 @{{.Doer.Name}} 提到了您。
</p>
{{end}}
<p>
<p>
<a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
{{if not (eq .Doer.FullName "")}}
({{.Doer.FullName}})
{{end}}
{{if eq .ActionName "new"}}
创建了
{{else if eq .ActionName "close"}}
关闭了
{{else if eq .ActionName "reopen"}}
重新打开了
{{else}}
更新了
{{end}}
<a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>。
</p>
{{if not (eq .Body "")}}
<h3>消息内容：</h3>
<hr>
{{.Body}}
{{end}}
</p>
<hr>
<p>
<a href="{{.Link}}">在 Gitea 上查看</a>。
</p>
</body>
</html>
```
该模板将生成以下内容：
### 主题
> [mike/stuff] @rhonda 在合并请求 #38 上进行了评论：New color palette
### 邮件正文
> [@rhonda](#)（Rhonda Myers）更新了 [mike/stuff#38](#)。
>
> #### 消息内容
>
> \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
>
> Mike, I think we should tone down the blues a little.
>
> \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
>
> [在 Gitea 上查看](#)。
## 高级用法
模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：
| 函数名 | 参数 | 可用于 | 用法 |
| ---------------- | ----------- | ---------- | ------------------------------------------------ |
| `AppUrl` | - | 任何地方 | Gitea 的 URL |
| `AppName` | - | 任何地方 | 从 `app.ini` 中设置，通常为 "Gitea" |
| `AppDomain` | - | 任何地方 | Gitea 的主机名 |
| `EllipsisString` | string, int | 任何地方 | 将字符串截断为指定长度；根据需要添加省略号 |
| `SanitizeHTML` | string | 仅正文部分 | 通过删除其中的危险 HTML 标签对文本进行清理 |
| `SafeHTML` | string | 仅正文部分 | 将输入作为 HTML 处理；可用于输出原始的 HTML 内容 |
这些都是 _函数_，而不是元数据，因此必须按以下方式使用：
```html
像这样使用： {{SanitizeHTML "Escape<my
>text"}} 或者这样使用： {{"Escape<my
>text" | SanitizeHTML}} 或者这样使用： {{AppUrl}} 但不要像这样使用：
{{.AppUrl}}</my
></my
>
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/repo-indexer.md
+50
View File
@@ -0,0 +1,50 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "repo-indexer"
sidebar_position: 45
aliases:
- /zh-cn/repo-indexer
---
# 仓库索引器
## 设置仓库索引器
通过在您的 [`app.ini`](../administration/config-cheat-sheet.md) 中启用此功能，Gitea 可以通过仓库的文件进行搜索：
```ini
[indexer]
; ...
REPO_INDEXER_ENABLED = true
REPO_INDEXER_PATH = indexers/repos.bleve
MAX_FILE_SIZE = 1048576
REPO_INDEXER_INCLUDE =
REPO_INDEXER_EXCLUDE = resources/bin/**
```
请记住，索引内容可能会消耗大量系统资源，特别是在首次创建索引或全局更新索引时（例如升级 Gitea 之后）。
### 按大小选择要索引的文件
`MAX_FILE_SIZE` 选项将使索引器跳过所有大于指定值的文件。
### 按路径选择要索引的文件
Gitea 使用 [`gobwas/glob` 库](https://github.com/gobwas/glob) 中的 glob 模式匹配来选择要包含在索引中的文件。
限制文件列表可以防止索引被派生或无关的文件（例如 lss、sym、map 等）污染，从而使搜索结果更相关。这还有助于减小索引的大小。
`REPO_INDEXER_EXCLUDE_VENDORED`（默认值为 true）将排除供应商文件不包含在索引中。
`REPO_INDEXER_INCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于在索引中**包含**的文件。空列表表示“_包含所有文件_”。
`REPO_INDEXER_EXCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于从索引中**排除**的文件。与该列表匹配的文件将不会被索引。`REPO_INDEXER_EXCLUDE` 优先于 `REPO_INDEXER_INCLUDE`。
模式匹配工作方式如下：
- 要匹配所有带有 `.txt` 扩展名的文件，无论在哪个目录中，请使用 `**.txt`。
- 要匹配仅在仓库的根级别中具有 `.txt` 扩展名的所有文件，请使用 `*.txt`。
- 要匹配 `resources/bin` 目录及其子目录中的所有文件，请使用 `resources/bin/**`。
- 要匹配位于 `resources/bin` 目录下的所有文件，请使用 `resources/bin/*`。
- 要匹配所有名为 `Makefile` 的文件，请使用 `**Makefile`。
- 匹配目录没有效果；模式 `resources/bin` 不会包含/排除该目录中的文件；`resources/bin/**` 会。
- 所有文件和模式都规范化为小写，因此 `**Makefile`、`**makefile` 和 `**MAKEFILE` 是等效的。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/reverse-proxies.md
+454
View File
@@ -0,0 +1,454 @@
---
date: "2018-05-22T11:00:00+00:00"
slug: "reverse-proxies"
sidebar_position: 16
aliases:
- /zh-cn/reverse-proxies
---
# 反向代理
## 通用配置
1. 在您的 `app.ini` 文件中添加配置 `[server] ROOT_URL = https://git.example.com/`
2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
6. Gitea 会在 `/-/ws` 使用 WebSocket 连接，用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1，并转发 `Upgrade` 和 `Connection` 头，参见下面的示例。否则 Gitea 会回退为定期轮询。
## 使用子路径
通常，**不推荐**将 Gitea 放到子路径。人们很少使用此配置，并且在极少数情况下可能会出现一些问题。
为了让 Gitea 在子路径工作（例如：`https://common.example.com/gitea/`），需要在上面的通用配置之外进行一些额外的配置：
1. 在 `app.ini` 文件中使用配置 `[server] ROOT_URL = https://common.example.com/gitea/`。
2. 将 `https://common.example.com/gitea/foo` 反向代理到 `http://gitea:3000/foo`。
3. 容器映像注册表需要在根目录级别有一个固定的子路径 `v2`，您必须做下列配置：
- 将 `https://common.example.com/v2` 反向代理到 `http://gitea:3000/v2`。
- 确保 URI 和标头也被正确的传递（见上面的通用配置）
## 使用 Nginx 作为反向代理服务
如果您想使用 Nginx 作为 Gitea 的反向代理服务，您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分。
确保 `client_max_body_size` 足够大，否则在上传大文件时会出现 "client_max_body_size" 错误。
```nginx
server {
...
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分，为 Gitea 添加路由规则：
```nginx
server {
...
location ~ ^/(gitea|v2)($|/) {
client_max_body_size 512M;
# 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
rewrite ^ $request_uri;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
proxy_http_version 1.1;
# 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
## 使用 Nginx 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Nginx 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
Nginx 为提供静态内容进行了优化，而代理大响应可能与这一优化行为相反。
（见[https://serverfault.com/q/587386](https://serverfault.com/q/587386)）
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea`。
在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
### 单服务器节点，单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件，并配置 nginx：
```nginx
server {
listen 80;
server_name git.example.com;
location /_/static/assets/ {
alias /path/to/gitea/public/;
}
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
```
### 双服务器节点，双域名
将 `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` 写入您的 Gitea 配置文件，并配置 nginx：
```nginx
# 运行 Gitea 的服务器
server {
listen 80;
server_name git.example.com;
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
```
```nginx
# 提供静态资源的服务器
server {
listen 80;
server_name cdn.example.com;
location /gitea/ {
alias /path/to/gitea/public/;
}
location / {
return 404;
}
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
创建 `/` 自定义 location 时，只需在其配置中加入：
```nginx
client_max_body_size 512M;
```
在代理主机上启用 `Websockets Support`，Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
## 使用 Apache HTTPD 作为反向代理服务
如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
```apacheconf
<VirtualHost *:80>
...
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。
`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它，否则 Apache HTTPD 将无法启动。
:::
如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。
## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
:::
## 使用 Apache HTTPD 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
### 单服务器节点，单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
:::
## 使用 Caddy 作为反向代理服务
如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
```
git.example.com {
reverse_proxy localhost:3000
}
```
## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `Caddyfile` 文件中增加以下配置，为 Gitea 添加路由规则：
```
git.example.com {
route /git/* {
uri strip_prefix /git
reverse_proxy localhost:3000
}
}
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
## 使用 IIS 作为反向代理服务
如果您想使用 IIS 作为 Gitea 的反向代理服务，你需要为 IIS 设置 URL 重写来作为反向代理。
1. 在 IIS 中设置一个空网页，比如命名为 `Gitea Proxy`。
2. 根据[微软社区中为 IIS 设置 URL 重写的指南](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343)的前两步进行配置，也就是：
- 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing（简称 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
- 一但这个模块被安装到 IIS 上，你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
- 安装 Windows 功能 `WebSocket Protocol`，否则 ARR 无法代理 Gitea 的 WebSocket 端点。
- 打开 IIS 管理控制台，在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
- 在管理控制台的右边选择 `Add Rule` 操作，并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
- 在 Inbound Rules 中， 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如，如果你在 localhost 的 3000 端口上运行 Gitea，则设置为 `127.0.0.1:3000`。
- 启用 SSL Offloading
- 在 Outbound Rules 中，确保设置了 `Rewrite the domain names of the links in HTTP response`，并且将 `From:` 设置为上面的 server name，将 `To:` 设置为你的外部访问名称，例如：`git.example.com`
- 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理器中选择服务器节点，打开 `Application Request Routing Cache`，再打开右侧的 `Server Proxy Settings`）。若保持开启，ARR 会把 `Location` 头里的主机改回内部地址，导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
- 现在，根据下面的内容为您的网页编辑 `web.config`（将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值）
```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.web>
<httpRuntime requestPathInvalidCharacters="" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<hiddenSegments>
<clear />
</hiddenSegments>
<denyUrlSequences>
<clear />
</denyUrlSequences>
<fileExtensions allowUnlisted="true">
<clear />
</fileExtensions>
</requestFiltering>
</security>
<rewrite>
<rules useOriginalURLEncoding="false">
<rule name="ReverseProxyInboundRule1" stopProcessing="true">
<match url="(.*)" />
<action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
<serverVariables>
<set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
<set name="HTTP_ACCEPT_ENCODING" value="" />
</serverVariables>
</rule>
</rules>
<outboundRules>
<rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
<!-- set the pattern correctly here - if you only want to accept http or https -->
<!-- change the pattern and the action value as appropriate -->
<match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
<action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
</rule>
<rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
<match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
<action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
</rule>
<preConditions>
<preCondition name="ResponseIsHtml1">
<add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
</preCondition>
<preCondition name="NeedsRestoringAcceptEncoding">
<add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
</preCondition>
</preConditions>
</outboundRules>
</rewrite>
<urlCompression doDynamicCompression="true" />
<handlers>
<clear />
<add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
</handlers>
<!-- Map all extensions to the same MIME type, so all files can be
downloaded. -->
<staticContent>
<clear />
<mimeMap fileExtension="*" mimeType="application/octet-stream" />
</staticContent>
</system.webServer>
</configuration>
```
## 使用 HAProxy 作为反向代理服务
如果您想使用 HAProxy 作为 Gitea 的反向代理服务，您可以将下面的内容加入您的 HAProxy 配置。
在 frontend 部分加入一个 acl 来将对 gitea.example.com 的请求重定向到正确的后端。
```
frontend http-in
...
acl acl_gitea hdr(host) -i gitea.example.com
use_backend gitea if acl_gitea
...
```
添加之前定义好的 backend 部分
```
backend gitea
server localhost:3000 check
```
如果您将 http 内容重定向到 https，上面的配置文件也能够使用。只需要记住，在 HAProxy 和 Gitea 之间的连接将由 http 完成，所以你不需要在 Gitea 的配置文件中启用 https。
## 使用 HAProxy 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 HAProxy 中加入如下配置，为 Gitea 添加路由规则：
```
frontend http-in
...
acl acl_gitea path_beg /gitea
use_backend gitea if acl_gitea
...
```
在这个配置下，http://example.com/gitea/ 将被重定向到您的 Gitea 实例。
接下来，对于 backend 部分：
```
backend gitea
http-request replace-path /gitea\/?(.*) \/\1
server localhost:3000 check
```
添加的 http-request 在需要的时候会自动加入反斜杠/，并且通过将 http://example.com/gitea 正确设置为根来在内部路径中删除 /gitea，使其能够正常工作。
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
## 使用 Traefik 作为反向代理服务
如果您想使用 traefik 作为 Gitea 的反向代理服务，您可以在 `docker-compose.yaml` 中添加 label 部分（假设使用 docker 作为 traefik 的 provider）：
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
```
这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
## 使用 Traefik 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `docker-compose.yaml` 文件中增加以下配置，为 Gitea 添加路由规则（假设使用 docker 作为 traefik 的 provider）：
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
- "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
- "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
```
这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/search-engines-indexation.md
+30
View File
@@ -0,0 +1,30 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "search-engines-indexation"
sidebar_position: 60
aliases:
- /zh-cn/search-engines-indexation
---
# 搜索引擎索引
默认情况下，您的 Gitea 安装将被搜索引擎索引。
如果您不希望您的仓库对搜索引擎可见，请进一步阅读。
## 使用 robots.txt 阻止搜索引擎索引
为了使 Gitea 为顶级安装提供自定义的`robots.txt`（默认为空的 404），请在 [`custom`文件夹或`CustomPath`]（administration/customizing-gitea.md）中创建一个名为 `public/robots.txt` 的文件。
有关如何配置 `robots.txt` 的示例，请参考 [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt)。
```txt
User-agent: *
Disallow: /
```
如果您将 Gitea 安装在子目录中，则需要在顶级目录中创建或编辑 `robots.txt`。
```txt
User-agent: *
Disallow: /gitea/
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/signing.md
+137
View File
@@ -0,0 +1,137 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "signing"
sidebar_position: 50
aliases:
- /zh-cn/signing
---
# GPG 提交签名
Gitea 将通过检查提交是否由 Gitea 数据库中的密钥签名，或者提交是否与 Git 的默认密钥匹配，来验证提供的树中的 GPG 提交签名。
密钥不会被检查以确定它们是否已过期或撤销。密钥也不会与密钥服务器进行检查。
如果找不到用于验证提交的密钥，提交将被标记为灰色的未锁定图标。如果提交被标记为红色的未锁定图标，则表示它使用带有 ID 的密钥签名。
请注意：提交的签署者不必是提交的作者或提交者。
此功能要求 Git >= 1.7.9，但要实现全部功能，需要 Git >= 2.0.0。
## 自动签名
有许多地方 Gitea 会生成提交：
- 仓库初始化
- Wiki 更改
- 使用编辑器或 API 进行的 CRUD 操作
- 从合并请求进行合并
根据配置和服务器信任，您可能希望 Gitea 对这些提交进行签名。
## 安装和生成 Gitea 的 GPG 密钥
如何安装签名密钥由服务器管理员决定。Gitea 目前使用服务器的 `git` 命令生成所有提交，因此将使用服务器的 `gpg` 进行签名（如果配置了）。管理员应该审查 GPG 的最佳实践 - 特别是可能建议仅安装签名的子密钥，而不是主签名和认证的密钥。
## 通用配置
Gitea 的签名配置可以在 `app.ini` 的 `[repository.signing]` 部分找到：
```ini
...
[repository.signing]
SIGNING_KEY = default
SIGNING_NAME =
SIGNING_EMAIL =
INITIAL_COMMIT = always
CRUD_ACTIONS = pubkey, twofa, parentsigned
WIKI = never
MERGES = pubkey, twofa, basesigned, commitssigned
...
```
### `SIGNING_KEY`
首先讨论的选项是 `SIGNING_KEY`。有三个主要选项：
- `none` - 这将阻止 Gitea 对任何提交进行签名
- `default` - Gitea 将使用 `git config` 中配置的默认密钥
- `KEYID` - Gitea 将使用具有 ID `KEYID` 的 GPG 密钥对提交进行签名。在这种情况下，您应该提供 `SIGNING_NAME` 和 `SIGNING_EMAIL`，以便显示此密钥的信息。
`default` 选项将读取 `git config` 中的 `commit.gpgsign` 选项 - 如果设置了该选项，它将使用 `user.signingkey`、`user.name` 和 `user.email` 的结果。
通过在 Gitea 的仓库中调整 Git 的 `config` 文件，可以使用 `SIGNING_KEY=default` 为每个仓库提供不同的签名密钥。然而，这显然不是一个理想的用户界面，因此可能会发生更改。
:::warning
**自 1.17 起**，Gitea 在自己的主目录 `[git].HOME_PATH`（默认为 `%(APP_DATA_PATH)/home`）中运行 git，并使用自己的配置文件 `{[git].HOME_PATH}/.gitconfig`。
如果您有自己定制的 Gitea git 配置，您应该将这些配置设置在系统 git 配置文件中（例如 `/etc/gitconfig`）或者 Gitea 的内部 git 配置文件 `{[git].HOME_PATH}/.gitconfig` 中。
与 git 命令相关的主目录文件（如 `.gnupg`）也应该放在 Gitea 的 git 主目录 `[git].HOME_PATH` 中。
如果您希望将 `.gnupg` 目录放在 `{[git].HOME_PATH}/` 之外的位置，请考虑设置 `$GNUPGHOME` 环境变量为您首选的位置，否则 Gitea 将会从 `{[git].HOME_PATH}/.gnupg` 查找私钥。
:::
### `INITIAL_COMMIT`
此选项确定在创建仓库时，Gitea 是否应该对初始提交进行签名。可能的取值有：
- `never`：从不签名
- `pubkey`：仅在用户拥有公钥时进行签名
- `twofa`：仅在用户使用 2FA 登录时进行签名
- `always`：始终签名
除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
### `WIKI`
此选项确定 Gitea 是否应该对 Wiki 的提交进行签名。可能的取值有：
- `never`：从不签名
- `pubkey`：仅在用户拥有公钥时进行签名
- `twofa`：仅在用户使用 2FA 登录时进行签名
- `parentsigned`：仅在父提交已签名时进行签名。
- `always`：始终签名
除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
### `CRUD_ACTIONS`
此选项确定 Gitea 是否应该对 Web 编辑器或 API CRUD 操作的提交进行签名。可能的取值有：
- `never`：从不签名
- `pubkey`：仅在用户拥有公钥时进行签名
- `twofa`：仅在用户使用 2FA 登录时进行签名
- `parentsigned`：仅在父提交已签名时进行签名。
- `always`：始终签名
除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则更改将被签名。
### `MERGES`
此选项确定 Gitea 是否应该对 PR 的合并提交进行签名。可能的选项有：
- `never`：从不签名
- `pubkey`：仅在用户拥有公钥时进行签名
- `twofa`：仅在用户使用 2FA 登录时进行签名
- `basesigned`：仅在基础仓库中的父提交已签名时进行签名。
- `headsigned`：仅在头分支中的头提交已签名时进行签名。
- `commitssigned`：仅在头分支中的所有提交到合并点的提交都已签名时进行签名。
- `approved`：仅对已批准的合并到受保护分支的提交进行签名。
- `always`：始终签名
除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则合并将被签名。
## 获取签名密钥的公钥
用于签署 Gitea 提交的公钥可以通过 API 获取：
```sh
/api/v1/signing-key.gpg
```
在存在特定于仓库的密钥的情况下，可以通过以下方式获取：
```sh
/api/v1/repos/:username/:reponame/signing-key.gpg
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/contributing/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "贡献",
"position": 35,
"link": {
"type": "generated-index",
"slug": "/contributing",
"title": "贡献"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/contributing/guidelines-backend.md
+110
View File
@@ -0,0 +1,110 @@
---
date: "2023-05-25T23:41:00+08:00"
slug: "guidelines-backend"
sidebar_position: 20
aliases:
- /zh-cn/guidelines-backend
---
# 后端开发指南
## 背景
Gitea 使用 Golang 作为后端编程语言。它使用了许多第三方包，并且自己也编写了一些包。
例如，Gitea 使用[Chi](https://github.com/go-chi/chi)作为基本的 Web 框架。[Xorm](https://xorm.io)是一个用于与数据库交互的 ORM 框架。
因此，管理这些包非常重要。在开始编写后端代码之前，请参考以下准则。
## 包设计准则
### 包列表
为了保持易于理解的代码并避免循环依赖，拥有良好的代码结构是很重要的。Gitea 后端分为以下几个部分：
- `build`：帮助构建 Gitea 的脚本。
- `cmd`：包含所有 Gitea 的实际子命令，包括 web、doctor、serv、hooks、admin 等。`web`将启动 Web 服务。`serv`和`hooks`将被 Git 或 OpenSSH 调用。其他子命令可以帮助维护 Gitea。
- `tests`：常用的测试函数
- `tests/integration`：集成测试，用于测试后端回归。
- `tests/e2e`：端到端测试，用于测试前端和后端的兼容性和视觉回归。
- `models`：包含由 xorm 用于构建数据库表的数据结构。它还包含查询和更新数据库的函数。应避免与其他 Gitea 代码的依赖关系。在某些情况下，比如日志记录时可以例外。
- `models/db`：基本的数据库操作。所有其他`models/xxx`包都应依赖于此包。`GetEngine`函数只能从 models/中调用。
- `models/fixtures`：单元测试和集成测试中使用的示例数据。一个`yml`文件表示一个将在测试开始时加载到数据库中的表。
- `models/migrations`：存储不同版本之间的数据库迁移。修改数据库结构的 PR**必须**包含一个迁移步骤。
- `modules`：在 Gitea 中处理特定功能的不同模块。工作正在进行中：其中一些模块应该移到`services`中，特别是那些依赖于 models 的模块，因为它们依赖于数据库。
- `modules/setting`：存储从 ini 文件中读取的所有系统配置，并在各处引用。但是在可能的情况下，应将其作为函数参数使用。
- `modules/git`：用于与`Git`命令行或 Gogit 包交互的包。
- `public`：编译后的前端文件（JavaScript、图像、CSS 等）
- `routers`：处理服务器请求。由于它使用其他 Gitea 包来处理请求，因此其他包（models、modules 或 services）不能依赖于 routers。
- `routers/api`：包含`/api/v1`相关路由，用于处理 RESTful API 请求。
- `routers/install`：只能在系统处于安装模式（INSTALL_LOCK=false）时响应。
- `routers/private`：仅由内部子命令调用，特别是`serv`和`hooks`。
- `routers/web`：处理来自 Web 浏览器或 Git SMART HTTP 协议的 HTTP 请求。
- `services`：用于常见路由操作或命令执行的支持函数。使用`models`和`modules`来处理请求。
- `templates`：用于生成 HTML 输出的 Golang 模板。
### 包依赖关系
由于 Golang 不支持导入循环，我们必须仔细决定包之间的依赖关系。这些包之间有一些级别。以下是理想的包依赖关系方向。
`cmd` -> `routers` -> `services` -> `models` -> `modules`
从左到右，左侧的包可以依赖于右侧的包，但右侧的包不能依赖于左侧的包。在同一级别的子包中，可以根据该级别的规则进行依赖。
**注意事项**
为什么我们需要在`models`之外使用数据库事务？以及如何使用？
某些操作在数据库记录插入/更新/删除失败时应该允许回滚。
因此，服务必须能够创建数据库事务。以下是一些示例：
```go
// services/repository/repository.go
func CreateXXXX() error {
return db.WithTx(func(ctx context.Context) error {
// do something, if err is returned, it will rollback automatically
if err := issues.UpdateIssue(ctx, repoID); err != nil {
// ...
return err
}
// ...
return nil
})
}
```
在`services`中**不应该**直接使用`db.GetEngine(ctx)`，而是应该在`models/`下编写一个函数。
如果该函数将在事务中使用，请将`context.Context`作为函数的第一个参数。
```go
// models/issues/issue.go
func UpdateIssue(ctx context.Context, repoID int64) error {
e := db.GetEngine(ctx)
// ...
}
```
### 包名称
对于顶层包，请使用复数作为包名，例如`services`、`models`，对于子包，请使用单数，例如`services/user`、`models/repository`。
### 导入别名
由于有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，当这些包在一个 Go 文件中被导入时，很难知道我们使用的是哪个包以及它是变量名还是导入名。因此，我们始终建议使用导入别名。为了与常见的驼峰命名法的包变量区分开，建议使用**snake_case**作为导入别名的命名规则。
例如：`import user_service "code.gitea.io/gitea/services/user"`
### 重要注意事项
- 永远不要写成`x.Update(exemplar)`，而没有明确的`WHERE`子句：
- 这将导致表中的所有行都被使用 exemplar 的非零值进行更新，包括 ID。
- 通常应该写成`x.ID(id).Update(exemplar)`。
- 如果在迁移过程中使用`x.Insert(exemplar)`向表中插入记录，而 ID 是预设的：
- 对于 MSSQL 变体，你将需要执行`` SET IDENTITY_INSERT `table` ON ``（否则迁移将失败）
- 对于 PostgreSQL，你还需要更新 ID 序列，否则迁移将悄无声息地通过，但后续的插入将失败：
`` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
### 未来的任务
目前，我们正在进行一些重构，以完成以下任务：
- 纠正不符合规则的代码。
- `models`中的文件太多了，所以我们正在将其中的一些移动到子包`models/xxx`中。
- 由于它们依赖于`models`，因此应将某些`modules`子包移动到`services`中。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/contributing/guidelines-frontend.md
+149
View File
@@ -0,0 +1,149 @@
---
date: "2023-05-25T16:00:00+02:00"
slug: "guidelines-frontend"
sidebar_position: 20
aliases:
- /zh-cn/guidelines-frontend
---
# 前端开发指南
## 背景
Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
源文件可以在以下目录中找到：
- **CSS 样式**： `web_src/css/`
- **JavaScript 文件**： `web_src/js/`
- **Vue 组件**： `web_src/js/components/`
- **Go HTML 模板**： `templates/`
## 通用准则
我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
## Gitea 特定准则
1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
2. HTML 的 id 和 class 应使用 kebab-case，最好包含 2-3 个与功能相关的关键词。
3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含 2-3 个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有 2-3 个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
11. 推荐使用自定义事件名称前缀`ce-`。
12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-ellipsis`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。
13. 尽量避免内联脚本和样式，建议将 JS 代码放入 JS 文件中并使用 CSS 类。如果内联脚本和样式不可避免，请解释无法避免的原因。
### 可访问性 / ARIA
在历史上，Gitea 大量使用了可访问性不友好的框架 Fomantic UI。
Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`），
但仍然存在许多问题需要大量的工作和时间来修复。
### 框架使用
不建议混合使用不同的框架，这会使代码难以维护。
一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
推荐的实现方式：
- Vue + Vanilla JS
- Fomantic-UI（jQuery）
- htmx （部分页面重新加载其他静态组件）
- Vanilla JS
不推荐的实现方式：
- Vue + Fomantic-UI（jQuery）
- jQuery + Vanilla JS
- htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
尽管不建议混合使用不同的框架，
我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例，其中应使用 htmx。如果您需要更高级的反应性，请不要使用 htmx，请使用其他框架（Vue/Vanilla JS）。
但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
### `async` 函数
只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
不建议使用`async`事件监听器，这可能会导致问题。
原因是`await`后的代码在事件分发之外执行。
参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
建议将其放在函数的开头。
如果我们想在非异步上下文中调用`async`函数，
建议使用`const _promise = asyncFoo()`来告诉读者
这是有意为之的，我们想调用异步函数并忽略 Promise。
一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
### 获取数据
要获取数据，请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
接受内容的`data`选项，将自动设置 CSRF 令牌并返回
[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
### HTML 属性和 dataset
禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
然而，仍然存在一些特殊情况，因此当前的准则是：
- 对于旧代码：
- 应将`$.data()`重构为`$.attr()`。
- 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
- 对于新代码：
- 不应使用`node.dataset`，而应使用`node.getAttribute`。
- 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
### 显示/隐藏元素
- 推荐在 Vue 组件中使用`v-if`和`v-show`来显示/隐藏元素。
- Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
### Go HTML 模板中的样式和属性
建议使用以下方式：
```html
<div
class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
{{if
.IsFoo}}data-foo{{end}}
></div>
```
而不是：
```html
<div
class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
{{if
.IsFoo}}
data-foo{{end}}
></div>
```
以使代码更易读。
### 旧代码
许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
### Vue3 和 JSX
Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。
### UI 示例
Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/contributing/guidelines-refactoring.md
+40
View File
@@ -0,0 +1,40 @@
---
date: "2023-05-25T00:00:00+00:00"
slug: "guidelines-refactoring"
sidebar_position: 20
aliases:
- /zh-cn/guidelines-refactoring
---
# 重构指南
## 背景
自 2014 年 2 月 12 日编写了第一行代码以来，Gitea 已经发展成为一个庞大的项目。
因此，代码库变得越来越大。代码库越大，维护就越困难。
存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
为了使代码库更易于维护，使 Gitea 变得更好，开发人员应牢记使用现代机制来重构旧代码。
本文档是关于重构代码库的指南集合。
## 重构建议
- 设计更多关于未来的内容，而不仅仅解决当前问题。
- 减少模糊性，减少冲突，提高可维护性。
- 描述重构，例如：
- 为什么需要重构。
- 如何解决旧问题。
- 重构的优点/缺点是什么。
- 只做必要的更改，尽量保留旧逻辑。
- 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
- 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
- 添加必要的测试以确保重构的正确性。
- 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
## 审查和合并建议
- 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
- 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
- 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
- 如果最终结果良好，容忍一些不完美/临时的步骤。
- 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/contributing/localization.md
+25
View File
@@ -0,0 +1,25 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "localization"
sidebar_position: 70
aliases:
- /zh-cn/localization
---
# 本地化
Gitea 的本地化是通过我们的[Crowdin 项目](https://crowdin.com/project/gitea)进行的。
对于对**英语翻译**的更改，可以发出 pull-request，来更改[英语语言环境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合适的关键字。
有关对**非英语**翻译的更改，请参阅上面的 Crowdin 项目。
## 支持的语言
上述 Crowdin 项目中列出的任何语言一旦翻译了 25% 或更多都将得到支持。
翻译被接受后，它将在下一次 Crowdin 同步后反映在主存储库中，这通常是在任何 PR 合并之后。
在撰写本文时，这意味着更改后的翻译可能要到 Gitea 的下一个版本才会出现。
如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "开发",
"position": 40,
"link": {
"type": "generated-index",
"slug": "/development",
"title": "开发"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/api-usage.md
+64
View File
@@ -0,0 +1,64 @@
---
date: "2018-06-24:00:00+02:00"
slug: "api-usage"
sidebar_position: 40
aliases:
- /zh-cn/api-usage
---
# API 使用指南
## 开启/配置 API 访问
通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
<a id="authentication"></a>
## 通过 API 认证
Gitea 支持以下几种 API 认证方式：
- HTTP basic authentication 方式
- 通过指定 `token=...` URL 查询参数方式
- 通过指定 `access_token=...` URL 查询参数方式
- 通过指定 `Authorization: token ...` HTTP header 方式
以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
您可以通过您的 gitea web 界面来创建 apiKey token：
`Settings | Applications | Generate New Token`.
### 关于 `Authorization:` header
由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
```
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
```
以 `curl` 命令为例，它会以如下形式携带在请求中：
```
curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
-H "accept: application/json" \
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
-H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
```
正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
## 通过 API 列出您发布的令牌
`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
### 使用 Basic authentication 认证
```
$ curl --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
```
## 使用 Sudo 方式请求 API
此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/hacking-on-gitea.md
+334
View File
@@ -0,0 +1,334 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "hacking-on-gitea"
sidebar_position: 10
aliases:
- /zh-cn/hacking-on-gitea
---
# 玩转 Gitea
## 快速入门
要获得快速工作的开发环境，您可以使用 Gitpod。
[![在 Gitpod 中打开](/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
## 安装 Golang
您需要 [安装 go](https://go.dev/doc/install) 并设置您的 go 环境。
接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建
JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 @minNodeVersion@
并且推荐使用最新的 LTS 版本。
**注意** ：当执行需要外部工具的 make 任务时，比如
`make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须
将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把 go bin 目录添加到可执行路径你必须手动
指定可执行程序路径。
**注意 2** ：Go 版本 @minGoVersion@ 或更高版本是必须的。Gitea 使用 `gofmt` 来
格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用
的 Go 版本。截至上次更新，Go 版本应该是 @goVersion@。
## 安装 Make
Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。
### 在 Linux 上
使用包管理器安装。
在 Ubuntu/Debian 上：
```bash
sudo apt-get install make
```
在 Fedora/RHEL/CentOS 上：
```bash
sudo yum install make
```
### 在 Windows 上
Make 的这三个发行版都可以在 Windows 上运行：
- [单个二进制构建](http://www.equation.com/servlet/equation.cmd?fa=make)。复制到某处并添加到 `PATH`。
- [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe)
- [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe)
- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。
- MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。
- 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。
- 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。
- 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 \_beginthread 一样。
- [Chocolatey 包管理器](https://chocolatey.org/packages/make)。运行`choco install make`
**注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。
## 下载并克隆 Gitea 源代码
获取源代码的推荐方法是使用 `git clone`。
```bash
git clone https://github.com/go-gitea/gitea
```
（自从 go modules 出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。）
## 派生 Gitea
如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)，
并为您的本地仓库切换 git 远程源，或添加另一个远程源：
```bash
# 将原来的 Gitea origin 重命名为 upstream
git remote rename origin upstream
git remote add origin "[email protected]:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
```
或者：
```bash
# 为我们的 fork 添加新的远程
git remote add "$FORK_NAME" "[email protected]:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
```
为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。
## 构建 Gitea（基本）
看看我们的
[说明](installation/from-source.md)
关于如何[从源代码构建](installation/from-source.md) 。
从源代码构建的最简单推荐方法是：
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
`build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。
有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。
## 持续构建
要在源文件更改时运行并持续构建：
```bash
# 对于前端和后端
make watch
# 或者：只看前端文件（html/js/css）
make watch-frontend
# 或者：只看后端文件 (go)
make watch-backend
```
在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。
### 格式化、代码分析和拼写检查
我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。
你应该格式化你的代码：
```bash
make fmt
```
并检查源代码：
```bash
# lint 前端和后端代码
make lint
# 仅 lint 后端代码
make lint-backend
```
**注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。
### 处理 JS 和 CSS
前端开发应遵循 [Guidelines for Frontend Development](contributing/guidelines-frontend.md)。
要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次：
```bash
make build && ./gitea
```
在提交之前，确保 linters 通过：
```bash
make lint-frontend
```
### 配置本地 ElasticSearch 实例
使用 docker 启动本地 ElasticSearch 实例：
```sh
mkdir -p $(pwd) /data/elasticsearch
sudo chown -R 1000:1000 $(pwd) /data/elasticsearch
docker run --rm --memory= "4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data /elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
```
配置`app.ini`：
```ini
[indexer]
ISSUE_INDEXER_TYPE = elasticsearch
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
REPO_INDEXER_ENABLED = true
REPO_INDEXER_TYPE = elasticsearch
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
```
### 构建和添加 SVGs
SVG 图标是使用 `make svg` 命令构建的，该命令将图标资源编译到输出目录 `public/assets/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。
### 构建 Logo
Gitea Logo 的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。
通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。
### 更新 API
创建新的 API 路由或修改现有的 API 路由时，您**必须**
更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
这些使用 [go-swagger](https://goswagger.io/) 评论的文档。
[规范](https://goswagger.io/use/spec.html#annotation-syntax)中描述了这些注释的结构。
如果您想了解更多有关 Swagger 结构的信息，可以查看
[Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除
或对 API 进行根本性更改将会被拒绝。
创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档：
```bash
make generate-swagger
```
您应该验证生成的 Swagger 文件：
```bash
make swagger-validate
```
您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成：
```bash
make swagger-check
```
**注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。
### 创建新的配置选项
创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
并到[配置备忘单](../administration/config-cheat-sheet.md)
在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
### 更改 Logo
更改 Gitea Logo SVG 时，您将需要运行并提交结果的：
```bash
make generate-images
```
这将创建必要的 Gitea 图标和其他图标。
### 数据库迁移
如果您对数据库中的任何数据库持久结构进行重大更改
`models/` 目录，您将需要进行新的迁移。可以找到这些
在 `models/migrations/` 中。您可以确保您的迁移适用于主要
数据库类型使用：
```bash
make test-sqlite-migration # 将 SQLite 切换为适当的数据库
```
## 测试
Gitea 运行两种类型的测试：单元测试和集成测试。
### 单元测试
`go test` 系统中的`*_test.go` 涵盖了单元测试。
您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
```
### 集成测试
单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
```
将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但
可能需要适应当地环境。
看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。
### 测试 PR
我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。
还将测试从几个最新版本的 Gitea 迁移。
请在 PR 中附带提交适当的单元测试和集成测试。
## 网站文档
该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成：
```bash
make lint-md
```
## Visual Studio Code
`contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看
[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。
## Goland
单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头
可以快速启动一个可调试的 Gitea 实例。
`Run/Debug Configuration` 中的 `Output Directory` 必须设置为
gitea 项目目录（包含 `main.go` 和 `go.mod`），
否则，启动实例的工作目录是 GoLand 的临时目录
并防止 Gitea 在开发环境中加载动态资源（例如：模板）。
要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify`
在 `运行/调试配置` 的 `Go 工具参数` 中。
## 提交 PR
对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR
分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。
任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的
[CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
文档。
如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道
并在那里聊天。
现在，您已准备好 Hacking Gitea。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/integrations.md
+37
View File
@@ -0,0 +1,37 @@
---
date: "2023-05-25T17:29:00+08:00"
slug: "integrations"
sidebar_position: 65
aliases:
- /zh-cn/integrations
---
# 集成
Gitea 拥有一个出色的第三方集成社区，以及在其他各种项目中的一流支持。
我们正在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)上整理一个列表来跟踪这些集成！
如果你正在寻找[CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)，
一个[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk)，
甚至一些额外的[主题](https://gitea.com/gitea/awesome-gitea#user-content-themes)，
你可以在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)中找到它们的列表！
## 预填新文件名和内容
如果你想打开一个具有给定名称和内容的新文件，
你可以使用查询参数来实现：
```txt
GET /{{org}}/{{repo}}/_new/{{filepath}}
?filename={{filename}}
&value={{content}}
```
例如：
```txt
GET https://git.example.com/johndoe/bliss/_new/articles/
?filename=hello-world.md
&value=Hello%2C%20World!
```
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/migrations.md
+31
View File
@@ -0,0 +1,31 @@
---
date: "2023-05-25T17:29:00+08:00"
slug: "migrations-interfaces"
sidebar_position: 55
aliases:
- /zh-cn/migrations-interfaces
---
# 迁移接口
完整迁移功能在 Gitea 1.9.0 版本中引入。它定义了两个接口，用于支持从其他 Git 托管平台迁移存储库数据到 Gitea，或者在将来将 Gitea 数据迁移到其他 Git 托管平台。
目前已实现了从 GitHub、GitLab 和其他 Gitea 实例的迁移。
首先，Gitea 在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
## 下载器接口
要从新的 Git 托管平台迁移，需要进行两个步骤的更新。
- 您应该实现一个`Downloader`，用于获取存储库信息。
- 您应该实现一个`DownloaderFactory`，用于检测 URL 是否匹配，并创建上述的`Downloader`。
- 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
## 上传器接口
目前，只实现了`GiteaLocalUploader`，因此我们只能通过此 Uploader 将下载的数据保存到本地的 Gitea 实例。目前不支持其他上传器。
您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/development/oauth2-provider.md
+128
View File
@@ -0,0 +1,128 @@
---
date: "2019-04-19:44:00+01:00"
slug: "oauth2-provider"
sidebar_position: 41
aliases:
- /zh-cn/oauth2-provider
---
# OAuth2 提供者
Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版起可用。
## 端点
| 端点 | URL |
| ------------------------ | ----------------------------------- |
| OpenID Connect Discovery | `/.well-known/openid-configuration` |
| Authorization Endpoint | `/login/oauth/authorize` |
| Access Token Endpoint | `/login/oauth/access_token` |
| OpenID Connect UserInfo | `/login/oauth/userinfo` |
| JSON Web Key Set | `/login/oauth/keys` |
## 支持的 OAuth2 授权
目前 Gitea 仅支持 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 标准，并额外支持以下扩展：
- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
要将 Authorization Code Grant 作为第三方应用程序，您需要通过在设置中添加一个新的 "应用程序" (`/user/settings/applications`)。
## 范围
Gitea 支持以下令牌范围:
| 名称 | 介绍 |
| ---------------------------------------- | --------------------------------------------------------------- |
| **(no scope)** | 授予对公共用户配置文件和公共存储库的只读访问权限 |
| **repo** | 完全控制所有存储库 |
| &nbsp;&nbsp;&nbsp; **repo:status** | 授予对所有存储库中提交状态的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **public_repo** | 仅授予对公共存储库的读/写访问权限 |
| **admin:repo_hook** | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
| &nbsp;&nbsp;&nbsp; **write:repo_hook** | 授予对存储库 Hooks 的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:repo_hook** | 授予对存储库 Hooks 的只读访问权限 |
| **admin:org** | 授予对组织设置的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **write:org** | 授予对组织设置的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:org** | 授予对组织设置的只读访问权限 |
| **admin:public_key** | 授予公钥管理的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **write:public_key** | 授予对公钥的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:public_key** | 授予对公钥的只读访问权限 |
| **admin:org_hook** | 授予对组织级别 Hooks 的完全访问权限 |
| **admin:user_hook** | 授予对用户级别 Hooks 的完全访问权限 |
| **notification** | 授予对通知的完全访问权限 |
| **user** | 授予对用户个人资料信息的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **read:user** | 授予对用户个人资料的读取权限 |
| &nbsp;&nbsp;&nbsp; **user:email** | 授予对用户电子邮件地址的读取权限 |
| &nbsp;&nbsp;&nbsp; **user:follow** | 授予访问权限以关注/取消关注用户 |
| **delete_repo** | 授予删除存储库的权限 |
| **package** | 授予对托管包的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **write:package** | 授予对包的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:package** | 授予对包的读取权限 |
| &nbsp;&nbsp;&nbsp; **delete:package** | 授予对包的删除权限 |
| **admin:gpg_key** | 授予 GPG 密钥管理的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **write:gpg_key** | 授予对 GPG 密钥的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:gpg_key** | 授予对 GPG 密钥的只读访问权限 |
| **admin:application** | 授予应用程序管理的完全访问权限 |
| &nbsp;&nbsp;&nbsp; **write:application** | 授予应用程序管理的读/写访问权限 |
| &nbsp;&nbsp;&nbsp; **read:application** | 授予应用程序管理的读取权限 |
| **sudo** | 允许以站点管理员身份执行操作 |
## 客户端类型
Gitea 支持私密和公共客户端类型，[参见 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
对于公共客户端, 允许在本地回环地址的重定向 URI 中使用任意端口，例如 `http://127.0.0.1/`。根据 [RFC 8252 的建议](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)，请避免使用 `localhost`。
## 示例
**注意：** 该示例中尚未使用 PKCE。
1. 将用户重定向到授权端点，以获得他们的访问资源授权:
```curl
https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
```
在设置中注册应用程序以获得 `CLIENT_ID`。`STATE` 是一个随机字符串，它将在获得用户授权后发送回您的应用程序。`state` 参数是可选的，但您应该使用它来防止 CSRF 攻击。
![Authorization Page](/authorize.png)
用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `REDIRECT_URL`，例如：
```curl
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
```
2. 使用重定向提供的 `code`，您可以请求一个新的应用程序和 Refresh Token。Access Token Endpoint 接受 `application/json` 或 `application/x-www-form-urlencoded` 类型的 POST 请求，例如：
```curl
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
```
```json
{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "RETURNED_CODE",
"grant_type": "authorization_code",
"redirect_uri": "REDIRECT_URI"
}
```
返回：
```json
{
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
}
```
`CLIENT_SECRET` 是生成给应用程序的唯一密钥。请注意，该密钥只会在您使用 Gitea 创建/注册应用程序后出现一次。如果您丢失了密钥，您必须在应用程序设置中重新生成密钥。
`access_token` 请求中的 `REDIRECT_URI` 必须与 `authorize` 请求中的 `REDIRECT_URI` 相符。
3. 使用 `access_token` 来构造 [API 请求](development/api-usage.md#oauth2-provider) 以读写用户的资源。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/help/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "帮助",
"position": 5,
"link": {
"type": "generated-index",
"slug": "/help",
"title": "帮助"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/help/faq.md
+433
View File
@@ -0,0 +1,433 @@
---
date: "2023-05-25T16:00:00+02:00"
slug: "faq"
sidebar_position: 5
aliases:
- /zh-cn/faq
---
# 常见问题
本页面包含一些常见问题和答案。
有关更多帮助资源，请查看所有[支持选项](help/support.md)。
## 1.x 和 1.x.x 下载之间的区别
以 1.7.x 版本为例。
**注意：**此示例也适用于 Docker 镜像！
在我们的[下载页面](https://dl.gitea.com/gitea/)上，您会看到一个 1.7 目录，以及 1.7.0、1.7.1、1.7.2、1.7.3、1.7.4、1.7.5 和 1.7.6 的目录。
1.7 目录和 1.7.0 目录是**不同**的。1.7 目录是在每个合并到[`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7)分支的提交上构建的。
然而，1.7.0 目录是在创建[`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0)标签时创建的构建。
这意味着 1.x 的下载会随着提交合并到各自的分支而改变（将其视为每个版本的单独的“main”分支）。
另一方面，1.x.x 的下载应该永远不会改变。
## 如何从 Gogs/GitHub 等迁移到 Gitea
要从 Gogs 迁移到 Gitea：
- [Gogs 版本 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
要从 GitHub 迁移到 Gitea，您可以使用 Gitea 内置的迁移表单。
为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。
[Example (requires login)](https://demo.gitea.com/repo/migrate)
要从 GitLab 迁移到 Gitea，您可以使用这个非关联的工具：
https://github.com/loganinak/MigrateGitlabToGogs
## Gitea 存储文件的位置
- _`AppWorkPath`_
- `--work-path`标志
- 或者环境变量`GITEA_WORK_DIR`
- 或者在构建时设置的内置值
- 或者包含 Gitea 二进制文件的目录
- `%(APP_DATA_PATH)`（数据库、索引器等的默认路径）
- `app.ini`中的`APP_DATA_PATH`
- 或者*`AppWorkPath`*`/data`
- _`CustomPath`_（自定义模板）
- `--custom-path`标志
- 或者环境变量`GITEA_CUSTOM`
- 或者在构建时设置的内置值
- 或者*`AppWorkPath`*`/custom`
- HomeDir
- Unix：环境变量`HOME`
- Windows：环境变量`USERPROFILE`，或者环境变量`HOMEDRIVE`+`HOMEPATH`
- RepoRootPath
- `app.ini`中\[repository]部分的`ROOT`（如果是绝对路径）
- 否则*`AppWorkPath`*`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相对路径）
- 默认值为`%(APP_DATA_PATH)/gitea-repositories`
- INI（配置文件）
- `--config`标志
- 或者在构建时设置的可能内置值
- 或者 _`CustomPath`_`/conf/app.ini`
- SQLite 数据库
- app.ini 中 database 部分的 PATH
- 或者`%(APP_DATA_PATH)/gitea.db`
## 看不到克隆 URL 或克隆 URL 不正确
有几个地方可能会导致显示不正确。
1. 如果使用反向代理，请确保按照[反向代理指南](../administration/reverse-proxies.md)中的正确说明进行设置。
2. 确保在`app.ini`的`server`部分中正确设置了`ROOT_URL`。
如果某些克隆选项未显示（HTTP/S 或 SSH），可以在`app.ini中`
- `DISABLE_HTTP_GIT`: 如果设为 true, 将会没有 HTTP/HTTPS 链接
- `DISABLE_SSH`: 如果设为 true, 将会没有 SSH 链接
- `SSH_EXPOSE_ANONYMOUS`: 如果设为 false, SSH 链接将会对匿名用户隐藏
## 文件上传失败：413 Request Entity Too Large
当反向代理限制文件上传大小时，会出现此错误。
有关使用 nginx 解决此问题，请参阅[反向代理指南](../administration/reverse-proxies.md)。
## 自定义模板无法加载或运行错误
Gitea 的自定义模板必须将其添加到正确的位置，否则 Gitea 将无法找到并使用自定义模板。
模板的正确路径应该相对于`CustomPath`。
1. 要找到`CustomPath`，请在站点管理 -> 配置 中查找自定义文件根路径。
如果找不到，请尝试`echo $GITEA_CUSTOM`。
2. 如果仍然找不到，默认值可以被[计算](faq.md#Gitea存储文件的位置)
3. 如果仍然找不到路径，则可以参考[自定义 Gitea](../administration/customizing-gitea.md)页面，将模板添加到正确的位置。
## Gitea 是否有"GitHub/GitLab Pages"功能？
Gitea 不提供内置的 Pages 服务器。您需要一个专用的域名来提供静态页面，以避免 CSRF 安全风险。
对于简单的用法，您可以使用反向代理来重写和提供 Gitea 的原始文件 URL 中的静态内容。
还有一些已经可用的第三方服务，比如独立[pages server](https://codeberg.org/Codeberg/pages-server)的或[caddy plugin](https://github.com/42wim/caddy-gitea)，可以提供所需的功能。
## 活跃用户与禁止登录用户
在 Gitea 中，"活跃用户"是指通过电子邮件激活其帐户的用户。
"禁止登录用户"是指不允许再登录到 Gitea 的用户。
## 设置日志记录
- [官方文档](../administration/logging-config.md)
## 什么是 Swagger？
[Swagger](https://swagger.io/) 是 Gitea 用于其 API 文档的工具。
所有 Gitea 实例都有内置的 API，无法完全禁用它。
但是，您可以在 app.ini 的 api 部分将 ENABLE_SWAGGER 设置为 false，以禁用其文档显示。
有关更多信息，请参阅 Gitea 的[API 文档](development/api-usage.md)。
您可以在上查看最新的 API（例如）https://gitea.com/api/swagger
您还可以在上查看`swagger.json`文件的示例 https://gitea.com/swagger.v1.json
## 调整服务器用于公共/私有使用
### 防止垃圾邮件发送者
有多种方法可以组合使用来防止垃圾邮件发送者：
1. 通过设置电子邮件域名的白名单或黑名单。
2. 通过设置一些域名或者 OpenID 白名单（见下文）。
3. 在您的`app.ini`中将`ENABLE_CAPTCHA`设置为`true`，并正确配置`RECAPTCHA_SECRET`和 `RECAPTCHA_SITEKEY`。
4. 将`DISABLE_REGISTRATION`设置为`true`，并通过 [CLI](../administration/command-line.md)、[API](development/api-usage.md) 或 Gitea 的管理界面创建新用户。
### 仅允许/阻止特定的电子邮件域名
您可以在`app.ini`中的`[service]`下的配置`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
### 仅允许/阻止特定的 OpenID 提供商
您可以在`app.ini`的`[openid]`下配置`WHITELISTED_URI`或`BLACKLISTED_URIS`。
**注意**： 白名单优先，如果白名单非空，则忽略黑名单。
### 仅允许发布问题的用户
目前实现这一点的方法是创建/修改一个具有最大仓库创建限制为 0 的用户。
### 受限制的用户
受限制的用户仅能访问其组织/团队成员和协作所在的内容的子集，而忽略组织/仓库等的公共标志。
示例用例：一个公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。
在某些情况下，某个客户或第三方需要访问特定的仓库，并且只能访问该仓库。通过将此类客户帐户设置为受限制帐户，并使用团队成员身份和/或协作来授予所需的任何访问权限，可以简单地实现这一点，而无需使所有内容都变为私有。
### 启用 Fail2ban
使用 [Fail2Ban](../administration/fail2ban-setup.md) 监视并阻止基于日志模式的自动登录尝试或其他恶意行为。
## SSHD vs 内建 SSH
SSHD 是大多数 Unix 系统上内建的 SSH 服务器。
Gitea 还提供了自己的 SSH 服务器，用于在 SSHD 不可用时使用。
## Gitea 运行缓慢
导致此问题的最常见原因是加载联合头像。
您可以通过在`app.ini`中将`ENABLE_FEDERATED_AVATAR`设置为`false`来关闭此功能。
还有一个可能需要更改的选项是在`app.ini`中将`DISABLE_GRAVATAR`设置为`true`。
## 无法创建仓库/文件
请确保 Gitea 具有足够的权限来写入其主目录和数据目录。
参见[AppDataPath 和 RepoRootPath](faq.md#Gitea存储文件的位置)
**适用于 Arch 用户的注意事项：**在撰写本文时，Arch 软件包的 systemd 文件包含了以下行：
`ReadWritePaths=/etc/gitea/app.ini`
这将使得 Gitea 无法写入其他路径。
## 翻译不正确/如何添加更多翻译
我们当前的翻译是在我们的[Crowdin 项目](https://crowdin.com/project/gitea)上众包进行的
无论您想要更改翻译还是添加新的翻译，都需要在 Crowdin 集成中进行，因为所有翻译都会被 CI 覆盖。
## 推送钩子/ Webhook / Actions 未运行
如果您可以推送但无法在主页仪表板上看到推送活动，或者推送不触发 Webhook 和 Actions，可能是 git 钩子不工作而导致的。
这可能是由于以下原因：
1. Git 钩子不同步：在站点管理面板上运行“重新同步所有仓库的 pre-receive、update 和 post-receive 钩子”
2. Git 仓库（和钩子）存储在一些不支持脚本执行的文件系统上（例如由 NAS 挂载），请确保文件系统支持`chmod a+x any-script`
3. 如果您使用的是 Docker，请确保 Docker Server（而不是客户端）的版本 >= 20.10.6
## SSH 问题
如果无法通过`ssh`访问仓库，但`https`正常工作，请考虑以下情况。
首先，请确保您可以通过 SSH 访问 Gitea。
`ssh [email protected]`
如果连接成功，您应该会收到以下错误消息：
```
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.
```
如果您收到以上消息但仍然连接成功，这意味着您的 SSH 密钥**没有**由 Gitea 管理。这意味着钩子不会运行，在其他一些潜在问题中也包括在内。
如果您无法连接，可能是因为您的 SSH 密钥在本地配置不正确。
这是针对 SSH 而不是 Gitea 的问题，因此在此不涉及。
### SSH 常见错误
```
Permission denied (publickey).
fatal: Could not read from remote repository.
```
此错误表示服务器拒绝登录尝试，
请检查以下事项：
- 在客户端：
- 确保公钥和私钥已添加到正确的 Gitea 用户。
- 确保远程 URL 中没有任何问题。特别是，请确保 ∂
Git 用户（@ 之前的部分）的名称拼写正确。
- 确保客户端机器上的公钥和私钥正确无误。
- 在服务器上：
- 确保存储库存在并且命名正确。
- 检查系统用户主目录中的 `.ssh` 目录的权限。
- 验证正确的公钥是否已添加到 `.ssh/authorized_keys` 中。
尝试在 Gitea 管理面板上运行
`Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
- 查看 Gitea 日志。
- 查看 /var/log/auth（或类似的文件）。
- 检查存储库的权限。
以下是一个示例，其中缺少公共 SSH 密钥，
认证成功，但是其他设置导致 SSH 无法访问正确的
存储库。
```
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
```
在这种情况下，请检查以下设置：
- 在服务器上：
- 确保`git`系统用户设置了可用的 shell
- 使用`getent passwd git | cut -d: -f7`进行验证
- 可以使用`usermod`或`chsh`进行修改。
- 确保`.ssh/authorized_keys`中的`gitea serv`命令使用
正确的配置文件。
## 迁移带有标签的存储库后缺失发布版本
要迁移带有所有标签的存储库，您需要执行两个操作：
- 推送标签到存储库：
```
git push --tags
```
- 在 Gitea 中重新同步所有存储库的标签：
```
gitea admin repo-sync-releases
```
## LFS 问题
针对涉及 LFS 数据上传的问题
```
batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'
```
检查`app.ini`文件中的`LFS_HTTP_AUTH_EXPIRY`值。
默认情况下，LFS 令牌在 20 分钟后过期。如果您的连接速度较慢或文件较大（或两者都是），可能无法在时间限制内完成上传。
您可以将此值设置为`60m`或`120m`。
## 如何在启动 Gitea 之前创建用户
Gitea 提供了一个子命令`gitea migrate`来初始化数据库，然后您可以使用[管理 CLI 命令](../administration/command-line.md#admin)像正常情况下添加用户。
## 如何启用密码重置
没有密码重置的设置。当配置了[邮件服务](../administration/email-setup.md)时，密码重置将自动启用；否则将被禁用。
## 如何更改用户的密码
- 作为管理员，您可以更改任何用户的密码（并可选择强制其在下次登录时更改密码）...
- 转到您的`站点管理 -> 用户账户`页面并编辑用户。
- 使用[管理 CLI 命令](../administration/command-line.md#admin)。
请注意，大多数命令还需要一个[全局标志](../administration/command-line.md#全局选项)来指向正确的配置。
- 作为**用户**，您可以更改密码...
- 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
- 使用`忘记密码`链接。
如果`忘记密码/账户恢复`页面被禁用，请联系管理员配置[邮件服务](../administration/email-setup.md)。
## 为什么我的 Markdown 显示错误
在 Gitea 版本 `1.11` 中，我们转换为使用[goldmark](https://github.com/yuin/goldmark)进行 Markdown 渲染，它符合[CommonMark](https://commonmark.org/)标准。
如果您在版本`1.11`之前的 Markdown 正常工作，但在升级后无法正常工作，请仔细阅读 CommonMark 规范，看看问题是由错误还是非兼容的语法引起的。
如果是后者，通常规范中会列出一种符合标准的替代方法。
## 使用 MySQL 进行升级时出现的错误
如果在使用 MySQL 升级 Gitea 时收到以下错误：
> `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...`
请运行 `gitea doctor convert` 或对数据库中的每个表运行 `ALTER TABLE table_name ROW_FORMAT=dynamic;`。
潜在问题是默认行格式分配给每个表的索引空间
太小。Gitea 要求其表的`ROWFORMAT`为`DYNAMIC`。
如果收到包含`Error 1071: Specified key was too long; max key length is 1000 bytes...`
的错误行，则表示您正在尝试在使用 ISAM 引擎的表上运行 Gitea。尽管在先前版本的 Gitea 中可能是凑巧能够工作的，但它从未得到官方支持，
您必须使用 InnoDB。您应该对数据库中的每个表运行`ALTER TABLE table_name ENGINE=InnoDB;`。
## 为什么 Emoji 只显示占位符或单色图像
Gitea 需要系统或浏览器安装其中一个受支持的 Emoji 字体，例如 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系统应该已经提供了其中一个字体，但特别是在 Linux 上，可能需要手动安装它们。
## SystemD 和 Docker 上的标准输出日志
SystemD 上的标准输出默认会写入日志记录中。您可以尝试使用 `journalctl`、`journalctl -u gitea` 或 `journalctl <path-to-gitea-binary>`来查看。
类似地，Docker 上的标准输出可以使用`docker logs <container>`来查看。
要收集日志以进行帮助和问题报告，请参阅[支持选项](help/support.md)。
## 初始日志记录
在 Gitea 读取配置文件并设置其日志记录之前，它会将一些内容记录到标准输出，以帮助调试日志记录无法工作的情况。
您可以通过设置`--quiet`或`-q`选项来停止此日志记录。请注意，这只会在 Gitea 设置自己的日志记录之前停止日志记录。
如果您报告了错误或问题，必须提供这些信息以恢复初始日志记录。
只有在完全配置了所有内容之后，您才应该设置此选项。
## 在数据库启动期间出现有关结构默认值的警告
有时，在迁移过程中，旧列和默认值可能在数据库架构中保持不变。
这可能会导致警告，例如：
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
```
可以安全地忽略这些警告，但您可以通过让 Gitea 重新创建这些表来停止这些警告，使用以下命令：
```
gitea doctor recreate-table user
```
这将导致 Gitea 重新创建用户表并将旧数据复制到新表中，
并正确设置默认值。
您可以使用以下命令要求 Gitea 重新创建多个表：
```
gitea doctor recreate-table table1 table2 ...
```
如果您希望 Gitea 重新创建所有表，请使用以下命令：
```
gitea doctor recreate-table
```
在运行这些命令之前，强烈建议您备份数据库。
## 为什么查看文件时制表符/缩进显示错误
如果您正在使用 Cloudflare，请在仪表板中关闭自动缩小选项。
`Speed` -> `Optimization` -> 在 `Auto-Minify` 设置中取消选中 `HTML`。
## 如何从磁盘采用存储库
- 将您的（裸）存储库添加到正确的位置，即您的配置所在的地方（`repository.ROOT`），确保它们位于正确的布局`<REPO_ROOT>/[user]/[repo].git`。
- **注意：**目录名必须为小写。
- 您还可以在`<ROOT_URL>/admin/config`中检查存储库根路径。
- 确保存在要采用存储库的用户/组织。
- 作为管理员，转到`<ROOT_URL>/admin/repos/unadopted`并搜索。
- 用户也可以通过配置[`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md#仓库) 获得类似的权限。
- 如果上述步骤都正确执行，您应该能够选择要采用的存储库。
- 如果没有找到存储库，请启用[调试日志记录](../administration/config-cheat-sheet.md#仓库)以检查是否有特定错误。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/help/support.md
+69
View File
@@ -0,0 +1,69 @@
---
date: "2017-01-20T15:00:00+08:00"
slug: "support"
sidebar_position: 20
aliases:
- /zh-cn/seek-help
---
# 支持选项
- [付费商业支持](https://about.gitea.com/)
- [Discord](https://discord.gg/Gitea)
- [论坛](https://forum.gitea.com/)
- [Matrix](https://matrix.to/#/#gitea-space:matrix.org)
- 注意：大多数 Matrix 频道都与 Discord 中的对应频道桥接，可能在桥接过程中会出现一定程度的不稳定性。
- 中文支持
- [Discourse 中文分类](https://forum.gitea.com/c/5-category/5)
- QQ 群 328432459
# Bug 报告
如果您发现了 Bug，请在 GitHub 上 [创建一个问题](https://github.com/go-gitea/gitea/issues)。
**注意：** 在请求支持时，可能需要准备以下信息，以便帮助者获得所需的所有信息：
1. 您的 `app.ini`（将任何敏感数据进行必要的清除）。
2. 您看到的任何错误消息。
3. Gitea 日志以及与情况相关的所有其他日志。
- 收集 `trace` / `debug` 级别的日志更有用（参见下一节）。
- 在使用 systemd 时，使用 `journalctl --lines 1000 --unit gitea` 收集日志。
- 在使用 Docker 时，使用 `docker logs --tail 1000 <gitea-container>` 收集日志。
4. 可重现的步骤，以便他人能够更快速、更容易地重现和理解问题。
- [demo.gitea.com](https://demo.gitea.com) 可用于重现问题。
5. 如果遇到慢速/挂起/死锁等问题，请在出现问题时报告堆栈跟踪。
转到 "Site Admin" -> "Monitoring" -> "Stacktrace" -> "Download diagnosis report"。
# 高级 Bug 报告提示
## 更多日志的配置选项
默认情况下，日志以 `info` 级别输出到控制台。
如果您需要设置日志级别和/或从文件中收集日志，
您只需将以下配置复制到您的 `app.ini` 中（删除所有其他 `[log]` 部分），
然后您将在 Gitea 的日志目录中找到 `*.log` 文件（默认为 `%(GITEA_WORK_DIR)/log`）。
```ini
; 要显示所有 SQL 日志，您还可以在 [database] 部分中设置 LOG_SQL=true
[log]
LEVEL=debug
MODE=console,file
```
## 使用命令行收集堆栈跟踪
Gitea 可以使用 Golang 的 pprof 处理程序和工具链来收集堆栈跟踪和其他运行时信息。
如果 Web UI 停止工作，您可以尝试通过命令行收集堆栈跟踪：
1. 设置 app.ini：
```
[server]
ENABLE_PPROF = true
```
2. 重新启动 Gitea
3. 尝试触发 bug，当请求卡住一段时间，使用或浏览器访问：获取堆栈跟踪。
`curl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1`
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/index.md
+75
View File
@@ -0,0 +1,75 @@
---
date: "2016-11-08T16:00:00+02:00"
slug: /
sidebar_position: 10
---
# 关于Gitea
Gitea 是一个轻量级的 DevOps 平台软件。从开发计划到产品成型的整个软件生命周期，他都能够高效而轻松的帮助团队和开发者。包括 Git 托管、代码审查、团队协作、软件包注册和 CI/CD。它与 GitHub、Bitbucket 和 GitLab 等比较类似。
Gitea 最初是从 [Gogs](http://gogs.io) 分支而来，几乎所有代码都已更改。对于我们Fork的原因可以看
[这里](https://blog.gitea.com/welcome-to-gitea/)。
## 目标
Gitea的首要目标是创建一个极易安装，运行非常快速，安装和使用体验良好
的自建 Git 服务。
采用Go作为后端语言，只需生成一个可执行程序即可。
支持 Linux, macOS 和 Windows等多平台，
支持主流的x86，amd64、
ARM 和 PowerPC等架构。
## 功能特性
- 代码托管：Gitea⽀持创建和管理仓库、浏览提交历史和代码⽂件、审查和合并代码提交、管理协作者、管理分⽀等。它还⽀持许多常见的Git特性，⽐如标签、Cherry-pick、hook、集成协作⼯具等。
- 轻量级和快速: Gitea 的设计目标之一就是轻量级和快速响应。它不像一些大型的代码托管平台那样臃肿，因此在性能方面表现出色，适用于资源有限的服务器环境。由于其轻量级设计，Gitea 在资源消耗方面相对较低，可以在资源有限的环境下运行良好。
- 易于部署和维护: 轻松地部署在各种服务器上，不需要复杂的配置和依赖。这使得个人开发者或小团队可以方便地设置和管理自己的 Git 服务。
- 安全性: Gitea 注重安全性，提供了用户权限管理、访问控制列表等功能，可以确保代码和数据的安全性。
- 代码评审：代码评审同时支持 Pull Request workflow 和 AGit workflow。评审⼈可以在线浏览代码，并提交评审意见或问题。 提交者可以接收到评审意见，并在线回 复或修改代码。代码评审可以帮助用户和企业提⾼代码质量。
- CI/CD: Gitea Actions⽀持 CI/CD 功能，该功能兼容 GitHub Actions，⽤⼾可以采用熟悉的YAML格式编写workflows，也可以重⽤⼤量的已有的 Actions 插件。Actions 插件支持从任意的 Git 网站中下载。
- 项目管理：Gitea 通过看板和⼯单来跟踪⼀个项⽬的需求，功能和bug。⼯单⽀持分支，标签、⾥程碑、 指派、时间跟踪、到期时间、依赖关系等功能。
- 制品库: Gitea支持超过 20 种不同种类的公有或私有软件包管理，包括：Cargo, Chef, Composer, Conan, Conda, Container, Helm, Maven, npm, NuGet, Pub, PyPI, RubyGems, Vagrant等
- 开源社区支持: Gitea 是一个基于 MIT 许可证的开源项目,Gitea 拥有一个活跃的开源社区，能够持续地进行开发和改进，同时也积极接受社区贡献，保持了平台的更新和创新。
- 多语言支持： Gitea 提供多种语言界面，适应全球范围内的用户，促进了国际化和本地化。
更多功能特性：详见：https://docs.gitea.com/installation/comparison#general-features
## 系统要求
- 树莓派Pi3功能强大，足以运行 Gitea 来处理小型工作负载。
- 对于小型团队/项目而言，2 个 CPU 内核和 1GB 内存通常就足够了。
- 在 UNIX 系统上，Gitea 应使用专用的非 root 系统账户运行。
- 注意：Gitea 管理 `~/.ssh/authorized_keys` 文件。以普通用户身份运行 Gitea 可能会破坏该用户的登录能力。
- [Git](https://git-scm.com/) 需要 2.0.0 或更高版本。
- [Git Large File Storage](https://git-lfs.github.com/) 如果启用，且 Git 版本大于等于 2.1.2，则该选项可用
- 如果 Git 版本大于等于 2.18，将自动启用 Git 提交历史图形化展示功能
## 浏览器支持
- Last 2 versions of Chrome, Firefox, Safari and Edge
- Firefox ESR
## 技术栈
- Web框架： [Chi](http://github.com/go-chi/chi)
- ORM: [XORM](https://xorm.io)
- UI 框架：
- [jQuery](https://jquery.com)
- [Fomantic UI](https://fomantic-ui.com)
- [Vue3](https://vuejs.org)
- 更多组件参见 package.json
- 编辑器：
- [CodeMirror](https://codemirror.net)
- [EasyMDE](https://github.com/Ionaru/easy-markdown-editor)
- [Monaco Editor](https://microsoft.github.io/monaco-editor)
- 数据库驱动：
- [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
- [github.com/lib/pq](https://github.com/lib/pq)
- [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
- [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
## 集成支持
请访问 [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) 获得更多的第三方集成支持
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "安装",
"position": 10,
"link": {
"type": "generated-index",
"slug": "/installation",
"title": "安装"
}
}
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/comparison.md
+140
View File
@@ -0,0 +1,140 @@
---
date: "2019-02-14T11:51:04+08:00"
slug: "comparison"
sidebar_position: 5
aliases:
- /zh-cn/comparison
---
# 对比 Gitea 与其它 Git 托管工具
这里列出了 Gitea 与其它一些 Git 托管工具之间的异同，以便确认 Gitea 是否能够满足您的需求。
请注意，此列表中的某些表项可能已经过时，因为我们并没有定期检查其它产品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 来帮助我们更新过时的内容，感谢！
_表格中的符号含义:_
- _✓ - 支持_
- _⁄ - 部分支持_
- _✘ - 不支持_
- _⚙️ - 由第三方服务或插件支持_
#### 主要特性
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
| 开源免费 | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ |
| 低资源开销 (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 支持多种数据库 | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ |
| 支持多种操作系统 | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ |
| 升级简便 | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 可观测性 | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 支持第三方渲染工具 | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? |
| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 扩展 API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 内置软件包/容器注册中心 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 同步提交到外部仓库 (push mirror) | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 同步外部仓库的提交 (pull mirror) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ? |
| 浅色和深色主题 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ? |
| 自定义主题支持 | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ |
| 支持 Markdown | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支持 CSV | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? |
| Git 驱动的静态 pages | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Git 驱动的集成化 wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ |
| 部署令牌 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 仓库写权限令牌 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| RSS Feeds | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ✘ |
| 内置 CI/CD | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 子组织：组织内的组织 | [✘](https://github.com/go-gitea/gitea/issues/1872) | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 多实例交互 | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| Markdown 绘图 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Markdown 数学公式 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
#### 代码管理
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ |
| 仓库主题描述 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 仓库内代码搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 全局代码搜索 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ |
| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 组织里程碑 | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 细粒度用户角色 | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 提交人的身份验证 | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ |
| GPG 签名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SSH 签名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ? |
| 拒绝未通过验证的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 外部仓库迁移 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 仓库活跃度页面 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 分支管理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 建立新分支 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 在线代码编辑 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 提交的统计图表 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 模板仓库 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ |
| Git Blame | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 可视化镜像变化 | ✓ | ✘ | ✓ | ? | ? | ? | ? |
#### 工单管理
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| ------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------- | -------------- | ------------ |
| 工单跟踪 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ |
| 工单模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 标签 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 时间跟踪 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 支持多个负责人 | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ |
| 关联的工单 | ✘ | ✘ | ⁄ | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓ | ✘ | ✘ |
| 私密工单 | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 评论反馈 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 锁定讨论 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工单批处理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工单看板 | [✓](https://github.com/go-gitea/gitea/pull/8346) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 从工单创建分支 | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 从评论创建工单 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工单搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 工单全局搜索 | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 工单依赖关系 | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 通过 Email 创建工单 | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘ | ✓ | ✓ | ✓ | ✘ |
| 服务台 | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103) | ✓ | ✘ | ✘ |
#### Pull/Merge requests
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| ------------------------------------ | -------------------------------------------------- | ---- | --------- | --------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------------ |
| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Squash merging | ✓ | ✘ | ✓ | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓ | ✓ | ✓ |
| Rebase merging | ✓ | ✓ | ✓ | ✘ | ⁄ | ✘ | ✓ |
| 评论 Pull/Merge request 中的某行代码 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 指定 Pull/Merge request 的审核人 | ✓ | ✘ | ⁄ | ✓ | ✓ | ✓ | ✓ |
| 解决 Merge 冲突 | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 限制某些用户的 push 和 merge 权限 | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ |
| 回退某些 commits 或 merge request | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| Pull/Merge requests 模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 查看 Cherry-picking 的更改 | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 下载 Patch | ✓ | ✘ | ✓ | ✓ | ✓ | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘ |
| Merge queues | ✘ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ |
#### 第三方集成
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | --------- | --------- | --------- | ------------ |
| 支持 Webhook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 自定义 Git 钩子 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 集成 AD / LDAP | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支持多个 LDAP / AD 服务 | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ |
| LDAP 用户同步 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SAML 2.0 service provider | [✘](https://github.com/go-gitea/gitea/issues/5512) | [✘](https://github.com/gogs/gogs/issues/1221) | ✓ | ✓ | ✓ | ✓ | ✘ |
| 支持 OpenId 连接 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ |
| 集成 OAuth 2.0（外部授权） | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✓ |
| 作为 OAuth 2.0 provider | [✓](https://github.com/go-gitea/gitea/pull/5378) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 二次验证 (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 集成 Mattermost/Slack | ✓ | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ |
| 集成 Discord | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 集成 Microsoft Teams | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 显示外部 CI/CD 的状态 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
[gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea
[gitea-pages-server]: https://codeberg.org/Codeberg/pages-server
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/database-preparation.md
+300
View File
@@ -0,0 +1,300 @@
---
date: "2020-01-16"
slug: "database-prep"
sidebar_position: 10
aliases:
- /zh-cn/database-prep
---
# 数据库准备
在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用，因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite，则可以忽略本章内容。
如果您使用不受支持的数据库版本，请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。
数据库实例可以与 Gitea 实例在相同机器上（本地数据库），也可以与 Gitea 实例在不同机器上（远程数据库）。
注意：以下所有步骤要求您的选择的数据库引擎已安装在您的系统上。对于远程数据库设置，请在数据库实例上安装服务器应用程序，在 Gitea 服务器上安装客户端程序。客户端程序用于测试 Gitea 服务器与数据库之间的连接，而 Gitea 本身使用 Go 提供的数据库驱动程序完成相同的任务。此外，请确保服务器和客户端使用相同的引擎版本，以使某些引擎功能正常工作。出于安全原因，请使用安全密码保护 `root`（MySQL）或 `postgres`（PostgreSQL）数据库超级用户。以下步骤假设您在数据库和 Gitea 服务器上都使用 Linux。
## MySQL/MariaDB
1. 对于远程数据库设置，您需要让 MySQL 监听您的 IP 地址。编辑数据库实例上的 `/etc/mysql/my.cnf` 文件中的 `bind-address` 选项为：
```ini
bind-address = 203.0.113.3
```
2. 在数据库实例上，使用 `root` 用户登录到数据库控制台：
```
mysql -u root -p
```
按提示输入密码。
3. 创建一个将被 Gitea 使用的数据库用户，并使用密码进行身份验证。以下示例中使用了 `'gitea'` 作为密码。请为您的实例使用一个安全密码。
对于本地数据库：
```sql
SET old_passwords=0;
CREATE USER 'gitea' IDENTIFIED BY 'gitea';
```
对于远程数据库：
```sql
SET old_passwords=0;
CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';
```
其中 `192.0.2.10` 是您的 Gitea 实例的 IP 地址。
根据需要替换上述用户名和密码。
4. 使用 UTF-8 字符集和大小写敏感的排序规则创建数据库。
`utf8mb4_bin` 是 MySQL/MariaDB 的通用排序规则。
Gitea 启动后会尝试把数据库修改为更合适的字符集 (`utf8mb4_0900_as_cs` 或者 `uca1400_as_cs`) 并在可能的情况下更改数据库。
如果你想指定自己的字符集规则，可以在 `app.ini` 中设置 `[database].CHARSET_COLLATION`。
```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';
```
根据需要替换数据库名称。
5. 将数据库上的所有权限授予上述创建的数据库用户。
对于本地数据库：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
FLUSH PRIVILEGES;
```
对于远程数据库：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10';
FLUSH PRIVILEGES;
```
6. 通过 `exit` 退出数据库控制台。
7. 在您的 Gitea 服务器上，测试与数据库的连接：
```
mysql -u gitea -h 203.0.113.3 -p giteadb
```
其中 `gitea` 是数据库用户名，`giteadb` 是数据库名称，`203.0.113.3` 是数据库实例的 IP 地址。对于本地数据库，省略 `-h` 选项。
到此您应该能够连接到数据库了。
## PostgreSQL
1. 对于远程数据库设置，通过编辑数据库实例上的 postgresql.conf 文件中的 `listen_addresses` 将 `PostgreSQL` 配置为监听您的 IP 地址：
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
2. PostgreSQL 默认使用 `md5` 质询-响应加密方案进行密码身份验证。现在这个方案不再被认为是安全的。改用 SCRAM-SHA-256 方案，通过编辑数据库服务器上的` postgresql.conf` 配置文件：
```ini
password_encryption = scram-sha-256
```
重启 PostgreSQL 以应用该设置。
3. 在数据库服务器上，以超级用户身份登录到数据库控制台：
```
su -c "psql" - postgres
```
4. 创建具有登录权限和密码的数据库用户（在 PostgreSQL 术语中称为角色）。请使用安全的、强密码，而不是下面的 `'gitea'`：
```sql
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
```
根据需要替换用户名和密码。
5. 使用 UTF-8 字符集创建数据库，并由之前创建的数据库用户拥有。可以根据预期内容使用任何 `libc` 排序规则，使用 `LC_COLLATE` 和 `LC_CTYPE` 参数指定：
```sql
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
根据需要替换数据库名称。
6. 通过将以下身份验证规则添加到 `pg_hba.conf`，允许数据库用户访问上面创建的数据库。
对于本地数据库：
```ini
local giteadb gitea scram-sha-256
```
对于远程数据库：
```ini
host giteadb gitea 192.0.2.10/32 scram-sha-256
```
根据您自己的数据库名称、用户和 Gitea 实例的 IP 地址进行替换。
注意：`pg_hba.conf` 上的规则按顺序评估，也就是第一个匹配的规则将用于身份验证。您的 PostgreSQL 安装可能附带了适用于所有用户和数据库的通用身份验证规则。如果是这种情况，您可能需要将此处提供的规则放置在此类通用规则之上。
重启 PostgreSQL 以应用新的身份验证规则。
7. 在您的 Gitea 服务器上，测试与数据库的连接。
对于本地数据库：
```
psql -U gitea -d giteadb
```
对于远程数据库：
```
psql "postgres://[email protected]/giteadb"
```
其中 `gitea` 是数据库用户，`giteadb` 是数据库名称，`203.0.113.3` 是您的数据库实例的 IP 地址。
您应该会被提示输入数据库用户的密码，并连接到数据库。
## 使用 TLS 进行数据库连接
如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的，或者如果 Gitea 和数据库运行在同一台服务器上，那么可以省略本节，因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是，如果数据库实例位于公共网络上，请使用 TLS 对数据库连接进行加密，以防止第三方拦截流量数据。
### 先决条件
- 您需要两个有效的 TLS 证书，一个用于数据库实例（数据库服务器），一个用于 Gitea 实例（数据库客户端）。两个证书都必须由受信任的 CA 签名。
- 数据库证书必须在 `X509v3 Extended Key Usage` 扩展属性中包含 `TLS Web Server Authentication`，而客户端证书则需要在相应的属性中包含 `TLS Web Client Authentication`。
- 在数据库服务器证书中，`Subject Alternative Name` 或 `Common Name` 条目之一必须是数据库实例的完全限定域名（FQDN）（例如 `db.example.com`）。在数据库客户端证书中，上述提到的条目之一必须包含 Gitea 将用于连接的数据库用户名。
- 您需要将 Gitea 和数据库服务器的域名映射到它们各自的 IP 地址。可以为它们设置 DNS 记录，也可以在每个系统上的 `/etc/hosts`（Windows 中的 `%WINDIR%\System32\drivers\etc\hosts`）中添加本地映射。这样可以通过域名而不是 IP 地址进行数据库连接。有关详细信息，请参阅您系统的文档。
### PostgreSQL TLS
Gitea 使用的 PostgreSQL 驱动程序支持双向 TLS。在双向 TLS 中，数据库客户端和服务器通过将各自的证书发送给对方进行验证来相互认证。换句话说，服务器验证客户端证书，客户端验证服务器证书。
1. 在数据库实例所在的服务器上，放置以下凭据：
- `/path/to/postgresql.crt`: 数据库实例证书
- `/path/to/postgresql.key`: 数据库实例私钥
- `/path/to/root.crt`: 用于验证客户端证书的 CA 证书链
2. 在 `postgresql.conf` 中添加以下选项：
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
3. 根据 PostgreSQL 的要求，调整凭据的所有权和权限：
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
4. 编辑 `pg_hba.conf` 规则，仅允许 Gitea 数据库用户通过 SSL 连接，并要求客户端证书验证。
对于 PostgreSQL 12：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
对于 PostgreSQL 11 及更早版本：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1
```
根据需要替换数据库名称、用户和 Gitea 实例的 IP 地址。
5. 重新启动 PostgreSQL 以应用上述配置。
6. 在运行 Gitea 实例的服务器上，将以下凭据放置在运行 Gitea 的用户的主目录下（例如 `git`）：
- `~/.postgresql/postgresql.crt`: 数据库客户端证书
- `~/.postgresql/postgresql.key`: 数据库客户端私钥
- `~/.postgresql/root.crt`: 用于验证服务器证书的 CA 证书链
注意：上述文件名在 PostgreSQL 中是硬编码的，无法更改。
7. 根据需要调整凭据、所有权和权限：
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
8. 测试与数据库的连接：
```
psql "postgres://[email protected]/giteadb?sslmode=verify-full"
```
您将被提示输入数据库用户的密码，然后连接到数据库。
### MySQL/MariaDB TLS
虽然 Gitea 使用的 MySQL 驱动程序也支持双向 TLS，但目前 Gitea 仅支持单向 TLS。有关详细信息，请参见工单＃10828。
在单向 TLS 中，数据库客户端在连接握手期间验证服务器发送的证书，而服务器则假定连接的客户端是合法的，因为不进行客户端证书验证。
1. 在数据库实例上放置以下凭据：
- `/path/to/mysql.crt`: 数据库实例证书
- `/path/to/mysql.key`: 数据库实例密钥
- `/path/to/ca.crt`: CA 证书链。在单向 TLS 中不使用此文件，但用于验证双向 TLS 中的客户端证书。
2. 将以下选项添加到 `my.cnf`：
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
3. 调整凭据的所有权和权限：
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
4. 重新启动 MySQL 以应用设置。
5. Gitea 的数据库用户可能已经创建过，但只会对运行 Gitea 的服务器的 IP 地址进行身份验证。要对其域名进行身份验证，请重新创建用户，并设置其需要通过 TLS 连接到数据库：
```sql
DROP USER 'gitea'@'192.0.2.10';
CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL;
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea';
FLUSH PRIVILEGES;
```
根据需要替换数据库用户名、密码和 Gitea 实例域名。
6. 确保用于验证数据库服务器证书的 CA 证书链位于数据库和 Gitea 服务器的系统证书存储中。请参考系统文档中有关将 CA 证书添加到证书存储的说明。
7. 在运行 Gitea 的服务器上，测试与数据库的连接：
```
mysql -u gitea -h example.db -p --ssl
```
至此应该成功连接到数据库了。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/from-binary.md
+205
View File
@@ -0,0 +1,205 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-binary"
sidebar_position: 15
aliases:
- /zh-cn/install-from-binary
---
# 使用二进制文件安装
所有打包的二进制程序均包含 SQLite，MySQL 和 PostgreSQL 的数据库连接支持，同时网站的静态资源均已嵌入到可执行程序中，这一点和曾经的 Gogs 有所不同。
## 下载
你可以从 [下载页面](https://dl.gitea.com/gitea/) 选择对应平台的二进制文件。
### 选择架构
- **对于 Linux**，`linux-amd64` 适用于 64-bit 的 Intel/AMD 平台。更多架构包含 `arm64` (Raspberry PI 4)，`386` (32-bit)，`arm-5` 以及 `arm-6`。
- **对于 Windows**，`windows-4.0-amd64` 适用于 64-bit 的 Intel/AMD 平台，`386` 适用于 32-bit 的 Intel/AMD 平台。（提示：`gogit-windows` 版本内建了 gogit 可能缓解在旧的 Windows 平台上 Go 程序调用 git 子程序时面临的 [性能问题](https://github.com/go-gitea/gitea/pull/15482)）
- **对于 macOS**，`darwin-arm64` 适用于 Apple Silicon 架构，`darwin-amd64` 适用于 Intel 架构.
- **对于 FreeBSD**，`freebsd12-amd64` 适用于 64-bit 的 Intel/AMD 平台。
### 使用 wget 下载
使用以下命令下载适用于 64-bit Linux 平台的二进制文件。
```sh
wget -O gitea https://dl.gitea.com/gitea/@version@/gitea-@version@-linux-amd64
chmod +x gitea
```
## 验证 GPG 签名
Gitea 对打包的二进制文件使用 [GPG 密钥](https://keys.openpgp.org/search?q=teabot%40gitea.io) 签名以防止篡改。
请根据对应文件名 `.asc` 中包含的校验码检验文件的一致性。
```sh
gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
gpg --verify gitea-@[email protected] gitea-@version@-linux-amd64
```
校验正确时的信息为 `Good signature from "Teabot <[email protected]>"`。
校验错误时的信息为 `This key is not certified with a trusted signature!`。
## 服务器设置
**提示：** `GITEA_WORK_DIR` 表示 Gitea 工作的路径。以下路径可以通过 [环境变量](../administration/environment-variables.md) 初始化。
### 准备环境
检查是否安装 Git。要求 Git 版本 >= 2.0。
```sh
git --version
```
创建用户（推荐使用名称 `git`）
```sh
# On Ubuntu/Debian:
adduser \
--system \
--shell /bin/bash \
--gecos 'Git Version Control' \
--group \
--disabled-password \
--home /home/git \
git
# On Fedora/RHEL/CentOS:
groupadd --system git
adduser \
--system \
--shell /bin/bash \
--comment 'Git Version Control' \
--gid git \
--home-dir /home/git \
--create-home \
git
```
### 创建工作路径
```sh
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
```
> **注意：** 为了让 Web 安装程序可以写入配置文件，我们临时为 `/etc/gitea` 路径授予了组外用户 `git` 写入权限。建议在安装结束后将配置文件的权限设置为只读。
>
> ```sh
> chmod 750 /etc/gitea
> chmod 640 /etc/gitea/app.ini
> ```
如果您不希望通过 Web 安装程序创建配置文件，可以将配置文件设置为仅供 Gitea 用户只读（owner/group `root:git`, mode `0640`）并手工创建配置文件：
- 设置 `INSTALL_LOCK=true` 关闭安装界面
- 手动配置数据库连接参数
- 使用 `gitea generate secret` 创建 `SECRET_KEY` 和 `INTERNAL_TOKEN`
- 提供所有必要的密钥
详情参考 [命令行文档](../administration/command-line.md) 中有关 `gitea generate secret` 的内容。
### 配置 Gitea 工作路径
**提示：** 如果使用 Systemd 管理 Gitea 的 Linux 服务，你可以采用 `WorkingDirectory` 参数来配置工作路径。 否则，使用环境变量 `GITEA_WORK_DIR` 来明确指出程序工作和数据存放路径。
```sh
export GITEA_WORK_DIR=/var/lib/gitea/
```
### 复制二进制文件到全局位置
```sh
cp gitea /usr/local/bin/gitea
```
### 添加 bash/zsh 自动补全（从 1.19 版本开始）
可以在 [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete) 找到启用 bash 自动补全的脚本。可以将其复制到 `/usr/share/bash-completion/completions/gitea`，或在 `.bashrc` 中引用。
同样地，zsh 自动补全的脚本可以在 [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete) 找到。您可以将其复制到 `/usr/share/zsh/_gitea`，或在您的 `.zshrc` 中引用。
具体情况可能会有所不同，这些脚本可能需要进一步的改进。
## 运行 Gitea
完成以上步骤后，可以通过两种方式运行 Gitea：
### 1. 创建服务自动启动 Gitea（推荐）
学习创建 [Linux 服务](installation/run-as-service-in-ubuntu.md)
### 2. 通过命令行终端运行
```sh
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
## 升级到最新版本
您可以通过停止程序，替换 `/usr/local/bin/gitea` 并重启来更新到新版本。直接替换可执行程序时不要更改或使用新的文件名称，以避免数据出错。
建议您在更新之前进行[备份](../administration/backup-and-restore.md)。
如果您按照上述描述执行了安装步骤，二进制文件的通用名称应为 gitea。请勿更改此名称，即不要包含版本号。
### 1. 使用 systemd 重新启动 Gitea（推荐）
我们建议使用 systemd 作为服务管理器，使用 `systemctl restart gitea` 安全地重启程序。
### 2. 非 systemd 重启方法
使用 SIGHUP 信号关闭程序：查询到 Gitea 程序的 PID，使用 `kill -1 $GITEA_PID`，或者 `killall -1 gitea`。
更优雅的停止指令可能包括 `kill $GITEA_PID` 或者 `killall gitea`。
**提示：** 我们不建议使用 SIGKILL 信号（`-9`），这会强制停止 Gitea 程序，但不会正确关闭队列、索引器等任务。
请参阅下面的疑难解答说明，以在 Gitea 版本更新后修复损坏的仓库。
## 排查故障
### 旧版 glibc
旧版 Linux 发行版（例如 Debian 7 和 CentOS 6）可能无法加载 Gitea 二进制文件，通常会产生类似于 `./gitea: /lib/x86_64-linux-gnu/libc.so.6:
version 'GLIBC\_2.14' not found (required by ./gitea)` 的错误。这是由于 dl.gitea.com 提供的二进制文件中集成了 SQLite 支持。在这种情况下，通常可以选择[从源代码安装](installation/from-source.md)，而不包括 SQLite 支持。
### 在另一个端口上运行 Gitea
对于出现类似于 `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
bind: address already in use` 的错误，需要将 Gitea 启动在另一个空闲端口上。您可以使用 `./gitea web -p $PORT` 来实现。可能已经有另一个 Gitea 实例在运行。
### 在 Raspbian 上运行 Gitea
从 v1.8 版本开始，arm7 版本的 Gitea 存在问题，无法在树莓派和类似设备上运行。
建议切换到 arm6 版本，该版本经过测试并已被证明可以在树莓派和类似设备上运行。
### 更新到新版本的 Gitea 后出现的 Git 错误
如果在更新过程中，二进制文件的名称已更改为新版本的 Gitea，则现有仓库中的 Git 钩子将不再起作用。在这种情况下，当推送到仓库时，会显示 Git 错误。
```
remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
```
错误信息中的 `[...]` 部分将包含您先前 Gitea 二进制文件的路径。
要解决此问题，请转到管理选项，并运行任务 `Resynchronize pre-receive, update and post-receive hooks of all repositories`，以将所有钩子更新为包含新的二进制文件路径。请注意，这将覆盖所有 Git 钩子，包括自定义的钩子。
如果您没有使用 Gitea 内置的 SSH 服务器，您还需要通过在管理选项中运行任务 `Update the '.ssh/authorized_keys' file with Gitea SSH keys.` 来重新编写授权密钥文件。
> 更多经验总结，请参考英文版 [Troubleshooting](https://docs.gitea.com/installation/install-from-binary#troubleshooting)
如果从本页中没有找到你需要的内容，请访问 [帮助页面](help/support.md)
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/from-package.md
+104
View File
@@ -0,0 +1,104 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-package"
sidebar_position: 20
aliases:
- /zh-cn/install-from-package
---
# 包管理器安装
## 官方包管理器
### macOS
macOS 平台下当前我们仅支持通过 `brew` 来安装。如果你没有安装 [Homebrew](http://brew.sh/)，你也可以查看 [从二进制安装](installation/from-binary.md)。在你安装了 `brew` 之后， 你可以执行以下命令：
```
brew install gitea
```
## 非官方包管理器
### Alpine Linux
Gitea 已经包含在 Alpine Linux 的[社区存储库](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge)中，版本与 Gitea 官方保持同步。
```sh
apk add gitea
```
### Arch Linux
Gitea 已经在滚动发布发行版的官方[社区存储库](https://www.archlinux.org/packages/community/x86_64/gitea/)中，版本与 Gitea 官方保持同步。
```sh
pacman -S gitea
```
### Arch Linux ARM
官方支持 [aarch64](https://archlinuxarm.org/packages/aarch64/gitea)， [armv7h](https://archlinuxarm.org/packages/armv7h/gitea) 和 [armv6h](https://archlinuxarm.org/packages/armv6h/gitea) 架构。
```sh
pacman -S gitea
```
### Gentoo Linux
滚动发布的发行版在其官方社区软件仓库中提供了 [Gitea](https://packages.gentoo.org/packages/www-apps/gitea)，并且会随着新的 Gitea 发布提供软件包更新。
```sh
emerge gitea -va
```
### Canonical Snap
目前 Gitea 已在 Snap Store 中发布，名称为 [gitea](https://snapcraft.io/gitea)。
```sh
snap install gitea
```
### SUSE/openSUSE
OpenSUSE 构建服务为 [openSUSE 和 SLE](https://software.opensuse.org/download/package?package=gitea&project=devel%3Atools%3Ascm)
提供包，你可以在开发软件配置管理存储库中找到它们。
### Windows
目前你可以通过 [Chocolatey](https://chocolatey.org/) 来安装 [Gitea](https://chocolatey.org/packages/gitea)。
```sh
choco install gitea
```
你也可以 [从二进制安装](installation/from-binary.md) 。
### FreeBSD
可以使用 Gitea 的 FreeBSD port `www/gitea`。 请安装预构建的二进制包：
```
pkg install gitea
```
对于最新版本，或使用自定义选项构建 port，请
[从 port 安装](https://www.freebsd.org/doc/handbook/ports-using.html)：
```
su -
cd /usr/ports/www/gitea
make install clean
```
该 port 使用标准的 FreeBSD 文件系统布局：配置文件在 `/usr/local/etc/gitea` 目录中，
模板、选项、插件和主题在 `/usr/local/share/gitea` 目录中，启动脚本在 `/usr/local/etc/rc.d/gitea` 目录中。
要使 Gitea 作为服务运行，请运行 `sysrc gitea_enable=YES` 并使用 `service gitea start` 命令启动它。
### 其它
如果这里没有找到你喜欢的包管理器，可以使用 Gitea 第三方软件包。这里有一个完整的列表： [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-packages)。
如果你知道其他 Gitea 第三方软件包，请发送 PR 来添加它。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/from-source.md
+218
View File
@@ -0,0 +1,218 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-source"
sidebar_position: 30
aliases:
- /zh-cn/install-from-source
---
# 使用源代码安装
你需要 [安装 Go](https://golang.google.cn/doc/install) 并正确设置 Go 环境。特别的，建议设置`$GOPATH`环境变量，并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。
接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
## 下载
首先，我们需要获取源码。由于引入了 Go 模块，最简单的方法是直接使用 Git，因为我们不再需要在 GOPATH 内构建 Gitea。
```bash
git clone https://github.com/go-gitea/gitea
```
（之前的版本中建议使用 `go get`，但现在不再需要。）
你可以选择编译和安装的版本，当前有多个选择。`main` 分支代表当前的开发版本。如果你想编译 `main` 版本，你可以直接跳到 [构建](#构建) 部分。
如果你想编译带有标签的发行版本，可以使用以下命令签出：
```bash
git branch -a
git checkout @sourceBranch@
```
要验证一个拉取请求（Pull Request, PR），要先启用新的分支（其中 `xyz` 是 PR 的 ID；例如，对于 [#2663](https://github.com/go-gitea/gitea/pull/2663)，ID 是 `2663 `）：
```bash
git fetch origin pull/xyz/head:pr-xyz
```
要以指定发行版本（如 @sourceVersion@ ）的源代码来构建 Gitea，可执行以下命令列出可用的版本并选择某个版本签出。
使用以下命令列出可用的版本：
```bash
git tag -l
git checkout @sourceVersion@ # or git checkout pr-xyz
```
## 构建
要从源代码进行构建，系统必须预先安装以下程序：
- `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
根据你的构建需求，以下 tags 可以使用：
- `bindata`: 构建一个单一的整体二进制文件，包含所有资源。适用于构建生产环境版本。
- `sqlite sqlite_unlock_notify`: 启用对 [SQLite3](https://sqlite.org/) 数据库的支持。仅建议在少数人使用时使用这个模式。
- `pam`: 启用对 PAM（ Linux 可插拔认证模块）的支持。可用于对本地用户进行身份验证或扩展身份验证到 PAM 可用的方法。
- `gogit`：（实验性功能）使用 go-git 变体的 Git 命令。
将所有资源（JS/CSS/模板等）打包到二进制文件中。在生产环境部署时，使用`bindata`构建标签是必需的。在开发/测试 Gitea 或能够明确分离资源时，可以不用`bindata`。
要包含所有资源，请使用 `bindata` 标签：
```bash
TAGS="bindata" make build
```
在我们的持续集成系统的默认发行版中，构建标签为：`TAGS="bindata sqlite sqlite_unlock_notify"`。因此，从源码构建的最简单、推荐方式是：
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
`build`目标分为两个子目标：
- `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。
如果存在预构建的前端文件，可以仅构建后端：
```bash
TAGS="bindata" make backend
```
## 测试
按照上述步骤完成后，工作目录中将会有一个`gitea`二进制文件。可以从该目录进行测试，或将其移动到带有测试数据的目录中。当手动从命令行启动 Gitea 时，可以通过按下`Ctrl + C`来停止程序。
```bash
./gitea web
```
## 更改默认路径
Gitea 将从`CustomPath`中查找许多信息。默认的，这会在运行 Gitea 时当前工作目录下的`custom/`目录中（译者案：即`$PATH_TO_YOUR_GITEA$/custom/`）。它还将在`$(CustomPath)/conf/app.ini`中查找其配置文件`CustomConf`，并将当前工作目录用作一些可配置值的相对基本路径`AppWorkPath`。最后，静态文件将从默认为 `AppWorkPath`的`StaticRootPath`提供。
尽管在开发时这些值很有用，但可能与下游用户的偏好冲突。
一种选择是使用脚本文件来隐藏`gitea`二进制文件，并在运行 Gitea 之前创建适当的环境。然而，在构建时，可以使用`make`的`LDFLAGS`环境变量来更改这些默认值。适当的设置如下：
- 要设置`CustomPath`，请使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
- 对于`CustomConf`，应该使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
- 对于`AppWorkPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
- 对于`StaticRootPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
- 要更改默认的 PID 文件位置，请使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
将这些字符串与其前导的`-X`添加到`LDFLAGS`变量中，并像上面那样使用适当的`TAGS`运行`make build`。
运行`gitea help`将允许您查看配置的`gitea`设置。
## 交叉编译
`go`编译器工具链支持将代码交叉编译到不同的目标架构上。请参考[`GOOS`和`GOARCH`环境变量](https://go.dev/doc/install/source#environment) 以获取支持的目标列表。如果您想为性能较弱的系统（如树莓派）构建 Gitea，交叉编译非常有用。
要使用构建标签（`TAGS`）进行交叉编译 Gitea，您还需要一个 C 交叉编译器，该编译器的目标架构与`GOOS`和`GOARCH`变量选择的架构相同。例如，要为 Linux ARM64（`GOOS=linux`和`GOARCH=arm64`）进行交叉编译，您需要`aarch64-unknown-linux-gnu-gcc`交叉编译器。这是因为 Gitea 构建标签使用了`cgo`的外部函数接口（FFI）。
在没有任何标签的情况下，交叉编译的 Gitea 为 Linux ARM64 版本：
```
GOOS=linux GOARCH=arm64 make build
```
要交叉编译 Linux ARM64 下的 Gitea，这是推荐的构建标签：
```
CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
```
根据您的目标架构，适当替换`CC`、`GOOS`和`GOARCH`。
有时您需要构建一个静态编译的镜像。为此，您需要添加以下内容：
```
LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
```
这可以与上述的`CC`、`GOOS`和`GOARCH`结合使用。
### 添加 bash/zsh 自动补全（从 1.19 版本起）
在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一个启用 bash 自动补全的脚本。您可以根据需要进行修改，并在您的 `.bashrc` 中使用 `source` 命令加载该脚本，或者将其复制到 `/usr/share/bash-completion/completions/gitea`。
类似地，可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一个用于 zsh 自动补全的脚本。您可以将其复制到 `/usr/share/zsh/_gitea`，或者在您的 `.zshrc` 中使用 `source` 命令加载该脚本。
可能需要你根据具体情况进一步改进这些脚本。
## 在 Linux 上使用 Zig 进行编译或交叉编译
请按照 [Zig 的入门指南](https://ziglang.org/learn/getting-started/#installing-zig) 安装 Zig。
- 编译 (Linux ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉编译 (Linux ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## 在 Windows 上使用 Zig 进行编译或交叉编译
使用`GIT BASH`编译。
- 编译 (Windows ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉编译 (Windows ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## Source Map
默认情况下，gitea 会为前端文件生成精简的 Source Map 以节省空间。 这可以通过“ENABLE_SOURCEMAP”环境变量进行控制：
- `ENABLE_SOURCEMAP=true` 生成所有 Source Map，这是开发版本的默认设置
- `ENABLE_SOURCEMAP=reduced` 生成有限的 Source Map，这是生产版本的默认设置
- `ENABLE_SOURCEMAP=false` 不生成 Source Map
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/on-cloud-provider.md
+42
View File
@@ -0,0 +1,42 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-on-cloud-provider"
sidebar_position: 90
aliases:
- /zh-cn/install-on-cloud-provider
---
# 在云服务器上安装 Gitea
## Cloudron
Gitea 可以在 [Cloudron](https://cloudron.io) 上进行一键安装。
Cloudron 使得在您的服务器上运行 Gitea，并保持其更新和安全变得简单。
[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
Gitea 软件包的维护地址在[这里](https://git.cloudron.io/cloudron/gitea-app).
这里有一个[demo 实例](https://my.demo.cloudron.io) (用户名: cloudron 密码: cloudron) 您可以在其中尝试运行 Gitea。
## Linode
[Linode](https://www.linode.com/) 将 Gitea 作为其市场中的一个应用程序.
要将 Gitea 部署到 Linode, 请参考 [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
## alwaysdata
[alwaysdata](https://www.alwaysdata.com/) 将 Gitea 作为其市场中的一个 droplet.
要将 Gitea 部署到 alwaysdata, 请参考 [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
## Exoscale
[Exoscale](https://www.exoscale.com/) 在其市场中提供由 [Glasskube](https://glasskube.eu/) 管理的 Gitea。
Exoscale 是一家欧洲的云服务提供商。
该软件包通过开源的 [Glasskube Kubernetes Operator](https://github.com/glasskube/operator) 进行维护和更新。
要在 Exoscale 上部署 Gitea，请参考 [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/)。
i18n/zh-cn/docusaurus-plugin-content-docs/version-28/installation/on-kubernetes.md
+74
View File
@@ -0,0 +1,74 @@
---
date: "2020-03-19T19:27:00+02:00"
slug: "install-on-kubernetes"
sidebar_position: 80
aliases:
- /zh-cn/install-on-kubernetes
---
# 在 Kubernetes 中安装 Gitea
Gitea 已经提供了便于在 Kubernetes 云原生环境中安装所需的 Helm Chart
默认安装指令为：
```bash
helm repo add gitea https://dl.gitea.com/charts
helm repo update
helm install gitea gitea/gitea
```
如果采用默认安装指令，Helm 会部署单实例的 Gitea, PostgreSQL, Memcached。若您想实现自定义安装（包括配置 Gitea 集群、NGINX Ingress、MySQL、MariaDB、持久存储等），请前往阅读：[Gitea Helm Chart](https://gitea.com/gitea/helm-chart/)
您也可以通过 `helm show` 命令导出 `README.md` 和配置文件 `values.yaml` 进行学习和编辑，例如：
```bash
helm show values gitea/gitea > values.yaml
helm show readme gitea/gitea > README.md
# 使用自定义的配置文件 values.yaml
helm install gitea -f values.yaml gitea/gitea
```
## 运行状况检查接口
Gitea 附带了一个运行状况检查接口 `/api/healthz`，你可以像这样在 Kubernetes 中配置它：
```yaml
livenessProbe:
httpGet:
path: /api/healthz
port: http
initialDelaySeconds: 200
timeoutSeconds: 5
periodSeconds: 10
successThreshold: 1
failureThreshold: 10
```
成功的运行状况检查响应代码为 HTTP `200`，下面是示例：
```json
HTTP/1.1 200 OK
{
"status": "pass",
"description": "Gitea: Git with a cup of tea",
"checks": {
"cache:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
],
"database:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
]
}
}
```
有关更多信息，请参考 Kubernetes 文档 [配置存活、就绪和启动探测器](https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
Loaded 50 of 338 files, more files were not shown because too many files have changed in this diff. Show more