跳至主要内容
版本：1.22.3

数据库准备

使用 Gitea 需要一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置）和 MSSQL（>= 2012 SP4）。此页面将指导您准备数据库。这里只介绍 PostgreSQL 和 MySQL，因为这些数据库引擎在生产环境中被广泛使用。如果您计划使用 SQLite，则可以忽略本章。

如果您使用的是不受支持的数据库版本，请联系我们以获取有关扩展支持合同的信息。我们可以为旧版数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。

数据库实例可以与 Gitea 位于同一台机器上（本地数据库设置），也可以位于不同的机器上（远程数据库）。

注意：以下所有步骤都需要在您的系统上安装您选择的数据库引擎。对于远程数据库设置，请在数据库实例上安装服务器应用程序，并在您的 Gitea 服务器上安装客户端程序。客户端程序用于测试从 Gitea 服务器到数据库的连接，而 Gitea 本身则使用 Go 提供的数据库驱动程序来完成相同的事情。此外，请确保服务器和客户端使用相同的引擎版本，以便某些引擎功能正常工作。出于安全原因，请使用安全密码保护root（MySQL）或postgres（PostgreSQL）数据库超级用户。这些步骤假定您为数据库和 Gitea 服务器都运行 Linux。

MySQL/MariaDB​

  1. 对于远程数据库设置，您需要使 MySQL 监听您的 IP 地址。在数据库实例上的/etc/mysql/my.cnf中编辑bind-address选项为

    bind-address = 203.0.113.3

  2. 在数据库实例上，以 root 身份登录到数据库控制台

    mysql -u root -p

    根据提示输入密码。

  3. 创建 Gitea 将使用的数据库用户，并通过密码进行身份验证。此示例使用'gitea'作为密码。请为您的实例使用安全密码。

    对于本地数据库

    SET old_passwords=0;
    CREATE USER 'gitea'@'%' IDENTIFIED BY 'gitea';

    对于远程数据库

    SET old_passwords=0;
    CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';

    其中192.0.2.10是您的 Gitea 实例的 IP 地址。

    根据需要替换上述用户名和密码。

  4. 创建具有 UTF-8 字符集和区分大小写的排序规则的数据库。

    utf8mb4_bin是 MySQL/MariaDB 的常用排序规则。当 Gitea 启动时，它会尝试查找更好的排序规则（utf8mb4_0900_as_cs或uca1400_as_cs）并在可能的情况下更改数据库。如果您想使用其他排序规则，可以在app.ini文件中设置[database].CHARSET_COLLATION。

    CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';

    根据需要替换数据库名称。

  5. 授予上面创建的数据库用户对数据库的所有权限。

    对于本地数据库

    GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
    FLUSH PRIVILEGES;

    对于远程数据库

    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 地址为

    listen_addresses = 'localhost, 203.0.113.3'

  2. PostgreSQL 默认使用md5质询响应加密方案进行密码身份验证。如今，此方案不再被认为是安全的。请改用 SCRAM-SHA-256 方案，方法是在数据库服务器上的postgresql.conf配置文件中进行编辑为

    password_encryption = scram-sha-256

    重新启动 PostgreSQL 以应用设置。

  3. 在数据库服务器上，以超级用户身份登录到数据库控制台

    su -c "psql" - postgres

  4. 创建具有登录权限和密码的数据库用户（在 PostgreSQL 术语中称为角色）。请使用安全、强大的密码，而不是下面的'gitea'

    CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';

    根据需要替换用户名和密码。

  5. 创建具有 UTF-8 字符集并由前面创建的数据库用户拥有的数据库。任何libc排序规则都可以使用LC_COLLATE和LC_CTYPE参数指定，具体取决于预期内容

    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，允许数据库用户访问上面创建的数据库。

    对于本地数据库

    local    giteadb    gitea    scram-sha-256

    对于远程数据库

    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://[email protected]/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 TLS​

Gitea 使用的 PostgreSQL 驱动程序支持双向 TLS。在双向 TLS 中，数据库客户端和服务器通过将各自的证书发送到各自的对等方以进行验证来相互进行身份验证。换句话说，服务器验证客户端证书，客户端验证服务器证书。

  1. 在带有数据库实例的服务器上，放置以下凭据

    • /path/to/postgresql.crt：数据库实例证书
    • /path/to/postgresql.key：数据库实例私钥
    • /path/to/root.crt：验证客户端证书的 CA 证书链

  2. 在postgresql.conf中添加以下选项

    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

    hostssl    giteadb    gitea    192.0.2.10/32    scram-sha-256    clientcert=verify-full

    对于 PostgreSQL 11 及更早版本

    hostssl    giteadb    gitea    192.0.2.10/32    scram-sha-256    clientcert=1

    根据需要替换数据库名称、用户和 Gitea 实例的 IP 地址。

  5. 重新启动 PostgreSQL 以应用上述配置。

  6. 在运行 Gitea 实例的服务器上，将以下凭据放置在运行 Gitea 的用户的 home 目录下（例如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://[email protected]/giteadb?sslmode=verify-full"

    系统将提示您输入数据库用户的密码，然后连接到数据库。

MySQL/MariaDB TLS​

虽然 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 中添加以下选项

    [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 才能连接到数据库

    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

    您应该已连接到数据库。