Move usage directories (#300)

Reviewed-on: https://gitea.com/gitea/docs/pulls/300
2026-09-20 04:58:52 +00:00 · 2025-11-20 19:49:24 +00:00
parent 00a36086b0
commit 9baa98ec3f
302 changed files with 24392 additions and 880 deletions
@@ -0,0 +1,9 @@
+{
+  "label": "Repository",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/repository",
+    "description": "Repository management, Git operations, and content features"
+  }
+}
@@ -0,0 +1,18 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+
+slug: "clone-filters"
+sidebar_position: 25
+aliases:
+  - /zh-tw/clone-filters
+---
+
+# 克隆过滤器 (部分克隆)
+
+Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。
+
+这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。
+
+默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。
+
+请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。
@@ -0,0 +1,38 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+
+slug: "incoming-email"
+sidebar_position: 13
+aliases:
+  - /zh-tw/incoming-email
+---
+
+# 邮件接收
+
+Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。
+
+## 要求
+
+处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。
+推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。
+接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。
+此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。
+
+Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。
+
+## 配置
+
+要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。
+
+`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。
+该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。
+此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。
+
+使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com`
+
+如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
+
+## 安全性
+
+在选择用于接收传入电子邮件的域时要小心。
+建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。
@@ -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`:
+
+![个人资料自述文件截图](/images/usage/profile-readme.png)
@@ -0,0 +1,61 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "push"
+sidebar_position: 15
+aliases:
+  - /zh-tw/push-to-create
+  - /zh-tw/push-options
+---
+
+# 推送
+
+在将提交推送到 Gitea 服务器时，还有一些额外的功能。
+
+## 通过推送打开 PR
+
+当您第一次将提交推送到非默认分支时，您将收到一个链接，您可以单击该链接访问分支与主分支的比较页面。
+从那里，您可以轻松创建一个拉取请求，即使您想要将其目标指向另一个分支。
+
+![Gitea 推送提示](/gitea-push-hint.png)
+
+## 推送选项
+
+在 Gitea `1.13` 版本中，添加了对一些 [推送选项](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支持。
+
+### 支持的选项
+
+- `repo.private` (true|false) - 更改仓库的可见性。
+
+  这在与 push-to-create 结合使用时特别有用。
+
+- `repo.template` (true|false) - 更改仓库是否为模板。
+
+将仓库的可见性更改为公开的示例：
+
+```shell
+git push -o repo.private=false -u origin main
+```
+
+## 推送创建
+
+推送创建是一项功能，允许您将提交推送到在 Gitea 中尚不存在的仓库。这对于自动化和允许用户创建仓库而无需通过 Web 界面非常有用。此功能默认处于禁用状态。
+
+### 启用推送创建
+
+在 `app.ini` 文件中，将 `ENABLE_PUSH_CREATE_USER` 设置为 `true`，如果您希望允许用户在自己的用户帐户和所属的组织中创建仓库，将 `ENABLE_PUSH_CREATE_ORG` 设置为 `true`。重新启动 Gitea 以使更改生效。您可以在 [配置速查表](../administration/config-cheat-sheet.md#仓库) 中了解有关这两个选项的更多信息。
+
+### 使用推送创建
+
+假设您在当前目录中有一个 git 仓库，您可以通过运行以下命令将提交推送到在 Gitea 中尚不存在的仓库：
+
+```shell
+# 添加要推送到的远程仓库
+git remote add origin git@{domain}:{username}/{尚不存在的仓库名称}.git
+
+# 推送到远程仓库
+git push -u origin main
+```
+
+这假设您使用的是 SSH 远程，但您也可以使用 HTTPS 远程。
+
+推送创建将默认使用 `app.ini` 中定义的可见性 `DEFAULT_PUSH_CREATE_PRIVATE`。
@@ -0,0 +1,98 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "repo-mirror"
+sidebar_position: 45
+aliases:
+  - /zh-tw/repo-mirror
+---
+
+# 仓库镜像
+
+仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。
+
+## 使用场景
+
+以下是一些仓库镜像的可能使用场景：
+
+- 您迁移到了 Gitea，但仍需要在其他源中保留您的项目。在这种情况下，您可以简单地设置它以进行镜像到 Gitea（拉取），这样您的 Gitea 实例中就可以获取到所有必要的提交历史、标签和分支。
+- 您在其他源中有一些旧项目，您不再主动使用，但出于归档目的不想删除。在这种情况下，您可以创建一个推送镜像，以便您的活跃的 Gitea 仓库可以将其更改推送到旧位置。
+
+## 从远程仓库拉取
+
+对于现有的远程仓库，您可以按照以下步骤设置拉取镜像：
+
+1. 在右上角的“创建...”菜单中选择“迁移外部仓库”。
+2. 选择远程仓库服务。
+3. 输入仓库的 URL。
+4. 如果仓库需要身份验证，请填写您的身份验证信息。
+5. 选中“该仓库将是一个镜像”复选框。
+6. 选择“迁移仓库”以保存配置。
+
+现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。
+
+:::warning
+:exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation:
+:::
+
+## 推送到远程仓库
+
+对于现有的仓库，您可以按照以下步骤设置推送镜像：
+
+1. 在仓库中，转到**设置** > **仓库**，然后进入**镜像设置**部分。
+2. 输入一个仓库的 URL。
+3. 如果仓库需要身份验证，请展开**授权**部分并填写您的身份验证信息。请注意，所请求的**密码**也可以是您的访问令牌。
+4. 选择**添加推送镜像**以保存配置。
+
+该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。
+
+:::warning
+:exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation:
+:::
+
+### 从 Gitea 向 GitHub 设置推送镜像
+
+要从 Gitea 设置镜像到 GitHub，您需要按照以下步骤进行操作：
+
+1. 创建一个具有选中 _public_repo_ 选项的 [GitHub 个人访问令牌](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)。
+2. 在 GitHub 上创建一个同名的仓库。与 Gitea 不同，GitHub 不支持通过推送到远程来创建仓库。如果您的现有远程仓库与您的 Gitea 仓库具有相同的提交历史，您也可以使用现有的远程仓库。
+3. 在您的 Gitea 仓库设置中，填写**Git 远程仓库 URL**：`https://github.com/<your_github_group>/<your_github_project>.git`。
+4. 使用您的 GitHub 用户名填写**授权**字段，并将个人访问令牌作为**密码**。
+5. （可选，适用于 Gitea 1.18+）选择`当推送新提交时同步`，这样一旦有更改，镜像将会及时更新。如果您愿意，您还可以禁用定期同步。
+6. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 从 Gitea 向 GitLab 设置推送镜像
+
+要从 Gitea 设置镜像到 GitLab，您需要按照以下步骤进行操作：
+
+1. 创建具有 _write_repository_ 作用域的 [GitLab 个人访问令牌](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)。
+2. 填写**Git 远程仓库 URL**：`https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`。
+3. 在**授权**字段中填写 `oauth2` 作为**用户名**，并将您的 GitLab 个人访问令牌作为**密码**。
+4. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 从 Gitea 向 Bitbucket 设置推送镜像
+
+要从 Gitea 设置镜像到 Bitbucket，您需要按照以下步骤进行操作：
+
+1. 创建一个具有选中 _Repository Write_ 选项的 [Bitbucket 应用密码](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)。
+2. 填写**Git 远程仓库 URL**：`https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`。
+3. 使用您的 Bitbucket 用户名填写**授权**字段，并将应用密码作为**密码**。
+4. 选择**添加推送镜像**以保存配置。
+
+仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
+
+### 镜像现有的 ssh 仓库
+
+当前，Gitea 不支持从 ssh 仓库进行镜像。如果您想要镜像一个 ssh 仓库，您需要将其转换为 http 仓库。您可以使用以下命令将现有的 ssh 仓库转换为 http 仓库：
+
+1. 确保运行 gitea 的用户有权限访问您试图从 shell 镜像到的 git 仓库。
+2. 在 Web 界面的版本库设置 > git 钩子中为镜像添加一个接收后钩子。
+
+```
+#!/usr/bin/env bash
+git push --mirror --quiet [email protected]:username/repository.git &>/dev/null &
+echo "GitHub mirror initiated .."
+```
@@ -0,0 +1,76 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "template-repositories"
+sidebar_position: 14
+aliases:
+  - /zh-tw/template-repositories
+---
+
+# 模板仓库
+
+Gitea `1.11.0` 及以上版本引入了模板仓库，并且其中一个实现的功能是自动展开模板文件中的特定变量。
+
+要告诉 Gitea 哪些文件需要展开，您必须在模板仓库的 `.gitea` 目录中包含一个 `template` 文件。
+
+Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。它与传统的 `.gitignore` 语法非常相似，但可能存在细微的差异。
+
+## `.gitea/template` 文件示例
+
+所有路径都是相对于仓库的根目录
+
+```gitignore
+# 仓库中的所有 .go 文件
+**.go
+
+# text 目录中的所有文本文件
+text/*.txt
+
+# 特定文件
+a/b/c/d.json
+
+# 匹配批处理文件的大小写变体
+**.[bB][aA][tT]
+```
+
+**注意：** 当从模板生成仓库时，`.gitea` 目录中的 `template` 文件将被删除。
+
+## 参数展开
+
+在与上述通配符匹配的任何文件中，将会扩展某些变量。
+
+文件名和路径的匹配也可以被扩展，并且会经过谨慎的清理处理，以支持跨平台的文件系统。
+
+所有变量都必须采用`$VAR`或`${VAR}`的形式。要转义扩展，使用双重`$$`，例如`$$VAR`或`$${VAR}`。
+
+| 变量                 | 扩展为                        | 可转换 |
+| -------------------- | ----------------------------- | ------ |
+| REPO_NAME            | 生成的仓库名称                | ✓      |
+| TEMPLATE_NAME        | 模板仓库名称                  | ✓      |
+| REPO_DESCRIPTION     | 生成的仓库描述                | ✘      |
+| TEMPLATE_DESCRIPTION | 模板仓库描述                  | ✘      |
+| REPO_OWNER           | 生成的仓库所有者              | ✓      |
+| TEMPLATE_OWNER       | 模板仓库所有者                | ✓      |
+| REPO_LINK            | 生成的仓库链接                | ✘      |
+| TEMPLATE_LINK        | 模板仓库链接                  | ✘      |
+| REPO_HTTPS_URL       | 生成的仓库的 HTTP(S) 克隆链接 | ✘      |
+| TEMPLATE_HTTPS_URL   | 模板仓库的 HTTP(S) 克隆链接   | ✘      |
+| REPO_SSH_URL         | 生成的仓库的 SSH 克隆链接     | ✘      |
+| TEMPLATE_SSH_URL     | 模板仓库的 SSH 克隆链接       | ✘      |
+
+## 转换器 :robot:
+
+Gitea `1.12.0` 添加了一些转换器以应用于上述适用的变量。
+
+例如，要以 `PASCAL`-case 获取 `REPO_NAME`，你的模板应使用 `${REPO_NAME_PASCAL}`
+
+将 `go-sdk` 传递给可用的转换器的效果如下...
+
+| 转换器 | 效果   |
+| ------ | ------ |
+| SNAKE  | go_sdk |
+| KEBAB  | go-sdk |
+| CAMEL  | goSdk  |
+| PASCAL | GoSdk  |
+| LOWER  | go-sdk |
+| UPPER  | GO-SDK |
+| TITLE  | Go-Sdk |
@@ -0,0 +1,185 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "webhooks"
+sidebar_position: 30
+aliases:
+  - /zh-tw/webhooks
+---
+
+# Webhooks
+
+Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
+所有事件推送都是 POST 请求。目前支持：
+
+- Gitea (也可以是 GET 请求)
+- Gogs
+- Slack
+- Discord
+- Dingtalk（钉钉）
+- Telegram
+- Microsoft Teams
+- Feishu
+- Wechatwork（企业微信）
+- Packagist
+
+### 事件信息
+
+**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
+
+以下是 Gitea 将发送给 payload URL 的事件信息示例：
+
+```http
+X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-GitHub-Event: push
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gitea-Event: push
+```
+
+```json
+{
+  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
+  "ref": "refs/heads/develop",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Webhooks Yay!",
+      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "Gitea",
+        "email": "[email protected]",
+        "username": "gitea"
+      },
+      "committer": {
+        "name": "Gitea",
+        "email": "[email protected]",
+        "username": "gitea"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "gitea",
+      "full_name": "Gitea",
+      "email": "[email protected]",
+      "avatar_url": "https://localhost:3000/avatars/1",
+      "username": "gitea"
+    },
+    "name": "webhooks",
+    "full_name": "gitea/webhooks",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "http://localhost:3000/gitea/webhooks",
+    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
+    "clone_url": "http://localhost:3000/gitea/webhooks.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "master",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "[email protected]",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  },
+  "sender": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "[email protected]",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  }
+}
+```
+
+### 示例
+
+这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
+在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
+
+- 目标 URL：http://mydomain.com/webhook.php
+- HTTP 方法：POST
+- POST Content Type：application/json
+- Secret：123
+- 触发条件：推送事件
+- 激活：勾选
+
+现在在你的服务器上创建 php 文件 webhook.php。
+
+```php
+<?php
+
+$secret_key = '123';
+
+// check for POST request
+if ($_SERVER['REQUEST_METHOD'] != 'POST') {
+    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
+    exit();
+}
+
+// get content type
+$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
+
+if ($content_type != 'application/json') {
+    error_log('FAILED - not application/json - '. $content_type);
+    exit();
+}
+
+// get payload
+$payload = trim(file_get_contents("php://input"));
+
+if (empty($payload)) {
+    error_log('FAILED - no payload');
+    exit();
+}
+
+// get header signature
+$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
+
+if (empty($header_signature)) {
+    error_log('FAILED - header signature missing');
+    exit();
+}
+
+// calculate payload signature
+$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
+
+// check payload signature against header signature
+if ($header_signature !== $payload_signature) {
+    error_log('FAILED - payload signature');
+    exit();
+}
+
+// convert json to array
+$decoded = json_decode($payload, true);
+
+// check for json decode errors
+if (json_last_error() !== JSON_ERROR_NONE) {
+    error_log('FAILED - json decode - '. json_last_error());
+    exit();
+}
+
+// success, do something
+```
+
+在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
+
+### 授权头（Authorization header）
+
+**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。