常见问题解答

此页面包含一些常见问题和答案。

要获得更多帮助资源，请查看所有 支持选项。

1.x 和 1.x.x 下载之间的区别，如何获取包含错误修复的最新稳定版本？

此示例将使用版本 1.20.x。

在我们的 下载页面 上，您会看到一个 1.20 目录，以及 1.20.0、1.20.1 的目录。

1.20 目录是每晚构建，它是在每个合并到 release/v1.20 分支的提交上构建的。

1.20.0 目录是在创建 v1.20.0 标签时创建的发布版本。

每晚构建 (1.x) 下载会在提交合并到各自分支时发生变化，它们包含最新更改/修复，在创建标签版本之前。

如果错误修复针对 1.20.1，但 1.20.1 尚未发布，您可以获取“1.20-nightly”构建来获取错误修复。

如何查找配置文件“app.ini”

这取决于您如何安装 Gitea。如果您没有手动设置自定义路径或配置文件路径，则配置文件 (app.ini) 应该存在于 Gitea 工作路径的“custom/conf”目录中。一些软件包供应商可能使用“/etc/gitea”来存储配置文件，而另一些则没有。

您可以通过查看 Gitea 启动日志或阅读 Gitea Web 的站点管理员 -> 配置摘要来手动查找配置文件 (app.ini)。

如果您使用的是某些隔离环境（例如容器（docker）），您看到的路径通常与主机文件系统中的路径不同。在这种情况下，您需要检查容器的文件系统卷映射，并找出主机上配置文件的实际路径。

如何从 Gogs/GitHub/等迁移到 Gitea

要从 Gogs 迁移到 Gitea

• Gogs 版本 0.11.46.0418

要从 GitHub 迁移到 Gitea，您可以使用 Gitea 的内置迁移表单。

为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。

示例（需要登录）

要从 GitLab 迁移到 Gitea，您可以使用此非关联工具

https://github.com/loganinak/MigrateGitlabToGogs

Gitea 在哪里存储什么文件

• AppWorkPath
  • app.ini 中的 WORK_PATH 选项
  • 或者 --work-path 标志
  • 或者环境变量 GITEA_WORK_DIR
  • 或者在构建时设置的内置值
  • 或者包含 Gitea 二进制文件的目录
• AppDataPath（数据库、索引器等的默认值）
  • 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
  • 或者如果 app.ini 中的 [repository] 部分的 ROOT 为相对路径，则为 AppWorkPath/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. 如果使用反向代理，请确保您已遵循 反向代理指南 中的更正说明
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 请求实体太大

当反向代理限制文件上传大小限制时，会发生此错误。

有关使用 nginx 的解决方案，请参阅 反向代理指南。

自定义模板未加载或工作不正常

Gitea 的自定义模板必须添加到正确的位置，否则 Gitea 无法找到和使用它们。

模板的正确路径将相对于 CustomPath

1. 要查找 CustomPath，请在站点管理员 -> 配置中查找自定义文件根路径
2. 如果您仍然无法找到路径，则默认路径可以 从上面计算得出
3. 确定正确的自定义路径后，您可以参考 自定义 Gitea 页面将您的模板添加到正确的位置。

Gitea 有“GitHub/GitLab Pages”功能吗？

Gitea 不提供内置的 Pages 服务器。您需要一个专用域名来提供静态页面，以避免 CSRF 安全风险。

对于简单用法，您可以使用反向代理来重写和提供来自 Gitea 的原始文件 URL 的静态内容。

已经存在可用的第三方服务，例如独立的 页面服务器 或 caddy 插件，可以提供所需的功能。

活跃用户 vs. 登录禁止用户

在 Gitea 中，“活跃”用户是指通过电子邮件激活其帐户的用户。

“登录禁止”用户是指不再允许登录 Gitea 的用户

设置日志记录

• 官方文档

什么是 Swagger？

Swagger 是 Gitea 用于 API 文档的工具。

