使用场景
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}/releases | Release 分页 |
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 | 提交分页、单次提交及指定范围的差异 |
…/releases | Release 列表 |
…/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。