第 19 章
故障排除
常见问题的解决方法，以及 Manta 将错误记录在哪里。如果你要报告错误，日志文件会很有帮助。
本页内容
日志文件¶
Manta 会将错误和重要事件写入：
~/Library/Logs/Manta/manta.log
查找方法：
- 在菜单栏中选择 帮助 → 在访达中显示日志文件，或者按 ⇧⌘P 打开命令面板，在其中选择 在访达中显示日志文件。
- 访达会打开日志文件夹（
~/Library/Logs/Manta）并显示文件manta.log。即使 Manta 是你的默认文件管理器，此操作也会在访达本身中打开。
Manta 向你显示的每条错误信息都会连同技术错误、路径和位置（本地、服务器等）记录在其中。文件达到 5 MB 时会轮换，并保留一份旧副本。
提示
要获得更详细的日志，请在终端中使用 MANTA_LOG=debug /Applications/Manta.app/Contents/MacOS/manta 启动 Manta。
说明
日志文件可能包含文件名和服务器名称。分享前请先检查。其中不包含密码、密码短语和私密密钥，SFTP、FTP 和 S3 的也不包含。
插件有自己的日志：设置 → 插件 → 插件卡片上的 显示日志。
报告错误¶
发现了错误？请在 GitHub 上报告。最简单的方法是 帮助 → 报告问题…（也可以在命令面板中输入“bug”或“错误”，或者在 设置 → 通用 → 关于 Manta → 反馈 中找到）。Manta 会在浏览器中打开错误报告表单，并预先填好 Manta 版本、macOS 版本和芯片（Apple 芯片或 Intel）。Manta 本身不会发送任何内容：你会看到表单，并自行决定提交什么。你需要一个免费的 GitHub 账户。
以下信息有助于找到错误：
- Manta 和 macOS 版本：Manta 会自动填入；也可以在 Manta → 关于 Manta 和苹果菜单 →“关于本机”中查看。
- 复现步骤：你依次做了什么？
- 预期行为和实际行为：本应发生什么，实际发生了什么？确切的错误信息很有帮助。
- 截图（⇧⌘4）或简短的屏幕录制（⇧⌘5）。
- 日志文件中的相关行：
~/Library/Logs/Manta/manta.log，可通过 帮助 → 在访达中显示日志文件 打开，参见日志文件。
重要
GitHub 上的错误报告是公开的。粘贴日志或截图之前，请删除或替换其中的私人数据：用户名和路径（例如 /Users/anna/…）、服务器名和主机名、IP 地址、存储桶名称。
注意
切勿在公开的 Issue 中报告安全漏洞。请按照安全政策中的说明，通过 GitHub 上的 Report a vulnerability 私下报告。
有想法或改进建议？帮助 → 提出建议… 会打开建议表单。所有入口也都在 github.com/web-workers-com/manta/issues/new/choose。
Manta 意外退出时¶
如果 Manta 崩溃，它会在 ~/Library/Logs/Manta 中保存一份崩溃报告——文件名以 crash- 开头，后跟日期和时间（UTC）。报告只包含查找错误所需的内容：Manta 和 macOS 的版本、芯片、错误信息，以及崩溃时的程序地址（“backtrace”）。你的个人文件夹显示为 ~，用户名、服务器名和主机名会被替换为 <user>、<redacted> 等占位符。
下次启动 Manta 时，右下角会显示一次提示：Manta 上次意外退出。
- 在 GitHub 上报告 会打开错误报告表单，并已填好版本信息和报告的简短摘要。请把报告文件附加到表单中（拖到文本框里）——链接无法携带文件。在你自己于 GitHub 上提交表单之前，不会发送任何内容。
- 显示报告 会在文本编辑器中打开报告，让你确切看到其中的内容。
- 忽略 会关闭提示。报告仍保留在文件夹中；Manta 保留最新的 10 份。
说明
Manta 从不自动发送崩溃报告，也不包含任何跟踪。如果你不想报告某次崩溃，忽略提示即可——或者删除 ~/Library/Logs/Manta 中的 crash-… 文件。
Manta 无法打开（Gatekeeper）¶
问题： 首次启动时，macOS 提示“未打开‘Manta’”（“Apple无法验证‘Manta’是否包含……恶意软件”），或在较早的 macOS 版本中提示“无法打开……，因为 Apple 无法检查其是否包含恶意软件”。
原因： Manta 未经 Apple 公证。macOS 会在首次启动时阻止此类 App。
解决方法：
- 在信息中点按 完成（不要点按 移到废纸篓）。
- 打开 系统设置 → 隐私与安全性，滚动到 安全性 部分。
- 在“已阻止‘Manta’……”旁点按 仍要打开，在 macOS 再次询问时再点按一次 仍要打开，然后使用密码或触控 ID 确认。
如果没有 仍要打开，请再次启动 Manta 并立即查看，此按钮只保留约一小时。所有步骤的图示以及通过终端的方法，请参阅首次启动：Gatekeeper。
macOS 15 之前：在 应用程序 文件夹中右键点按（或按住 Control 键点按）Manta → 打开 → 打开。
“macOS 阻止了访问”¶
问题： 某个文件夹无法打开，或者 Manta 提示“macOS 阻止了对‘……’的访问（不允许此操作）”。
原因： 你尚未允许 Manta 访问此文件夹（或误点了“不允许”），或者该文件夹需要完全磁盘访问权限。
解决方法：
- 打开 系统设置 → 隐私与安全性 → 文件和文件夹。
- 找到 Manta 并打开相应的文件夹（桌面、文稿、下载、可移除的宗卷、网络宗卷）。
- 对于
~/Library/Mail等文件夹：完全磁盘访问权限 → 打开 Manta。 - 退出 Manta 并重新启动。
如果列表中没有 Manta，说明 macOS 尚未询问过。在 Manta 中打开一次该文件夹，询问就会出现。
“你没有打开此文件夹的权限”则是另一回事：缺少的是常规的 Unix 权限。请联系该文件夹的所有者，或在访达中（显示简介）更改权限。
控制访达或终端的功能¶
问题： “在访达中显示”、“在 Terminal.app 中打开”或将重复项移到废纸篓不起作用。
解决方法： 系统设置 → 隐私与安全性 → 自动化 → 在 Manta 下打开 访达 和 终端。
FTP：文件夹无法载入，出现“TLS”错误¶
问题： 能够登录 FTPS 服务器，但文件夹一直为空或一直在载入，或者 Manta 提示“网络阻止了加密的 FTP 数据连接”。
原因： 一些公司网络和防火墙会重置加密的 FTP 数据连接。
解决方法：
- 右键点按该个人收藏 → 编辑连接…（或按 ⌘K 新建连接）。
- 将 数据通道 设为 自动。
- 重新连接。
此后 Manta 会以未加密方式传输列表和文件；登录仍保持加密。位置标签上的警告盾牌图标会提示这一点。
警告
对于机密数据，这不是一个好的解决方法。请改用 SFTP、其他网络或 VPN，并将数据通道设为 必需。
更多 FTP 提示：
- “无法建立安全连接”：服务器在此端口上不支持 FTPS（如果你的网络允许，可以尝试 FTP），或者其证书不受信任。
- Manta 不支持隐式 FTPS（端口 990）。
没有 Shell 的容器¶
问题： 容器以只读方式打开，或者 Manta 提示“容器没有 Shell”。
原因： Manta 需要容器中的 sh 来列出和更改文件。Distroless 和 scratch 映像没有 Shell。
解决方法：
- 读取和向外拷贝（F5、拖移）仍然可行，通过
docker cp完成。 - 要进行更改，你需要一个带有 Shell 的映像（例如该映像的调试版本）。
- Kubernetes Pod 即使只读取也需要
sh。 - 已停止的容器同样是只读的：启动它们后才能进行更改。
Docker 或 Kubernetes 未显示¶
- “Docker 未运行”：启动 Docker Desktop。
- “未安装 Docker”：安装 Docker Desktop，或确保
docker命令位于你的 PATH 中。Manta 还会在/opt/homebrew/bin、/usr/local/bin以及 Docker Desktop App 内部查找。 - “未安装 kubectl”：
brew install kubectl。 - “无法访问 Kubernetes 集群”：检查上下文和 VPN，或启动你的本地集群。
服务器连接¶
| 信息 | 解决方法 |
|---|---|
| “服务器的密钥已更改” | 密钥与 ~/.ssh/known_hosts 不匹配；Manta 不会连接（可能存在中间人攻击）。请向管理员索取指纹。如果服务器确实已重新安装，请使用对话框中的命令（ssh-keygen -R host）移除旧条目。 |
| “未知服务器” | 首次连接到此服务器。核对指纹后点按 连接并记住，请参阅连接。 |
| “在钥匙串中找不到已存储的密码” | 该项目已被删除，例如在“钥匙串访问”中。请输入密码，并保持 记住密码 处于打开状态。 |
| “ssh-agent 中没有可用的密钥” | ssh-add ~/.ssh/id_ed25519 |
| “你的 Mac 时钟不准确” | 系统设置 → 通用 → 日期与时间 → 自动设置。 |
| “该 Bucket 位于其他区域” | 在对话框中将区域设为提示中所指的区域。 |
| “与服务器的连接已断开” | 检查网络，然后点按 重试。 |
传输停滞不前¶
| 你看到的内容 | 解决方法 |
|---|---|
| “正在等待连接…（第 5 次尝试，16 秒后重试）” | 网络或服务器已断开。Manta 会不断尝试，并从中断处继续。请检查 Wi-Fi/VPN；立即重试 会立刻开始下一次尝试。 |
| 传输 顶部显示 无互联网连接 | 你的 Mac 处于离线状态。一旦恢复联网，传输会自动继续。 |
| “需要连接到……” | 重新启动后缺少服务器连接。点按 重新连接 并输入密码。 |
| “已暂停 · ……” | 你（或 全部暂停）暂停了该任务。点按 继续。 |
目标位置中有隐藏的 .NAME.manta-part 文件 | 这是中断任务的部分文件。如果还要继续该任务，请保留它们；否则可以删除。 |
请参阅暂停和继续传输。
更新失败¶
请参阅更新。通常是因为 Manta 不是从“应用程序”文件夹运行的。
云端：“移除下载”不起作用¶
对于 Google Drive、OneDrive、Dropbox 等，由服务提供商的 App 决定。请使用访达：右键点按 → 移除下载项。请参阅云存储。
文件夹显示的内容已过时¶
按 ⌘R。其他 App 或服务器所做的更改，Manta 只有在刷新后才能看到。
重置 Manta¶
作为最后的手段：
- 退出 Manta。
- 将
~/Library/Application Support/Manta重新命名（例如改为Manta old）。 - 启动 Manta。它会像首次启动一样运行。
你的个人收藏和快速操作仍保存在重新命名后的文件夹中。