# GitCandy 架构设计 > 版本：v1.0 | 日期：2026-07-20 | 来源：代码结构分析 本文档描述 GitCandy 的分层架构、核心组件与关键流程。功能需求参见[需求文档](/NewLife/GitCandy/Blob/master/Doc/需求文档.md)，完成状态在[功能清单](/NewLife/GitCandy/Blob/master/Doc/功能清单.md)追踪。 --- ## 1. 项目分层 ``` GitCandy.sln ├── GitCandy (GitCandy.Data) ← 数据层 (.NET Standard 2.1) │ ├── Entity/ ← XCode 实体模型 (Model.xml) + 实体类 + Biz 业务逻辑 │ ├── Base/ ← 基础工具类 (Pager, FileHelper, RegularExpression) │ ├── Configuration/ ← [已排除] 旧配置模块 │ └── Security/ ← [已排除] 旧安全模块 (Token) │ ├── GitCandy.Web ← Web 表现层 (.NET 10.0, ASP.NET Core MVC + Cube) │ ├── Areas/GitCandy/ ← Cube 区域（后台管理） │ │ ├── Controllers/ ← EntityController 魔方实体控制器 │ │ └── Views/ ← Razor 视图 │ ├── Controllers/ ← 自定义 Web 控制器（前台页面 + Git协议） │ ├── Services/ ← 应用服务（AccountService） │ ├── Data/ ← 数据服务（MembershipService, RepositoryService） │ ├── Git/ ← Git 核心访问层 │ │ └── Cache/ ← Git 缓存层 │ ├── Models/ ← 视图模型 │ ├── Views/ ← Razor 视图 │ ├── Extensions/ ← 扩展方法 │ └── wwwroot/ ← 静态资源 │ └── Test ← 测试项目 (.NET 8.0) ``` ### 依赖关系 ``` GitCandy.Web → GitCandy（数据层） GitCandy.Web → NewLife.Cube.Core（魔方框架） GitCandy.Web → LibGit2Sharp（Git 操作库） GitCandy → NewLife.XCode（ORM） GitCandy → NewLife.Core（基础库） GitCandy → NewLife.Stardust（星尘监控） Test → GitCandy（数据层） ``` --- ## 2. 数据层设计 ### 2.1 实体模型（Model.xml） | 实体 | 表名 | 主键 | 说明 | |------|------|:--:|------| | User | User | Int32 自增 | 用户/团队（通过 IsTeam 区分） | | Repository | Repository | Int32 自增 | Git 仓库 | | UserTeam | UserTeam | Int32 自增 | 用户↔团队 多对多关联 | | UserRepository | UserRepository | Int32 自增 | 用户↔仓库 多对多权限关联 | | GitHistory | GitHistory | Int64 | Git 操作审计日志 | > **设计要点**：User 实体通过 `IsTeam` 字段同时承载「个人用户」和「团队」两种角色。团队也是特殊的用户，通过 `UserTeam` 关联表维护成员关系。链接字段 `LinkID` 用于关联 Cube 基础用户表。 ### 2.2 实体 Biz 层 | 实体 | Biz 文件 | 核心方法 | |------|----------|----------| | User | 用户.Biz.cs | `Create`, `CreateTeam`, `Search`, `SearchByName`, `SearchTeam`, `SearchUser`, `GetOrAdd` | | Repository | 仓库.Biz.cs | `FindByOwnerAndName`, `Search`, `GetPublics` | | UserTeam | 用户团队.Biz.cs | `FindByUserAndTeam`, `Search`, `SearchSql` | | UserRepository | 用户仓库.Biz.cs | `FindByUserIDAndRepositoryID`, `Search` | | GitHistory | Git历史.Biz.cs | `Search` | --- ## 3. Web 层组件 ### 3.1 控制器矩阵 | 控制器 | 类型 | 命名空间 | 职责 | 对应功能编码 | |--------|------|----------|------|:----------:| | `GitController` (Area) | `ConfigController<GitSetting>` | Areas/GitCandy | 系统配置管理（Cube ConfigController） | SYS-1 | | `UserController` (Area) | `EntityController<User>` | Areas/GitCandy | 用户后台管理（Cube CRUD） | USER-1 | | `RepositoryController` (Area) | `EntityController<Repository>` | Areas/GitCandy | 仓库后台管理（Cube CRUD） | REPO-1 | | `UserTeamController` (Area) | `EntityController<UserTeam>` | Areas/GitCandy | 用户团队关联管理（Cube CRUD） | TEAM-2 | | `UserRepositoryController` (Area) | `EntityController<UserRepository>` | Areas/GitCandy | 用户仓库关联管理（Cube CRUD） | REPO-3 | | `GitHistoryController` (Area) | `ReadOnlyEntityController<GitHistory>` | Areas/GitCandy | Git操作历史查看（Cube 只读） | HIST-1b | | `HomeController` | `CandyControllerBase` | Controllers | 首页重定向、关于、语言切换 | SYS-3 | | `AccountController` | `CandyControllerBase` | Controllers | 用户账号详情、搜索 | USER-2 | | `RepositoryController` | `CandyControllerBase` | Controllers | 仓库浏览/创建/编辑/删除/协作/代码浏览 | REPO-2/4/5, GIT-2~11 | | `TeamController` | `CandyControllerBase` | Controllers | 团队创建/编辑/详情/成员管理 | TEAM-1, TEAM-3 | | `GitController` | `Controller` | Controllers | Git Smart HTTP 协议处理 | GIT-1 | ### 3.2 服务层 | 服务 | 文件 | 职责 | |------|------|------| | `AccountService` | Services/AccountService.cs | 用户登录认证（密码/Token双重验证） | | `MembershipService` | Data/MembershipService.cs | 用户/团队数据查询与模型转换 | | `RepositoryService` | Data/RepositoryService.cs | 仓库 CRUD、协作管理、列表查询 | ### 3.3 Git 核心访问层（Git/ 目录） | 组件 | 文件 | 职责 | |------|------|------| | `GitService` | Git/GitService.cs | Git 仓库操作核心：Smart HTTP、代码树、文件内容、分支/标签等 | | `ArchiverAccessor` | Git/ArchiverAccessor.cs | 代码归档打包下载 | | `BlameAccessor` | Git/BlameAccessor.cs | 文件逐行审阅（blame） | | `CommitsAccessor` | Git/CommitsAccessor.cs | 提交历史查询 | | `ContributorsAccessor` | Git/ContributorsAccessor.cs | 贡献者统计分析 | | `HistoryDivergenceAccessor` | Git/HistoryDivergenceAccessor.cs | 分支差异比较 | | `LastCommitAccessor` | Git/LastCommitAccessor.cs | 最后提交信息获取 | | `RepositorySizeAccessor` | Git/RepositorySizeAccessor.cs | 仓库大小计算 | | `ScopeAccessor` | Git/ScopeAccessor.cs | 仓库作用域访问 | | `SummaryAccessor` | Git/SummaryAccessor.cs | 仓库摘要信息 | ### 3.4 基础组件 | 组件 | 文件 | 职责 | |------|------|------| | `CandyControllerBase` | Controllers/CandyControllerBase.cs | 控制器基类：认证桥接、语言文化、Session管理 | | `GitSetting` | GitSetting.cs | 系统配置类（NewLife.Config），持久化到 `appsettings.json` | | `GitCandyArea` | Areas/GitCandy/GitCandyArea.cs | Cube 区域注册，菜单项「糖果仓库」 | | `UserUrlConstraint` | Base/UserUrlConstraint.cs | 路由约束：区分用户名和团队名 | | `GitUrlConstraint` | Base/GitUrlConstraint.cs | 路由约束：识别 Git 协议动词 | --- ## 4. 关键流程 ### 4.1 Git Smart HTTP 协议流程 ``` Git Client (git push/pull/clone) │ ├─ GET /{owner}/{project}.git/info/refs?service=git-upload-pack │ └─ GitController.Smart() → Basic Auth → GitService.InfoRefs() │ └─ POST /{owner}/{project}.git/git-upload-pack └─ GitController.Smart() → Session Auth → GitService.ExecutePack() ``` ### 4.2 Web 用户认证流程 ``` 浏览器请求 └─ CandyControllerBase.OnActionExecuting() ├─ 检查 Session["GitToken"] ├─ 无Token → ManageProvider.Provider.TryLogin(HttpContext) ├─ 有Cube用户 → User.GetOrAdd(user) → 存入 Session └─ 设置 ViewBag.Token ``` ### 4.3 仓库路由规则 ``` /{owner}/{name} → RepositoryController.Tree (默认) /{owner}/{name}/{action} → RepositoryController.{action} /{owner}/{name}/{action}/{path} → RepositoryController.{action}(path) /{owner}/{project}/{*verb} → GitController.Smart (Git协议) /{name} → AccountController.Detail (用户) 或 TeamController.Detail (团队) ``` --- ## 5. 配置体系 `GitSetting` 继承 `Config<GitSetting>`，配置键前缀 `Git`，存储在 `appsettings.json`： | 配置项 | 默认值 | 说明 | |--------|--------|------| | IsPublicServer | true | 是否开放服务 | | AllowRegisterUser | true | 允许注册 | | AllowRepositoryCreation | true | 允许创建代码库 | | RepositoryPath | ../Repos | 代码库存储路径 | | CachePath | ../Cache | 缓存路径 | | GitCorePath | 自动探测 | git-core 路径 | | Commits | 30 | 每页提交数 | | PageSize | 30 | 分页大小 | | Contributors | 50 | 显示参与者数 | | AllowArchive | true | 允许打包下载 | | AllowBlame | true | 允许查看审阅 | | AllowCommits | true | 允许查看提交 | | AllowContributors | true | 允许查看贡献者 | | AllowHistoryDivergence | true | 允许查看分支差异 | | AllowSummary | true | 允许查看摘要 | --- ## 6. 关键技术决策 | 决策 | 内容 | 理由 | |------|------|------| | User 实体承载用户+团队 | `IsTeam` 字段区分 | 简化模型，团队可像用户一样拥有仓库 | | 本地用户表 + Cube 用户表分离 | `LinkID` 关联 | 保持 GitCandy 用户体系独立，同时复用 Cube 认证 | | Git 操作使用外部 git.exe | `GitService.RunGitCmdAsync` | 利用 LibGit2Sharp 管理仓库元数据，git-core 处理传输协议 | | 仅支持 HTTP 协议 | 不支持 SSH | 简化部署，无需管理 SSH Key | | Cube 魔方做后台管理 | EntityController CRUD | 零代码获得 CRUD 界面，专注业务定制 |