架构设计

整体架构

┌─────────────────────────────────────────────────────┐
│                    浏览器 / Git 客户端                 │
└──────────┬──────────────────────┬───────────────────┘
           │ HTTP (3001)          │ HTTP/SSH (8081/2022)
           ▼                      ▼
┌──────────────────┐    ┌──────────────────────────────┐
│  web (Next.js)   │    │       server (Go + Fiber)     │
│  ┌────────────┐  │    │  ┌──────────┐  ┌───────────┐  │
│  │ SSR/CSR    │──┼────┼─▶│ Router   │─▶│ Handler   │  │
│  │ Chakra UI  │  │    │  │ Middleware│  │ Service   │  │
│  └────────────┘  │    │  └──────────┘  └─────┬─────┘  │
└──────────────────┘    │                      │        │
                        │  ┌───────────────────▼──────┐ │
                        │  │  Repository (GORM)       │ │
                        │  │  ┌─────────────────────┐ │ │
                        │  │  │ SQLite/MySQL/PG     │ │ │
                        │  │  └─────────────────────┘ │ │
                        │  └───────────────────────────┘ │
                        │  ┌───────────────────────────┐ │
                        │  │  Git Service (go-git)     │ │
                        │  │  ┌─────────────────────┐  │ │
                        │  │  │  repositories/      │  │ │
                        │  │  │  (bare git repos)   │  │ │
                        │  │  └─────────────────────┘  │ │
                        │  └───────────────────────────┘ │
                        └──────────────────────────────┘

后端分层

层	职责	目录
Router	路由注册、中间件链	internal/router/
Handler	HTTP 请求处理、参数校验、响应序列化	internal/handler/
Service	业务逻辑、事务编排	internal/service/
Repository	数据访问、GORM 操作	internal/repository/
Model	数据模型定义	internal/model/
Middleware	认证、CORS、限流、日志	internal/middleware/
Git	Git 操作封装（含输入验证、仓库锁）	internal/git/
Container	依赖注入容器	internal/container/

Git 安全层

internal/git/ 包提供所有 Git 操作，并内置安全机制：

文件	职责
validation.go	输入验证工具（IsValidRefName、ValidateRepoPath、IsValidCommitHash）
lock.go	仓库级并发锁（GetRepoLock）
branches.go	分支操作（含输入验证和锁）
tags.go	标签操作（含输入验证和锁）
files.go	文件操作（含路径验证和锁）
commits.go	提交查询
diff.go	差异对比

依赖注入

所有服务通过 container.Container 统一管理，启动时初始化，handler 通过容器获取 service 实例。

数据库迁移

启动顺序：
InitGORMDB → AutoMigrate（建表）→ RunMigrations（数据回填）

• AutoMigrate：GORM 自动建表/加列（幂等）
• RunMigrations：版本化 SQL 迁移（internal/database/migrations/*.up.sql）

前端架构

Next.js App Router

web/src/
├── app/                    # 页面路由
│   ├── [owner]/[repo]/    # 仓库相关页面
│   ├── projects/[slug]/   # 项目管理页面
│   ├── admin/             # 管理后台
│   └── settings/          # 用户设置
├── components/             # 共享组件
├── contexts/              # React Context（认证、WebSocket、i18n）
├── lib/                   # 工具函数、API 客户端
└── api/                   # API 请求封装

API 客户端

lib/api.ts 中的 ApiClient 统一处理：

• 认证 token（localStorage + cookie）
• 请求/响应拦截
• 401 自动跳转登录
• API 基址动态适配（浏览器 hostname）

国际化

使用 I18nContext + JSON locale 文件（src/locales/en.json / zh.json）。