From aa2b317e081615830522ca072ac703aa0487eea3 Mon Sep 17 00:00:00 2001
From: HesterG <hestergong@gmail.com>
Date: Fri, 26 May 2023 00:01:01 +0800
Subject: [PATCH] Add Chinese docs for help, contribution and development
 (#24925)

---
 .../contributing/guidelines-backend.en-us.md  |   3 +-
 .../contributing/guidelines-backend.zh-cn.md  | 123 +++++
 .../contributing/guidelines-frontend.zh-cn.md | 138 +++++
 .../guidelines-refactoring.zh-cn.md           |  53 ++
 .../doc/contributing/translation.zh-cn.md     |  17 +
 .../doc/development/integrations.zh-cn.md     |  46 ++
 .../doc/development/migrations.zh-cn.md       |  40 ++
 docs/content/doc/help/faq.zh-cn.md            | 472 ++++++++++++++++++
 8 files changed, 890 insertions(+), 2 deletions(-)
 create mode 100644 docs/content/doc/contributing/guidelines-backend.zh-cn.md
 create mode 100644 docs/content/doc/contributing/guidelines-frontend.zh-cn.md
 create mode 100644 docs/content/doc/contributing/guidelines-refactoring.zh-cn.md
 create mode 100644 docs/content/doc/contributing/translation.zh-cn.md
 create mode 100644 docs/content/doc/development/integrations.zh-cn.md
 create mode 100644 docs/content/doc/development/migrations.zh-cn.md
 create mode 100644 docs/content/doc/help/faq.zh-cn.md

diff --git a/docs/content/doc/contributing/guidelines-backend.en-us.md b/docs/content/doc/contributing/guidelines-backend.en-us.md
index fd0f8b083..283fbdf3a 100644
--- a/docs/content/doc/contributing/guidelines-backend.en-us.md
+++ b/docs/content/doc/contributing/guidelines-backend.en-us.md
@@ -37,7 +37,7 @@ To maintain understandable code and avoid circular dependencies it is important
 - `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
 - `tests`: Common test utility functions
   - `tests/integration`: Integration tests, to test back-end regressions
-  - `tests/e2e`: E2e tests, to test test front-end <> back-end compatibility and visual regressions.
+  - `tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions.
 - `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
   - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
   - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
@@ -72,7 +72,6 @@ So services must be allowed to create a database transaction. Here is some examp
 // services/repository/repository.go
 func CreateXXXX() error {
     return db.WithTx(func(ctx context.Context) error {
-        e := db.GetEngine(ctx)
         // do something, if err is returned, it will rollback automatically
         if err := issues.UpdateIssue(ctx, repoID); err != nil {
             // ...
diff --git a/docs/content/doc/contributing/guidelines-backend.zh-cn.md b/docs/content/doc/contributing/guidelines-backend.zh-cn.md
new file mode 100644
index 000000000..c94d4305e
--- /dev/null
+++ b/docs/content/doc/contributing/guidelines-backend.zh-cn.md
@@ -0,0 +1,123 @@
+---
+date: "2023-05-25T23:41:00+08:00"
+title: "后端开发指南"
+slug: "guidelines-backend"
+weight: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-backend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "后端开发指南"
+    weight: 20
+    identifier: "guidelines-backend"
+---
+
+# 后端开发指南
+
+**目录**
+
+{{< toc >}}
+
+## 背景
+
+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`中。
diff --git a/docs/content/doc/contributing/guidelines-frontend.zh-cn.md b/docs/content/doc/contributing/guidelines-frontend.zh-cn.md
new file mode 100644
index 000000000..3a58db0c7
--- /dev/null
+++ b/docs/content/doc/contributing/guidelines-frontend.zh-cn.md
@@ -0,0 +1,138 @@
+---
+date: "2023-05-25T16:00:00+02:00"
+title: "前端开发指南"
+slug: "guidelines-frontend"
+weight: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-frontend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "前端开发指南"
+    weight: 20
+    identifier: "guidelines-frontend"
+---
+
+# 前端开发指南
+
+**目录**
+
+{{< toc >}}
+
+## 背景
+
+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. Gitea 的 tailwind-style CSS 类使用`gt-`前缀（`gt-relative`），而 Gitea 自身的私有框架级 CSS 类使用`g-`前缀（`g-modal-confirm`）。
+
+### 可访问性 / ARIA
+
+在历史上，Gitea大量使用了可访问性不友好的框架 Fomantic UI。
+Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`aria.md`），
+但仍然存在许多问题需要大量的工作和时间来修复。
+
+### 框架使用
+
+不建议混合使用不同的框架，这会使代码难以维护。
+一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
+
+推荐的实现方式：
+
+* Vue + Vanilla JS
+* Fomantic-UI（jQuery）
+* Vanilla JS
+
+不推荐的实现方式：
+
+* Vue + Fomantic-UI（jQuery）
+* jQuery + Vanilla JS
+
+为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
+尽管不建议混合使用不同的框架，
+但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
+
+### 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 时发出警告。
+
+### HTML 属性和 dataset
+
+禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
+然而，仍然存在一些特殊情况，因此当前的准则是：
+
+* 对于旧代码：
+  * 应将`$.data()`重构为`$.attr()`。
+  * 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
+
+* 对于新代码：
+  * 不应使用`node.dataset`，而应使用`node.getAttribute`。
+  * 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
+
+### 显示/隐藏元素
+
+* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
+* Go 模板代码应使用 Gitea 的 `.gt-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.gt-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 代码分离。
diff --git a/docs/content/doc/contributing/guidelines-refactoring.zh-cn.md b/docs/content/doc/contributing/guidelines-refactoring.zh-cn.md
new file mode 100644
index 000000000..9356fbd11
--- /dev/null
+++ b/docs/content/doc/contributing/guidelines-refactoring.zh-cn.md
@@ -0,0 +1,53 @@
+---
+date: "2023-05-25T00:00:00+00:00"
+title: "重构指南"
+slug: "guidelines-refactoring"
+weight: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-refactoring
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "重构指南"
+    weight: 20
+    identifier: "guidelines-refactoring"
+---
+
+# 重构指南
+
+**目录**
+
+{{< toc >}}
+
+## 背景
+
+自2014年2月12日编写了第一行代码以来，Gitea已经发展成为一个庞大的项目。
+因此，代码库变得越来越大。代码库越大，维护就越困难。
+存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
+为了使代码库更易于维护，使Gitea变得更好，开发人员应牢记使用现代机制来重构旧代码。
+
+本文档是关于重构代码库的指南集合。
+
+## 重构建议
+
+* 设计更多关于未来的内容，而不仅仅解决当前问题。
+* 减少模糊性，减少冲突，提高可维护性。
+* 描述重构，例如：
+  * 为什么需要重构。
+  * 如何解决旧问题。
+  * 重构的优点/缺点是什么。
+* 只做必要的更改，尽量保留旧逻辑。
+* 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个PR中完成。
+* 如果存在分歧，应该请TOC（技术监督委员会）参与决策。
+* 添加必要的测试以确保重构的正确性。
+* 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
+
+## 审查和合并建议
+
+* 重构的PR不应该长时间保持打开状态（通常为7天），应尽快进行审查。
+* 重构的PR应尽快合并，不应被其他PR阻塞。
+* 如果TOC没有异议，重构的PR可以在7天后由一名核心成员（非作者）批准后合并。
+* 如果最终结果良好，容忍一些不完美/临时的步骤。
+* 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
diff --git a/docs/content/doc/contributing/translation.zh-cn.md b/docs/content/doc/contributing/translation.zh-cn.md
new file mode 100644
index 000000000..8082c30be
--- /dev/null
+++ b/docs/content/doc/contributing/translation.zh-cn.md
@@ -0,0 +1,17 @@
+---
+date: "2023-05-25T00:00:00+02:00"
+title: "翻译指南"
+weight: 70
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "翻译指南"
+    weight: 70
+    identifier: "translation-guidelines"
+---
+
+本页面用于提供一套通用规则，以确保翻译的一致性。
+
+* [German](/de-de/übersetzungs-richtlinien/)
diff --git a/docs/content/doc/development/integrations.zh-cn.md b/docs/content/doc/development/integrations.zh-cn.md
new file mode 100644
index 000000000..694a9d561
--- /dev/null
+++ b/docs/content/doc/development/integrations.zh-cn.md
@@ -0,0 +1,46 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+title: "集成"
+slug: "integrations"
+weight: 65
+toc: false
+draft: false
+aliases:
+  - /zh-cn/integrations
+menu:
+  sidebar:
+    parent: "development"
+    name: "集成"
+    weight: 65
+    identifier: "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!
+```
diff --git a/docs/content/doc/development/migrations.zh-cn.md b/docs/content/doc/development/migrations.zh-cn.md
new file mode 100644
index 000000000..8e3d73417
--- /dev/null
+++ b/docs/content/doc/development/migrations.zh-cn.md
@@ -0,0 +1,40 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+title: "迁移界面"
+slug: "migrations-interfaces"
+weight: 55
+toc: false
+draft: false
+aliases:
+  - /zh-cn/migrations-interfaces
+menu:
+  sidebar:
+    parent: "development"
+    name: "迁移界面"
+    weight: 55
+    identifier: "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)中找到这些接口。
diff --git a/docs/content/doc/help/faq.zh-cn.md b/docs/content/doc/help/faq.zh-cn.md
new file mode 100644
index 000000000..1b7960473
--- /dev/null
+++ b/docs/content/doc/help/faq.zh-cn.md
@@ -0,0 +1,472 @@
+---
+date: "2023-05-25T16:00:00+02:00"
+title: "常见问题"
+slug: "faq"
+weight: 5
+toc: false
+draft: false
+aliases:
+  - /zh-cn/faq
+menu:
+  sidebar:
+    parent: "help"
+    name: "常见问题"
+    weight: 5
+    identifier: "faq"
+---
+
+# 常见问题 <!-- omit in toc -->
+
+本页面包含一些常见问题和答案。
+
+有关更多帮助资源，请查看所有[支持选项]({{< relref "doc/help/support.en-us.md" >}})。
+
+**目录**
+
+{{< toc >}}
+
+## 1.x和1.x.x下载之间的区别
+
+以1.7.x版本为例。
+
+**注意：**此示例也适用于Docker镜像！
+
+在我们的[下载页面](https://dl.gitea.io/gitea/)上，您会看到一个1.7目录，以及1.7.0、1.7.1、1.7.2、1.7.3、1.7.4、1.7.5和1.7.6的目录。
+
+1.7目录和1.7.0目录是**不同**的。1.7目录是在每个合并到[`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7)分支的提交上构建的。
+
+然而，1.7.0目录是在创建[`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0)标签时创建的构建。
+
+这意味着1.x的下载会随着提交合并到各自的分支而改变（将其视为每个版本的单独的“main”分支）。
+
+另一方面，1.x.x的下载应该永远不会改变。
+
+## 如何从Gogs/GitHub等迁移到Gitea
+
+要从Gogs迁移到Gitea：
+
+- [Gogs版本0.9.146或更低]({{< relref "doc/installation/upgrade-from-gogs.en-us.md" >}})
+- [Gogs版本0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
+
+要从GitHub迁移到Gitea，您可以使用Gitea内置的迁移表单。
+
+为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。
+
+[Example (requires login)](https://try.gitea.io/repo/migrate)
+
+要从GitLab迁移到Gitea，您可以使用这个非关联的工具：
+
+https://github.com/loganinak/MigrateGitlabToGogs
+
+## Gitea存储文件的位置
+
+- _`AppWorkPath`_
+  - `--work-path`标志
+  - 或者环境变量`GITEA_WORK_DIR`
+  - 或者在构建时设置的内置值
+  - 或者包含Gitea二进制文件的目录
+- `%(APP_DATA_PATH)`（数据库、索引器等的默认路径）
+  - `app.ini`中的`APP_DATA_PATH`
+  - 或者_`AppWorkPath`_`/data`
+- _`CustomPath`_（自定义模板）
+  - `--custom-path`标志
+  - 或者环境变量`GITEA_CUSTOM`
+  - 或者在构建时设置的内置值
+  - 或者_`AppWorkPath`_`/custom`
+- HomeDir
+  - Unix：环境变量`HOME`
+  - Windows：环境变量`USERPROFILE`，或者环境变量`HOMEDRIVE`+`HOMEPATH`
+- RepoRootPath
+  - `app.ini`中\[repository]部分的`ROOT`（如果是绝对路径）
+  - 否则_`AppWorkPath`_`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相对路径）
+  - 默认值为`%(APP_DATA_PATH)/gitea-repositories`
+- INI（配置文件）
+  - `--config`标志
+  - 或者在构建时设置的可能内置值
+  - 或者 _`CustomPath`_`/conf/app.ini`
+- SQLite数据库
+  - app.ini中database部分的PATH
+  - 或者`%(APP_DATA_PATH)/gitea.db`
+
+## 看不到克隆URL或克隆URL不正确
+
+有几个地方可能会导致显示不正确。
+
+1. 如果使用反向代理，请确保按照[反向代理指南]({{< relref "doc/administration/reverse-proxies.en-us.md" >}})中的正确说明进行设置。
+2. 确保在`app.ini`的`server`部分中正确设置了`ROOT_URL`。
+
+如果某些克隆选项未显示（HTTP/S或SSH），可以在`app.ini中`
+
+- `DISABLE_HTTP_GIT`: 如果设为true, 将会没有HTTP/HTTPS链接
+- `DISABLE_SSH`: 如果设为true, 将会没有SSH链接
+- `SSH_EXPOSE_ANONYMOUS`: 如果设为false, SSH链接将会对匿名用户隐藏
+
+## 文件上传失败：413 Request Entity Too Large
+
+当反向代理限制文件上传大小时，会出现此错误。
+
+有关使用nginx解决此问题，请参阅[反向代理指南]({{< relref "doc/administration/reverse-proxies.en-us.md" >}})。
+
+## 自定义模板无法加载或运行错误
+
+Gitea的自定义模板必须将其添加到正确的位置，否则Gitea将无法找到并使用自定义模板。
+
+模板的正确路径应该相对于`CustomPath`。
+
+1. 要找到`CustomPath`，请在站点管理 -> 配置 中查找自定义文件根路径。
+
+    如果找不到，请尝试`echo $GITEA_CUSTOM`。
+
+2. 如果仍然找不到，默认值可以被[计算]({{< relref "doc/help/faq.en-us.md#where-does-gitea-store-what-file" >}})
+3. 如果仍然找不到路径，则可以参考[自定义Gitea]({{< relref "doc/administration/customizing-gitea.en-us.md" >}})页面，将模板添加到正确的位置。
+
+## Gitea是否有"GitHub/GitLab Pages"功能？
+
+Gitea不提供内置的Pages服务器。您需要一个专用的域名来提供静态页面，以避免CSRF安全风险。
+
+对于简单的用法，您可以使用反向代理来重写和提供Gitea的原始文件URL中的静态内容。
+
+还有一些已经可用的第三方服务，比如独立[pages server](https://codeberg.org/Codeberg/pages-server)的或[caddy plugin](https://github.com/42wim/caddy-gitea)，可以提供所需的功能。
+
+## 活跃用户与禁止登录用户
+
+在Gitea中，"活跃用户"是指通过电子邮件激活其帐户的用户。
+
+"禁止登录用户"是指不允许再登录到Gitea的用户。
+
+## 设置日志记录
+
+- [官方文档]({{< relref "doc/administration/logging-config.en-us.md" >}})
+
+## 什么是Swagger？
+
+[Swagger](https://swagger.io/) 是Gitea用于其API文档的工具。
+
+所有Gitea实例都有内置的API，无法完全禁用它。
+但是，您可以在app.ini的api部分将ENABLE_SWAGGER设置为false，以禁用其文档显示。
+有关更多信息，请参阅Gitea的[API文档]({{< relref "doc/development/api-usage.en-us.md" >}})。
+
+您可以在上查看最新的API（例如）<https://try.gitea.io/api/swagger>。
+
+您还可以在上查看`swagger.json`文件的示例 <https://try.gitea.io/swagger.v1.json>。
+
+## 调整服务器用于公共/私有使用
+
+### 防止垃圾邮件发送者
+
+有多种方法可以组合使用来防止垃圾邮件发送者：
+
+1. 通过设置电子邮件域名的白名单或黑名单。
+2. 通过设置一些域名或者OpenID白名单（见下文）。
+3. 在您的`app.ini`中将`ENABLE_CAPTCHA`设置为`true`，并正确配置`RECAPTCHA_SECRET`和 `RECAPTCHA_SITEKEY`。
+4. 将`DISABLE_REGISTRATION`设置为`true`，并通过 [CLI]({{< relref "doc/administration/command-line.en-us.md" >}})、[API]({{< relref "doc/development/api-usage.en-us.md" >}}) 或 Gitea 的管理界面创建新用户。
+
+### 仅允许/阻止特定的电子邮件域名
+
+您可以在`app.ini`中的`[service]`下的配置`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
+
+### 仅允许/阻止特定的 OpenID 提供商
+
+您可以在`app.ini`的`[openid]`下配置`WHITELISTED_URI`或`BLACKLISTED_URIS`。
+
+**注意**： 白名单优先，如果白名单非空，则忽略黑名单。
+
+### 仅允许发布问题的用户
+
+目前实现这一点的方法是创建/修改一个具有最大仓库创建限制为 0 的用户。
+
+### 受限制的用户
+
+受限制的用户仅能访问其组织/团队成员和协作所在的内容的子集，而忽略组织/仓库等的公共标志。
+
+示例用例：一个公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。
+
+在某些情况下，某个客户或第三方需要访问特定的仓库，并且只能访问该仓库。通过将此类客户帐户设置为受限制帐户，并使用团队成员身份和/或协作来授予所需的任何访问权限，可以简单地实现这一点，而无需使所有内容都变为私有。
+
+### 启用 Fail2ban
+
+使用 [Fail2Ban]({{< relref "doc/administration/fail2ban-setup.en-us.md" >}}) 监视并阻止基于日志模式的自动登录尝试或其他恶意行为。
+
+## 如何添加/使用自定义主题
+
+Gitea 目前支持三个官方主题，分别是 `gitea`（亮色）、`arc-green`（暗色）和 `auto`（根据操作系统设置自动切换前两个主题）。
+要添加自己的主题，目前唯一的方法是提供一个完整的主题（不仅仅是颜色覆盖）。
+
+假设我们的主题是 `arc-blue`（这是一个真实的主题，可以在[此问题](https://github.com/go-gitea/gitea/issues/6011)中找到）
+
+将`.css`文件命名为`theme-arc-blue.css`并将其添加到`custom/public/css`文件夹中
+
+通过将`arc-blue`添加到`app.ini`中的`THEMES`列表中，允许用户使用该主题
+
+## SSHD vs 内建SSH
+
+SSHD是大多数Unix系统上内建的SSH服务器。
+
+Gitea还提供了自己的SSH服务器，用于在SSHD不可用时使用。
+
+## Gitea运行缓慢
+
+导致此问题的最常见原因是加载联合头像。
+
+您可以通过在`app.ini`中将`ENABLE_FEDERATED_AVATAR`设置为`false`来关闭此功能。
+
+还有一个可能需要更改的选项是在`app.ini`中将`DISABLE_GRAVATAR`设置为`true`。
+
+## 无法创建仓库/文件
+
+请确保Gitea具有足够的权限来写入其主目录和数据目录。
+
+参见[AppDataPath 和 RepoRootPath]({{< relref "doc/help/faq.en-us.md#where-does-gitea-store-what-file" >}})
+
+**适用于Arch用户的注意事项：**在撰写本文时，Arch软件包的systemd文件包含了以下行：
+
+`ReadWritePaths=/etc/gitea/app.ini`
+
+这将使得Gitea无法写入其他路径。
+
+## 翻译不正确/如何添加更多翻译
+
+我们当前的翻译是在我们的[Crowdin项目](https://crowdin.com/project/gitea)上众包进行的
+
+无论您想要更改翻译还是添加新的翻译，都需要在Crowdin集成中进行，因为所有翻译都会被CI覆盖。
+
+## 推送钩子/ Webhook未运行
+
+如果您可以推送但无法在主页仪表板上看到推送活动，或者推送不触发Webhook，有几种可能性：
+
+1. Git钩子不同步：在站点管理面板上运行“重新同步所有仓库的pre-receive、update和post-receive钩子”
+2. Git仓库（和钩子）存储在一些不支持脚本执行的文件系统上（例如由NAS挂载），请确保文件系统支持`chmod a+x any-script`
+3. 如果您使用的是Docker，请确保Docker Server（而不是客户端）的版本 >= 20.10.6
+
+## SSH问题
+
+如果无法通过`ssh`访问仓库，但`https`正常工作，请考虑以下情况。
+
+首先，请确保您可以通过SSH访问Gitea。
+
+`ssh git@myremote.example`
+
+如果连接成功，您应该会收到以下错误消息：
+
+```
+Hi there, You've successfully authenticated, but Gitea does not provide shell access.
+If this is unexpected, please log in with password and setup Gitea under another user.
+```
+
+如果您收到以上消息但仍然连接成功，这意味着您的 SSH 密钥**没有**由 Gitea 管理。这意味着钩子不会运行，在其他一些潜在问题中也包括在内。
+
+如果您无法连接，可能是因为您的 SSH 密钥在本地配置不正确。
+这是针对 SSH 而不是 Gitea 的问题，因此在此不涉及。
+
+### SSH 常见错误
+
+```
+Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+此错误表示服务器拒绝登录尝试，
+请检查以下事项：
+
+- 在客户端：
+  - 确保公钥和私钥已添加到正确的 Gitea 用户。
+  - 确保远程 URL 中没有任何问题。特别是，请确保∂
+  Git 用户（@ 之前的部分）的名称拼写正确。
+  - 确保客户端机器上的公钥和私钥正确无误。
+- 在服务器上：
+  - 确保存储库存在并且命名正确。
+  - 检查系统用户主目录中的 `.ssh` 目录的权限。
+  - 验证正确的公钥是否已添加到 `.ssh/authorized_keys` 中。
+
+  尝试在 Gitea 管理面板上运行
+  `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
+- 查看 Gitea 日志。
+- 查看 /var/log/auth（或类似的文件）。
+- 检查存储库的权限。
+
+以下是一个示例，其中缺少公共 SSH 密钥，
+认证成功，但是其他设置导致 SSH 无法访问正确的
+存储库。
+
+```
+fatal: Could not read from remote repository.
+
+Please make sure you have the correct access rights
+and the repository exists.
+```
+
+在这种情况下，请检查以下设置：
+
+- 在服务器上：
+  - 确保`git`系统用户设置了可用的 shell
+    - 使用`getent passwd git | cut -d: -f7`进行验证
+    - 可以使用`usermod`或`chsh`进行修改。
+  - 确保`.ssh/authorized_keys`中的`gitea serv`命令使用
+    正确的配置文件。
+
+## 迁移带有标签的存储库后缺失发布版本
+
+要迁移带有所有标签的存储库，您需要执行两个操作：
+
+- 推送标签到存储库：
+
+```
+ git push --tags
+```
+
+- 在 Gitea 中重新同步所有存储库的标签：
+
+```
+gitea admin repo-sync-releases
+```
+
+## LFS 问题
+
+针对涉及 LFS 数据上传的问题
+
+```
+batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
+Check that you have proper access to the repository
+error: failed to push some refs to '<GIT_REPO_URL>'
+```
+
+检查`app.ini`文件中的`LFS_HTTP_AUTH_EXPIRY`值。
+
+默认情况下，LFS 令牌在 20 分钟后过期。如果您的连接速度较慢或文件较大（或两者都是），可能无法在时间限制内完成上传。
+
+您可以将此值设置为`60m`或`120m`。
+
+## 如何在启动 Gitea 之前创建用户
+
+Gitea 提供了一个子命令`gitea migrate`来初始化数据库，然后您可以使用[管理 CLI 命令]({{< relref "doc/administration/command-line.en-us.md#admin" >}})像正常情况下添加用户。
+
+## 如何启用密码重置
+
+没有密码重置的设置。当配置了[邮件服务]({{< relref "doc/administration/email-setup.en-us.md" >}})时，密码重置将自动启用；否则将被禁用。
+
+## 如何更改用户的密码
+
+- 作为管理员，您可以更改任何用户的密码（并可选择强制其在下次登录时更改密码）...
+  - 转到您的`站点管理 -> 用户账户`页面并编辑用户。
+- 使用[管理 CLI 命令]({{< relref "doc/administration/command-line.en-us.md#admin" >}})。
+
+  请注意，大多数命令还需要一个[全局标志]({{< relref "doc/administration/command-line.en-us.- md#global-options" >}})来指向正确的配置。
+- 作为**用户**，您可以更改密码...
+  - 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
+  - 使用`忘记密码`链接。
+
+  如果`忘记密码/账户恢复`页面被禁用，请联系管理员配置[邮件服务]({{< relref "doc/administration/email-setup.en-us.md" >}})。
+
+## 为什么我的 Markdown 显示错误
+
+在 Gitea 版本 `1.11` 中，我们转换为使用[goldmark](https://github.com/yuin/goldmark)进行 Markdown 渲染，它符合[CommonMark](https://commonmark.org/)标准。
+
+如果您在版本`1.11`之前的Markdown正常工作，但在升级后无法正常工作，请仔细阅读CommonMark规范，看看问题是由错误还是非兼容的语法引起的。
+
+如果是后者，通常规范中会列出一种符合标准的替代方法。
+
+## 使用 MySQL 进行升级时出现的错误
+
+如果在使用 MySQL 升级 Gitea 时收到以下错误：
+
+> `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...`
+
+请运行`gitea convert`或对数据库中的每个表运行`ALTER TABLE table_name ROW_FORMAT=dynamic;`。
+
+潜在问题是默认行格式分配给每个表的索引空间
+太小。Gitea 要求其表的`ROWFORMAT`为`DYNAMIC`。
+
+如果收到包含`Error 1071: Specified key was too long; max key length is 1000 bytes...`
+的错误行，则表示您正在尝试在使用 ISAM 引擎的表上运行 Gitea。尽管在先前版本的 Gitea 中可能是凑巧能够工作的，但它从未得到官方支持，
+您必须使用 InnoDB。您应该对数据库中的每个表运行`ALTER TABLE table_name ENGINE=InnoDB;`。
+
+如果您使用的是 MySQL 5，另一个可能的修复方法是：
+
+```mysql
+SET GLOBAL innodb_file_format=Barracuda;
+SET GLOBAL innodb_file_per_table=1;
+SET GLOBAL innodb_large_prefix=1;
+```
+
+## 为什么 MySQL 上的 Emoji 显示错误
+
+不幸的是，MySQL 的`utf8`字符集不完全允许所有可能的 UTF-8 字符，特别是 Emoji。
+他们创建了一个名为 `utf8mb4`的字符集和校对规则，允许存储 Emoji，但使用
+utf8 字符集的表和连接将不会使用它。
+
+请运行 `gitea convert` 或对数据库运行`ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
+并对每个表运行
+`ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`。
+
+您还需要将`app.ini`文件中的数据库字符集设置为`CHARSET=utf8mb4`。
+
+## 为什么 Emoji 只显示占位符或单色图像
+
+Gitea 需要系统或浏览器安装其中一个受支持的 Emoji 字体，例如 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系统应该已经提供了其中一个字体，但特别是在 Linux 上，可能需要手动安装它们。
+
+## SystemD 和 Docker 上的标准输出日志
+
+SystemD 上的标准输出默认会写入日志记录中。您可以尝试使用 `journalctl`、`journalctl -u gitea` 或 `journalctl <path-to-gitea-binary>`来查看。
+
+类似地，Docker 上的标准输出可以使用`docker logs <container>`来查看。
+
+要收集日志以进行帮助和问题报告，请参阅[支持选项]({{< relref "doc/help/support.en-us.md" >}})。
+
+## 初始日志记录
+
+在 Gitea 读取配置文件并设置其日志记录之前，它会将一些内容记录到标准输出，以帮助调试日志记录无法工作的情况。
+
+您可以通过设置`--quiet`或`-q`选项来停止此日志记录。请注意，这只会在 Gitea 设置自己的日志记录之前停止日志记录。
+
+如果您报告了错误或问题，必须提供这些信息以恢复初始日志记录。
+
+只有在完全配置了所有内容之后，您才应该设置此选项。
+
+## 在数据库启动期间出现有关结构默认值的警告
+
+有时，在迁移过程中，旧列和默认值可能在数据库架构中保持不变。
+这可能会导致警告，例如：
+
+```
+2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [W] Table user Column keep_activity_private db default is , struct default is 0
+```
+
+可以安全地忽略这些警告，但您可以通过让 Gitea 重新创建这些表来停止这些警告，使用以下命令：
+
+```
+gitea doctor recreate-table user
+```
+
+这将导致 Gitea 重新创建用户表并将旧数据复制到新表中，
+并正确设置默认值。
+
+您可以使用以下命令要求 Gitea 重新创建多个表：
+
+```
+gitea doctor recreate-table table1 table2 ...
+```
+
+如果您希望 Gitea 重新创建所有表，请使用以下命令：
+
+```
+gitea doctor recreate-table
+```
+
+在运行这些命令之前，强烈建议您备份数据库。
+
+## 为什么查看文件时制表符/缩进显示错误
+
+如果您正在使用 Cloudflare，请在仪表板中关闭自动缩小选项。
+
+`Speed` -> `Optimization` -> 在 `Auto-Minify` 设置中取消选中 `HTML`。
+
+## 如何从磁盘采用存储库
+
+- 将您的（裸）存储库添加到正确的位置，即您的配置所在的地方（`repository.ROOT`），确保它们位于正确的布局`<REPO_ROOT>/[user]/[repo].git`。
+  - **注意：**目录名必须为小写。
+  - 您还可以在`<ROOT_URL>/admin/config`中检查存储库根路径。
+- 确保存在要采用存储库的用户/组织。
+- 作为管理员，转到`<ROOT_URL>/admin/repos/unadopted`并搜索。
+- 用户也可以通过配置[`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`]({{< relref "doc/administration/- config-cheat-sheet.en-us.md#repository" >}}) 获得类似的权限。
+- 如果上述步骤都正确执行，您应该能够选择要采用的存储库。
+  - 如果没有找到存储库，请启用[调试日志记录]({{< relref "doc/administration/config-cheat-sheet.en-us.- md#repository" >}})以检查是否有特定错误。