利用 Gitea Doctor自助诊断工具帮助管理员排查问题

​我常常在Gitea论坛或者Hostea为网友解答Gitea版本升级方面的问题，但发现少有人知道利用 gitea doctor 命令行工具排查问题，因此这篇博文将给大家带来通俗易懂的介绍。

• 你知道吗？我们现在已经开通了微信公众号和哔哩哔哩视频栏目，欢迎关注、点赞、一键三连!
• 点击链接加入群聊【Gitea 官方技术群】：328432459

什么是 Doctor？

gitea doctor 是 Gitea 程序自带的一个命令行工具，它可以扫描 Gitea 系统工作状况，诊断出常见的故障。这项功能已经发布超过两年了，我们希望借助它让 Gitea 管理员的运维工作变得更加简单。

注意事项

• 本文基于容器创建的 Gitea 1.17.0 实例进行示范。如果你还没有安装，请参阅文档~
• gitea doctor 兼容相邻的几个 Gitea 版本，跨越多个版本可能会出现意料之外的问题。
• 在 Docker 容器中，Gitea 采用有限权限的 git 账号作为程序运行环境。因此当你进入到容器内操作 gitea doctor 前，你需要为当前终端指定账号名称和工作路径，如下所示：

docker exec -it --user git --workdir=/tmp gitea bash

开始使用 Gitea Doctor

如果你想要完整检查整个系统的工况，请确保至少初始化一个仓库。完成操作后再次执行命令：

$ gitea doctor --all

[1] Check paths and basic configuration
 - [I] Configuration File Path:    "/data/gitea/conf/app.ini"
 - [I] Repository Root Path:       "/data/git/repositories"
 - [I] Data Root Path:             "/data/gitea"
 - [I] Custom File Root Path:      "/data/gitea"
 - [I] Work directory:             "/app/gitea"
 - [I] Log Root Path:              "/data/gitea/log"
OK
[2] Check if there is garbage storage files
OK
[3] Check Database Version
OK
[4] Check consistency of database
OK
[5] Check if user with wrong type exist
OK
[6] Check if OpenSSH authorized_keys file is up-to-date
OK
[7] Check if SCRIPT_TYPE is available
 - [I] ScriptType bash is on the current PATH at /bin/bash
OK
[8] Check if hook files are up-to-date and executable
OK
[9] Recalculate Stars number for all user
 - [I] No check available for User Stars numbers (skipped)
OK
[10] Check old archives
 - [I] 0 old archives in repository need to be deleted
OK
[11] Check that all git repositories have receive.advertisePushOptions set to true
 - [I] Checked 1 repositories, 0 need updates.
OK
[12] Check for incorrectly dumped repo_units (See #16961)
 - [I] Found no broken repo_units
OK
[13] Recalculate merge bases
 - [I] All 0 PRs in 1 repos have a correct mergebase
OK
[14] Check git-daemon-export-ok files
 - [I] Checked 1 repositories, 0 need updates.
OK
[15] Check if users has an valid email address
 - [I] All users have a valid e-mail.
OK

检查结果看起来一切正常，这很好！

Doctor 还可以干什么？

如果把 doctor 类比为 fsck （一款知名的文件系统检查工具），我们可以在不影响软件系统正常工作的情况下进行一些更细致和精确的诊断。打开终端，使用 gitea doctor --list 可以列出所有可用的常规诊断方法：

$ gitea doctor --list
Default Name                            Title
*       paths                           Check paths and basic configuration
        storages                        Check if there is garbage storage files
*       check-db-version                Check Database Version
        check-db-consistency            Check consistency of database
*       check-user-type                 Check if user with wrong type exist
*       authorized-keys                 Check if OpenSSH authorized_keys file is up-to-date
        script-type                     Check if SCRIPT_TYPE is available
        hooks                           Check if hook files are up-to-date and executable
        recalculate-stars-number        Recalculate Stars number for all user
        check-old-archives              Check old archives
        enable-push-options             Check that all git repositories have receive.advertisePushOptions set to true
        fix-broken-repo-units           Check for incorrectly dumped repo_units (See #16961)
        recalculate-merge-bases         Recalculate merge bases
        check-git-daemon-export-ok      Check git-daemon-export-ok files
        check-user-email                Check if users has an valid email address

例如，我们想检查 OpenSSH 的 authorized_keys 文件是否是最新的，可以运行：

$ gitea doctor --run authorized-keys
[1] Check if OpenSSH authorized_keys file is up-to-date
OK

以上便是，doctor目前可用的全部功能。如果你还想了解它是如何工作的，可以直接切入源码本身，doctor.go 是命令入口点，doctor 目录包含每一项检查的细节，如果你还发现了新的问题解决方法欢迎提交PR。

遇到问题时别担心，即便你不知道如何编写Go程序，我们也欢迎你加入我们的社区一起讨论。

• 中文QQ群：328432459
• GitHub Issues（英语，汇聚了世界各地的项目维护者）：https://github.com/go-gitea/gitea/issues>
• 官方论坛（支持中文）：https://discourse.gitea.io/c/5-category/5

检查过程不会影响软件工作

Doctor 可以检查系统完整性，并且丝毫不影响正在运行的 Gitea 服务，它会给出以下两种提示：

• [I] 表示 Information，只是一些常规的信息提醒，可以忽略
• [W] 表示 Warning，是一些值得注意的问题，但是并不严重

我们可以举个形象的例子，例如首先人为造成破坏，从我们的存储库中删除 hooks 的可执行权限：

chmod -x /data/git/repositories/user/test.git/hooks/post-receive

此时运行 gitea doctor --run hooks，应该会发现问题：

$ gitea doctor --run hooks

[1] Check if hook files are up-to-date and executable
 - [W] old hook file /data/git/repositories/user/test.git/hooks/post-receive is not executable

修复问题，使用 gitea doctor --run hooks --fix：

$ gitea doctor --run hooks --fix

[1] Check if hook files are up-to-date and executable
 - [W] Regenerated hooks for user/test
 - [W] old hook file /data/git/repositories/user/test.git/hooks/post-receive is not executable

再次检查：

$ docker exec gitea gitea doctor --run hooks
[1] Check if hook files are up-to-date and executable
OK

以上操作足够修复简单的问题。如果故障仍未解决，我们还可以检查当前工作目录下生成的doctor.log 日志，获得更充足的情报。使用 --log-file - 可以方便地将日志打印到控制台，例如：

gitea doctor --log-file -

更进一步

如果这对您有帮助，欢迎留言评论，通过 Mastodon 可以联系到原作者 dachary。如果你有更好的想法：你可以进入我们的 GitHub 仓库发送一个PR请求来帮助改善 gitea doctor。