Merge branch 'main' into lunny/add_project_workflow

This commit is contained in:
Lunny Xiao committed 2026-10-22 23:22:15 +00:00
commit c902fe9253
2340 files changed
+379885 -36853

No files matched your search

-8
View File
@@ -1,8 +0,0 @@
{
"outdated.message": {
"message": "当前中文文档翻译不是最新版,访问英文版本查看最新内容,或"
},
"outdated.help": {
"message": "帮助我们翻译"
}
}
@@ -0,0 +1,34 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: adding-legal-pages
sidebar_position: 110
aliases:
- /zh-cn/adding-legal-pages
---
# 添加法律页面
一些法域(例如欧盟)要求在网站上添加特定的法律页面(例如隐私政策)。按照以下步骤将它们添加到你的 Gitea 实例中。
## 获取页面
Gitea 源代码附带了示例页面,位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如,如果要添加隐私政策:
```
wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
```
现在,你需要编辑该页面以满足你的需求。特别是,你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用,以匹配你的情况。
请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。
## 使其可见
创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中:
```go
<a class="item" href="{{AppSubUrl}}/assets/privacy.html">隐私政策</a>
```
重启 Gitea 以查看更改。
@@ -80,7 +80,7 @@ cd gitea-dump-1610949662
mv app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/repositories/
mv repos/* /var/lib/gitea/data/gitea-repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
# mysql
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,454 @@
---
date: "2018-05-22T11:00:00+00:00"
slug: "reverse-proxies"
sidebar_position: 16
aliases:
- /zh-cn/reverse-proxies
---
# 反向代理
## 通用配置
1. 在您的 `app.ini` 文件中添加配置 `[server] ROOT_URL = https://git.example.com/`
2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea,使 Gitea 可以看到正在访问的真实 URL。
5. 确保 Web 服务器有完整的证书(包括所有中间证书和根证书),以便 `git clone` 和 `git pull` 正常工作。
6. Gitea 会在 `/-/ws` 使用 WebSocket 连接,用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1,并转发 `Upgrade` 和 `Connection` 头,参见下面的示例。否则 Gitea 会回退为定期轮询。
## 使用子路径
通常,**不推荐**将 Gitea 放到子路径。人们很少使用此配置,并且在极少数情况下可能会出现一些问题。
为了让 Gitea 在子路径工作(例如:`https://common.example.com/gitea/`),需要在上面的通用配置之外进行一些额外的配置:
1. 在 `app.ini` 文件中使用配置 `[server] ROOT_URL = https://common.example.com/gitea/`。
2. 将 `https://common.example.com/gitea/foo` 反向代理到 `http://gitea:3000/foo`。
3. 容器映像注册表需要在根目录级别有一个固定的子路径 `v2`,您必须做下列配置:
- 将 `https://common.example.com/v2` 反向代理到 `http://gitea:3000/v2`。
- 确保 URI 和标头也被正确的传递(见上面的通用配置)
## 使用 Nginx 作为反向代理服务
如果您想使用 Nginx 作为 Gitea 的反向代理服务,您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分。
确保 `client_max_body_size` 足够大,否则在上传大文件时会出现 "client_max_body_size" 错误。
```nginx
server {
...
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名,您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分,为 Gitea 添加路由规则:
```nginx
server {
...
location ~ ^/(gitea|v2)($|/) {
client_max_body_size 512M;
# 确保 nginx 使用未转义 URI, 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀, 按原样传递 "/v2"。
rewrite ^ $request_uri;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
proxy_http_version 1.1;
# 其他的常规 HTTP 表头,见上面“使用 Nginx 作为反向代理服务”小节的配置
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
## 使用 Nginx 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Nginx 可以直接提供静态资源,并且只代理动态资源请求给 Gitea。
Nginx 为提供静态内容进行了优化,而代理大响应可能与这一优化行为相反。
(见[https://serverfault.com/q/587386](https://serverfault.com/q/587386))
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea`。
在此之后,在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下,我们只对 `public/` 目录感兴趣,您可以删除剩下的其他目录。
(为了生成静态资源,您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`)
取决于您的用户量的大小,您可以将流量分离到两个不同的服务器,或者为静态资源配置一个 cdn。
### 单服务器节点,单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件,并配置 nginx:
```nginx
server {
listen 80;
server_name git.example.com;
location /_/static/assets/ {
alias /path/to/gitea/public/;
}
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
```
### 双服务器节点,双域名
将 `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` 写入您的 Gitea 配置文件,并配置 nginx:
```nginx
# 运行 Gitea 的服务器
server {
listen 80;
server_name git.example.com;
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
```
```nginx
# 提供静态资源的服务器
server {
listen 80;
server_name cdn.example.com;
location /gitea/ {
alias /path/to/gitea/public/;
}
location / {
return 404;
}
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理,配置与原生 Nginx 略有不同。
它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf),因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复(尤其是 `proxy_set_header Host $host`)出现 `400 bad request`。
创建 `/` 自定义 location 时,只需在其配置中加入:
```nginx
client_max_body_size 512M;
```
在代理主机上启用 `Websockets Support`,Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
## 使用 Apache HTTPD 作为反向代理服务
如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务,您可以为您的 Apache HTTPD 作如下配置(在 Ubuntu 中,配置文件通常在 `/etc/apache2/httpd.conf` 目录下):
```apacheconf
<VirtualHost *:80>
...
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必须启用以下 Apache HTTPD 组件:`proxy`, `proxy_http`。
`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它,否则 Apache HTTPD 将无法启动。
:::
如果希望用 Let's Encrypt 的 webroot 验证,请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`,避免把这些请求代理到 Gitea。
## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名,您可以增加以下配置为 Gitea 添加路由规则(在 Ubuntu 中,配置文件通常在 `/etc/apache2/httpd.conf` 目录下):
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
:::note
必须启用以下 Apache HTTPD 组件:`proxy`, `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本,更旧的版本请去掉它。
:::
## 使用 Apache HTTPD 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Apache HTTPD 可以直接提供静态资源,并且只代理动态资源请求给 Gitea。
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
在此之后,在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下,我们只对 `public/` 目录感兴趣,您可以删除剩下的其他目录。
(为了生成静态资源,您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`)
取决于您的用户量的大小,您可以将流量分离到两个不同的服务器,或者为静态资源配置一个 cdn。
### 单服务器节点,单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件:
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必须启用以下 Apache HTTPD 组件:`proxy`, `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本,更旧的版本请去掉它。
:::
## 使用 Caddy 作为反向代理服务
如果您想使用 Caddy 作为 Gitea 的反向代理服务,您可以在 `Caddyfile` 中添加如下配置:
```
git.example.com {
reverse_proxy localhost:3000
}
```
## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名,您可以在您的 `Caddyfile` 文件中增加以下配置,为 Gitea 添加路由规则:
```
git.example.com {
route /git/* {
uri strip_prefix /git
reverse_proxy localhost:3000
}
}
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
## 使用 IIS 作为反向代理服务
如果您想使用 IIS 作为 Gitea 的反向代理服务,你需要为 IIS 设置 URL 重写来作为反向代理。
1. 在 IIS 中设置一个空网页,比如命名为 `Gitea Proxy`。
2. 根据[微软社区中为 IIS 设置 URL 重写的指南](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343)的前两步进行配置,也就是:
- 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing(简称 ARR),或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
- 一但这个模块被安装到 IIS 上,你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
- 安装 Windows 功能 `WebSocket Protocol`,否则 ARR 无法代理 Gitea 的 WebSocket 端点。
- 打开 IIS 管理控制台,在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
- 在管理控制台的右边选择 `Add Rule` 操作,并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
- 在 Inbound Rules 中, 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如,如果你在 localhost 的 3000 端口上运行 Gitea,则设置为 `127.0.0.1:3000`。
- 启用 SSL Offloading
- 在 Outbound Rules 中,确保设置了 `Rewrite the domain names of the links in HTTP response`,并且将 `From:` 设置为上面的 server name,将 `To:` 设置为你的外部访问名称,例如:`git.example.com`
- 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`(在 IIS 管理器中选择服务器节点,打开 `Application Request Routing Cache`,再打开右侧的 `Server Proxy Settings`)。若保持开启,ARR 会把 `Location` 头里的主机改回内部地址,导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
- 现在,根据下面的内容为您的网页编辑 `web.config`(将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.web>
<httpRuntime requestPathInvalidCharacters="" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<hiddenSegments>
<clear />
</hiddenSegments>
<denyUrlSequences>
<clear />
</denyUrlSequences>
<fileExtensions allowUnlisted="true">
<clear />
</fileExtensions>
</requestFiltering>
</security>
<rewrite>
<rules useOriginalURLEncoding="false">
<rule name="ReverseProxyInboundRule1" stopProcessing="true">
<match url="(.*)" />
<action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
<serverVariables>
<set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
<set name="HTTP_ACCEPT_ENCODING" value="" />
</serverVariables>
</rule>
</rules>
<outboundRules>
<rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
<!-- set the pattern correctly here - if you only want to accept http or https -->
<!-- change the pattern and the action value as appropriate -->
<match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
<action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
</rule>
<rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
<match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
<action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
</rule>
<preConditions>
<preCondition name="ResponseIsHtml1">
<add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
</preCondition>
<preCondition name="NeedsRestoringAcceptEncoding">
<add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
</preCondition>
</preConditions>
</outboundRules>
</rewrite>
<urlCompression doDynamicCompression="true" />
<handlers>
<clear />
<add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
</handlers>
<!-- Map all extensions to the same MIME type, so all files can be
downloaded. -->
<staticContent>
<clear />
<mimeMap fileExtension="*" mimeType="application/octet-stream" />
</staticContent>
</system.webServer>
</configuration>
```
## 使用 HAProxy 作为反向代理服务
如果您想使用 HAProxy 作为 Gitea 的反向代理服务,您可以将下面的内容加入您的 HAProxy 配置。
在 frontend 部分加入一个 acl 来将对 gitea.example.com 的请求重定向到正确的后端。
```
frontend http-in
...
acl acl_gitea hdr(host) -i gitea.example.com
use_backend gitea if acl_gitea
...
```
添加之前定义好的 backend 部分
```
backend gitea
server localhost:3000 check
```
如果您将 http 内容重定向到 https,上面的配置文件也能够使用。只需要记住,在 HAProxy 和 Gitea 之间的连接将由 http 完成,所以你不需要在 Gitea 的配置文件中启用 https。
## 使用 HAProxy 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名,您可以在您的 HAProxy 中加入如下配置,为 Gitea 添加路由规则:
```
frontend http-in
...
acl acl_gitea path_beg /gitea
use_backend gitea if acl_gitea
...
```
在这个配置下,http://example.com/gitea/ 将被重定向到您的 Gitea 实例。
接下来,对于 backend 部分:
```
backend gitea
http-request replace-path /gitea\/?(.*) \/\1
server localhost:3000 check
```
添加的 http-request 在需要的时候会自动加入反斜杠/,并且通过将 http://example.com/gitea 正确设置为根来在内部路径中删除 /gitea,使其能够正常工作。
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
## 使用 Traefik 作为反向代理服务
如果您想使用 traefik 作为 Gitea 的反向代理服务,您可以在 `docker-compose.yaml` 中添加 label 部分(假设使用 docker 作为 traefik 的 provider):
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
```
这份配置假设您使用 traefik 来处理 HTTPS 服务,并在其和 Gitea 之间使用 HTTP 进行通信。
## 使用 Traefik 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名,您可以在您的 `docker-compose.yaml` 文件中增加以下配置,为 Gitea 添加路由规则(假设使用 docker 作为 traefik 的 provider):
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
- "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
- "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
```
这份配置假设您使用 traefik 来处理 HTTPS 服务,并在其和 Gitea 之间使用 HTTP 进行通信。
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
@@ -0,0 +1,64 @@
---
date: "2018-06-24:00:00+02:00"
slug: "api-usage"
sidebar_position: 40
aliases:
- /zh-cn/api-usage
---
# API 使用指南
## 开启/配置 API 访问
通常情况下, `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
<a id="authentication"></a>
## 通过 API 认证
Gitea 支持以下几种 API 认证方式:
- HTTP basic authentication 方式
- 通过指定 `token=...` URL 查询参数方式
- 通过指定 `access_token=...` URL 查询参数方式
- 通过指定 `Authorization: token ...` HTTP header 方式
以上提及的认证方法接受相同的 apiKey token 类型,您可以在编码时通过查阅代码更好地理解这一点。
Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
您可以通过您的 gitea web 界面来创建 apiKey token:
`Settings | Applications | Generate New Token`.
### 关于 `Authorization:` header
由于一些历史原因,Gitea 需要在 header 的 apiKey token 里引入前缀 `token`,类似于如下形式:
```
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
```
以 `curl` 命令为例,它会以如下形式携带在请求中:
```
curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
-H "accept: application/json" \
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
-H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
```
正如上例所示,您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
## 通过 API 列出您发布的令牌
`/users/:name/tokens` 是一个特殊的接口,需要您使用 basic authentication 进行认证,具体原因在 issue 中
[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及,使用方法如下所示:
### 使用 Basic authentication 认证
```
$ curl --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
```
## 使用 Sudo 方式请求 API
此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
@@ -0,0 +1,218 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-source"
sidebar_position: 30
aliases:
- /zh-cn/install-from-source
---
# 使用源代码安装
你需要 [安装 Go](https://golang.google.cn/doc/install) 并正确设置 Go 环境。特别的,建议设置`$GOPATH`环境变量,并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。
接下来,[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/), 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@,建议使用最新的 LTS 版本。
**注意**:需要 Go 版本 @minGoVersion@ 或更高版本。不过,建议获取与我们的持续集成(continuous integration, CI)相同的版本,请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
## 下载
首先,我们需要获取源码。由于引入了 Go 模块,最简单的方法是直接使用 Git,因为我们不再需要在 GOPATH 内构建 Gitea。
```bash
git clone https://github.com/go-gitea/gitea
```
(之前的版本中建议使用 `go get`,但现在不再需要。)
你可以选择编译和安装的版本,当前有多个选择。`main` 分支代表当前的开发版本。如果你想编译 `main` 版本,你可以直接跳到 [构建](#构建) 部分。
如果你想编译带有标签的发行版本,可以使用以下命令签出:
```bash
git branch -a
git checkout @sourceBranch@
```
要验证一个拉取请求(Pull Request, PR),要先启用新的分支(其中 `xyz` 是 PR 的 ID;例如,对于 [#2663](https://github.com/go-gitea/gitea/pull/2663),ID 是 `2663 `):
```bash
git fetch origin pull/xyz/head:pr-xyz
```
要以指定发行版本(如 @sourceVersion@ )的源代码来构建 Gitea,可执行以下命令列出可用的版本并选择某个版本签出。
使用以下命令列出可用的版本:
```bash
git tag -l
git checkout @sourceVersion@ # or git checkout pr-xyz
```
## 构建
要从源代码进行构建,系统必须预先安装以下程序:
- `go` @minGoVersion@ 或更高版本,请参阅 [这里](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本,并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
为了尽可能简化编译过程,提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
根据你的构建需求,以下 tags 可以使用:
- `bindata`: 构建一个单一的整体二进制文件,包含所有资源。适用于构建生产环境版本。
- `sqlite sqlite_unlock_notify`: 启用对 [SQLite3](https://sqlite.org/) 数据库的支持。仅建议在少数人使用时使用这个模式。
- `pam`: 启用对 PAM( Linux 可插拔认证模块)的支持。可用于对本地用户进行身份验证或扩展身份验证到 PAM 可用的方法。
- `gogit`:(实验性功能)使用 go-git 变体的 Git 命令。
将所有资源(JS/CSS/模板等)打包到二进制文件中。在生产环境部署时,使用`bindata`构建标签是必需的。在开发/测试 Gitea 或能够明确分离资源时,可以不用`bindata`。
要包含所有资源,请使用 `bindata` 标签:
```bash
TAGS="bindata" make build
```
在我们的持续集成系统的默认发行版中,构建标签为:`TAGS="bindata sqlite sqlite_unlock_notify"`。因此,从源码构建的最简单、推荐方式是:
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
`build`目标分为两个子目标:
- `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。
如果存在预构建的前端文件,可以仅构建后端:
```bash
TAGS="bindata" make backend
```
## 测试
按照上述步骤完成后,工作目录中将会有一个`gitea`二进制文件。可以从该目录进行测试,或将其移动到带有测试数据的目录中。当手动从命令行启动 Gitea 时,可以通过按下`Ctrl + C`来停止程序。
```bash
./gitea web
```
## 更改默认路径
Gitea 将从`CustomPath`中查找许多信息。默认的,这会在运行 Gitea 时当前工作目录下的`custom/`目录中(译者案:即`$PATH_TO_YOUR_GITEA$/custom/`)。它还将在`$(CustomPath)/conf/app.ini`中查找其配置文件`CustomConf`,并将当前工作目录用作一些可配置值的相对基本路径`AppWorkPath`。最后,静态文件将从默认为 `AppWorkPath`的`StaticRootPath`提供。
尽管在开发时这些值很有用,但可能与下游用户的偏好冲突。
一种选择是使用脚本文件来隐藏`gitea`二进制文件,并在运行 Gitea 之前创建适当的环境。然而,在构建时,可以使用`make`的`LDFLAGS`环境变量来更改这些默认值。适当的设置如下:
- 要设置`CustomPath`,请使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
- 对于`CustomConf`,应该使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
- 对于`AppWorkPath`,应该使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
- 对于`StaticRootPath`,应该使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
- 要更改默认的 PID 文件位置,请使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
将这些字符串与其前导的`-X`添加到`LDFLAGS`变量中,并像上面那样使用适当的`TAGS`运行`make build`。
运行`gitea help`将允许您查看配置的`gitea`设置。
## 交叉编译
`go`编译器工具链支持将代码交叉编译到不同的目标架构上。请参考[`GOOS`和`GOARCH`环境变量](https://go.dev/doc/install/source#environment) 以获取支持的目标列表。如果您想为性能较弱的系统(如树莓派)构建 Gitea,交叉编译非常有用。
要使用构建标签(`TAGS`)进行交叉编译 Gitea,您还需要一个 C 交叉编译器,该编译器的目标架构与`GOOS`和`GOARCH`变量选择的架构相同。例如,要为 Linux ARM64(`GOOS=linux`和`GOARCH=arm64`)进行交叉编译,您需要`aarch64-unknown-linux-gnu-gcc`交叉编译器。这是因为 Gitea 构建标签使用了`cgo`的外部函数接口(FFI)。
在没有任何标签的情况下,交叉编译的 Gitea 为 Linux ARM64 版本:
```
GOOS=linux GOARCH=arm64 make build
```
要交叉编译 Linux ARM64 下的 Gitea,这是推荐的构建标签:
```
CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
```
根据您的目标架构,适当替换`CC`、`GOOS`和`GOARCH`。
有时您需要构建一个静态编译的镜像。为此,您需要添加以下内容:
```
LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
```
这可以与上述的`CC`、`GOOS`和`GOARCH`结合使用。
### 添加 bash/zsh 自动补全(从 1.19 版本起)
在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一个启用 bash 自动补全的脚本。您可以根据需要进行修改,并在您的 `.bashrc` 中使用 `source` 命令加载该脚本,或者将其复制到 `/usr/share/bash-completion/completions/gitea`。
类似地,可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一个用于 zsh 自动补全的脚本。您可以将其复制到 `/usr/share/zsh/_gitea`,或者在您的 `.zshrc` 中使用 `source` 命令加载该脚本。
可能需要你根据具体情况进一步改进这些脚本。
## 在 Linux 上使用 Zig 进行编译或交叉编译
请按照 [Zig 的入门指南](https://ziglang.org/learn/getting-started/#installing-zig) 安装 Zig。
- 编译 (Linux ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉编译 (Linux ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## 在 Windows 上使用 Zig 进行编译或交叉编译
使用`GIT BASH`编译。
- 编译 (Windows ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉编译 (Windows ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## Source Map
默认情况下,gitea 会为前端文件生成精简的 Source Map 以节省空间。 这可以通过“ENABLE_SOURCEMAP”环境变量进行控制:
- `ENABLE_SOURCEMAP=true` 生成所有 Source Map,这是开发版本的默认设置
- `ENABLE_SOURCEMAP=reduced` 生成有限的 Source Map,这是生产版本的默认设置
- `ENABLE_SOURCEMAP=false` 不生成 Source Map
@@ -0,0 +1,63 @@
---
date: "2017-07-21T12:00:00+02:00"
slug: "linux-service"
sidebar_position: 40
aliases:
- /zh-cn/linux-service
---
# 在 Linux 中以 service 方式运行
## 在 Ubuntu 16.04 LTS 中以 service 方式运行
### systemd 方式
在 terminal 中执行以下命令:
```
sudo vim /etc/systemd/system/gitea.service
```
接着拷贝示例代码 [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/service/systemd/gitea.service) 并取消对任何需要运行在主机上的服务部分的注释,譬如 MySQL。
修改 user,home 目录以及其他必须的初始化参数,如果使用自定义端口,则需修改 PORT 参数,反之如果使用默认端口则需删除 -p 标记。
激活 gitea 并将它作为系统自启动服务:
```
sudo systemctl enable gitea
sudo systemctl start gitea
```
### 使用 supervisor
在 terminal 中执行以下命令安装 supervisor:
```
sudo apt install supervisor
```
为 supervisor 配置日志路径:
```
# assuming gitea is installed in /home/git/gitea/
mkdir /home/git/gitea/log/supervisor
```
在文件编辑器中打开 supervisor 的配置文件:
```
sudo vim /etc/supervisor/supervisord.conf
```
增加如下示例配置
[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/service/supervisor/gitea)。
将 user(git) 和 home(/home/git) 设置为与上文部署中匹配的值。如果使用自定义端口,则需修改 PORT 参数,反之如果使用默认端口则需删除 -p 标记。
最后激活 supervisor 并将它作为系统自启动服务:
```
sudo systemctl enable supervisor
sudo systemctl start supervisor
```
@@ -0,0 +1,325 @@
---
date: "2020-02-09T20:00:00+02:00"
slug: "install-with-docker-rootless"
sidebar_position: 60
aliases:
- /zh-cn/install-with-docker-rootless
---
# 使用 Docker 安装 (rootless)
Gitea 在其 Docker Hub 组织中提供自动更新的 Docker 镜像。您可以始终使用最新的稳定标签,或使用其他处理 Docker 镜像更新的服务。
rootless 镜像使用 Gitea 内部 SSH 功能来提供 Git 协议,但不支持 OpenSSH。
本参考设置指南将用户引导通过基于 `docker-compose` 的设置。但是,`docker-compose` 的安装超出了本文档的范围。要安装`docker-compose` 本身, 请按照官方的 [安装说明](https://docs.docker.com/compose/install/)进行操作。
## 基础设置
最简单的设置只需创建一个卷和一个网络,并将 `docker.gitea.com/gitea:latest-rootless` 镜像作为服务启动。由于没有可用的数据库,可以使用 SQLite3 来初始化一个。
创建一个名为 `data` 和 `config`:
```sh
mkdir -p gitea/{data,config}
cd gitea
touch docker-compose.yml
```
然后将以下内容粘贴到名为 `docker-compose.yml` 的文件中:
```yaml
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
请注意,卷应由在配置文件中指定的 UID/GID 的用户/组所有。默认情况下,Docker 中的 Gitea 将使用 uid:1000 gid:1000。如果需要,您可以使用以下命令设置这些文件夹的所有权:
```sh
sudo chown 1000:1000 config/ data/
```
> 如果未为卷设置正确的权限,容器可能无法启动。
对于稳定版本,您可以使用 `:latest-rootless`、`:1-rootless`,或指定特定的版本,如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本,则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交,可以使用 `:1.x-nightly-rootless` 标签,其中 x 是 Gitea 的次要版本号(例如:`1.27-nightly-rootless`)。
## 自定义端口
要将集成的 SSH 和 Web 服务器绑定到不同的端口,请调整端口部分。通常只需更改主机端口并保持容器内的端口不变。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "2222:2222"
+ - "80:3000"
+ - "22:2222"
```
## MySQL 数据库
要将 Gitea 与 MySQL 数据库结合使用,请对上面创建的 `docker-compose.yml` 文件进行以下更改。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
+ environment:
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
## PostgreSQL 数据库
要将 Gitea 与 PostgreSQL 数据库结合使用,请对上面创建的 `docker-compose.yml` 文件进行以下更改。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
environment:
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## 命名卷 (Named Volumes)
要使用命名卷 (Named Volumes) 而不是主机卷 (Host Volumes),请在 `docker-compose.yml` 配置中定义和使用命名卷。这样的更改将自动创建所需的卷。您不需要担心权限问题,Docker 会自动处理。
```diff
version: "2"
+volumes:
+ gitea-data:
+ driver: local
+ gitea-config:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- - ./data:/var/lib/gitea
+ - gitea-data:/var/lib/gitea
- - ./config:/etc/gitea
+ - gitea-config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
MySQL 或 PostgreSQL 容器需要单独创建。
## 自定义用户
你可以选择使用自定义用户 (遵循 --user 标志定义 https://docs.docker.com/engine/reference/run/#user)。
例如,要克隆主机用户 `git` 的定义,请使用命令 `id -u git` 并将其添加到 `docker-compose.yml` 文件中:
请确用户对保挂载的文件夹具有写权限。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
+ user: 1001
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
## 启动
要启动基于 `docker-compose` 的这个设置,请执行 `docker-compose up -d`,以在后台启动 Gitea。使用 `docker-compose ps` 命令可以查看 Gitea 是否正确启动。可以使用 `docker-compose logs` 命令查看日志。
要关闭设置,请执行 `docker-compose down` 命令。这将停止和终止容器,但卷仍将存在。
注意:如果在 HTTP 上使用的是非 3000 端口,请将 app.ini 更改为匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
## 安装
在通过 `docker-compose` 启动 Docker 设置后,可以使用喜爱的浏览器访问 Gitea,完成安装过程。访问 `http://<服务器-IP>:3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的,请注意必须使用 `db` 作为数据库主机名。
## 自定义
自定义文件的位置位于 `/var/lib/gitea/custom` 目录中,可以在这里找到有关自定义的文件说明。如果使用主机卷(host volumes),很容易访问这些文件;如果使用命名卷(named volumes),则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后,配置文件将保存在 `/etc/gitea/app.ini` 中。
## 升级
:::warning
:exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation:
:::
要将安装升级到最新版本,请按照以下步骤操作:
```bash
# 如果在 docker-compose.yml 中指定了版本,请编辑该文件以更新版本
# 拉取新的镜像
docker-compose pull
# 启动一个新的容器,自动移除旧的容器
docker-compose up -d
```
## 从标准镜像升级
- 备份您的设置
- 将卷挂载点从 `/data` 更改为 `/var/lib/gitea`
- 如果使用了自定义的 `app.ini`,请将其移动到新的挂载到 `/etc/gitea` 的卷中
- 将卷中的文件夹(gitea)重命名为 custom
- 如果需要,编辑 `app.ini`
- 设置 `START_SSH_SERVER = true`
- 使用镜像 ` docker.gitea.com/gitea:@dockerVersion@-rootless`
## 使用环境变量管理部署
除了上述的环境变量外,`app.ini` 中的任何设置都可以通过形式为 `GITEA__SECTION_NAME__KEY_NAME` 的环境变量进行设置或覆盖。这些设置在每次 Docker 容器启动时都会生效。完整信息请参考[这里](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
这些环境变量可以在 `docker-compose.yml` 中传递给 Docker 容器。以下示例将启用 SMTP 邮件服务器,如果主机上设置了所需的环境变量 GITEA**mailer**FROM、GITEA**mailer**HOST、GITEA**mailer**PASSWD,或者在与 `docker-compose.yml` 相同目录中的 `.env` 文件中设置了这些环境变量:
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtp
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__IS_TLS_ENABLED=true
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
要设置所需的 TOKEN 和 SECRET 值,可以使用 Gitea 的内置[生成使用函数](../administration/command-line.md#generate).
# SSH 容器透传
由于 SSH 在容器内运行,如果需要 SSH 支持,需要将 SSH 从主机透传到容器。一种选择是在容器内运行 SSH,并使用非标准端口(或将主机端口移动到非标准端口)。另一种可能更直接的选择是将主机上的 SSH 命令转发到容器。下面解释了这种设置。
本指南假设您已在主机上创建了一个名为 `git` 的用户,并具有运行 `docker exec` 的权限,并且 Gitea 容器的名称为 `gitea`。您需要修改该用户的 shell,以将命令转发到容器内的 `sh` 可执行文件,使用 `docker exec`。
首先,在主机上创建文件 `/usr/local/bin/gitea-shell`,并填入以下内容:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
注意上述 docker 命令中的 `gitea` 是容器的名称。如果您的容器名称不同,请记得更改。
还应确保正确设置了 shell 包装器的权限:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
一旦包装器就位,您可以将其设置为 `git` 用户的 shell:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
现在,所有的 SSH 命令都会被转发到容器,您需要在主机上设置 SSH 认证。这可以通过利用 [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) 来匹配 Gitea 接受的密钥。在主机的 `/etc/ssh/sshd_config` 文件中添加以下代码块:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(从 1.16.0 开始,您将不需要设置 `-c /etc/gitea/app.ini` 选项。)
剩下的就是重新启动 SSH 服务器:
```bash
sudo systemctl restart sshd
```
**注意**
这实际上并没有使用 Docker 的 SSH,而是仅仅使用了围绕它的命令。
从理论上讲,您可以不运行内部的 SSH 服务器。
@@ -0,0 +1,373 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-with-docker"
sidebar_position: 70
aliases:
- /zh-cn/install-with-docker
---
# 使用 Docker 安装
Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始终使用最新的稳定标签或使用其他服务来更新 Docker 镜像。
该参考设置指导用户完成基于 `docker-compose` 的设置,但是 `docker-compose` 的安装不在本文档的范围之内。要安装 `docker-compose` 本身,请遵循官方[安装说明](https://docs.docker.com/compose/install/)。
## 基本
最简单的设置只是创建一个卷和一个网络,然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库,因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录,并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意,该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限,则容器可能无法启动。另请注意,标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版,您也可以使用 `:1` 或指定某个发行版,例如 `@dockerVersion@`。如果您想使用最新的开发版本,则可以使用 `:main-nightly` 标签;如果您想运行发布分支的最新提交,可以使用 `:1.x-nightly` 标签,其中 x 是 Gitea 的次要版本号(例如:`1.27-nightly`)。
```yaml
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
## 端口
要将集成的 openSSH 守护进程和 Web 服务器绑定到其他端口,请调整端口部分。通常,只需更改主机端口,容器内的端口保持原样即可。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "222:22"
+ - "8080:3000"
+ - "2221:22"
```
## 数据库
### MySQL 数据库
要将 Gitea 与 MySQL 数据库结合使用,请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
### PostgreSQL 数据库
要将 Gitea 与 PostgreSQL 数据库结合使用,请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## 命名卷
要使用命名卷而不是主机卷,请在 `docker-compose.yml` 配置中定义并使用命名卷。此更改将自动创建所需的卷。您无需担心命名卷的权限;Docker 将自动处理该问题。
```diff
version: "3"
networks:
gitea:
external: false
+volumes:
+ gitea:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
restart: always
networks:
- gitea
volumes:
- - ./gitea:/data
+ - gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
MySQL 或 PostgreSQL 容器将需要分别创建。
## 启动
要基于 `docker-compose` 启动此设置,请执行 `docker-compose up -d`,以在后台启动 Gitea。使用 `docker-compose ps` 将显示 Gitea 是否正确启动。可以使用 `docker-compose logs` 查看日志。
要关闭设置,请执行 `docker-compose down`。这将停止并杀死容器。这些卷将仍然存在。
注意:如果在 http 上使用非 3000 端口,请更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
## 安装
通过 `docker-compose` 启动 Docker 安装后,应该可以使用喜欢的浏览器访问 Gitea,以完成安装。访问 http://server-ip:3000 并遵循安装向导。如果数据库是通过上述 `docker-compose` 设置启动的,请注意,必须将 `db` 用作数据库主机名。
## 环境变量
您可以通过环境变量配置 Gitea 的一些设置:
(默认值以**粗体**显示)
- `APP_NAME`:**“Gitea: Git with a cup of tea”**:应用程序名称,在页面标题中使用。
- `RUN_MODE`:**prod**:应用程序运行模式,会影响性能和调试。"dev","prod"或"test"。
- `DOMAIN`:**localhost**:此服务器的域名,用于 Gitea UI 中显示的 http 克隆 URL。
- `SSH_DOMAIN`:**localhost**:该服务器的域名,用于 Gitea UI 中显示的 ssh 克隆 URL。如果启用了安装页面,则 SSH 域服务器将采用以下形式的 DOMAIN 值(保存时将覆盖此设置)。
- `SSH_PORT`:**22**:克隆 URL 中显示的 SSH 端口。
- `SSH_LISTEN_PORT`:**%(SSH_PORT)s**:内置 SSH 服务器的端口。
- `DISABLE_SSH`:**false**:如果不可用,请禁用 SSH 功能。如果要禁用 SSH 功能,则在安装 Gitea 时应将 SSH 端口设置为 `0`。
- `HTTP_PORT`:**3000**:HTTP 监听端口。
- `ROOT_URL`:**""**:覆盖自动生成的公共 URL。如果内部 URL 和外部 URL 不匹配(例如在 Docker 中),这很有用。
- `LFS_START_SERVER`:**false**:启用 git-lfs 支持。
- `DB_TYPE`:**sqlite3**:正在使用的数据库类型[mysql,postgres,mssql,sqlite3]。
- `DB_HOST`:**localhost:3306**:数据库主机地址和端口。
- `DB_NAME`:**gitea**:数据库名称。
- `DB_USER`:**root**:数据库用户名。
- `DB_PASSWD`:**"_empty_"** :数据库用户密码。如果您在密码中使用特殊字符,请使用“您的密码”进行引用。
- `INSTALL_LOCK`:**false**:禁止访问安装页面。
- `SECRET_KEY`:**""** :全局密钥。这应该更改。如果它具有一个值并且 `INSTALL_LOCK` 为空,则 `INSTALL_LOCK` 将自动设置为 `true`。
- `DISABLE_REGISTRATION`:**false**:禁用注册,之后只有管理员才能为用户创建帐户。
- `REQUIRE_SIGNIN_VIEW`:**false**:启用此选项可强制用户登录以查看任何页面。
- `USER_UID`:**1000**:在容器内运行 Gitea 的用户的 UID(Unix 用户 ID)。如果使用主机卷,则将其与 `/data` 卷的所有者的 UID 匹配(对于命名卷,则不需要这样做)。
- `USER_GID`:**1000**:在容器内运行 Gitea 的用户的 GID(Unix 组 ID)。如果使用主机卷,则将其与 `/data` 卷的所有者的 GID 匹配(对于命名卷,则不需要这样做)。
## 自定义
[此处](../administration/customizing-gitea.md)描述的定制文件应放在 `/data/gitea` 目录中。如果使用主机卷,则访问这些文件非常容易;对于命名卷,可以通过另一个容器或通过直接访问 `/var/lib/docker/volumes/gitea_gitea/_data` 来完成。安装后,配置文件将保存在 `/data/gitea/conf/app.ini` 中。
## 升级
:::warning
:exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation:
:::
要将安装升级到最新版本:
```bash
# Edit `docker-compose.yml` to update the version, if you have one specified
# Pull new images
docker-compose pull
# Start a new container, automatically removes old one
docker-compose up -d
```
## 使用环境变量管理部署
除了上面的环境变量之外,`app.ini` 中的任何设置都可以使用以下形式的环境变量进行设置或覆盖:`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器启动时都会应用这些设置。 完整信息在[这里](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtps
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `app.ini`。 如果您想手动设置 `SECRET_KEY`,您可以使用以下 docker 命令来使用 Gitea 内置的[方法](../administration/command-line.md#generate)生成 `SECRET_KEY`。 安装后请妥善保管您的 `SECRET_KEY`,如若丢失则无法解密已加密的数据。
以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`,然后您可以将其放入环境变量中。
```bash
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
```
```yaml
---
services:
server:
environment:
- GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH 容器直通
由于 SSH 在容器内运行,因此,如果需要 SSH 支持,则需要将 SSH 从主机传递到容器。一种选择是在非标准端口上运行容器 SSH(或将主机端口移至非标准端口)。另一个可能更直接的选择是将 SSH 连接从主机转发到容器。下面将说明此设置。
本指南假定您已经在名为 `git` 的主机上创建了一个用户,该用户与容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。这些值可以在 `docker-compose.yml` 中设置为环境变量:
```bash
environment:
- USER_UID=1000
- USER_GID=1000
```
接下来将主机的 `/home/git/.ssh` 装入容器。否则,SSH 身份验证将无法在容器内运行。
```bash
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
现在,需要在主机上创建 SSH 密钥对。该密钥对将用于向主机验证主机上的 `git` 用户。
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
在下一步中,需要在主机上创建一个名为 `/usr/local/bin/gitea` 的文件(具有可执行权限)。该文件将发出从主机到容器的 SSH 转发。将以下内容添加到 `/usr/local/bin/gitea`:
```bash
ssh -p 2222 -o StrictHostKeyChecking=no [email protected] "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
```
为了使转发正常工作,需要将容器(22)的 SSH 端口映射到 `docker-compose.yml` 中的主机端口 2222。由于此端口不需要暴露给外界,因此可以将其映射到主机的 `localhost`:
```bash
ports:
# [...]
- "127.0.0.1:2222:22"
```
另外,主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此,将您在上面创建的密钥(“Gitea 主机密钥”)的公共密钥添加到 `/home/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示:来自 `git` 用户的公钥需要“按原样”添加,而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。
该文件应该看起来像:
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
这是详细的说明,当发出 SSH 请求时会发生什么:
1. 使用 `git` 用户向主机发出 SSH 请求,例如 `git clone git@domain:user/repo.git`。
2. 在 `/home/git/.ssh/authorized_keys` 中,该命令执行 `/usr/local/bin/gitea` 脚本。
3. `/usr/local/bin/gitea` 将 SSH 请求转发到端口 2222,该端口已映射到容器的 SSH 端口(22)。
4. 由于 `/home/git/.ssh/authorized_keys` 中存在 `git` 用户的公钥,因此身份验证主机 → 容器成功,并且 SSH 请求转发到在 docker 容器中运行的 Gitea。
如果在 Gitea Web 界面中添加了新的 SSH 密钥,它将以与现有密钥相同的方式附加到 `.ssh/authorized_keys` 中。
**注意**
SSH 容器直通仅在以下情况下有效
- 在容器中使用 `opensshd`
- 如果未将 `AuthorizedKeysCommand` 与 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 结合使用以禁用授权文件密钥生成
- `LOCAL_ROOT_URL` 不变
Loaded 50 of 2340 files, more files were not shown because too many files have changed in this diff. Show more