# GitKS RPC 补齐任务 > 对照 Gitaly 分析后，梳理有必要实现但目前缺失的功能，按优先级排列。 > 每个任务标注：类别、预估工作量、前置依赖、实现思路。 --- ## P0 — 核心功能缺失（影响基本使用场景） ### P0-1. `RefService` — 原子性引用操作 | 项 | 内容 | |------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `UpdateReferences`, `DeleteRefs`, `FindDefaultBranchName`, `RefExists` | | **Proto** | 新建 `proto/ref.proto`（独立 RefService） | | **工作量** | **M**（3-5 天） | | **为什么必要** | 当前 `branch.proto` / `tag.proto` 每个操作单独一个 RPC，无法做批量原子更新。`UpdateReferences` 是 Gitaly 中最核心的写操作之一，支持 `expected_old_oid` 校验 | | **实现思路** | 1. 新建 `ref/` 模块 2. `UpdateReferences` 调用 `git update-ref --stdin` 批量原子更新 3. `DeleteRefs` 调用 `git update-ref -d` 批量删除 4. `RefExists` 用 `gix` 检查 reference 是否存在 5. `FindDefaultBranchName` 从已有的 `default_branch_name()` 抽取 | ### P0-2. `RepositoryService` — FindMergeBase | 项 | 内容 | |------------|-----------------------------------------------------------------------------| | **新增 RPC** | `FindMergeBase` | | **Proto** | 扩展现有 `proto/repository.proto` | | **工作量** | **S**（1 天） | | **为什么必要** | diff、merge、rebase 操作都依赖 merge-base 计算。当前 GitKS 的 merge/diff 模块各自计算，缺少独立 API | | **实现思路** | 调用 `gix::Repository::merge_base()` 返回两个 revision 的 merge base OID | ### P0-3. `RepositoryService` — SearchFiles（代码搜索） | 项 | 内容 | |------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `SearchFilesByContent`, `SearchFilesByName` | | **Proto** | 扩展现有 `proto/repository.proto` | | **工作量** | **M**（2-3 天） | | **为什么必要** | 代码搜索是代码托管平台的基础功能，当前完全缺失 | | **实现思路** | `SearchFilesByContent` → `git grep -I --line-number --column `；`SearchFilesByName` → `git ls-tree -r --name-only ` + 正则过滤。需注意大仓库性能（加 timeout、limit） | ### P0-4. `RepositoryService` — WriteRef | 项 | 内容 | |------------|------------------------------------------------------------------------------------------| | **新增 RPC** | `WriteRef` | | **Proto** | 扩展现有 `proto/repository.proto` | | **工作量** | **S**（0.5 天） | | **为什么必要** | 直接写 ref 是最底层的仓库操作，Replica 同步、快照恢复都依赖此能力。当前 `sync.rs` 中 `update_local_ref` 是内部函数，应暴露为 RPC | | **实现思路** | `git update-ref ` -- 已有 `update_local_ref` 可直接封装 | --- ## P1 — 重要功能缺失（影响高级场景） ### P1-1. `RemoteService` — 远程仓库交互 | 项 | 内容 | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 Service** | `RemoteService`（3 个 RPC） | | **新增 RPC** | `FindRemoteRepository`, `FindRemoteRootRef`, `UpdateRemoteMirror` | | **Proto** | 新建 `proto/remote.proto` | | **工作量** | **L**（5-7 天） | | **为什么必要** | 支持从远程 URL 导入仓库、镜像同步。`FetchRemote` 在 Gitaly 的 RepositoryService 中也有对应 | | **实现思路** | 1. `FindRemoteRepository` → `git ls-remote ` 2. `FindRemoteRootRef` → 取 ls-remote 的 HEAD 3. `UpdateRemoteMirror` → `git remote add` + `git fetch --mirror` + 清理。需注意认证（支持 SSH key / token 注入） | ### P1-2. `RepositoryService` — FetchRemote / CreateRepositoryFromURL | 项 | 内容 | |------------|----------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `FetchRemote`, `CreateRepositoryFromURL` | | **Proto** | 扩展现有 `proto/repository.proto` | | **工作量** | **M**（3-4 天） | | **为什么必要** | 仓库导入是核心 onboarding 流程，当前只能创建空仓库 | | **实现思路** | `CreateRepositoryFromURL` → `git clone --bare --mirror `；`FetchRemote` → `git fetch `。复用 RemoteService 的认证基础设施 | ### P1-3. `CommitService` — 扩展查询能力 | 项 | 内容 | |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `FindCommit`, `ListCommitsByOid`, `CommitIsAncestor`, `CheckObjectsExist`, `CommitsByMessage` | | **Proto** | 扩展现有 `proto/commit.proto` | | **工作量** | **M**（3-4 天） | | **为什么必要** | 当前 `list_commits` / `get_commit` 太基础，缺少批量查询、ancestor 判断、message 搜索等常用模式 | | **实现思路** | 1. `FindCommit` → `gix::Repository::find_object()` + 解析 Commit 2. `ListCommitsByOid` → 批量 `gix::Repository::find_commit()` 3. `CommitIsAncestor` → `gix::Repository::merge_base()` 判断 4. `CheckObjectsExist` → 批量 `gix::Repository::try_find()` 5. `CommitsByMessage` → `git log --all --grep=` | ### P1-4. `RepositoryService` — ObjectsSize / RepositorySize | 项 | 内容 | |------------|---------------------------------------------------------------------------------------------------------| | **新增 RPC** | `ObjectsSize`, `RepositorySize` | | **Proto** | 扩展现有 `proto/repository.proto` | | **工作量** | **S**（1 天） | | **为什么必要** | 前端需要展示仓库大小、文件大小，当前 `RepositoryStatistics` 只有对象计数没有大小 | | **实现思路** | `ObjectsSize` → `git cat-file --batch-check` 批量获取对象大小；`RepositorySize` → `du -sb ` 或遍历 objects 目录 | ### P1-5. `DiffService` — RawDiff / RawPatch | 项 | 内容 | |------------|---------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `RawDiff`, `RawPatch` | | **Proto** | 扩展现有 `proto/diff.proto` | | **工作量** | **S**（1 天） | | **为什么必要** | 当前 `get_diff` 返回结构化 protobuf，对于大 diff 非常低效。Raw 格式可直接流式返回文本，用于 patch 应用、邮件发送 | | **实现思路** | `RawDiff` → `git diff ..` streaming stdout；`RawPatch` → `git format-patch ..` streaming。注意大 diff 时的内存控制 | ### P1-6. `CommitService` — CommitStats / LastCommitForPath | 项 | 内容 | |------------|--------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `CommitStats`, `LastCommitForPath` | | **Proto** | 扩展现有 `proto/commit.proto` | | **工作量** | **S**（1 天） | | **为什么必要** | 文件列表需要显示最后修改 commit，commit 详情需要统计信息。当前 `CommitStats` 内嵌在 `Commit` message 中需额外请求才填充 | | **实现思路** | `CommitStats` → `git diff --stat ^..` 解析输出；`LastCommitForPath` → `git log -1 --format=%H -- ` | --- ## P2 — 锦上添花（完善体验） ### P2-1. `RepositoryService` — FindLicense | 项 | 内容 | |------------|-----------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `FindLicense` | | **工作量** | **S**（1 天） | | **实现思路** | 基于 GitHub Licensee 算法：读取 `LICENSE*` / `COPYING*` 文件 → 用 go-license-detector 等价逻辑（Rust 可用 `askalono` crate）做文本匹配 | ### P2-2. `RepositoryService` — OptimizeRepository | 项 | 内容 | |------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `OptimizeRepository` | | **工作量** | **M**（2-3 天） | | **实现思路** | 根据仓库状态自动决定优化策略：loose objects > N → `repack -d`；packfiles > N → `repack -ad`；没有 commit-graph → `commit-graph write`；没有 bitmap → `repack -adb`。比当前单独调用 `gc`/`repack`/`write_commit_graph` 更智能 | ### P2-3. `RepositoryService` — GetRawChanges | 项 | 内容 | |------------|------------------------------------------------------------------------------| | **新增 RPC** | `GetRawChanges` | | **工作量** | **S**（0.5 天） | | **实现思路** | `git diff-tree --raw -r ..` 返回纯文件级变更列表（旧模式、新模式、状态），不生成完整 diff 内容 | ### P2-4. `CommitService` — CountCommits / CountDivergingCommits | 项 | 内容 | |------------|-----------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `CountCommits`, `CountDivergingCommits` | | **工作量** | **S**（0.5 天） | | **实现思路** | `CountCommits` → `git rev-list --count `；`CountDivergingCommits` → `git rev-list --count --left-right ...` | ### P2-5. `RefService` — FindRefsByOID / ListRefs（增强查询） | 项 | 内容 | |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | **新增 RPC** | `FindRefsByOID`, `ListRefs` | | **工作量** | **S**（1 天） | | **实现思路** | `FindRefsByOID` → `git for-each-ref --points-at=`；`ListRefs` → `git for-each-ref --format=... --sort=...` 通用 ref 列表（当前只能在 branch/tag service 中分别查询） | ### P2-6. `DiffService` — FindChangedPaths | 项 | 内容 | |------------|-----------------------------------------------------------------------------------------------| | **新增 RPC** | `FindChangedPaths` | | **工作量** | **S**（0.5 天） | | **实现思路** | `git diff-tree --name-status -r ..` 只返回变更的文件路径和状态（A/M/D/R），无 diff 内容，适合只展示文件列表的场景 | --- ## P3 — 低优先级（生态特定 / 边缘场景） ### P3-1. ObjectPoolService（Fork 去重） | 项 | 内容 | |----------------|------------------------------------------------------------------------------| | **新增 Service** | `ObjectPoolService`（6 个 RPC） | | **工作量** | **XL**（2-3 周） | | **前置依赖** | P0-1 `UpdateReferences` 稳定后 | | **为什么低优** | Fork 去重是 GitLab.com 级别的需求。单租户或小规模部署用不上，且实现复杂（需管理 alternates、pool 生命周期、GC 协调） | ### P3-2. HookService（Server 端 gRPC Hook 回调） | 项 | 内容 | |----------------|------------------------------------------------------------------------------------| | **新增 Service** | `HookService`（6 个 RPC） | | **工作量** | **L**（1-2 周） | | **为什么低优** | GitKS 的 hook 是内嵌脚本执行的"客户端模式"，改为 gRPC 回调的"server 模式"需要对 hook runner 彻底重构，且需要下游客户端对接 | ### P3-3. CommitService — GPG 签名相关 | 项 | 内容 | |------------|-------------------------------------------------------------------------| | **新增 RPC** | `GetCommitSignatures`, `FilterShasWithSignatures`, `GetTagSignatures` | | **工作量** | **M**（2-3 天） | | **为什么低优** | 需要 GPG 工具链依赖。可用 `gpg --verify` 或 `sequoia-openpgp`（Rust crate）实现，但非刚性需求 | ### P3-4. SmartHTTP / SSH Service — Sidechannel + SSH 支持 | 项 | 内容 | |-----------|--------------------------------------------------------------------------------------------------| | **新增/扩展** | `PostUploadPackWithSidechannel`, `SSHUploadPack`, `SSHReceivePack` | | **工作量** | **XL**（3-4 周） | | **为什么低优** | Sidechannel 需要 Unix socket 旁路，平台依赖强。SSH 支持需要完整的 SSH server 协议栈（或依赖外部 SSH → gRPC 代理）。建议通过外部网关层来解决 | ### P3-5. ServerService — 健康检查 / 磁盘统计 | 项 | 内容 | |----------------|--------------------------------------------------------------------------------------------------------------------------| | **新增 Service** | `ServerService`（4 个 RPC） | | **工作量** | **S**（1 天） | | **为什么低优** | GitKS 已有 Prometheus metrics endpoint + logging，`ServerInfo`/`ReadinessCheck`/`DiskStatistics` 更多用于 Kubernetes/平台集成。可快速补充 | --- ## 汇总 | 优先级 | Service 数 | RPC 数 | 预估总工作量 | |--------|-------------|---------|------------------------| | **P0** | 2（扩展现有） | 9 | ~8 天 | | **P1** | 1 新建 + 4 扩展 | 17 | ~17 天 | | **P2** | 3 扩展 | 9 | ~7 天 | | **P3** | 3 新建 + 2 扩展 | 22+ | ~10 周 | | **合计** | | **57+** | **~13 周**（P0-P2 约 5 周） | > **建议路线**：优先完成 P0 + P1（共 26 个 RPC，约 4-5 周），可覆盖 80% 的常用场景。 > P2 在核心功能稳定后逐步添加。P3 按实际用户需求驱动，不必全部实现。