所有 Gitea 实例都具有内置的 API，无法完全禁用它。但是，您可以通过将 app.ini 中的 api 部分的 ENABLE_SWAGGER 设置为 false 来禁用显示其文档。有关更多信息，请参考 Gitea 的 API 文档。

您可以在 https://gitea.com/api/swagger 上查看最新的 API（例如）。

您还可以查看 https://gitea.com/swagger.v1.json 上的 swagger.json 文件示例。

调整您的服务器以用于公共/私人使用

防止垃圾邮件发送者

您可以组合多种方法来防止垃圾邮件发送者。

1. 通过将某些电子邮件域名列入白名单或黑名单
2. 仅将具有 OpenID 的某些域名列入白名单（见下文）
3. 在您的 app.ini 中将 ENABLE_CAPTCHA 设置为 true，并正确配置 RECAPTCHA_SECRET 和 RECAPTCHA_SITEKEY
4. 将 DISABLE_REGISTRATION 设置为 true，并通过 CLI、API 或 Gitea 的管理员 UI 创建新用户

仅允许/阻止某些电子邮件域名

您可以在 app.ini 的 [service] 部分中配置 EMAIL_DOMAIN_WHITELIST 或 EMAIL_DOMAIN_BLOCKLIST

仅允许/阻止某些 OpenID 提供商

您可以在 app.ini 的 [openid] 部分中配置 WHITELISTED_URIS 或 BLACKLISTED_URIS

注意

白名单优先，因此如果它不为空，则忽略黑名单

仅问题用户

当前实现此目标的方法是创建一个/修改一个用户，其最大仓库创建限制为 0。

受限用户

受限用户仅限于基于其组织/团队成员身份和协作的子集内容，忽略组织/仓库等上的公共标志。

用例示例：一家公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。

在某些时候，客户或第三方需要访问特定仓库，并且仅限于该仓库。将此类客户帐户限制并使用团队成员身份和/或协作授予任何必要的访问权限是一种简单的方法，无需将所有内容设为私有。

启用 Fail2ban

使用 Fail2Ban 监视和阻止基于日志模式的自动登录尝试或其他恶意行为

SSHD 与内置 SSH

SSHD 是大多数 Unix 系统上的内置 SSH 服务器。

Gitea 还提供自己的 SSH 服务器，用于 SSHD 不可用时使用。

Gitea 运行缓慢

造成这种情况的最常见原因是加载联合头像。

可以通过在您的 app.ini 中将 ENABLE_FEDERATED_AVATAR 设置为 false 来关闭它

另一个可能需要更改的选项是在您的 app.ini 中将 DISABLE_GRAVATAR 设置为 true

无法创建仓库/文件

确保 Gitea 具有足够的权限写入其主目录和数据目录。

参见 AppDataPath 和 RepoRootPath

**注意 Arch 用户：** 在撰写本文时，Arch 包的 systemd 文件存在问题，其中包含以下行

ReadWritePaths=/etc/gitea/app.ini

这使得 Gitea 无法写入所有其他路径。

翻译不正确/如何添加更多翻译

我们目前在 Crowdin 项目 上进行众包翻译。

无论您是想更改翻译还是添加新翻译，都需要在 Crowdin 中进行，因为所有翻译都将在我们的 CI 中通过 Crowdin 集成被覆盖。

推送钩子/Webhook/Actions 无法运行

如果您能推送但无法在首页仪表板上看到推送活动，或者推送没有触发 Webhook 和 Actions 工作流，则可能是 git 钩子不起作用。

有几种可能性

1. git 钩子不同步：在站点管理员面板上运行“重新同步所有仓库的 pre-receive、update 和 post-receive 钩子”
2. git 仓库（和钩子）存储在不支持脚本执行的某些文件系统（例如：由 NAS 挂载）上，确保文件系统支持 chmod a+x any-script
3. 如果您使用的是 docker，请确保 Docker 服务器（而不是客户端）>= 20.10.6

SSH 问题

如果您无法通过 ssh 访问仓库，但 https 工作正常，请考虑以下事项。

首先，确保您可以通过 SSH 访问 Gitea。

ssh [email protected]

