Git仓库管理工具Forks部署教程

叹一曲当时只道是寻常2026-04-05 8:14

文章目录

Git 仓库管理工具 Forks：部署、配置与 MCP 集成 AI 助手完整教程

完整源码：github.com/cicbyte/forks（MIT 开源）

本地 clone 了一堆 GitHub/Gitee 仓库，管理混乱、查找困难、团队共享不便？本文介绍一个自研的轻量级 Git 仓库管理工具 Forks，支持 Web 界面管理仓库、局域网镜像加速克隆、在线文件浏览，并通过 MCP 协议让 Claude Code、OpenClaw（龙虾）、Cursor 等 AI 编程助手直接管理你的仓库。

环境说明

项目 版本/说明
操作系统 Linux / macOS / Windows 均支持
Go 1.23+（需要 CGO，用于 SQLite 驱动）
Node.js ^20.19.0 或 >=22.12.0
数据库 内置 SQLite，无需额外部署
Docker 可选，推荐使用 Docker 部署

功能概览

先看界面截图，快速了解：

首页仪表盘 --- 仓库统计一览。

仓库列表 --- 搜索、筛选、批量操作。

仓库详情 --- 克隆地址、文件浏览。

核心功能：

  • 仓库管理 --- 添加、克隆、拉取、重置 GitHub/Gitee 仓库
  • 批量操作 --- 批量克隆、扫描本地目录自动导入
  • 文件浏览 --- 在线浏览文件树，支持语法高亮、Markdown 渲染、图片/音视频预览
  • 镜像加速 --- 内置 Git Smart HTTP 服务，局域网加速克隆
  • MCP 集成 --- AI 编程助手（Claude Code、OpenClaw 龙虾、Cursor）可直接操作仓库

一、Docker 部署（推荐）

最简单的方式，一行命令搞定：

bash 复制代码 
docker run -d \
  -p 8080:8080 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  ghcr.io/cicbyte/forks:latest

自定义端口：

bash 复制代码 
docker run -d \
  -p 9090:9090 \
  -e FORKS_PORT=9090 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  ghcr.io/cicbyte/forks:latest

使用 docker-compose.yml 部署：

yaml 复制代码 
services:
  forks:
    image: ghcr.io/cicbyte/forks:latest
    container_name: forks
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
      - FORKS_HOME=/data
      - FORKS_PORT=8083
    volumes:
      - ./data:/data
bash 复制代码 
docker compose up -d

环境变量说明：

变量 说明 默认值
FORKS_PORT 服务端口 8080
FORKS_ADDRESS 监听地址 0.0.0.0
FORKS_HOME 数据目录 ~/.cicbyte/forks/
FORKS_REPO_PATH 仓库存储路径 首次运行交互式输入
TZ 时区 UTC

优先级：命令行参数 > 环境变量 > 默认值。

二、源码构建

如果需要自定义修改，可以从源码构建：

bash 复制代码 
# 1. 克隆仓库
git clone https://github.com/cicbyte/forks.git
cd forks

# 2. 构建前端
cd web
npm install
npm run build
cd ..

# 3. 构建后端（会自动嵌入前端产物）
go build -o forks

构建完成后会生成一个 forks 可执行文件，包含前端和后端的所有内容。

启动服务：

bash 复制代码 
./forks serve                # 默认监听 :8080
./forks serve -p 9090        # 指定端口
./forks serve --token xxx    # 启用 Bearer Token 认证

首次运行会提示输入仓库存储路径，数据保存在 ~/.cicbyte/forks/ 目录下。

三、镜像加速克隆

这是 Forks 最实用的功能之一。部署在内网服务器上后，团队成员 clone 仓库时直接从镜像拉取，无需走外网。

使用方式

bash 复制代码 
# 直接从镜像服务克隆
git clone http://<server-ip>:8080/git/github/torvalds/linux.git

路径规则：/git/{source}/{author}/{repo}.git

其中 source 支持 github 和 gitee。

使用 fclone 工具（推荐）

