Tolaria Git 认证故障排查指南系统 Git CLI 认证模型、症状定位与完整修复方案【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文是 Tolaria基于 Tauri 的 Markdown 知识库桌面应用的 Git 认证故障排查实战指南。Tolaria 不内置任何提供商专用认证所有推送、拉取与克隆都委托给用户已有的系统 Git 配置SSH 密钥、Git Credential Manager、macOS Keychain、gh auth等。读完本文你将理解这一认证模型的来龙去脉掌握终端复现 → 定位环节 → 逐项修复的排查方法论并能读懂 Tolaria 内部对认证错误的分类逻辑直接对号入座解决问题。先理解 Tolaria 的认证模型为什么它不管理你的密码Tolaria 在 Git 认证上有一个明确的设计立场它不直接管理任何提供商的密码或令牌。官方故障排查文档的第一句话就点明了这一点Tolaria uses system Git authentication. It does not manage provider passwords directly.这背后是架构决策的主动选择而不是功能缺失。在 ADR-0056System git auth only — no provider-specific OAuth or repo APIs 中Tolaria 明确记录了这一决定应用的远程工作流commit、pull、push、status、history、冲突解决全部使用系统git可执行文件完成曾经实现的 GitHub Device Flow OAuthADR-0019已被 0056 取代被整体移除包括github_token/github_username设置项、GitHub 专属的仓库列表/创建 API、以及 Settings 面板中的 GitHub 连接区块克隆流程退化为通用的粘贴任意 Git URLclone_repo只是调用系统 git 做 clone不注入任何提供商令牌认证失败时应用直接把 git 的原始 stderr 分类后呈现给用户不再有第二套认证栈。ADR-0056 给出的理由很实际Tolaria 的远程同步用户大多是开发者他们通常已经用 SSH 密钥、Credential Manager、Keychain helper 或gh auth配好了 git。再维护一套提供商专属认证栈反而引入令牌存储、提供商锁定和双认证模型的复杂度。对使用者的含义任何能在你的终端里正常工作的 Git 认证方式GitHub、GitLab、Bitbucket、Gitea、自建 Git 服务都能在 Tolaria 里正常工作但前提是——认证必须在 Tolaria 之外、在你的系统 Git 环境里先配好。典型症状什么时候该怀疑是 Git 认证问题官方文档列出了三类最典型的症状值得逐一对照症状可能原因Push 失败远端认证失败、权限不足、或远端已有新提交rejectedPull 反复要求输入凭据终端被禁用、credential helper 未持久化、凭据已过期终端里 fetch 正常但 Tolaria 里不行应用环境与终端环境不一致如 WSL2 Git、不同凭据 helper、代理设置最后一条尤其容易让人误判为应用 bug。实际上 Tolaria 调用的就是同一个系统 git两者的差异通常来自环境例如 Tolaria 通过系统 Git Credential Manager 在 Windows 上工作而你的终端用的是 SSH 密钥或者 Tolaria 配置为 WSL2 Git provider见后文而你终端里跑的是原生 Windows Git。第一步在终端里复现先把范围缩小一半Tolaria 官方排查文档给出的检查步骤非常简单但极其有效——先在终端里验证系统 Git 本身是否畅通# 进入你的 vault 目录 cd /path/to/your/vault # 1. 查看当前配置的远程仓库 git remote -v # 2. 尝试拉取远端 git fetch如果git fetch在终端里就失败了那么问题一定出在系统 Git 的认证配置上与 Tolaria 无关应该先修复系统 Git 认证。只有终端 fetch 成功而 Tolaria 仍失败时才需要检查应用侧的因素Git provider 设置、凭据 helper 是否被应用环境绕过等。这一原则也体现在 连接远程仓库指南 的前置条件里确保远程仓库已存在并且你的系统 Git 能够对它完成认证。Tolaria 使用系统 Git而不是存储提供商专属凭据。第二步读懂 Tolaria 的错误分类对号入座Tolaria 不会把 git 的原始错误一股脑抛给你而是在 Rust 后端对 stderr 做了分类。理解这些分类能帮你快速定位问题环节。Push 错误分类classify_push_error在 src-tauri/src/git/remote.rs 中push 失败被归类为五种状态状态判定关键字stderr 中命中即触发提示文案rejectednon-fast-forward、[rejected]、fetch first或failed to push some refsupdates were rejectedPush rejected: remote has new commits. Pull first, then push.auth_errorauthentication failed、could not read username、permission denied、403、invalid credentialsPush failed: authentication error. Check your credentials.network_errorcould not resolve host、unable to access、connection refused、network is unreachable、timed outPush failed: network error. Check your connection and try again.no_remoteno configured push destination、does not appear to be a git repository、no such remote、no upstream branchNo remote configurederror其他所有情况提取 stderr 中首个hint:行或首行原始信息也就是说当你看到auth_error时问题 100% 出在认证环节——凭据缺失、过期、权限不足或 URL 指向了你不拥有/不存在的仓库permission denied与403都会被归到这一类。注意rejected不是认证问题它提示远端有新提交正确的处理是先 pull 再 push详见 同步冲突排查。连接远程时的错误分类classify_connect_error在 src-tauri/src/git/connect.rs 中连接远程git_add_remote的失败同样被分类。认证类错误auth_error的判定关键字包括authentication failed、could not read username、permission denied、the requested url returned error: 403、invalid credentials、repository not found。网络类错误network_error则包括could not resolve host、unable to access、connection refused、network is unreachable、timed out、couldnt connect。这里有一个对排查很有用的细节repository not found被归为认证错误。因为对大多数 Git 托管服务来说探测不存在的仓库与认证失败返回的信息是等价的——这可以防止攻击者通过错误信息枚举仓库是否存在。如果你看到这条提示请检查远程 URL 是否拼写正确、仓库是否真的存在、以及你的账号是否有访问权限。macOS 上的特殊行为Keychain 凭据预填充src-tauri/src/git/credentials.rs 展示了 Tolaria 在 macOS 上与系统认证协作的具体方式连接 HTTPS 远程时它会以GIT_TERMINAL_PROMPT0运行git credential fill从 remote URL 解析出protocol、host、username、path喂给 git 的凭据子系统从而触发 Keychain helper 完成免交互取凭据。这意味着在 macOS 上只要你的钥匙串里存有该主机的 HTTPS 凭据或配置了 SSHTolaria 就能直接复用这正是系统认证模型的落地体现。第三步四种常见修复方案详解官方文档列出了四类最常见的修复方向GitHub CLI 登录、SSH 密钥、更新远程 URL、检查 credential helper。下面逐一展开并补充 Windows/WSL 场景。方案 1用 GitHub CLI 登录gh auth login如果你使用 GitHub 且本机装有 GitHub CLI这是最省事的方案gh auth login按提示选择协议推荐 HTTPS、完成浏览器授权。gh auth login会同时配置 git 的 credential helpergh auth setup-git可手动补齐之后 Tolaria 里的 push/pull 会直接复用这份凭据。验证方法gh auth status git credential fill $protocolhttps\nhostgithub.com\n # 应能返回 username 与 password这与 Tolaria 曾经的 Device Flow OAuthADR-0019形成了鲜明对比过去凭据由应用自己存储和管理现在则完全由 GitHub CLI / 系统 git 负责Tolaria 不再接触令牌。方案 2配置 SSH 密钥SSH 是官方推荐的首选认证方式因为它天然免交互、不依赖 credential helper# 1. 生成密钥如尚未生成 ssh-keygen -t ed25519 -C youexample.com # 2. 将公钥添加到你的 Git 托管服务账户GitHub/GitLab/Gitea 等 # 3. 验证连通性 ssh -T gitgithub.com # 应看到欢迎信息使用 SSH 时远程 URL 形如gitgithub.com:user/repo.git。Tolaria 的连接对话框占位符AddRemoteModal.tsx同时接受githost:owner/repo.git与https://host/owner/repo.git两种形式SSH、Git Credential Manager 和任何系统 git 认证方式都能正常工作。方案 3更新远程 URLHTTPS ↔ SSH 互转如果当前 remote 是 HTTPS 但认证总失败可以切换到 SSH反之亦然# 查看当前 URL git remote -v # 切到 SSH git remote set-url origin gitgithub.com:user/repo.git # 切回 HTTPS使用 gh 或 credential helper 时 git remote set-url origin https://github.com/user/repo.git # 改完再验证 git fetch改完之后可以在 Tolaria 的状态栏远程指示器或命令面板Add Remote中重新连接应用会重新走一遍 fetch 与历史校验流程。方案 4检查 credential helperHTTPS 远程的认证持久化依赖 git 的 credential helper 配置# 查看全局与仓库级配置 git config --get credential.helper git config --global --get credential.helper常见取值包括helper适用平台说明manager/manager-coreWindowsGit Credential ManagerTolaria 官方推荐的方式之一osxkeychainmacOS复用 KeychainTolaria 会通过git credential fill触发见上文 credentials.rsgh auth git-credential-github跨平台GitHub CLI 安装的 helperstore/cache通用明文存储 / 内存缓存安全性较低如果credential.helper为空HTTPS push/pull 会反复要求输入用户名密码对应症状表中的第二条。配置后建议用git credential fill验证凭据可取出再回到 Tolaria 重试。方案 5Windows 专用确认 Git provider 设置最后一条终端可以但 Tolaria 不行的症状在 Windows 上有一个常见且明确的原因Tolaria 的 Git provider 设置与终端不一致。根据 ADR-0152WSL2 Git providerTolaria 在 Windows 上把 Git 视为每个 vault 的能力并引入了显式的 Git provider 设置原生 Git 是默认 providerWSL2 Git 是可选 provider。如果你把 vault 和凭据都放在 WSL2 里就需要在 Settings 的 Git 区块中显式选择 WSL2 分发版应用会自动探测可用的 WSL 分发但不会自动切换应用会把仓库路径转换为 Linux 风格路径后通过wsl.exe --distribution name --exec git执行命令。反之如果你的终端用的是原生 Windows Git 而 Tolaria 被配置成了 WSL2 Git也会出现终端正常、应用失败的割裂现象。Tolaria 还提供了两个探测命令src-tauri/src/commands/git.rs帮助诊断这类问题git_provider_status和test_git_provider两者都有 12 秒超时GIT_PROVIDER_PROBE_TIMEOUT_SECONDS即使 WSL 分发不可用也不会卡死界面。Settings 中的 Git 区块会在保存前展示 provider、WSL 分发和测试结果。在 Tolaria 中安全地重连远程修复系统认证后如果 vault 的 remote 本身也有问题可以在 Tolaria 里重新连接。官方 连接远程仓库指南 给出的流程是打开底部状态栏的远程指示器或从命令面板运行Add Remote粘贴远程 URLAddRemoteModal.tsx 支持 SSH 与 HTTPS 两种格式确认远程名称默认origin按应用提示执行 fetch 或 push。连接不是无脑git remote add。从 connect.rs 的实现看Tolaria 会在连接前做一整套安全校验若 vault 已有 remote直接返回already_configured避免覆盖添加 remote 后执行git fetch origin --prune检查远端分支若远端已存在分支但与当前分支名不匹配、或历史无共同祖先merge-base失败、或远端有本地没有的提交git rev-list --left-right --count计算 behind会返回incompatible_history并自动回滚刚添加的 remotedisconnect_all_remotes只有远端为空或与本地历史兼容时才执行git push -u origin branch建立跟踪。因此请使用空仓库或由本 vault 导出的仓库来连接——这条在 AddRemoteModal.tsx 的提示文案中也有体现。任何认证失败都会以auth_error状态返回提示你检查凭据。补充没有 remote 时认证问题其实与你无关如果你的 vault 根本没有配置 remoteTolaria 的 push/pull 不会报认证错误。从 remote.rs 的代码可以看到git_pull和git_push在检测到没有已配置的 remote 时会直接返回no_remote状态与 No remote configured 消息而git_remote_status会返回空的 branch 与has_remote: false。这由 commands/git.rs 中的 Tauri 命令层在调用后端前先行判定。此时你依然可以享受本地 Git 的全部价值提交、历史、diff、回滚。手动/自动 Git 提交指南 指出没有 remote 时手动提交仍能提供本地历史、差异对比和回滚能力你还可以开启 AutoGit让 Tolaria 在编辑停顿或应用失活后自动创建保守的检查点提交。排查流程图与速查表Push/Pull 失败 │ ├─ 在终端进入 vault 执行 git fetch │ ├─ 终端失败 → 修复系统 Git 认证与 Tolaria 无关 │ ├─ HTTPSgh auth login / 配置 credential.helper / 检查 Keychain、GCM │ ├─ SSHssh-keygen → 添加公钥 → ssh -T githost 验证 │ └─ 仍未解决 → git remote set-url 切换协议 │ └─ 终端正常但 Tolaria 失败 ├─ Windows检查 Settings → Git provider原生 vs WSL2是否与终端一致 ├─ macOS确认 Keychain 中凭据可用git credential fill 验证 └─ 仍失败 → 检查是否 remote URL 与终端配置不同最后回到 Tolaria 的错误提示本身auth_error→ 认证环节凭据、权限、URL 拼写、仓库存在性network_error→ 网络环节DNS、连通性、代理rejected→ 先 pull 再 pushno_remote→ 去状态栏或命令面板添加远程。掌握了这套对应关系绝大多数 Git 认证问题都能在几分钟内解决。延伸阅读Git 认证排查官方文档本文主体来源连接 Git 远程仓库指南手动与 AutoGit 提交指南ADR-0056仅系统 Git CLI 认证 与 被取代的 ADR-0019GitHub Device FlowADR-0152WSL2 Git provider同步冲突排查【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tolaria Git 认证故障排查指南：系统 Git CLI 认证模型、症状定位与完整修复方案
Tolaria Git 认证故障排查指南系统 Git CLI 认证模型、症状定位与完整修复方案【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文是 Tolaria基于 Tauri 的 Markdown 知识库桌面应用的 Git 认证故障排查实战指南。Tolaria 不内置任何提供商专用认证所有推送、拉取与克隆都委托给用户已有的系统 Git 配置SSH 密钥、Git Credential Manager、macOS Keychain、gh auth等。读完本文你将理解这一认证模型的来龙去脉掌握终端复现 → 定位环节 → 逐项修复的排查方法论并能读懂 Tolaria 内部对认证错误的分类逻辑直接对号入座解决问题。先理解 Tolaria 的认证模型为什么它不管理你的密码Tolaria 在 Git 认证上有一个明确的设计立场它不直接管理任何提供商的密码或令牌。官方故障排查文档的第一句话就点明了这一点Tolaria uses system Git authentication. It does not manage provider passwords directly.这背后是架构决策的主动选择而不是功能缺失。在 ADR-0056System git auth only — no provider-specific OAuth or repo APIs 中Tolaria 明确记录了这一决定应用的远程工作流commit、pull、push、status、history、冲突解决全部使用系统git可执行文件完成曾经实现的 GitHub Device Flow OAuthADR-0019已被 0056 取代被整体移除包括github_token/github_username设置项、GitHub 专属的仓库列表/创建 API、以及 Settings 面板中的 GitHub 连接区块克隆流程退化为通用的粘贴任意 Git URLclone_repo只是调用系统 git 做 clone不注入任何提供商令牌认证失败时应用直接把 git 的原始 stderr 分类后呈现给用户不再有第二套认证栈。ADR-0056 给出的理由很实际Tolaria 的远程同步用户大多是开发者他们通常已经用 SSH 密钥、Credential Manager、Keychain helper 或gh auth配好了 git。再维护一套提供商专属认证栈反而引入令牌存储、提供商锁定和双认证模型的复杂度。对使用者的含义任何能在你的终端里正常工作的 Git 认证方式GitHub、GitLab、Bitbucket、Gitea、自建 Git 服务都能在 Tolaria 里正常工作但前提是——认证必须在 Tolaria 之外、在你的系统 Git 环境里先配好。典型症状什么时候该怀疑是 Git 认证问题官方文档列出了三类最典型的症状值得逐一对照症状可能原因Push 失败远端认证失败、权限不足、或远端已有新提交rejectedPull 反复要求输入凭据终端被禁用、credential helper 未持久化、凭据已过期终端里 fetch 正常但 Tolaria 里不行应用环境与终端环境不一致如 WSL2 Git、不同凭据 helper、代理设置最后一条尤其容易让人误判为应用 bug。实际上 Tolaria 调用的就是同一个系统 git两者的差异通常来自环境例如 Tolaria 通过系统 Git Credential Manager 在 Windows 上工作而你的终端用的是 SSH 密钥或者 Tolaria 配置为 WSL2 Git provider见后文而你终端里跑的是原生 Windows Git。第一步在终端里复现先把范围缩小一半Tolaria 官方排查文档给出的检查步骤非常简单但极其有效——先在终端里验证系统 Git 本身是否畅通# 进入你的 vault 目录 cd /path/to/your/vault # 1. 查看当前配置的远程仓库 git remote -v # 2. 尝试拉取远端 git fetch如果git fetch在终端里就失败了那么问题一定出在系统 Git 的认证配置上与 Tolaria 无关应该先修复系统 Git 认证。只有终端 fetch 成功而 Tolaria 仍失败时才需要检查应用侧的因素Git provider 设置、凭据 helper 是否被应用环境绕过等。这一原则也体现在 连接远程仓库指南 的前置条件里确保远程仓库已存在并且你的系统 Git 能够对它完成认证。Tolaria 使用系统 Git而不是存储提供商专属凭据。第二步读懂 Tolaria 的错误分类对号入座Tolaria 不会把 git 的原始错误一股脑抛给你而是在 Rust 后端对 stderr 做了分类。理解这些分类能帮你快速定位问题环节。Push 错误分类classify_push_error在 src-tauri/src/git/remote.rs 中push 失败被归类为五种状态状态判定关键字stderr 中命中即触发提示文案rejectednon-fast-forward、[rejected]、fetch first或failed to push some refsupdates were rejectedPush rejected: remote has new commits. Pull first, then push.auth_errorauthentication failed、could not read username、permission denied、403、invalid credentialsPush failed: authentication error. Check your credentials.network_errorcould not resolve host、unable to access、connection refused、network is unreachable、timed outPush failed: network error. Check your connection and try again.no_remoteno configured push destination、does not appear to be a git repository、no such remote、no upstream branchNo remote configurederror其他所有情况提取 stderr 中首个hint:行或首行原始信息也就是说当你看到auth_error时问题 100% 出在认证环节——凭据缺失、过期、权限不足或 URL 指向了你不拥有/不存在的仓库permission denied与403都会被归到这一类。注意rejected不是认证问题它提示远端有新提交正确的处理是先 pull 再 push详见 同步冲突排查。连接远程时的错误分类classify_connect_error在 src-tauri/src/git/connect.rs 中连接远程git_add_remote的失败同样被分类。认证类错误auth_error的判定关键字包括authentication failed、could not read username、permission denied、the requested url returned error: 403、invalid credentials、repository not found。网络类错误network_error则包括could not resolve host、unable to access、connection refused、network is unreachable、timed out、couldnt connect。这里有一个对排查很有用的细节repository not found被归为认证错误。因为对大多数 Git 托管服务来说探测不存在的仓库与认证失败返回的信息是等价的——这可以防止攻击者通过错误信息枚举仓库是否存在。如果你看到这条提示请检查远程 URL 是否拼写正确、仓库是否真的存在、以及你的账号是否有访问权限。macOS 上的特殊行为Keychain 凭据预填充src-tauri/src/git/credentials.rs 展示了 Tolaria 在 macOS 上与系统认证协作的具体方式连接 HTTPS 远程时它会以GIT_TERMINAL_PROMPT0运行git credential fill从 remote URL 解析出protocol、host、username、path喂给 git 的凭据子系统从而触发 Keychain helper 完成免交互取凭据。这意味着在 macOS 上只要你的钥匙串里存有该主机的 HTTPS 凭据或配置了 SSHTolaria 就能直接复用这正是系统认证模型的落地体现。第三步四种常见修复方案详解官方文档列出了四类最常见的修复方向GitHub CLI 登录、SSH 密钥、更新远程 URL、检查 credential helper。下面逐一展开并补充 Windows/WSL 场景。方案 1用 GitHub CLI 登录gh auth login如果你使用 GitHub 且本机装有 GitHub CLI这是最省事的方案gh auth login按提示选择协议推荐 HTTPS、完成浏览器授权。gh auth login会同时配置 git 的 credential helpergh auth setup-git可手动补齐之后 Tolaria 里的 push/pull 会直接复用这份凭据。验证方法gh auth status git credential fill $protocolhttps\nhostgithub.com\n # 应能返回 username 与 password这与 Tolaria 曾经的 Device Flow OAuthADR-0019形成了鲜明对比过去凭据由应用自己存储和管理现在则完全由 GitHub CLI / 系统 git 负责Tolaria 不再接触令牌。方案 2配置 SSH 密钥SSH 是官方推荐的首选认证方式因为它天然免交互、不依赖 credential helper# 1. 生成密钥如尚未生成 ssh-keygen -t ed25519 -C youexample.com # 2. 将公钥添加到你的 Git 托管服务账户GitHub/GitLab/Gitea 等 # 3. 验证连通性 ssh -T gitgithub.com # 应看到欢迎信息使用 SSH 时远程 URL 形如gitgithub.com:user/repo.git。Tolaria 的连接对话框占位符AddRemoteModal.tsx同时接受githost:owner/repo.git与https://host/owner/repo.git两种形式SSH、Git Credential Manager 和任何系统 git 认证方式都能正常工作。方案 3更新远程 URLHTTPS ↔ SSH 互转如果当前 remote 是 HTTPS 但认证总失败可以切换到 SSH反之亦然# 查看当前 URL git remote -v # 切到 SSH git remote set-url origin gitgithub.com:user/repo.git # 切回 HTTPS使用 gh 或 credential helper 时 git remote set-url origin https://github.com/user/repo.git # 改完再验证 git fetch改完之后可以在 Tolaria 的状态栏远程指示器或命令面板Add Remote中重新连接应用会重新走一遍 fetch 与历史校验流程。方案 4检查 credential helperHTTPS 远程的认证持久化依赖 git 的 credential helper 配置# 查看全局与仓库级配置 git config --get credential.helper git config --global --get credential.helper常见取值包括helper适用平台说明manager/manager-coreWindowsGit Credential ManagerTolaria 官方推荐的方式之一osxkeychainmacOS复用 KeychainTolaria 会通过git credential fill触发见上文 credentials.rsgh auth git-credential-github跨平台GitHub CLI 安装的 helperstore/cache通用明文存储 / 内存缓存安全性较低如果credential.helper为空HTTPS push/pull 会反复要求输入用户名密码对应症状表中的第二条。配置后建议用git credential fill验证凭据可取出再回到 Tolaria 重试。方案 5Windows 专用确认 Git provider 设置最后一条终端可以但 Tolaria 不行的症状在 Windows 上有一个常见且明确的原因Tolaria 的 Git provider 设置与终端不一致。根据 ADR-0152WSL2 Git providerTolaria 在 Windows 上把 Git 视为每个 vault 的能力并引入了显式的 Git provider 设置原生 Git 是默认 providerWSL2 Git 是可选 provider。如果你把 vault 和凭据都放在 WSL2 里就需要在 Settings 的 Git 区块中显式选择 WSL2 分发版应用会自动探测可用的 WSL 分发但不会自动切换应用会把仓库路径转换为 Linux 风格路径后通过wsl.exe --distribution name --exec git执行命令。反之如果你的终端用的是原生 Windows Git 而 Tolaria 被配置成了 WSL2 Git也会出现终端正常、应用失败的割裂现象。Tolaria 还提供了两个探测命令src-tauri/src/commands/git.rs帮助诊断这类问题git_provider_status和test_git_provider两者都有 12 秒超时GIT_PROVIDER_PROBE_TIMEOUT_SECONDS即使 WSL 分发不可用也不会卡死界面。Settings 中的 Git 区块会在保存前展示 provider、WSL 分发和测试结果。在 Tolaria 中安全地重连远程修复系统认证后如果 vault 的 remote 本身也有问题可以在 Tolaria 里重新连接。官方 连接远程仓库指南 给出的流程是打开底部状态栏的远程指示器或从命令面板运行Add Remote粘贴远程 URLAddRemoteModal.tsx 支持 SSH 与 HTTPS 两种格式确认远程名称默认origin按应用提示执行 fetch 或 push。连接不是无脑git remote add。从 connect.rs 的实现看Tolaria 会在连接前做一整套安全校验若 vault 已有 remote直接返回already_configured避免覆盖添加 remote 后执行git fetch origin --prune检查远端分支若远端已存在分支但与当前分支名不匹配、或历史无共同祖先merge-base失败、或远端有本地没有的提交git rev-list --left-right --count计算 behind会返回incompatible_history并自动回滚刚添加的 remotedisconnect_all_remotes只有远端为空或与本地历史兼容时才执行git push -u origin branch建立跟踪。因此请使用空仓库或由本 vault 导出的仓库来连接——这条在 AddRemoteModal.tsx 的提示文案中也有体现。任何认证失败都会以auth_error状态返回提示你检查凭据。补充没有 remote 时认证问题其实与你无关如果你的 vault 根本没有配置 remoteTolaria 的 push/pull 不会报认证错误。从 remote.rs 的代码可以看到git_pull和git_push在检测到没有已配置的 remote 时会直接返回no_remote状态与 No remote configured 消息而git_remote_status会返回空的 branch 与has_remote: false。这由 commands/git.rs 中的 Tauri 命令层在调用后端前先行判定。此时你依然可以享受本地 Git 的全部价值提交、历史、diff、回滚。手动/自动 Git 提交指南 指出没有 remote 时手动提交仍能提供本地历史、差异对比和回滚能力你还可以开启 AutoGit让 Tolaria 在编辑停顿或应用失活后自动创建保守的检查点提交。排查流程图与速查表Push/Pull 失败 │ ├─ 在终端进入 vault 执行 git fetch │ ├─ 终端失败 → 修复系统 Git 认证与 Tolaria 无关 │ ├─ HTTPSgh auth login / 配置 credential.helper / 检查 Keychain、GCM │ ├─ SSHssh-keygen → 添加公钥 → ssh -T githost 验证 │ └─ 仍未解决 → git remote set-url 切换协议 │ └─ 终端正常但 Tolaria 失败 ├─ Windows检查 Settings → Git provider原生 vs WSL2是否与终端一致 ├─ macOS确认 Keychain 中凭据可用git credential fill 验证 └─ 仍失败 → 检查是否 remote URL 与终端配置不同最后回到 Tolaria 的错误提示本身auth_error→ 认证环节凭据、权限、URL 拼写、仓库存在性network_error→ 网络环节DNS、连通性、代理rejected→ 先 pull 再 pushno_remote→ 去状态栏或命令面板添加远程。掌握了这套对应关系绝大多数 Git 认证问题都能在几分钟内解决。延伸阅读Git 认证排查官方文档本文主体来源连接 Git 远程仓库指南手动与 AutoGit 提交指南ADR-0056仅系统 Git CLI 认证 与 被取代的 ADR-0019GitHub Device FlowADR-0152WSL2 Git provider同步冲突排查【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
