使用场景

Repo 的目标,是让自己的代码项目也能像文章一样在微光集里阅读。整体介绍见 关于本站:微光集。

最直接的做法当然是跳到 GitHub,但我希望在本站就能看 README、查文件、看提交和版本,同时参与标签、搜索和星轨图。

这里选择 GitHub 作为上游,Gitea 保存单向 Git 镜像,微光集读取镜像并提供页面。

实现内容

  • Repo 首页与语言分类、排序和分页。
  • 分支、标签、目录和源码浏览。
  • 文件名查找、代码搜索、提交记录、差异查看。
  • README、Markdown 与 Mermaid 渲染。
  • Release 列表、源码归档和文件下载。
  • 仓库项目进入全站内容索引,并复用 Artalk 评论。

项目内部文件树只在仓库页面里展开,全站导航到仓库这一层为止。

对接入口与数据来源

公开页面使用 /Repo/{仓库名},分支、路径、提交等状态放进页面参数中。

GitHub 公开仓库
    ↓ 仓库发现与单向镜像
Gitea + 本地裸 Git 仓库 + repositories.json
    ↓ Go 仓库适配器
/api/repo/…
    ↓
Repo 页面、全站搜索、标签和星轨图
内容当前读取位置
仓库公开状态、是否为镜像Gitea API
仓库描述、GitHub 星标、Topics 等元信息镜像发现服务生成的快照
分支、文件、提交、差异、归档只读挂载的本地 Git 仓库
默认分支语言占比Gitea /languages
Release 资料、附件原始下载地址GitHub API
用户资料与公开代码活动GitHub API,经过本站缓存和整理

GitHub → Gitea 的同步

独立的 github-sync 服务发现公开仓库,创建 Gitea 的 pull mirror。后续 Git 拉取由 Gitea 完成,镜像包含分支、标签和提交历史,不建立双向编辑关系。

发现服务会先读完 GitHub 分页,再处理仓库。已有普通仓库、镜像来源不一致的仓库不会被直接覆盖;上游请求失败时保留此前可用的快照,失败不能标记成同步成功。

创建或检查镜像时,还会比较默认分支的实际 SHA。发现两端不一致,就请求 mirror-sync,并等待提交真正一致,不能只看仓库的更新时间判断是否同步完毕。

本站原有用户活动刷新还会检查公开代码事件。发现新代码变化后,通过共享目录里的 Unix socket 请求同步,再刷新本站仓库索引。这个入口不对外监听 TCP,也没有为了检测同一件事再加一个频繁轮询任务。

周期发现仍然作为兜底。GitHub 活动接口可能有延迟,也不能完整代替仓库状态校验。

两种 Token

配置入口在 星枢 → 服务 中对应的 GitHub、Gitea 项目。

凭据用途
GitHub Token访问 GitHub API,获取仓库、活动、Release 等数据
Gitea Token在 Gitea 中查询管理身份、创建镜像、修改镜像和触发拉取

它们不是同一个 Token,也不能混用。微光集读取公开 Gitea 仓库的部分 API 可以匿名访问,不能因此把镜像管理令牌也当成不需要。

凭据的主记录保存在 MySQL 的 provider_credentials 中,使用独立密钥加密。镜像发现服务是另一个进程,所以本站会把需要的 Token 投影为权限受限的文件,供它按轮读取。

星枢保存凭据 → 加密数据库记录 → 原子写入受限文件 → 镜像服务读取

数据库是配置来源,文件是交给外部任务使用的输出。 不是要求手动维护两份 Token。投影使用临时文件后原子替换,权限为 0600;清空配置时也处理对应投影。GitHub Token 不放进 Git 远程地址。

使用的 API 与 Git 命令

上游接口调用方与用途
GitHub GET /users/{owner}/repos镜像服务发现公开仓库
GitHub GET /repos/{owner}/{repo}/git/ref/heads/{branch}比较上游默认分支 SHA
GitHub GET /users/{owner}/events/public本站检查公开代码活动
GitHub GET /repos/{owner}/{repo}/releasesRelease 分页
Gitea GET /api/v1/user管理 Token 验证与目标用户确认
Gitea GET /api/v1/users/{owner}/repos本站核对公开镜像范围
Gitea POST /api/v1/repos/migrate创建单向镜像
Gitea GET、PATCH /api/v1/repos/{owner}/{repo}查询和维护镜像信息
Gitea GET /api/v1/repos/{owner}/{repo}/branches/{branch}确认镜像中的提交 SHA
Gitea POST /api/v1/repos/{owner}/{repo}/mirror-sync请求镜像立即拉取
Gitea GET /api/v1/repos/{owner}/{repo}/languages代码语言字节占比

本站浏览入口统一经过 GET /api/repo/…:

路径用途
/api/repo/catalog仓库目录、资料和分类依据
/api/repo/{name}/info分支、标签、默认分支及当前 SHA
…/tree、…/browse、…/file、…/readme目录、文件和 README
…/files、…/search文件列表和代码搜索
…/commits、…/diff提交分页、单次提交及指定范围的差异
…/releasesRelease 列表
…/raw、…/archive文件与源码归档下载

请求中的 ref 指定分支、标签或提交,path 指定仓库内路径;差异接口还支持 base、head,分页使用 page。内部使用 git ls-tree、cat-file、grep、日志和差异命令读取已经存在的 Git 对象,不会为了每次打开页面重新 clone。

页面改造与权限边界

Go 先把分支或标签解析成提交 SHA,再读取相应路径。路径要限制在仓库内,不能把前端传来的任意路径直接交给文件系统。

目录同时核对本地快照和 Gitea 当前的公开镜像状态:只有已经就绪、仍在公开范围里的项目,才会提供浏览。仓库文件挂载是只读的,页面阅读不会反向改写镜像。

README 使用本站的 Markdown 展示方式,Mermaid 复用已有组件并随主题重新渲染。仓库标题、标签和 README 里的站内项目链接,也会进入统一的内容关联逻辑。

评论以仓库项目为单位,切分支、打开文件不会换一套评论。管理员可以在右键菜单中切换普通用户评论权限,具体实现见 Artalk评论系统对接。

缓存、失败与当前限制

目录有短缓存,按提交 SHA 读取的目录结果可以使用更长缓存;语言统计和 Release 也各有独立缓存。GitHub 临时失败时,Release 链路允许使用已有缓存并标记过期数据。

排查“页面还是旧代码”,应依次检查上游 SHA、Gitea 实际 SHA、本地镜像和本站目录索引,而不是只刷新浏览器。

主要实现分为三处:独立 github-sync、本站后端 internal/repo,以及前端 repo*.ts。凭据投影在 internal/application/credentials.go。


星轨图