直接 git clone 从镜像克隆后，remote 地址会指向镜像服务器。配套的 fclone 工具会在克隆完成后自动将 remote 改回原始 GitHub 地址：

bash 复制代码 
# 构建 fclone
cd fclone && go build -o fclone .

# 使用 fclone 克隆
fclone http://<server-ip>:8080/git/github/torvalds/linux.git
# 克隆完成后 origin 自动指向 https://github.com/torvalds/linux.git

克隆完成后 remote 配置：

  • origin → https://github.com/author/repo.git（原始仓库，支持 push/pull）

技术原理

Forks 通过 git-upload-pack --stateless-rpc 实现只读的 Git Smart HTTP 镜像服务。选择只读是因为定位是镜像缓存------push 操作直接走原始 GitHub 地址，不需要中间代理。

四、批量备份

配套的 fbackup 工具支持从 Forks 服务端并发备份仓库到本地：

bash 复制代码 
# 构建
cd fbackup && go build -o fbackup .

# 配置服务端
fbackup config server http://<server-ip>:8080
fbackup config token xxx              # 如果服务端启用了认证
fbackup config dir /data/backup       # 备份目录

# 执行备份
fbackup              # 默认 5 并发
fbackup -c 10        # 10 并发
fbackup -c 10 -d /backup  # 指定并发数和目录
  • 通过服务端 Git HTTP 接口（/git/...）从局域网复制，不访问外网
  • 已存在的仓库执行 git pull --ff-only，不存在则 git clone
  • 配置文件：~/.fbackup.json

五、MCP 集成：让 AI 助手管理你的仓库

这是 Forks 最有想象力的功能。通过实现 MCP（Model Context Protocol）接口，AI 编程助手可以直接操作你本地管理的仓库------不用手动切浏览器、不用 find 找仓库、不用 cat 看代码。

端点： http://<server>:8080/mcp

可用工具

工具 功能
list_repos 搜索/筛选仓库列表
add_repo 添加仓库
get_repo 获取仓库详情
list_repo_files 浏览文件结构
read_repo_file 读取文件内容

认证方式与 API 相同，使用 Bearer Token。

Claude Code 集成

在 Claude Code 的 MCP 配置中添加 Forks：

