QuickQ访问Git代码仓库时下载正常、推送失败怎么排查？

出现下载正常但推送失败时，应先确认本地 Git 状态、远程仓库地址与权限，再逐步排查凭证、网络、代理、防火墙以及服务端钩子或仓库限制，记录完整错误信息以便有针对性解决，必要时在服务端复现并联系仓库管理员获取日志支持。
<h2>quickq 下载正常但推送失败的快速排查思路</h2>

<h3>确认本地 Git 状态并重现问题</h3>
<ul>
  <li><strong>检查分支与提交一致性：</strong>在本地使用 git status 和 git log 确认当前分支是否干净且包含欲推送的提交，避免未合并或冲突的提交阻止推送操作，记录提交哈希便于比对。</li>
  <li><strong>尝试重复推送并保存输出：</strong>在终端执行 git push 并把完整输出重定向保存到文件，重复重现相同失败场景以便分析错误代码和提示文本，方便后续定位问题点。</li>
  <li><strong>切换到新分支进行推送测试：</strong>创建一个临时分支提交小改动并尝试推送，以判断问题是否与当前分支或提交内容相关，若临时分支可推送则说明问题局限于原分支或其引用历史。</li>
</ul>

<h3>查看推送时的错误信息并记录</h3>
<ul>
  <li><strong>捕获完整错误与代码说明：</strong>将 git push 的错误信息完整拷贝并对照 Git 文档或 quickq 的帮助文档，注意 HTTP 状态码或 SSH 错误提示，记录时间以便与服务端日志比对分析。</li>
  <li><strong>分析常见错误关键词：</strong>重点关注 authentication、permission、rejected、hook、timeout 等关键词，这些通常指示凭证、权限、钩子或网络问题，针对关键词拟定下一步排查清单。</li>
  <li><strong>在不同终端重复获取错误：</strong>尝试在另一台机器或使用不同网络环境执行同样的推送来判断问题是局部环境还是服务器侧导致，记录不同环境返回的错误差异。</li>
</ul>

<h2>quickq 本地环境配置检查步骤</h2>

<h3>检查 Git 配置和凭证缓存</h3>
<ul>
  <li><strong>核查全局与仓库配置：</strong>使用 git config --list --show-origin 检查 user.name、user.email、credential.helper 等设置，确认没有被错误配置导致凭证或用户名不匹配，必要时重设。</li>
  <li><strong>清理并重建凭证缓存：</strong>根据 credential.helper 的类型清理缓存或凭证管理器中的记录，重新输入凭证或生成新的访问令牌以排除过期或损坏的凭证问题影响推送。</li>
  <li><strong>使用 HTTPS/SSH 切换测试：</strong>将远程地址从 HTTPS 改为 SSH（或反之），尝试使用密钥或令牌进行推送，以判断问题是否由当前认证类型或凭证存储方式引起。</li>
</ul>

<h3>验证 SSH/HTTPS 配置并尝试手动连接</h3>
<ul>
  <li><strong>测试 SSH 连接有效性：</strong>执行 ssh -T git@your.quickq.host 或相应命令验证公钥是否被识别，若失败则检查本地密钥存在、权限设置以及 quickq 上的公钥是否正确绑定。</li>
  <li><strong>验证 HTTPS 证书与代理设置：</strong>在 HTTPS 情况下使用 curl 或 wget 访问仓库 API 接口以确认 SSL 证书和代理配置正常，排除中间代理篡改或证书链问题导致的连接失败。</li>
  <li><strong>检查本地 SSH Agent 与密钥权限：</strong>确保私钥文件权限为 600，SSH Agent 已加载私钥并且没有多个冲突密钥导致认证选择错误，重启 Agent 并重新加载密钥后再试推送。</li>
</ul>

<h2>quickq 远程仓库与权限检查方法</h2>

<h3>核对远程仓库地址和分支映射</h3>
<ul>
  <li><strong>确认 remote URL 与期望仓库一致：</strong>使用 git remote -v 检查 origin 地址是否指向正确的 quickq 仓库，确保没有误指向只读或不同权限的仓库导致推送被拒绝。</li>
  <li><strong>检查上游分支与推送目标：</strong>使用 git branch -vv 查看分支追踪信息，确认本地分支的上游分支与推送目标映射正确，避免推送到不存在或只读分支。</li>
  <li><strong>验证分支保护策略影响：</strong>在 quickq 管理界面查看目标分支是否启用了保护策略，例如强制 PR、必须通过 CI 或限制直接推送者列表，若启用需按策略流程进行合并。</li>
</ul>

<h3>检查账号权限与组织成员设置</h3>
<ul>
  <li><strong>核实仓库访问权限等级：</strong>在 quickq 中检查当前账号对目标仓库的权限（读/写/管理员），若权限不足请联系仓库管理员为账号赋予写入或更高权限再进行推送操作。</li>
  <li><strong>确认团队/组织权限继承关系：</strong>若通过团队或组织分配权限，检查账号是否被正确加入到具备推送权限的团队，并确认没有被拒绝继承或单独限制。</li>
  <li><strong>检查令牌或 SSH Key 与账号绑定：</strong>确认用于推送的访问令牌或 SSH Key 属于正确账号，避免使用被撤销或绑定到不同账号的凭证导致鉴权失败。</li>
