From 9858d3b6df709d73b1f6db93585c3292402e063e Mon Sep 17 00:00:00 2001 From: sillyguodong <33891828+sillyguodong@users.noreply.github.com> Date: Thu, 25 May 2023 12:32:39 +0800 Subject: [PATCH] Add chinese documentations for installation (#24904) --- .../database-preparation.zh-cn.md | 307 ++++++++++++++++ .../doc/installation/from-binary.zh-cn.md | 6 +- .../doc/installation/from-source.zh-cn.md | 6 +- .../installation/on-cloud-provider.zh-cn.md | 57 +++ .../doc/installation/on-kubernetes.zh-cn.md | 4 +- .../with-docker-rootless.zh-cn.md | 332 ++++++++++++++++++ 6 files changed, 704 insertions(+), 8 deletions(-) create mode 100644 docs/content/doc/installation/database-preparation.zh-cn.md create mode 100644 docs/content/doc/installation/on-cloud-provider.zh-cn.md create mode 100644 docs/content/doc/installation/with-docker-rootless.zh-cn.md diff --git a/docs/content/doc/installation/database-preparation.zh-cn.md b/docs/content/doc/installation/database-preparation.zh-cn.md new file mode 100644 index 0000000000..6c23f8ce5d --- /dev/null +++ b/docs/content/doc/installation/database-preparation.zh-cn.md @@ -0,0 +1,307 @@ +--- +date: "2020-01-16" +title: "数据库准备" +slug: "database-prep" +weight: 10 +toc: false +draft: false +aliases: + - /zh-cn/database-prep +menu: + sidebar: + parent: "installation" + name: "数据库准备" + weight: 10 + identifier: "database-prep" +--- + +# 数据库准备 + +在使用 Gitea 前,您需要准备一个数据库。Gitea 支持 PostgreSQL(>=10)、MySQL(>=5.7)、SQLite 和 MSSQL(>=2008R2 SP3)这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用,因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite,则可以忽略本章内容。 + +数据库实例可以与 Gitea 实例在相同机器上(本地数据库),也可以与 Gitea 实例在不同机器上(远程数据库)。 + +注意:以下所有步骤要求您的选择的数据库引擎已安装在您的系统上。对于远程数据库设置,请在数据库实例上安装服务器应用程序,在 Gitea 服务器上安装客户端程序。客户端程序用于测试 Gitea 服务器与数据库之间的连接,而 Gitea 本身使用 Go 提供的数据库驱动程序完成相同的任务。此外,请确保服务器和客户端使用相同的引擎版本,以使某些引擎功能正常工作。出于安全原因,请使用安全密码保护 `root`(MySQL)或 `postgres`(PostgreSQL)数据库超级用户。以下步骤假设您在数据库和 Gitea 服务器上都使用 Linux。 + +**目录** + +{{< toc >}} + +## MySQL + +1. 对于远程数据库设置,您需要让 MySQL 监听您的 IP 地址。编辑数据库实例上的 `/etc/mysql/my.cnf` 文件中的 `bind-address` 选项为: + + ```ini + bind-address = 203.0.113.3 + ``` + +2. 在数据库实例上,使用 `root` 用户登录到数据库控制台: + + ``` + mysql -u root -p + ``` + + 按提示输入密码。 + +3. 创建一个将被 Gitea 使用的数据库用户,并使用密码进行身份验证。以下示例中使用了 `'gitea'` 作为密码。请为您的实例使用一个安全密码。 + + 对于本地数据库: + + ```sql + SET old_passwords=0; + CREATE USER 'gitea' IDENTIFIED BY 'gitea'; + ``` + + 对于远程数据库: + + ```sql + SET old_passwords=0; + CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea'; + ``` + + 其中 `192.0.2.10` 是您的 Gitea 实例的 IP 地址。 + + 根据需要替换上述用户名和密码。 + +4. 使用 UTF-8 字符集和排序规则创建数据库。确保使用 `**utf8mb4**` 字符集,而不是 `utf8`,因为前者支持 _Basic Multilingual Plane_ 之外的所有 Unicode 字符(包括表情符号)。排序规则根据您预期的内容选择。如果不确定,可以使用 `unicode_ci` 或 `general_ci`。 + + ```sql + CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'; + ``` + + 根据需要替换数据库名称。 + +5. 将数据库上的所有权限授予上述创建的数据库用户。 + + 对于本地数据库: + + ```sql + GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'; + FLUSH PRIVILEGES; + ``` + + 对于远程数据库: + + ```sql + GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10'; + FLUSH PRIVILEGES; + ``` + +6. 通过 exit 退出数据库控制台。 + +7. 在您的 Gitea 服务器上,测试与数据库的连接: + + ``` + mysql -u gitea -h 203.0.113.3 -p giteadb + ``` + + 其中 `gitea` 是数据库用户名,`giteadb` 是数据库名称,`203.0.113.3` 是数据库实例的 IP 地址。对于本地数据库,省略 -h 选项。 + + 到此您应该能够连接到数据库了。 + +## PostgreSQL + +1. 对于远程数据库设置,通过编辑数据库实例上的 postgresql.conf 文件中的 listen_addresses 将 PostgreSQL 配置为监听您的 IP 地址: + + ```ini + listen_addresses = 'localhost, 203.0.113.3' + ``` + +2. PostgreSQL 默认使用 `md5` 质询-响应加密方案进行密码身份验证。现在这个方案不再被认为是安全的。改用 SCRAM-SHA-256 方案,通过编辑数据库服务器上的` postgresql.conf` 配置文件: + + ```ini + password_encryption = scram-sha-256 + ``` + + 重启 PostgreSQL 以应用该设置。 + +3. 在数据库服务器上,以超级用户身份登录到数据库控制台: + + ``` + su -c "psql" - postgres + ``` + +4. 创建具有登录权限和密码的数据库用户(在 PostgreSQL 术语中称为角色)。请使用安全的、强密码,而不是下面的 `'gitea'`: + + ```sql + CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea'; + ``` + + 根据需要替换用户名和密码。 + +5. 使用 UTF-8 字符集创建数据库,并由之前创建的数据库用户拥有。可以根据预期内容使用任何 `libc` 排序规则,使用 `LC_COLLATE` 和 `LC_CTYPE` 参数指定: + + ```sql + CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8'; + ``` + + 根据需要替换数据库名称。 + +6. 通过将以下身份验证规则添加到 `pg_hba.conf`,允许数据库用户访问上面创建的数据库。 + + 对于本地数据库: + + ```ini + local giteadb gitea scram-sha-256 + ``` + + 对于远程数据库: + + ```ini + host giteadb gitea 192.0.2.10/32 scram-sha-256 + ``` + + 根据您自己的数据库名称、用户和 Gitea 实例的 IP 地址进行替换。 + + 注意:`pg_hba.conf` 上的规则按顺序评估,也就是第一个匹配的规则将用于身份验证。您的 PostgreSQL 安装可能附带了适用于所有用户和数据库的通用身份验证规则。如果是这种情况,您可能需要将此处提供的规则放置在此类通用规则之上。 + + 重启 PostgreSQL 以应用新的身份验证规则。 + +7. 在您的 Gitea 服务器上,测试与数据库的连接。 + + 对于本地数据库: + + ``` + psql -U gitea -d giteadb + ``` + + 对于远程数据库: + + ``` + psql "postgres://gitea@203.0.113.3/giteadb" + ``` + + 其中 `gitea` 是数据库用户,`giteadb` 是数据库名称,`203.0.113.3` 是您的数据库实例的 IP 地址。 + + 您应该会被提示输入数据库用户的密码,并连接到数据库。 + +## 使用 TLS 进行数据库连接 + +如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的,或者如果 Gitea 和数据库运行在同一台服务器上,那么可以省略本节,因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是,如果数据库实例位于公共网络上,请使用 TLS 对数据库连接进行加密,以防止第三方拦截流量数据。 + +### 先决条件 + +- 您需要两个有效的 TLS 证书,一个用于数据库实例(数据库服务器),一个用于 Gitea 实例(数据库客户端)。两个证书都必须由受信任的 CA 签名。 +- 数据库证书必须在 `X509v3 Extended Key Usage` 扩展属性中包含 `TLS Web Server Authentication`,而客户端证书则需要在相应的属性中包含 `TLS Web Client Authentication`。 +- 在数据库服务器证书中,`Subject Alternative Name` 或 `Common Name` 条目之一必须是数据库实例的完全限定域名(FQDN)(例如 `db.example.com`)。在数据库客户端证书中,上述提到的条目之一必须包含 Gitea 将用于连接的数据库用户名。 +- 您需要将 Gitea 和数据库服务器的域名映射到它们各自的 IP 地址。可以为它们设置 DNS 记录,也可以在每个系统上的 `/etc/hosts`(Windows 中的 `%WINDIR%\System32\drivers\etc\hosts`)中添加本地映射。这样可以通过域名而不是 IP 地址进行数据库连接。有关详细信息,请参阅您系统的文档。 + +### PostgreSQL + +Gitea 使用的 PostgreSQL 驱动程序支持双向 TLS。在双向 TLS 中,数据库客户端和服务器通过将各自的证书发送给对方进行验证来相互认证。换句话说,服务器验证客户端证书,客户端验证服务器证书。 + +1. 在数据库实例所在的服务器上,放置以下凭据: + + - `/path/to/postgresql.crt`: 数据库实例证书 + - `/path/to/postgresql.key`: 数据库实例私钥 + - `/path/to/root.crt`: 用于验证客户端证书的CA证书链 + +2. 在 `postgresql.conf` 中添加以下选项: + + ```ini + ssl = on + ssl_ca_file = '/path/to/root.crt' + ssl_cert_file = '/path/to/postgresql.crt' + ssl_key_file = '/path/to/postgresql.key' + ssl_min_protocol_version = 'TLSv1.2' + ``` + +3. 根据 PostgreSQL 的要求,调整凭据的所有权和权限: + + ``` + chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key + chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key + ``` + +4. 编辑 `pg_hba.conf` 规则,仅允许 Gitea 数据库用户通过SSL连接,并要求客户端证书验证。 + + 对于PostgreSQL 12: + + ```ini + hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full + ``` + + 对于PostgreSQL 11及更早版本: + + ```ini + hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1 + ``` + + 根据需要替换数据库名称、用户和 Gitea 实例的 IP 地址。 + +5. 重新启动 PostgreSQL 以应用上述配置。 + +6. 在运行 Gitea 实例的服务器上,将以下凭据放置在运行 Gitea 的用户的主目录下(例如 `git`): + + - `~/.postgresql/postgresql.crt`: 数据库客户端证书 + - `~/.postgresql/postgresql.key`: 数据库客户端私钥 + - `~/.postgresql/root.crt`: 用于验证服务器证书的CA证书链 + + 注意:上述文件名在 PostgreSQL 中是硬编码的,无法更改。 + +7. 根据需要调整凭据、所有权和权限: + + ``` + chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt + chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt + ``` + +8. 测试与数据库的连接: + + ``` + psql "postgres://gitea@example.db/giteadb?sslmode=verify-full" + ``` + + 您将被提示输入数据库用户的密码,然后连接到数据库。 + +### MySQL + +虽然 Gitea 使用的MySQL驱动程序也支持双向 TLS,但目前 Gitea 仅支持单向 TLS。有关详细信息,请参见工单#10828。 + +在单向TLS中,数据库客户端在连接握手期间验证服务器发送的证书,而服务器则假定连接的客户端是合法的,因为不进行客户端证书验证。 + +1. 在数据库实例上放置以下凭据: + + - `/path/to/mysql.crt`: 数据库实例证书 + - `/path/to/mysql.key`: 数据库实例密钥 + - `/path/to/ca.crt`: CA证书链。在单向TLS中不使用此文件,但用于验证双向TLS中的客户端证书。 + +2. 将以下选项添加到 `my.cnf`: + + ```ini + [mysqld] + ssl-ca = /path/to/ca.crt + ssl-cert = /path/to/mysql.crt + ssl-key = /path/to/mysql.key + tls-version = TLSv1.2,TLSv1.3 + ``` + +3. 调整凭据的所有权和权限: + + ``` + chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key + chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key + ``` + +4. 重新启动MySQL以应用设置。 + +5. Gitea 的数据库用户可能已经创建过,但只会对运行 Gitea 的服务器的 IP 地址进行身份验证。要对其域名进行身份验证,请重新创建用户,并设置其需要通过 TLS 连接到数据库: + + ```sql + DROP USER 'gitea'@'192.0.2.10'; + CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL; + GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea'; + FLUSH PRIVILEGES; + ``` + + 根据需要替换数据库用户名、密码和 Gitea 实例域名。 + +6. 确保用于验证数据库服务器证书的CA证书链位于数据库和 Gitea 服务器的系统证书存储中。请参考系统文档中有关将 CA 证书添加到证书存储的说明。 + +7. 在运行Gitea的服务器上,测试与数据库的连接: + + ``` + mysql -u gitea -h example.db -p --ssl + ``` + + 至此应该成功连接到数据库了。 diff --git a/docs/content/doc/installation/from-binary.zh-cn.md b/docs/content/doc/installation/from-binary.zh-cn.md index 248f03d63f..126ebf6e06 100644 --- a/docs/content/doc/installation/from-binary.zh-cn.md +++ b/docs/content/doc/installation/from-binary.zh-cn.md @@ -1,6 +1,6 @@ --- date: "2016-12-01T16:00:00+02:00" -title: "从二进制安装" +title: "使用二进制文件安装" slug: "install-from-binary" weight: 15 toc: false @@ -10,12 +10,12 @@ aliases: menu: sidebar: parent: "installation" - name: "从二进制安装" + name: "使用二进制文件安装" weight: 15 identifier: "install-from-binary" --- -# 从二进制安装 +# 使用二进制文件安装 所有打包的二进制程序均包含 SQLite,MySQL 和 PostgreSQL 的数据库连接支持,同时网站的静态资源均已嵌入到可执行程序中,这一点和曾经的 Gogs 有所不同。 diff --git a/docs/content/doc/installation/from-source.zh-cn.md b/docs/content/doc/installation/from-source.zh-cn.md index 8f3ccbe7e2..9cd835ae58 100644 --- a/docs/content/doc/installation/from-source.zh-cn.md +++ b/docs/content/doc/installation/from-source.zh-cn.md @@ -1,6 +1,6 @@ --- date: "2016-12-01T16:00:00+02:00" -title: "从源代码安装" +title: "使用源代码安装" slug: "install-from-source" weight: 30 toc: false @@ -10,12 +10,12 @@ aliases: menu: sidebar: parent: "installation" - name: "从源代码安装" + name: "使用源代码安装" weight: 30 identifier: "install-from-source" --- -# 从源代码安装 +# 使用源代码安装 首先你需要安装Golang,关于Golang的安装,参见[官方文档](https://golang.google.cn/doc/install)。 diff --git a/docs/content/doc/installation/on-cloud-provider.zh-cn.md b/docs/content/doc/installation/on-cloud-provider.zh-cn.md new file mode 100644 index 0000000000..80fbf2d51d --- /dev/null +++ b/docs/content/doc/installation/on-cloud-provider.zh-cn.md @@ -0,0 +1,57 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "在云服务器中安装 Gitea" +slug: "install-on-cloud-provider" +weight: 90 +toc: false +draft: false +aliases: + - /zh-cn/install-on-cloud-provider +menu: + sidebar: + parent: "installation" + name: "在云服务器中安装 Gitea" + weight: 90 + identifier: "install-on-cloud-provider" +--- + +# 在云服务器上安装 Gitea + +**Table of Contents** + +{{< toc >}} + +## Cloudron + +Gitea 可以在 [Cloudron](https://cloudron.io) 上进行一键安装。 +Cloudron 使得在您的服务器上运行 Gitea,并保持其更新和安全变得简单。 + +[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp) + +Gitea软件包的维护地址在[这里](https://git.cloudron.io/cloudron/gitea-app). + +这里有一个[demo 实例](https://my.demo.cloudron.io) (用户名: cloudron 密码: cloudron) 您可以在其中尝试运行Gitea。 + +## Vultr + +Gitea 可以在 [Vultr](https://www.vultr.com) 的市场中被找到。 + +要将 Gitea 部署到 Vultr,请参考 [Vultr Marketplace](https://www.vultr.com/marketplace/apps/gitea). + +## DigitalOcean + +[DigitalOcean](https://www.digitalocean.com) 将 Gitea 作为其市场中的一个 droplet。 + +要将 Gitea 部署到 DigitalOcean, 请参考 [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/gitea). + +## Linode + +[Linode](https://www.linode.com/) 将 Gitea 作为其市场中的一个应用程序. + +要将 Gitea 部署到 Linode, 请参考 [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/). + +## alwaysdata + +[alwaysdata](https://www.alwaysdata.com/) 将 Gitea 作为其市场中的一个 droplet. + +要将 Gitea 部署到 alwaysdata, 请参考 [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/). diff --git a/docs/content/doc/installation/on-kubernetes.zh-cn.md b/docs/content/doc/installation/on-kubernetes.zh-cn.md index 367aef1cf3..f5e8f9f762 100644 --- a/docs/content/doc/installation/on-kubernetes.zh-cn.md +++ b/docs/content/doc/installation/on-kubernetes.zh-cn.md @@ -1,6 +1,6 @@ --- date: "2020-03-19T19:27:00+02:00" -title: "在 Kubernetes 安装 Gitea" +title: "在 Kubernetes 中安装 Gitea" slug: "install-on-kubernetes" weight: 80 toc: false @@ -10,7 +10,7 @@ aliases: menu: sidebar: parent: "installation" - name: "Kubernetes" + name: "在 Kubernetes 中安装 Gitea" weight: 80 identifier: "install-on-kubernetes" --- diff --git a/docs/content/doc/installation/with-docker-rootless.zh-cn.md b/docs/content/doc/installation/with-docker-rootless.zh-cn.md new file mode 100644 index 0000000000..eca2e4381a --- /dev/null +++ b/docs/content/doc/installation/with-docker-rootless.zh-cn.md @@ -0,0 +1,332 @@ +--- +date: "2020-02-09T20:00:00+02:00" +title: "使用 Docker 安装 (rootless)" +slug: "install-with-docker-rootless" +weight: 60 +toc: false +draft: false +aliases: + - /zh-cn/install-with-docker-rootless +menu: + sidebar: + parent: "installation" + name: "使用 Docker 安装 (rootless)" + weight: 60 + identifier: "install-with-docker-rootless" +--- + +# 使用 Docker 安装 + +Gitea 在其 Docker Hub 组织中提供自动更新的 Docker 镜像。您可以始终使用最新的稳定标签,或使用其他处理 Docker 镜像更新的服务。 + +rootless 镜像使用 Gitea 内部 SSH 功能来提供 Git 协议,但不支持 OpenSSH。 + +本参考设置指南将用户引导通过基于 `docker-compose` 的设置。但是,`docker-compose` 的安装超出了本文档的范围。要安装`docker-compose` 本身, 请按照官方的 [安装说明](https://docs.docker.com/compose/install/)进行操作。 + +## 基础设置 + +最简单的设置只需创建一个卷和一个网络,并将 `gitea/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: gitea/gitea:{{< version >}}-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`,或指定特定的版本,如: `{{< version >}}-rootless`。如果您想使用最新的开发版本,则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交,可以使用 `:1.x-dev-rootless` 标签,其中 x是 Gitea 的次要版本号(例如:`1.16-dev-rootless`)。 + +## 自定义端口 + +要将集成的SSH和Web服务器绑定到不同的端口,请调整端口部分。通常只需更改主机端口并保持容器内的端口不变。 + +```diff +version: "2" + +services: + server: + image: gitea/gitea:{{< version >}}-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: gitea/gitea:{{< version >}}-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: 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: gitea/gitea:{{< version >}}-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: 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: gitea/gitea:{{< version >}}-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: gitea/gitea:{{< version >}}-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` 中。 + +# 升级 + +:exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: + +要将安装升级到最新版本,请按照以下步骤操作: + +``` +# 如果在 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` +- 使用镜像 `gitea/gitea:{{< version >}}-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__MAILER_TYPE=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 的内置[生成使用函数](https://docs.gitea.io/en-us/command-line/#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](https://docs.gitea.io/en-us/command-line/#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 服务器。