|
@@ -1,415 +0,0 @@
|
|
|
-# Gitr 重写计划
|
|
|
|
|
-
|
|
|
|
|
-## 目标
|
|
|
|
|
-
|
|
|
|
|
-这个项目是对 Gogs 核心后端的 Rust 重写，当前约束有三个：
|
|
|
|
|
-
|
|
|
|
|
-- 尽量按 Gogs 原有模块边界重写，而不是只做概念相似
|
|
|
|
|
-- 尽量保持运行时和部署成本轻量
|
|
|
|
|
-- 尽量用确定性的端到端测试验证行为正确
|
|
|
|
|
-
|
|
|
|
|
-当前技术选型：
|
|
|
|
|
-
|
|
|
|
|
-- HTTP: `actix-web`
|
|
|
|
|
-- 数据库: `SQLite` + `rusqlite`
|
|
|
|
|
-- Git 交互: 外部 `git` 二进制
|
|
|
|
|
-
|
|
|
|
|
-当前不包含：
|
|
|
|
|
-
|
|
|
|
|
-- `frontend`
|
|
|
|
|
-- HTML 模板与浏览器页面
|
|
|
|
|
-- session/cookie 登录流
|
|
|
|
|
-
|
|
|
|
|
-## 当前定位
|
|
|
|
|
-
|
|
|
|
|
-当前代码已经不是“脚手架阶段”，而是已经完成了第一批核心后端闭环：
|
|
|
|
|
-
|
|
|
|
|
-- 用户与本地密码认证
|
|
|
|
|
-- access token 鉴权
|
|
|
|
|
-- 仓库创建与 bare Git 初始化
|
|
|
|
|
-- Git over HTTP 最小读写链路
|
|
|
|
|
-- 协作者与最小权限模型
|
|
|
|
|
-- fork
|
|
|
|
|
-- 分支列表
|
|
|
|
|
-- 最小 PR/MR 创建、列表、详情、compare、merge、close、reopen
|
|
|
|
|
-
|
|
|
|
|
-这意味着项目现在已经具备一个“最小可用的 Git 服务后端核心”，但距离 Gogs 的完整产品能力还差几个大块。
|
|
|
|
|
-
|
|
|
|
|
-## 已完成功能
|
|
|
|
|
-
|
|
|
|
|
-### 1. 配置与基础设施
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/conf.rs`](./src/conf.rs)
|
|
|
|
|
-- [`src/repox.rs`](./src/repox.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- 从 `gitr.toml` 或默认值加载配置
|
|
|
|
|
-- 自动准备数据库目录和仓库根目录
|
|
|
|
|
-- 统一推导 `owner/repo.git` 的磁盘路径
|
|
|
|
|
-
|
|
|
|
|
-### 2. 用户、认证与访问令牌
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-- [`src/http.rs`](./src/http.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- 创建本地用户
|
|
|
|
|
-- 用户名、邮箱唯一性校验
|
|
|
|
|
-- 用户名合法性校验
|
|
|
|
|
-- 使用 `argon2` 存储密码哈希
|
|
|
|
|
-- 支持用户名或邮箱登录
|
|
|
|
|
-- 登录后签发 access token
|
|
|
|
|
-- 支持额外创建命名 token
|
|
|
|
|
-- 支持列出当前用户 token
|
|
|
|
|
-- 支持删除当前用户 token
|
|
|
|
|
-- token 名在同一用户下唯一
|
|
|
|
|
-- 数据库只存 token 的 SHA-256 hash
|
|
|
|
|
-- Bearer token 鉴权
|
|
|
|
|
-- token 被使用后更新 `updated_unix`
|
|
|
|
|
-
|
|
|
|
|
-当前安全边界：
|
|
|
|
|
-
|
|
|
|
|
-- `POST /api/admin/users` 只允许首个用户 bootstrap
|
|
|
|
|
-- bootstrap 之后只能由 admin 创建新用户
|
|
|
|
|
-- API 不再暴露 `password_hash`
|
|
|
|
|
-- 匿名读取用户资料时隐藏邮箱
|
|
|
|
|
-
|
|
|
|
|
-### 3. 仓库核心
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-- [`src/git.rs`](./src/git.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- 创建仓库元数据
|
|
|
|
|
-- 同 owner 下仓库名唯一
|
|
|
|
|
-- 仓库名合法性校验
|
|
|
|
|
-- 初始化 bare Git 仓库
|
|
|
|
|
-- 设置默认分支
|
|
|
|
|
-- 运行 `update-server-info`
|
|
|
|
|
-- 支持 `auto_init`
|
|
|
|
|
-- `auto_init` 时创建首个 README 提交
|
|
|
|
|
-- Git 初始化失败时回滚数据库记录和仓库目录
|
|
|
|
|
-
|
|
|
|
|
-### 4. 权限与协作
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/models.rs`](./src/models.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- `access` 表
|
|
|
|
|
-- `collaboration` 表
|
|
|
|
|
-- 最小权限枚举：`Read / Write / Admin / Owner`
|
|
|
|
|
-- owner 隐式拥有 `Owner`
|
|
|
|
|
-- 公有仓库匿名只读
|
|
|
|
|
-- 协作者添加、更新、删除
|
|
|
|
|
-- 协作者列表
|
|
|
|
|
-- 协作者单项检查
|
|
|
|
|
-- collaborator permission 严格校验，只接受 `read / write / admin`
|
|
|
|
|
-- Git HTTP 和 API 复用同一套权限判断
|
|
|
|
|
-
|
|
|
|
|
-当前语义：
|
|
|
|
|
-
|
|
|
|
|
-- 私有仓库未授权访问尽量返回 `404`
|
|
|
|
|
-- 公有仓库上的权限不足返回 `403`
|
|
|
|
|
-
|
|
|
|
|
-### 5. Git over HTTP
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/http.rs`](./src/http.rs)
|
|
|
|
|
-- [`src/git.rs`](./src/git.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- 通过 `git http-backend` 提供最小 Git HTTP 能力
|
|
|
|
|
-- 公有仓库匿名 `git-upload-pack`
|
|
|
|
|
-- 私有仓库 Basic 认证
|
|
|
|
|
-- Basic 认证支持密码或 access token
|
|
|
|
|
-- 按读写权限区分 `upload-pack` / `receive-pack`
|
|
|
|
|
-
|
|
|
|
|
-### 6. Fork
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-- [`src/git.rs`](./src/git.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- fork 元数据：`is_fork`、`fork_id`
|
|
|
|
|
-- 禁止 fork 到原 owner 自己
|
|
|
|
|
-- 禁止同一用户重复 fork 同一仓库
|
|
|
|
|
-- 通过 bare clone 复制源仓库
|
|
|
|
|
-
|
|
|
|
|
-### 7. 分支
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/git.rs`](./src/git.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- 列出分支
|
|
|
|
|
-- 校验分支存在性
|
|
|
|
|
-
|
|
|
|
|
-### 8. 最小 PR / MR 主链
|
|
|
|
|
-
|
|
|
|
|
-说明：
|
|
|
|
|
-
|
|
|
|
|
-- 当前明确不接 Gogs 的 issue/comment/timeline 体系
|
|
|
|
|
-- 只保留代码合并请求本身
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/models.rs`](./src/models.rs)
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-- [`src/http.rs`](./src/http.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- `pull_request` 表
|
|
|
|
|
-- 创建 PR/MR
|
|
|
|
|
-- 列出 PR/MR
|
|
|
|
|
-- 获取 PR/MR 详情
|
|
|
|
|
-- compare
|
|
|
|
|
-- merge
|
|
|
|
|
-- close
|
|
|
|
|
-- reopen
|
|
|
|
|
-- 校验 base branch / head branch 存在
|
|
|
|
|
-- 校验 head repo 必须为同仓库或其 fork
|
|
|
|
|
-- 校验创建者对 base repo 有读权限
|
|
|
|
|
-- 校验创建者对 head repo 有写权限
|
|
|
|
|
-- 阻止同一 head/base 分支对的未合并重复 PR
|
|
|
|
|
-- 计算 merge base
|
|
|
|
|
-- 通过临时克隆试合并，判断 `Mergeable / Conflict`
|
|
|
|
|
-- merge 后记录 `merged_commit_id`
|
|
|
|
|
-- merged PR 详情不会再把 base-only 的后续提交混入 compare
|
|
|
|
|
-- PR index 在数据库事务内分配，并有唯一索引保护
|
|
|
|
|
-
|
|
|
|
|
-### 9. 已暴露的 API
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/http.rs`](./src/http.rs)
|
|
|
|
|
-- [`src/main.rs`](./src/main.rs)
|
|
|
|
|
-
|
|
|
|
|
-当前已有接口：
|
|
|
|
|
-
|
|
|
|
|
-- `POST /api/admin/users`
|
|
|
|
|
-- `POST /api/user/login`
|
|
|
|
|
-- `POST /api/user/tokens`
|
|
|
|
|
-- `GET /api/user/tokens`
|
|
|
|
|
-- `DELETE /api/user/tokens/{id}`
|
|
|
|
|
-- `GET /api/users/{username}`
|
|
|
|
|
-- `GET /api/users/{username}/repos`
|
|
|
|
|
-- `GET /api/user/repos`
|
|
|
|
|
-- `POST /api/repos`
|
|
|
|
|
-- `GET /api/repos/search`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/forks`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/branches`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/compare`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/pulls`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/pulls`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/pulls/{index}`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/pulls/{index}/merge`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/pulls/{index}/close`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/pulls/{index}/reopen`
|
|
|
|
|
-- `POST /api/repos/{owner}/{repo}/collaborators`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/collaborators`
|
|
|
|
|
-- `GET /api/repos/{owner}/{repo}/collaborators/{username}`
|
|
|
|
|
-- `DELETE /api/repos/{owner}/{repo}/collaborators/{username}`
|
|
|
|
|
-- `GET /healthz`
|
|
|
|
|
-
|
|
|
|
|
-### 10. Repo 可见性与列表 API
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/db.rs`](./src/db.rs)
|
|
|
|
|
-- [`src/service.rs`](./src/service.rs)
|
|
|
|
|
-- [`src/http.rs`](./src/http.rs)
|
|
|
|
|
-- [`src/models.rs`](./src/models.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- owner 维度 repo 列表接口
|
|
|
|
|
-- 当前用户可见 repo 集合接口
|
|
|
|
|
-- 基于可见性过滤的 repo 搜索接口
|
|
|
|
|
-- 统一 repo 可见性过滤函数
|
|
|
|
|
-- repo permission DTO
|
|
|
|
|
-- repo 列表/详情返回当前请求视角下的 permission 信息
|
|
|
|
|
-
|
|
|
|
|
-### 11. API 错误语义与返回结构
|
|
|
|
|
-
|
|
|
|
|
-对应模块：
|
|
|
|
|
-
|
|
|
|
|
-- [`src/error.rs`](./src/error.rs)
|
|
|
|
|
-- [`tests/core_flow.rs`](./tests/core_flow.rs)
|
|
|
|
|
-
|
|
|
|
|
-已完成：
|
|
|
|
|
-
|
|
|
|
|
-- API 错误响应统一为结构化 JSON
|
|
|
|
|
-- 错误响应包含稳定的 `code` / `message` / `status`
|
|
|
|
|
-- `400/401/403/404/409/500` 具备稳定错误码语义
|
|
|
|
|
-- `500` 响应不再把底层 I/O / DB / Git 细节直接暴露给客户端
|
|
|
|
|
-
|
|
|
|
|
-## 已验证行为
|
|
|
|
|
-
|
|
|
|
|
-主要测试文件：
|
|
|
|
|
-
|
|
|
|
|
-- [`tests/core_flow.rs`](./tests/core_flow.rs)
|
|
|
|
|
-
|
|
|
|
|
-目前已覆盖的行为包括：
|
|
|
|
|
-
|
|
|
|
|
-- 用户创建、重复拒绝、非法用户名拒绝
|
|
|
|
|
-- bootstrap admin 与后续 admin-only 创建用户
|
|
|
|
|
-- 密码登录、错误密码失败
|
|
|
|
|
-- token 创建、唯一性、list/delete、使用后更新时间
|
|
|
|
|
-- 仓库创建、自动初始化、重复拒绝、非法仓库名拒绝
|
|
|
|
|
-- Git 初始化失败回滚
|
|
|
|
|
-- 公有仓库匿名 Git HTTP pull
|
|
|
|
|
-- 私有仓库 Git HTTP 鉴权
|
|
|
|
|
-- 协作者读权限与禁止 push
|
|
|
|
|
-- fork
|
|
|
|
|
-- 分支列表
|
|
|
|
|
-- PR/MR 创建、去重、列表、详情、compare
|
|
|
|
|
-- PR/MR merge、close、reopen
|
|
|
|
|
-- reopen 时 duplicate open PR 拒绝
|
|
|
|
|
-- merged PR compare 结果稳定
|
|
|
|
|
-- 私有仓库元数据与读接口的未授权不可见
|
|
|
|
|
-- API 响应不暴露 `password_hash`
|
|
|
|
|
-- owner repo list 会隐藏无权限 private repo
|
|
|
|
|
-- 当前用户 repo list 会包含 owned/public/collaborator 可见仓库
|
|
|
|
|
-- repo search 会按当前可见性过滤结果
|
|
|
|
|
-- collaborator list/check 返回协作者及权限
|
|
|
|
|
-- private repo 的 collaborator 读接口对未授权用户继续返回 `404`
|
|
|
|
|
-- validation / unauthorized / conflict / not-found 错误返回结构化 JSON
|
|
|
|
|
-- internal error 返回 `internal_error`，且 message 已脱敏
|
|
|
|
|
-
|
|
|
|
|
-当前测试状态：
|
|
|
|
|
-
|
|
|
|
|
-- `cargo test`
|
|
|
|
|
-- 现状：`38 passed`
|
|
|
|
|
-
|
|
|
|
|
-## 还需要完成的功能
|
|
|
|
|
-
|
|
|
|
|
-下面按优先级拆分，而不是按“想到什么做什么”。
|
|
|
|
|
-
|
|
|
|
|
-### Phase 1A: 补齐当前这一批核心 API
|
|
|
|
|
-
|
|
|
|
|
-目标：
|
|
|
|
|
-
|
|
|
|
|
-- 把“已经有底层能力但 API 还不完整”的部分补齐
|
|
|
|
|
-
|
|
|
|
|
-还缺：
|
|
|
|
|
-
|
|
|
|
|
-- token 使用审计字段进一步丰富
|
|
|
|
|
-
|
|
|
|
|
-建议优先级：
|
|
|
|
|
-
|
|
|
|
|
-1. token 使用审计字段进一步丰富
|
|
|
|
|
-2. 组织/团队出现前的权限边界再抽象
|
|
|
|
|
-3. organization / team 模型
|
|
|
|
|
-
|
|
|
|
|
-### Phase 1B: 强化权限与仓库可见性模型
|
|
|
|
|
-
|
|
|
|
|
-目标：
|
|
|
|
|
-
|
|
|
|
|
-- 让“谁能看到什么 repo、谁能对什么 repo 发 PR/fork/compare”更接近 Gogs
|
|
|
|
|
-
|
|
|
|
|
-还缺：
|
|
|
|
|
-
|
|
|
|
|
-- 更完整的 public/private/not-found 语义梳理
|
|
|
|
|
-- 组织/团队出现前的权限边界再抽象
|
|
|
|
|
-- token 使用审计字段进一步丰富
|
|
|
|
|
-
|
|
|
|
|
-### Phase 2: 组织、团队、组织仓库
|
|
|
|
|
-
|
|
|
|
|
-这是后续真正会改变权限模型的一大块。
|
|
|
|
|
-
|
|
|
|
|
-还缺：
|
|
|
|
|
-
|
|
|
|
|
-- organization 用户模型
|
|
|
|
|
-- team
|
|
|
|
|
-- team repo permission
|
|
|
|
|
-- org 仓库创建
|
|
|
|
|
-- org 成员与 owner/admin 关系
|
|
|
|
|
-
|
|
|
|
|
-这部分完成后，repo 权限才会开始接近 Gogs 的真实结构。
|
|
|
|
|
-
|
|
|
|
|
-### Phase 3: SSH 与 hook
|
|
|
|
|
-
|
|
|
|
|
-还缺：
|
|
|
|
|
-
|
|
|
|
|
-- SSH push/pull 链路
|
|
|
|
|
-- server-side hook
|
|
|
|
|
-- deploy key
|
|
|
|
|
-- 受保护分支最小实现
|
|
|
|
|
-
|
|
|
|
|
-这部分是“能不能真正拿来替代现有 Git 服务”的关键。
|
|
|
|
|
-
|
|
|
|
|
-### Phase 4: Issue / Comment / Timeline 体系
|
|
|
|
|
-
|
|
|
|
|
-当前 PR/MR 是脱离 issue 系统的最小闭环。
|
|
|
|
|
-
|
|
|
|
|
-如果要继续接近 Gogs，还缺：
|
|
|
|
|
-
|
|
|
|
|
-- issue
|
|
|
|
|
-- issue index
|
|
|
|
|
-- comment
|
|
|
|
|
-- close/reopen timeline
|
|
|
|
|
-- label/milestone
|
|
|
|
|
-- PR 与 issue 的完整关联
|
|
|
|
|
-
|
|
|
|
|
-这块工作量会明显高于当前阶段。
|
|
|
|
|
-
|
|
|
|
|
-### Phase 5: Web 产品层
|
|
|
|
|
-
|
|
|
|
|
-当前明确未做：
|
|
|
|
|
-
|
|
|
|
|
-- HTML/template
|
|
|
|
|
-- session 登录流
|
|
|
|
|
-- 浏览器交互页面
|
|
|
|
|
-- frontend 整合
|
|
|
|
|
-
|
|
|
|
|
-这块应在后端主链稳定后再接。
|
|
|
|
|
-
|
|
|
|
|
-## 建议开发顺序
|
|
|
|
|
-
|
|
|
|
|
-如果继续推进，建议顺序如下：
|
|
|
|
|
-
|
|
|
|
|
-1. 补 token 使用审计字段
|
|
|
|
|
-2. 再抽象一层 organization / team 之前的权限边界
|
|
|
|
|
-3. 开始组织/团队模型
|
|
|
|
|
-4. 再进入 SSH/hook
|
|
|
|
|
-5. 最后再考虑 issue/timeline 和 Web 层
|
|
|
|
|
-
|
|
|
|
|
-## 当前结论
|
|
|
|
|
-
|
|
|
|
|
-当前仓库已经完成：
|
|
|
|
|
-
|
|
|
|
|
-- “单用户/协作者/私有仓库/fork/最小 PR”的第一批核心后端闭环
|
|
|
|
|
-
|
|
|
|
|
-当前最值得继续做的，不是再加零散功能，而是：
|
|
|
|
|
-
|
|
|
|
|
-- 先把 token 审计与权限边界抽象补扎实
|
|
|
|
|
-- 再进入 organization / team 这条真正影响权限模型的主线
|
|
|
LoganZ2