ZH-CN translation of Advanced part (#5090)
BetaCat
6 years ago
committed by
Lauris BH
parent
34695f460a
commit
4cdab02273
@ -0,0 +1,71 @@ |
||||
--- |
||||
date: "2018-06-24:00:00+02:00" |
||||
title: "API 使用指南" |
||||
slug: "api-usage" |
||||
weight: 40 |
||||
toc: true |
||||
draft: false |
||||
menu: |
||||
sidebar: |
||||
parent: "advanced" |
||||
name: "API 使用指南" |
||||
weight: 40 |
||||
identifier: "api-usage" |
||||
--- |
||||
|
||||
# Gitea API 使用指南 |
||||
|
||||
## 开启/配置 API 访问 |
||||
|
||||
通常情况下， `ENABLE_SWAGGER_ENDPOINT` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat |
||||
Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) 中获取更多配置相关信息。 |
||||
|
||||
## 通过 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 -X POST "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 --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens |
||||
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] |
||||
``` |
||||
|
||||
## 使用 Sudo 方式请求 API |
||||
|
||||
此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。 |
||||
@ -0,0 +1,88 @@ |
||||
--- |
||||
date: "2017-04-15T14:56:00+02:00" |
||||
title: "自定义 Gitea 配置" |
||||
slug: "customizing-gitea" |
||||
weight: 9 |
||||
toc: false |
||||
draft: false |
||||
menu: |
||||
sidebar: |
||||
parent: "advanced" |
||||
name: "自定义 Gitea 配置" |
||||
weight: 9 |
||||
identifier: "customizing-gitea" |
||||
--- |
||||
|
||||
# 自定义 Gitea 配置 |
||||
|
||||
Gitea 引用 `custom` 目录中的自定义配置文件来覆盖配置、模板等默认配置。 |
||||
|
||||
如果从二进制部署 Gitea ，则所有默认路径都将相对于该 gitea 二进制文件；如果从发行版安装，则可能会将这些路径修改为Linux文件系统标准。Gitea |
||||
将会自动创建包括 `custom/` 在内的必要应用目录，应用本身的配置存放在 |
||||
`custom/conf/app.ini` 当中。在发行版中可能会以 `/etc/gitea/` 的形式为 `custom` 设置一个符号链接，查看配置详情请移步： |
||||
|
||||
- [快速备忘单](https://docs.gitea.io/en-us/config-cheat-sheet/) |
||||
- [完整配置清单](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) |
||||
|
||||
如果您在 binary 同目录下无法找到 `custom` 文件夹，请检查您的 `GITEA_CUSTOM` |
||||
环境变量配置， 因为它可能被配置到了其他地方（可能被一些启动脚本设置指定了目录）。 |
||||
|
||||
- [环境变量清单](https://docs.gitea.io/en-us/specific-variables/) |
||||
|
||||
**注：** 必须完全重启 Gitea 以使配置生效。 |
||||
|
||||
## 使用自定义 /robots.txt |
||||
|
||||
将 [想要展示的内容](http://www.robotstxt.org/) 存放在 `custom` 目录中的 |
||||
`robots.txt` 文件来让 Gitea 使用自定义的`/robots.txt` （默认：空 404）。 |
||||
|
||||
## 使用自定义的公共文件 |
||||
|
||||
将自定义的公共文件（比如页面和图片）作为 webroot 放在 `custom/public/` 中来让 Gitea 提供这些自定义内容（符号链接将被追踪）。 |
||||
|
||||
举例说明：`image.png` 存放在 `custom/public/`中，那么它可以通过链接 http://gitea.domain.tld/image.png 访问。 |
||||
|
||||
## 修改默认头像 |
||||
|
||||
替换以下目录中的 png 图片： `custom/public/img/avatar\_default.png` |
||||
|
||||
## 自定义 Gitea 页面 |
||||
|
||||
您可以改变 Gitea `custom/templates` 的每个单页面。您可以在 Gitea 源码的 `templates` 目录中找到用于覆盖的模板文件，应用将根据 |
||||
`custom/templates` 目录下的路径结构进行匹配和覆盖。 |
||||
|
||||
包含在 `{{` 和 `}}` 中的任何语句都是 Gitea 的模板语法，如果您不完全理解这些组件，不建议您对它们进行修改。 |
||||
|
||||
### 添加链接和页签 |
||||
|
||||
如果您只是想添加额外的链接到顶部导航栏或额外的选项卡到存储库视图，您可以将它们放在您 `custom/templates/custom/` 目录下的 `extra_links.tmpl` 和 `extra_tabs.tmpl` 文件中。 |
||||
|
||||
举例说明：假设您在德国，必须添加着名的法律要求的“Impressum”用以罗列谁负责网站的内容页面，您只需将该页面放在您的 |
||||
"custom/public/"目录下（比如 `custom/public/impressum.html`）并且将它与 `custom/templates/custom/extra_links.tmpl` 链接起来即可。 |
||||
|
||||
这个链接应当使用一个名为“item”的 class 来匹配当前样式，您可以使用 `{{AppSubUrl}}` 来获取 base URL: |
||||
`<a class="item" href="{{AppSubUrl}}/impressum.html">Impressum</a>` |
||||
|
||||
同理，您可以将页签添加到 `extra_tabs.tmpl` 中，使用同样的方式来添加页签。它的具体样式需要与 |
||||
`templates/repo/header.tmpl` 中已有的其他选项卡的样式匹配 |
||||
([source in GitHub](https://github.com/go-gitea/gitea/blob/master/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 目前由两种内置主题，分别为默认 `gitea` 主题和深色主题 `arc-green`，您可以通过修改 |
||||
`app.ini` [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) 部分的 `DEFAULT_THEME` 的值来变更至一个可用的 Gitea 外观。 |
||||
@ -0,0 +1,45 @@ |
||||
--- |
||||
date: "2017-01-14T11:00:00-02:00" |
||||
title: "Make 安装" |
||||
slug: "make" |
||||
weight: 10 |
||||
toc: true |
||||
draft: false |
||||
menu: |
||||
sidebar: |
||||
parent: "advanced" |
||||
name: "Make 安装" |
||||
weight: 30 |
||||
identifier: "make" |
||||
--- |
||||
|
||||
# 安装 Make |
||||
|
||||
Gitea 大量使用了 Make 工具来自动执行任务并改进开发，本文将介绍如何安装 Make。 |
||||
|
||||
### 在 Linux 环境下 |
||||
|
||||
可以使用包管理工具来安装 Make。 |
||||
|
||||
Ubuntu/Debian 环境，执行以下命令： |
||||
|
||||
```bash |
||||
sudo apt-get install make |
||||
``` |
||||
|
||||
Fedora/RHEL/CentOS，执行以下命令： |
||||
|
||||
```bash |
||||
sudo yum install make |
||||
``` |
||||
|
||||
### 在 Windows 环境下 |
||||
|
||||
您可以参照以下三种方案在 Windows 环境安装 Make： |
||||
|
||||
- 直接使用 [exe文件](http://www.equation.com/servlet/equation.cmd?fa=make)：将适合您系统的exe文件拷贝到某处并添加至环境变量 `PATH` 中。 |
||||
- [32 位版本](ftp://ftp.equation.com/make/32/make.exe) |
||||
- [64 位版本](ftp://ftp.equation.com/make/64/make.exe) |
||||
- 使用 [MinGW](http://www.mingw.org/) 工具： |
||||
- 此处使用二进制文件 `mingw32-make.exe` 替代前面提到的 `make.exe`文件。同样您需要将包含此exe文件的 `bin` 目录添加至环境变量 `PATH`中。 |
||||
- 通过 [Chocolatey](https://chocolatey.org/packages/make) 安装： 执行 `choco install make` 命令即可。 |
||||
@ -0,0 +1,62 @@ |
||||
--- |
||||
date: "2017-04-08T11:34:00+02:00" |
||||
title: "环境变量清单" |
||||
slug: "specific-variables" |
||||
weight: 20 |
||||
toc: false |
||||
draft: false |
||||
menu: |
||||
sidebar: |
||||
parent: "advanced" |
||||
name: "环境变量清单" |
||||
weight: 20 |
||||
identifier: "specific-variables" |
||||
--- |
||||
|
||||
# 环境变量清单 |
||||
|
||||
这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效： |
||||
|
||||
``` |
||||
GITEA_CUSTOM=/home/gitea/custom ./gitea web |
||||
``` |
||||
|
||||
## Go 的配置 |
||||
|
||||
因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数： |
||||
|
||||
* `GOOS` |
||||
* `GOARCH` |
||||
* [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable) |
||||
|
||||
您可以在[官方文档](https://golang.org/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 目录相对路径 |
||||
|
||||
## Macaron（Gitea 使用的 web 框架） |
||||
|
||||
* `HOST`：Macaron 监听的主机地址 |
||||
* `PORT`：Macaron 监听的端口地址 |
||||
* `MACARON_ENV`：为开发环境和生产环境提供特殊功能性配置的全局变量，当 MACARON_ENV 设置为 "" 或 "development" |
||||
时，每次请求都会重编译页面模板。为了提高性能表现，可将它设置为 "production"。 |
||||
|
||||
## Miscellaneous |
||||
|
||||
* `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。 |
||||
Loading…
Reference in new issue