</ul>

<h2>quickq 网络与代理相关故障排除</h2>

<h3>排查网络连通性并使用替代通道</h3>
<ul>
  <li><strong>测试基本网络连通性：</strong>通过 ping、traceroute 或 mtr 检查到 quickq 服务器的网络路径是否存在丢包或高延迟，若发现异常尝试更换网络或联系网络管理员排查。</li>
  <li><strong>使用 VPN 或不同网络重试：</strong>在公司网络或受限网络下可能存在策略阻断，尝试切换到家庭网络、手机热点或 VPN 通道进行推送测试以判断是否为网络限制问题。</li>
  <li><strong>检测端口与协议可达性：</strong>确认用于 Git 的端口（SSH 22 或 HTTPS 443）在本地网络和防火墙中未被封锁，必要时向网络方申请放行相关端口再进行推送。</li>
</ul>

<h3>检查本地代理与防火墙配置</h3>
<ul>
  <li><strong>验证系统和 Git 代理设置：</strong>检查环境变量 http_proxy、https_proxy 以及 git config 中的 proxy 配置，确保代理地址、认证信息正确且代理服务器可达且未拦截推送请求。</li>
  <li><strong>排查本地防火墙与安全软件拦截：</strong>临时关闭本地防火墙或安全软件（在安全允许情况下）进行推送测试，若推送成功则按规则添加信任或放行 quickq 地址。</li>
  <li><strong>确认中间设备无深度包检查干扰：</strong>一些企业级防火墙会对 SSH 或 HTTPS 进行深度包检测导致连接异常，必要时与安全或运维团队沟通以绕过或加入白名单。</li>
</ul>

<h2>quickq 服务端与钩子日志诊断流程</h2>

<h3>查看服务端日志与钩子脚本输出</h3>
<ul>
  <li><strong>请求 quickq 管理端提供服务器日志：</strong>联系仓库管理员或运维导出收到请求时间点的服务器端日志、Git 服务日志以及钩子执行输出，以便定位服务器侧是否拒绝或拦截了推送。</li>
  <li><strong>检查服务器端钩子（pre-receive/post-receive）：</strong>确认是否存在自定义钩子对提交或分支进行校验，钩子返回非零退出码会导致推送失败，查看钩子日志以确定失败原因并调整规则。</li>
  <li><strong>分析 CI 或审查流程阻断情况：</strong>若 quickq 配置了强制 CI 校验或代码审查流程，检查相应流水线或审查规则日志，按规则修复提交或通过审批后重试推送。</li>
</ul>

<h3>在服务端重现推送并记录失败条件</h3>
<ul>
  <li><strong>使用仓库管理员权限在服务端尝试推送：</strong>在保证安全的前提下，请管理员在服务器或具有完全权限的环境中执行相同的推送操作以判断是否为权限或网络中间件导致的异常。</li>
  <li><strong>对比成功与失败请求的差异：</strong>将成功的下载/拉取请求与失败的推送请求在服务端日志中逐项比对，检查请求头、认证标识、IP 来源及请求体差异以确认异常点。</li>
  <li><strong>模拟不同用户与凭证进行测试：</strong>在服务端或管理员环境中使用其他用户凭证或测试账号执行推送，以确认是否为单个账号受限或某些凭证被误列入黑名单。</li>
</ul>

<h2>常见问题解答（FAQ）</h2>

<h3>Q1: 下载正常但推送时提示 "permission denied" 应如何处理？</h3>
<p>A1: 首先确认使用的凭证或 SSH Key 是否归属当前账号，检查 quickq 上的访问权限和分支保护策略，必要时联系仓库管理员提升权限或替换正确凭证后重试。</p>

<h3>Q2: 推送过程中出现超时或网络断开，怎么排查？</h3>
<p>A2: 检查本地网络质量、路由器与防火墙设置，尝试切换网络或使用 VPN，再次执行 git push 并记录 traceroute/mtr 结果，若为服务器端问题联系运维查看接入层日志。</p>

<h3>Q3: 提示 pre-receive hook failed，如何定位问题？</h3>
<p>A3: 这是服务器端钩子脚本阻止了推送，需要管理员查看 pre-receive 钩子输出日志，确认校验规则或脚本错误并按需修改或放宽钩子规则以允许合法提交。</p>

<h3>Q4: 使用令牌登录成功但推送仍失败是什么原因？</h3>
<p>A4: 可能是令牌权限不足、范围未包含写权限或绑定到错误账号，检查 quickq 上令牌权限范围（repo 写权限）并确认令牌没有过期或被撤销，必要时重新生成并替换。</p>