mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-15 14:23:44 +00:00
Move usage directories (#300)
Reviewed-on: https://gitea.com/gitea/docs/pulls/300
This commit is contained in:
Lunny Xiao committed
1 parent
00a36086b0
commit
9baa98ec3f
302 files changed
+24392
-880
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Access Control",
|
||||
"position": 100,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/access-control",
|
||||
"description": "Permissions, security, and access control features"
|
||||
}
|
||||
}
|
||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Issues & Pull Requests",
|
||||
"position": 20,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/issues-prs",
|
||||
"description": "Issues and Pull Requests workflow, templates, and collaboration features"
|
||||
}
|
||||
}
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Repository",
|
||||
"position": 10,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/repository",
|
||||
"description": "Repository management, Git operations, and content features"
|
||||
}
|
||||
}
|
||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,15 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "profile-readme"
|
||||
sidebar_position: 12
|
||||
---
|
||||
|
||||
# 个人资料 README
|
||||
|
||||
要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 `.profile` 的仓库，并编辑其中的 `README.md` 文件。Gitea 将自动获取该文件并在您的仓库上方显示。
|
||||
|
||||
注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。
|
||||
|
||||
用户示例 `.profile/README.md`:
|
||||
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "User Setting",
|
||||
"position": 200,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/user-setting",
|
||||
"description": "Configuring user preferences and settings"
|
||||
}
|
||||
}
|
||||
@@ -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是什麼?"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "運維",
|
||||
"position": 30,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/administration",
|
||||
"title": "運維"
|
||||
}
|
||||
}
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: adding-legal-pages
|
||||
sidebar_position: 110
|
||||
|
||||
aliases:
|
||||
- /zh-tw/adding-legal-pages
|
||||
---
|
||||
|
||||
# 添加法律頁面
|
||||
|
||||
一些法域（例如歐盟）要求在網站上添加特定的法律頁面（例如隱私政策）。按照以下步驟將它們添加到你的 Gitea 實例中。
|
||||
|
||||
## 獲取頁面
|
||||
|
||||
Gitea 源代碼附帶了示例頁面，位於 `contrib/legal` 目錄中。將它們複製到 `custom/public/assets/` 目錄下。例如，如果要添加隱私政策：
|
||||
|
||||
```
|
||||
wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/legal/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 以查看更改。
|
||||
+301
@@ -0,0 +1,301 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "authentication"
|
||||
sidebar_position: 10
|
||||
aliases:
|
||||
- /zh-tw/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 保护。
|
||||
:::
|
||||
+146
@@ -0,0 +1,146 @@
|
||||
---
|
||||
date: "2018-06-06T09:33:00+08:00"
|
||||
slug: "backup-and-restore"
|
||||
sidebar_position: 11
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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/gitea-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 --database $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/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/gitea-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/gitea-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
|
||||
```
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "cmd-embedded"
|
||||
sidebar_position: 20
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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
|
||||
```
|
||||
+534
File diff suppressed because it is too large.
Load diff
+1380
File diff suppressed because it is too large.
Load diff
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
date: "2017-04-15T14:56:00+02:00"
|
||||
slug: "customizing-gitea"
|
||||
sidebar_position: 100
|
||||
|
||||
aliases:
|
||||
- /zh-tw/customizing-gitea
|
||||
---
|
||||
|
||||
# 自定义 Gitea 配置
|
||||
|
||||
Gitea 引用 `custom` 目录中的自定义配置文件来覆盖配置、模板等默认配置。
|
||||
|
||||
如果从二进制部署 Gitea ，则所有默认路径都将相对于该 gitea 二进制文件；如果从发行版安装，则可能会将这些路径修改为 Linux 文件系统标准。Gitea
|
||||
将会自动创建包括 `custom/` 在内的必要应用目录，应用本身的配置存放在
|
||||
`custom/conf/app.ini` 当中。在发行版中可能会以 `/etc/gitea/` 的形式为 `custom` 设置一个符号链接，查看配置详情请移步：
|
||||
|
||||
- [快速备忘单](../administration/config-cheat-sheet.md)
|
||||
- [完整配置清单](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
|
||||
|
||||
如果您在 binary 同目录下无法找到 `custom` 文件夹，请检查您的 `GITEA_CUSTOM`
|
||||
环境变量配置， 因为它可能被配置到了其他地方（可能被一些启动脚本设置指定了目录）。
|
||||
|
||||
- [环境变量清单](../administration/environment-variables.md)
|
||||
|
||||
**注：** 必须完全重启 Gitea 以使配置生效。
|
||||
|
||||
## 使用自定义 /robots.txt
|
||||
|
||||
将 [想要展示的内容](http://www.robotstxt.org/) 存放在 `custom` 目录中的
|
||||
`robots.txt` 文件来让 Gitea 使用自定义的`/robots.txt` （默认：空 404）。
|
||||
|
||||
## 使用自定义的公共文件
|
||||
|
||||
将自定义的公共文件（比如页面和图片）作为 webroot 放在 `custom/public/` 中来让 Gitea 提供这些自定义内容（符号链接将被追踪）。
|
||||
|
||||
举例说明：`image.png` 存放在 `custom/public/assets/`中，那么它可以通过链接 http://gitea.domain.tld/assets/image.png 访问。
|
||||
|
||||
## 修改默认头像
|
||||
|
||||
替换以下目录中的 png 图片： `custom/public/assets/img/avatar\_default.png`
|
||||
|
||||
## 自定义 Gitea 页面
|
||||
|
||||
您可以改变 Gitea `custom/templates` 的每个单页面。您可以在 Gitea 源码的 `templates` 目录中找到用于覆盖的模板文件，应用将根据
|
||||
`custom/templates` 目录下的路径结构进行匹配和覆盖。
|
||||
|
||||
包含在 `{{` 和 `}}` 中的任何语句都是 Gitea 的模板语法，如果您不完全理解这些组件，不建议您对它们进行修改。
|
||||
|
||||
### 添加链接和页签
|
||||
|
||||
如果您只是想添加额外的链接到顶部导航栏或额外的选项卡到存储库视图，您可以将它们放在您 `custom/templates/custom/` 目录下的 `extra_links.tmpl` 和 `extra_tabs.tmpl` 文件中。
|
||||
|
||||
举例说明：假设您需要在网站放置一个静态的“关于”页面，您只需将该页面放在您的
|
||||
"custom/public/"目录下（比如 `custom/public/impressum.html`）并且将它与 `custom/templates/custom/extra_links.tmpl` 链接起来即可。
|
||||
|
||||
这个链接应当使用一个名为“item”的 class 来匹配当前样式，您可以使用 `{{AppSubUrl}}` 来获取 base URL:
|
||||
`<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
|
||||
|
||||
同理，您可以将页签添加到 `extra_tabs.tmpl` 中，使用同样的方式来添加页签。它的具体样式需要与
|
||||
`templates/repo/header.tmpl` 中已有的其他选项卡的样式匹配
|
||||
([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl))
|
||||
|
||||
### 页面的其他新增内容
|
||||
|
||||
除了 `extra_links.tmpl` 和 `extra_tabs.tmpl`，您可以在您的 `custom/templates/custom/` 目录中存放一些其他有用的模板，例如：
|
||||
|
||||
- `header.tmpl`，在 `<head>` 标记结束之前的模板，例如添加自定义 CSS 文件
|
||||
- `body_outer_pre.tmpl`，在 `<body>` 标记开始处的模板
|
||||
- `body_inner_pre.tmpl`，在顶部导航栏之前，但在主 container 内部的模板，例如添加一个 `<div class="full height">`
|
||||
- `body_inner_post.tmpl`，在主 container 结束处的模板
|
||||
- `body_outer_post.tmpl`，在底部 `<footer>` 元素之前.
|
||||
- `footer.tmpl`，在 `<body>` 标签结束处的模板，可以在这里填写一些附加的 Javascript 脚本。
|
||||
|
||||
## 自定义 gitignores，labels， licenses， locales 以及 readmes
|
||||
|
||||
将自定义文件放在 `custom/options` 下相应子的文件夹中即可
|
||||
|
||||
## 更改 Gitea 外观
|
||||
|
||||
内置主题是“gitea-light”、“gitea-dark”和“gitea-auto”（自动适应操作系统设置）。
|
||||
|
||||
默认主题可以通过 `app.ini` 的 [ui](../administration/config-cheat-sheet.md#界面) 部分中的 `DEFAULT_THEME` 进行更改。
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "email-setup"
|
||||
sidebar_position: 12
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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 帐户密码。
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
---
|
||||
date: "2017-04-08T11:34:00+02:00"
|
||||
slug: "environment-variables"
|
||||
sidebar_position: 10
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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 的形式运行。
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "external-renderers"
|
||||
sidebar_position: 60
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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 样式应用到特定的外部渲染器，使其具有所需的样式效果。
|
||||
+86
@@ -0,0 +1,86 @@
|
||||
---
|
||||
date: "2022-08-01T00:00:00+00:00"
|
||||
slug: "fail2ban-setup"
|
||||
sidebar_position: 16
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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#安全性)）
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "git-lfs-setup"
|
||||
sidebar_position: 12
|
||||
|
||||
aliases:
|
||||
- /zh-tw/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 以上版本。
|
||||
+89
@@ -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 上。
|
||||
+263
@@ -0,0 +1,263 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "logging-config"
|
||||
sidebar_position: 40
|
||||
aliases:
|
||||
- /zh-tw/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`。
|
||||
+254
@@ -0,0 +1,254 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "mail-templates"
|
||||
sidebar_position: 45
|
||||
aliases:
|
||||
- /zh-tw/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
|
||||
>
|
||||
```
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "repo-indexer"
|
||||
sidebar_position: 45
|
||||
aliases:
|
||||
- /zh-tw/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` 是等效的。
|
||||
+391
@@ -0,0 +1,391 @@
|
||||
---
|
||||
date: "2018-05-22T11:00:00+00:00"
|
||||
slug: "reverse-proxies"
|
||||
sidebar_position: 16
|
||||
aliases:
|
||||
- /zh-tw/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。
|
||||
|
||||
## 使用子路径
|
||||
|
||||
通常，**不推荐**将 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_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)?(/.*) $2 break;
|
||||
proxy_pass http://127.0.0.1:3000$uri;
|
||||
|
||||
# 其他的常规 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 / {
|
||||
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 / {
|
||||
proxy_pass http://localhost:3000;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```nginx
|
||||
# 提供静态资源的服务器
|
||||
server {
|
||||
listen 80;
|
||||
server_name cdn.example.com;
|
||||
|
||||
location /gitea/ {
|
||||
alias /path/to/gitea/public/;
|
||||
}
|
||||
|
||||
location / {
|
||||
return 404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用 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
|
||||
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
|
||||
|
||||
## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
|
||||
|
||||
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
|
||||
|
||||
```
|
||||
<VirtualHost *:80>
|
||||
...
|
||||
<Proxy *>
|
||||
Order allow,deny
|
||||
Allow from all
|
||||
</Proxy>
|
||||
AllowEncodedSlashes NoDecode
|
||||
# 注意: 路径和 URL 后面都不要写路径符号 '/'
|
||||
ProxyPass /git http://localhost:3000 nocanon
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
```apacheconf
|
||||
<VirtualHost *:80>
|
||||
...
|
||||
<Proxy *>
|
||||
Order allow,deny
|
||||
Allow from all
|
||||
</Proxy>
|
||||
AllowEncodedSlashes NoDecode
|
||||
# 注意: 路径和 URL 后面都不要写路径符号 '/'
|
||||
ProxyPass /git http://localhost:3000 nocanon
|
||||
ProxyPreserveHost On
|
||||
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
|
||||
|
||||
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
|
||||
|
||||
## 使用 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 的新图标。
|
||||
- 打开 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`
|
||||
- 现在，根据下面的内容为您的网页编辑 `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/` 的配置项。
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "search-engines-indexation"
|
||||
sidebar_position: 60
|
||||
aliases:
|
||||
- /zh-tw/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/
|
||||
```
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "signing"
|
||||
sidebar_position: 50
|
||||
aliases:
|
||||
- /zh-tw/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
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "貢獻",
|
||||
"position": 35,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/contributing",
|
||||
"title": "貢獻"
|
||||
}
|
||||
}
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
---
|
||||
date: "2023-05-25T23:41:00+08:00"
|
||||
slug: "guidelines-backend"
|
||||
sidebar_position: 20
|
||||
aliases:
|
||||
- /zh-tw/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`中。
|
||||
+149
@@ -0,0 +1,149 @@
|
||||
---
|
||||
date: "2023-05-25T16:00:00+02:00"
|
||||
slug: "guidelines-frontend"
|
||||
sidebar_position: 20
|
||||
aliases:
|
||||
- /zh-tw/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 示例的页面。
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
date: "2023-05-25T00:00:00+00:00"
|
||||
slug: "guidelines-refactoring"
|
||||
sidebar_position: 20
|
||||
aliases:
|
||||
- /zh-tw/guidelines-refactoring
|
||||
---
|
||||
|
||||
# 重构指南
|
||||
|
||||
## 背景
|
||||
|
||||
自 2014 年 2 月 12 日编写了第一行代码以来，Gitea 已经发展成为一个庞大的项目。
|
||||
因此，代码库变得越来越大。代码库越大，维护就越困难。
|
||||
存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
|
||||
为了使代码库更易于维护，使 Gitea 变得更好，开发人员应牢记使用现代机制来重构旧代码。
|
||||
|
||||
本文档是关于重构代码库的指南集合。
|
||||
|
||||
## 重构建议
|
||||
|
||||
- 设计更多关于未来的内容，而不仅仅解决当前问题。
|
||||
- 减少模糊性，减少冲突，提高可维护性。
|
||||
- 描述重构，例如：
|
||||
- 为什么需要重构。
|
||||
- 如何解决旧问题。
|
||||
- 重构的优点/缺点是什么。
|
||||
- 只做必要的更改，尽量保留旧逻辑。
|
||||
- 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
|
||||
- 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
|
||||
- 添加必要的测试以确保重构的正确性。
|
||||
- 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
|
||||
|
||||
## 审查和合并建议
|
||||
|
||||
- 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
|
||||
- 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
|
||||
- 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
|
||||
- 如果最终结果良好，容忍一些不完美/临时的步骤。
|
||||
- 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "localization"
|
||||
sidebar_position: 70
|
||||
aliases:
|
||||
- /zh-tw/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 的下一个版本才会出现。
|
||||
|
||||
如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "開發",
|
||||
"position": 40,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/development",
|
||||
"title": "開發"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
date: "2018-06-24:00:00+02:00"
|
||||
slug: "api-usage"
|
||||
sidebar_position: 40
|
||||
aliases:
|
||||
- /zh-tw/api-usage
|
||||
---
|
||||
|
||||
# API 使用指南
|
||||
|
||||
## 开启/配置 API 访问
|
||||
|
||||
通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
|
||||
|
||||
## 通过 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 即可。
|
||||
+334
@@ -0,0 +1,334 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "hacking-on-gitea"
|
||||
sidebar_position: 10
|
||||
aliases:
|
||||
- /zh-tw/hacking-on-gitea
|
||||
---
|
||||
|
||||
# 玩转 Gitea
|
||||
|
||||
## 快速入门
|
||||
|
||||
要获得快速工作的开发环境，您可以使用 Gitpod。
|
||||
|
||||
[](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/zh-tw/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-tw.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。
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: "2023-05-25T17:29:00+08:00"
|
||||
slug: "integrations"
|
||||
sidebar_position: 65
|
||||
aliases:
|
||||
- /zh-tw/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!
|
||||
```
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
date: "2023-05-25T17:29:00+08:00"
|
||||
slug: "migrations-interfaces"
|
||||
sidebar_position: 55
|
||||
aliases:
|
||||
- /zh-tw/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)中找到这些接口。
|
||||
+128
@@ -0,0 +1,128 @@
|
||||
---
|
||||
date: "2019-04-19:44:00+01:00"
|
||||
slug: "oauth2-provider"
|
||||
sidebar_position: 41
|
||||
aliases:
|
||||
- /zh-tw/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** | 完全控制所有存储库 |
|
||||
| **repo:status** | 授予对所有存储库中提交状态的读/写访问权限 |
|
||||
| **public_repo** | 仅授予对公共存储库的读/写访问权限 |
|
||||
| **admin:repo_hook** | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
|
||||
| **write:repo_hook** | 授予对存储库 Hooks 的读/写访问权限 |
|
||||
| **read:repo_hook** | 授予对存储库 Hooks 的只读访问权限 |
|
||||
| **admin:org** | 授予对组织设置的完全访问权限 |
|
||||
| **write:org** | 授予对组织设置的读/写访问权限 |
|
||||
| **read:org** | 授予对组织设置的只读访问权限 |
|
||||
| **admin:public_key** | 授予公钥管理的完全访问权限 |
|
||||
| **write:public_key** | 授予对公钥的读/写访问权限 |
|
||||
| **read:public_key** | 授予对公钥的只读访问权限 |
|
||||
| **admin:org_hook** | 授予对组织级别 Hooks 的完全访问权限 |
|
||||
| **admin:user_hook** | 授予对用户级别 Hooks 的完全访问权限 |
|
||||
| **notification** | 授予对通知的完全访问权限 |
|
||||
| **user** | 授予对用户个人资料信息的完全访问权限 |
|
||||
| **read:user** | 授予对用户个人资料的读取权限 |
|
||||
| **user:email** | 授予对用户电子邮件地址的读取权限 |
|
||||
| **user:follow** | 授予访问权限以关注/取消关注用户 |
|
||||
| **delete_repo** | 授予删除存储库的权限 |
|
||||
| **package** | 授予对托管包的完全访问权限 |
|
||||
| **write:package** | 授予对包的读/写访问权限 |
|
||||
| **read:package** | 授予对包的读取权限 |
|
||||
| **delete:package** | 授予对包的删除权限 |
|
||||
| **admin:gpg_key** | 授予 GPG 密钥管理的完全访问权限 |
|
||||
| **write:gpg_key** | 授予对 GPG 密钥的读/写访问权限 |
|
||||
| **read:gpg_key** | 授予对 GPG 密钥的只读访问权限 |
|
||||
| **admin:application** | 授予应用程序管理的完全访问权限 |
|
||||
| **write:application** | 授予应用程序管理的读/写访问权限 |
|
||||
| **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 攻击。
|
||||
|
||||
|
||||
|
||||
用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `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) 以读写用户的资源。
|
||||
Loaded 50 of 302 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user