如何解决 Tartelet 常见问题？新手必看的故障排除指南

如何解决 Tartelet 常见问题？新手必看的故障排除指南

【免费下载链接】tartelet⚙️💻 A macOS app that makes it a breeze to manage multiple GitHub Actions runners in ephemeral virtual machines on a single host machine. The benefits are that runners can run in parallel, and each job runs in an isolated environment.项目地址: https://gitcode.com/gh_mirrors/ta/tartelet

Tartelet 是一款在 macOS 上运行的应用，能轻松在单台主机上的临时虚拟机中管理多个 GitHub Actions 运行器，让运行器可并行运行且每个任务都在隔离环境中执行。但新手使用时可能会遇到各类问题，本文将介绍常见问题及解决办法，助你顺利使用 Tartelet。

一、虚拟机器启动失败怎么办？

虚拟机器启动失败是使用 Tartelet 时可能遇到的常见问题，通常有以下几种原因及解决办法。

1.1 检查 Tart 安装与配置

Tartelet 依赖 Tart 来管理虚拟机器，若 Tart 未正确安装或配置，会导致虚拟机器启动失败。首先确认 Tart 已安装，可通过相关命令检查。若未安装，按照官方指引安装。安装后，还需确保 Tart 的配置正确，比如检查 Tart 的路径设置等。

1.2 检查系统资源是否充足

虚拟机器运行需要一定的系统资源，包括内存、磁盘空间等。若系统资源不足，虚拟机器可能无法启动。打开系统监控工具，查看内存和磁盘空间使用情况。若内存不足，关闭不必要的应用程序释放内存；若磁盘空间不足，清理磁盘空间，确保有足够的空间供虚拟机器运行。

1.3 查看错误日志定位问题

当虚拟机器启动失败时，Tartelet 会生成错误日志，可通过查看日志来定位具体问题。日志文件通常位于 LoggingData/Internal/LogsDirectory.swift 所指定的目录。在日志中查找与启动失败相关的错误信息，根据错误信息进行相应的处理。

二、SSH 连接失败如何解决？

SSH 连接是 Tartelet 与虚拟机器通信的重要方式，连接失败会影响虚拟机器的正常使用。以下是常见的解决方法。

2.1 检查 SSH 用户名和密码设置

SSH 连接需要正确的用户名和密码，若未设置或设置错误，会导致连接失败。在 Tartelet 的设置中，检查 SSH 用户名和密码是否正确。可通过 SettingsUI/Internal/GitHubSettings/GitHubSettingsView.swift 路径找到相关设置界面进行查看和修改。

2.2 确认虚拟机器 IP 地址获取正常

虚拟机器的 IP 地址是 SSH 连接的关键，若无法获取 IP 地址，连接将无法建立。Tartelet 通过 VirtualMachineDomain/SSH/VirtualMachineIPAddressReader.swift 来读取虚拟机器的 IP 地址。若获取 IP 地址失败，可尝试重启虚拟机器或检查网络设置。

2.3 检查网络连接和防火墙设置

网络连接不稳定或防火墙阻止了 SSH 连接，也会导致连接失败。确保主机和虚拟机器在同一网络中，且网络连接正常。检查防火墙设置，确保 SSH 端口（默认为 22）未被阻止。

三、GitHub 配置相关问题解决

正确配置 GitHub 相关信息是 Tartelet 正常运行 GitHub Actions 运行器的前提，若配置出现问题，需及时解决。

3.1 检查 GitHub 凭据是否有效

Tartelet 需要有效的 GitHub 凭据来注册和管理 GitHub Actions 运行器。在设置中检查 GitHub 凭据是否正确且有效，可通过 GitHubDomain/GitHubCredentialsStore.swift 相关代码查看凭据的存储和获取方式。若凭据无效，重新输入正确的凭据。

3.2 确认 GitHub 应用安装和权限

若使用 GitHub 应用来进行认证和授权，需确保应用已正确安装且具有足够的权限。检查 GitHub 应用的安装状态和权限设置，确保其能够正常获取访问令牌和注册运行器。

四、Tart Home 文件夹设置问题

Tart Home 文件夹是存放虚拟机器相关文件的重要目录，设置不当可能导致虚拟机器管理出现问题。

4.1 正确设置 Tart Home 文件夹路径

在 Tartelet 的设置中，可通过 SettingsUI/Internal/VirtualMachineSettings/TartHomeFolderPicker.swift 来选择和设置 Tart Home 文件夹路径。确保选择的路径存在且有足够的权限，若路径错误或无权限，可重新选择或修改文件夹权限。

4.2 重置 Tart Home 文件夹为默认值

若手动设置 Tart Home 文件夹后出现问题，可尝试将其重置为默认值。在设置界面中找到“重置为默认值”按钮，点击即可将 Tart Home 文件夹恢复为默认路径。

五、其他常见问题及解决办法

5.1 应用无法正常打开

若 Tartelet 应用无法正常打开，可能是应用文件损坏或与系统版本不兼容。尝试重新下载安装应用，确保下载的版本与 macOS 系统版本相匹配。

5.2 虚拟机器运行缓慢

虚拟机器运行缓慢可能是由于系统资源分配不足或虚拟机器配置不当。在 Tartelet 的设置中，适当调整虚拟机器的内存、CPU 等资源分配，以提高运行速度。

5.3 运行器无法注册到 GitHub

若运行器无法注册到 GitHub，检查网络连接、GitHub 凭据以及 GitHub 组织或仓库的设置，确保运行器的注册信息正确无误，且 GitHub 允许添加自托管运行器。

通过以上方法，大部分 Tartelet 的常见问题都能得到解决。若遇到其他未提及的问题，可查阅项目的官方文档或在相关社区寻求帮助。希望本文能帮助新手顺利使用 Tartelet，享受其带来的便捷 GitHub Actions 运行器管理体验！

【免费下载链接】tartelet⚙️💻 A macOS app that makes it a breeze to manage multiple GitHub Actions runners in ephemeral virtual machines on a single host machine. The benefits are that runners can run in parallel, and each job runs in an isolated environment.项目地址: https://gitcode.com/gh_mirrors/ta/tartelet