如果连接成功，您应该收到类似以下的错误消息

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 管理员面板上运行“重写“.ssh/authorized_keys' 文件（用于 Gitea SSH 密钥）”。

  • 阅读 Gitea 日志。

  • 阅读 /var/log/auth（或类似文件）。

  • 检查仓库的权限。

以下是一个缺少公钥的示例，其中身份验证成功，但其他设置阻止了 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 命令 像往常一样添加用户。

如何启用密码重置

没有密码重置的设置。配置了 邮件服务 后将启用它，否则将禁用它。

如何更改用户的密码

• 作为 **管理员**，您可以更改任何用户的密码（并可以选择在下次登录时强制他们更改密码）...

  • 通过导航到 网站管理 -> 用户帐户 页面并编辑用户。

  • 通过使用 管理员 CLI 命令。

    请记住，大多数命令还需要一个全局标志来将 CLI 指向正确的配置。

• 作为用户，您可以更改它...

  • 在您的帐户设置 -> 帐户页面（此方法需要您知道当前密码）。

  • 使用忘记密码链接。

    如果忘记密码/帐户恢复页面被禁用，请联系您的管理员配置邮件服务。

为什么我的 Markdown 坏了

在 Gitea 版本1.11中，我们迁移到goldmark用于 Markdown 渲染，它符合CommonMark。

如果您在版本1.11之前对 Markdown 有预期效果，而在升级后它不再起作用，请查看 CommonMark 规范，看看问题是否是由错误或不符合规范的语法引起的。

如果是后者，通常规范中会列出符合规范的替代方案。

使用 MySQL 升级时出错

如果您在使用 MySQL 升级 Gitea 时遇到错误，显示

ORM 引擎初始化失败: migrate: do migrate: Error: 1118: Row size too large...

请运行gitea doctor 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;。

为什么 Emoji 只能显示为占位符或单色

Gitea 要求系统或浏览器安装一个支持的 Emoji 字体，包括 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系统应该已经提供其中一种字体，但特别是在 Linux 上，可能需要手动安装它们。

初始日志记录

在 Gitea 读取配置文件并设置其日志记录之前，它会将许多信息记录到标准输出，以帮助调试日志记录不起作用的情况。

您可以通过设置--quiet或-q选项来停止此日志记录。请注意，这只会停止日志记录，直到 Gitea 设置了自己的日志记录。

如果您报告错误或问题，您必须提供包含此信息的日志。

您应该只在完全配置好所有内容后才设置此选项。

数据库启动期间关于结构默认值的警告

有时在进行迁移时，旧的列和默认值可能会在数据库模式中保持不变。这可能会导致以下警告：

2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [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

强烈建议您在运行这些命令之前备份您的数据库。

如何从磁盘采用存储库

• 将您的（裸）存储库添加到与您的配置（repository.ROOT）相匹配的位置，确保它们以正确的布局<REPO_ROOT>/[user]/[repo].git进行排列。
  • 注意：目录名称必须为小写。
  • 您也可以检查<ROOT_URL>/admin/config以获取存储库根路径。
• 确保您想要为其采用存储库的用户/组织存在。
• 作为管理员，请转到<ROOT_URL>/admin/repos/unadopted并搜索。
  • 用户也可以通过配置获得类似的权限 ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES。
• 如果以上步骤正确完成，您应该可以选择要采用的存储库。
  • 如果没有找到存储库，请启用调试日志记录以检查是否有任何特定错误。

Gitea 无法在 NFS 上启动

在大多数情况下，这是由损坏的 NFS 锁系统造成的。您可以尝试停止 Gitea 进程并运行flock -n /data-nfs/gitea/queues/LOCK echo 'lock acquired'，看看锁是否可以立即获取。如果锁无法获取，NFS 可能会在其服务器日志中报告一些错误，例如lockd: cannot monitor node-3, statd: server rpc.statd not responding, timed out。

然后，NFS 锁可以重置为

# /etc/init.d/nfs stop
# rm -rf /var/lib/nfs/sm/*
# /etc/init.d/nfs start