XHGit · 产品文档

常见问题与排错

定位登录、邮件、Git、合并请求、构建和页面显示问题。

01

阅读导览

出现问题时,先确定操作对象、登录身份和实际错误,再决定下一步。XHGit 的站点开关、仓库单元、成员权限与保护规则会共同影响结果。按本页记录最短复现过程,比反复刷新、重复注册或删除重建更容易找到原因。

02

先准备一份有效的问题记录

  1. 记录发生时间、页面地址、账号角色、操作步骤和预期结果。
  2. 保存完整错误文字与状态码,截图只保留相关区域。
  3. 说明是所有仓库都发生,还是某个仓库、某个浏览器或手机才发生。
  4. 隐去访问令牌、Cookie、短信验证码、真实密码和不应公开的个人信息,再交给维护者。

浏览器开发工具可能包含认证头,不能直接把整份网络请求导出到公开议题。管理员排查需要的是错误上下文,并不需要你的登录密码。

03

注册、激活和短信不正常

先查看页面要求的是手机、邮箱还是任选其一。验证码应在原浏览器会话内使用;发送有冷却和频率限制,旧验证码与旧激活链接可能已经失效。只打开最新邮件,并检查垃圾箱和收件规则。

如果页面提示确认密钥过期,但账号可能已激活,先尝试正常登录,再到账号设置检查状态。已注册账号需要添加联系方式时,应使用绑定入口,不能重新注册同名账号。短信入口缺失或服务未配置,需要管理员检查注册与短信设置,详见账号说明。

04

登录保持与第三方绑定失败

“记住此设备”依赖站点 Cookie。无痕窗口、清理浏览器数据、阻止 Cookie、在 HTTP/HTTPS 或不同域名间切换,都会影响保持状态。先统一使用站点正式地址,检查设备时间,再在普通窗口重试。

已有账号绑定 GitHub,应先登录 XHGit,再从“安全 → 关联账号”操作。redirect_uri 不属于应用的提示,通常是双方应用回调、站点 ROOT_URL 或代理协议不一致,需管理员核对完整回调;改变账号密码不能修正回调。具体见集成与授权。

05

邮件发送或测试失败

普通用户先确认邮箱已验证、通知订阅已开启,并检查垃圾邮件;没有相关事件就不会产生通知。仍未收到邮件时,请向站点支持提供发生时间和脱敏后的错误提示。

06

克隆或推送被拒绝

先运行 git remote -v 检查地址,确认自己能在浏览器读取该仓库。HTTPS 检查令牌类型和范围,SSH 检查公钥是否加到正确账号,以及复制地址中的端口。不要把 SSH 私钥或包含令牌的地址发给别人。

推送失败再检查仓库是否镜像、归档或受保护,目标分支是否有新提交,以及文件和 LFS 限制。non-fast-forward 需要先了解远程历史,不要用强推作为默认修复。具体操作见Git 指南。

07

看不到合并请求、看板或 Wiki

确认登录账号具有对应单元的读取权限,仓库管理员已启用功能。镜像、归档或空仓库不具备正常的合并请求条件;草稿 PR 也不能立即合并。标准 PR 地址使用 /pulls,不要把议题的 /issues 与它混为一谈。

功能入口跳到外部网站,说明仓库配置了外部议题或 Wiki。404 既可能是资源不存在,也可能是没有访问权限;不要凭这个状态就判断数据被删除。让仓库拥有者核对单元设置和团队授权,参见仓库管理。

08

构建排队、失败或没有安装包

排队先看是否有匹配 runs-on 标签、可用且未停用的 Runner。任务开始后失败,应查看日志中第一个真实错误:依赖安装、环境版本、权限与构建命令都有可能失败。

构建成功但没有文件时,检查上传产物步骤的路径与实际输出目录、保留期限和读取权限。Windows、Android、Linux 的项目需要各自工具链,工作流模板也需要适配项目。不要把源码 ZIP 当成安装包。见多平台自动打包和Runner 管理。

09

头像、手机排版和论坛状态异常

头像先确认账号是否上传了个人头像、提交邮箱是否关联,随后刷新缓存;未上传时使用站点默认头像。贡献者统计与账号资料不是同一份数据,历史作者无法匹配账号时可能显示默认图。

手机上正文越界时,记录具体页面与内容类型,区分代码块横向滚动和整个页面超宽。论坛刚投稿不可见时查看我的投稿:待 AI 或人工复核不会自动公开,模型异常也会保留人工复核状态。状态、权限与举报规则见论坛指南。

10

哪些问题交给谁处理

仓库拥有者负责协作者、功能开关与保护规则;组织拥有者负责团队分工;站点管理员负责登录源、短信、邮件、AI、SEO 和运行环境。普通用户不要通过删除仓库、关闭验证或公开密钥尝试绕过问题。维护者处理后,使用最初的复现步骤验证,再在原记录补充结果,便于其他用户查找。