json 复制代码 
{
  "mcpServers": {
    "forks": {
      "type": "streamableHttp",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

配置完成后，直接用自然语言操作仓库：

复制代码 
> 帮我找一下本地有没有 gin 框架相关的仓库
> 看看 torvalds/linux 仓库的 Makefile 内容
> 把 https://github.com/gin-gonic/gin 添加到 Forks

OpenClaw（龙虾）集成

OpenClaw 同样支持 MCP 协议，配置方式类似。在设置中添加 MCP Server：

  • 类型：Streamable HTTP
  • 地址 ：http://<server-ip>:8080/mcp
  • Token：你的 Forks Token

添加后就可以让龙虾帮你管理仓库、浏览代码、查看项目结构。

Cursor 集成

在 Cursor 的 MCP 设置中添加 Forks 服务端信息即可，配置方式与上述相同。

实际使用场景

  • 代码审阅：让 AI 助手直接读取仓库文件，快速了解项目结构和实现逻辑
  • 仓库查找：「我之前 clone 过一个关于 WebSocket 的项目，叫什么来着？」------AI 帮你搜
  • 批量管理：「把这些 star 数小于 10 的仓库列出来」------不用写脚本
  • 学习辅助：「帮我看看这个开源项目的入口文件和架构设计」------AI 直接从本地仓库读取

技术栈

层 技术
后端 Go 1.23、Gin、SQLite、Cobra
前端 Vue 3、Naive UI、CodeMirror、Pinia
构建 Vite 7、go:embed

Go 的 //go:embed 指令将前端构建产物打包进二进制文件，实现单文件交付：

go 复制代码 
//go:embed web/dist
var webDist embed.FS

实时推送采用 SSE（Server-Sent Events），适合 clone/pull/扫描这类单向进度推送场景，比 WebSocket 更轻量。

常见问题 FAQ

Q: Docker 部署后访问页面空白？

A: 检查是否正确映射了端口和数据卷。确保 ./data 目录有写权限。如果使用自定义端口，需要同时设置 -p 映射和 FORKS_PORT 环境变量。

Q: 克隆仓库时报错 fatal: unable to access？

A: 检查网络是否能正常访问 GitHub。

Q: 镜像克隆后的仓库无法 push？

A: 使用 fclone 工具代替直接 git clone，克隆完成后会自动将 origin 指向原始 GitHub 地址。如果已经用 git clone 克隆了，手动修改 remote：

bash 复制代码 
git remote set-url origin https://github.com/author/repo.git

Q: Token 认证怎么配置？

A: 首次启动如果没有指定 Token，会自动生成一个随机 Token 并打印在控制台日志中。三种方式配置：

  1. 自动生成：不传任何参数，启动后查看控制台输出获取 Token
  2. 手动指定 ：启动时通过 --token 参数指定
  3. 页面修改：在 Web 设置页面中直接查看和修改 Token

Q: 和 Gitea/GitLab 有什么区别？

A: Forks 定位是本地仓库管理 + 镜像加速，不支持 CI/CD 和代码托管。适合个人或小团队管理已有仓库的场景，部署更简单、资源占用更低。

总结

Forks 是一个轻量级的 Git 仓库管理工具，核心特点：

  • 单文件部署 --- Docker 一行命令或直接运行二进制
  • 零配置 --- 内置 SQLite，开箱即用
  • 镜像加速 --- 局域网 Git Smart HTTP 服务
  • AI 原生 --- MCP 协议集成，Claude Code、OpenClaw 龙虾、Cursor 等 AI 助手直接管理仓库

GitHub : github.com/cicbyte/forks
Docker : docker pull ghcr.io/cicbyte/forks:latest

有问题欢迎评论区讨论，也可以直接提 Issue。

：

  • 单文件部署 --- Docker 一行命令或直接运行二进制
  • 零配置 --- 内置 SQLite，开箱即用
  • 镜像加速 --- 局域网 Git Smart HTTP 服务
  • AI 原生 --- MCP 协议集成，Claude Code、OpenClaw 龙虾、Cursor 等 AI 助手直接管理仓库

GitHub : github.com/cicbyte/forks
Docker : docker pull ghcr.io/cicbyte/forks:latest

有问题欢迎评论区讨论，也可以直接提 Issue。

相关推荐
一个程序猿老马5 小时前
012、远程协作：连接GitHub/Gitee与git remote
git·gitee·github
Lisonseekpan9 小时前
Git：如何将一个分支的特定提交合并到另一个分支？
java·大数据·git·后端·elasticsearch
pas13610 小时前
git 配置
git
独隅14 小时前
Git误操作急救手册
大数据·git·elasticsearch
水无痕simon14 小时前
03 Git 工作流程
git
一个程序猿老马15 小时前
013、推送与拉取：git push与git pull的协作流程
大数据·git·elasticsearch
每天进步一点点️16 小时前
GIT - 常用命令合辑
git
csdn_aspnet16 小时前
Git Submodule深度避坑指南，破解子模块同步混乱、版本漂移、CI失败等高频协作痛点
git·ci/cd·submodule·checklist·detached·subtree
一个程序猿老马17 小时前
011、更优雅的合并：git rebase变基操作详解
git
zhensherlock20 小时前
Protocol Launcher 系列：Working Copy 文件操作与高级命令详解
javascript·git·typescript·node.js·自动化·github·js
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元052026年AI前瞻：量子AI、具身智能与科学发现的新纪元06codex app每次打开重连5次Reconnecting问题解决07AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析08CC-Switch & Claude 基于 Linux 服务器安装使用指南09在 OpenCode 中快速启用 DeepSeek V4 模型102026 年 AI 辅助编程工具全景对比：Copilot、Cursor、Claude Code 与 Codex 深度解析