跳到主要内容

架构设计

1. 概述​

CSGHub 是一款开源、可信的大模型资产管理平台，其架构设计以私有化部署为核心目标，致力于为用户提供与 Hugging Face 功能一致的完整资产管理能力，实现对模型、数据集、代码等大模型原生资产的全生命周期治理。系统采用微服务架构模式，具备良好的扩展性，可支持从单机 Docker 轻量化部署到大规模 Kubernetes 集群部署的平滑演进，适配不同规模、不同场景的部署需求。

2. 逻辑架构与组件​

CSGHub 采用标准化微服务架构，各核心组件职责清晰、协同工作，形成完整的架构体系。在 Docker 部署模式下，所有组件运行在同一个容器的不同进程中，简化部署与管理；在 Kubernetes 部署模式下，各组件以独立 Pod 形式运行，实现组件隔离、弹性伸缩及高可用部署。

2.1 核心业务与接入层 (Core Business & Access)​

  • Portal & Server: 作为平台的核心接入入口，提供 Web UI 前端交互界面与核心业务逻辑 API 服务，主要负责模型、数据集等资产的元数据管理，以及用户操作的接收与响应，是用户与平台交互的核心载体。
  • User & Casdoor: 构建平台完整的身份管理体系，承担用户注册、登录、权限分配及多租户 OAuth 认证等功能，保障平台访问的安全性与合规性，支持多场景下的身份校验与授权。
  • Nginx & RProxy: 负责平台所有流量的接入与动态路由分发，其中 RProxy 专门处理 Space 应用等动态负载请求，实现请求的精准转发与负载均衡，提升平台访问性能与稳定性。
  • Notifier: 统一通知服务组件，整合邮件、Webhook 及系统内部消息等多种通知方式，负责将平台内的关键事件（如任务完成、资产更新、异常告警等）及时推送至相关用户，保障信息同步高效。
  • DataViewer: 数据集在线预览工具，支持对各类格式数据集的内容解析、结构展示与可视化查看，帮助用户快速了解数据集详情，提升数据管理与使用效率。

2.2 AI 算力与任务调度层 (AI Computing & Orchestration)​

负责算力资源分配、各类 AI 任务执行与代码助手后端能力支撑，是平台实现 AI 相关功能的核心层级。

  • AI Gateway: AI 服务统一入口，整合推理请求的路由分发、流量限流、计费统计及安全管控等功能，为各类 AI 推理任务提供标准化接入通道，保障服务的稳定性与可管控性。
  • CSGShip: 代码助手后端服务，专门为 IDE 侧的 CodeSouler 插件提供后端能力支持，助力开发人员在 IDE 环境中快速调用平台资源，提升代码开发效率。
  • Runner: (关键执行组件) 分布式任务执行器，继承原 Space Builder 的核心能力，主要负责 Space 应用构建、模型微调、任务执行等各类计算密集型任务，是平台任务落地的核心载体。
  • Dataflow: 数据流水线服务，专注于处理大规模数据集的清洗、转换、格式化等预处理操作，为模型训练、推理提供高质量的数据支撑，提升数据利用效率。
  • Temporal & Worker: 异步任务管理核心（异步任务大脑），负责资源同步、镜像构建等长周期任务的状态机管理，确保长耗时任务的稳定执行、状态跟踪与异常恢复。
  • Accounting: 资源计费系统，实时统计算力资源使用、存储占用及 API 调用量等核心数据，为资源管控、成本核算提供数据支撑。

2.3 资产存储与传输加速层 (Asset Storage & Acceleration)​

负责平台所有资产的持久化存储、版本化管理，以及大文件传输的效率优化，保障资产存储的安全性与访问的高效性。

  • xNet: (核心加速组件) 智能加速引擎，专为大文件（如 LFS 文件、模型权重文件）管理设计，通过优化传输路径、缓存策略等方式，大幅提升大文件的读写与传输效率，解决大资产传输缓慢的痛点。
  • Gitaly & Gitlab-shell: 高性能 Git 存储后端，负责所有资产（模型、代码、数据集）的版本控制与 SSH 接入管理，保障资产版本的可追溯性与访问安全性。
  • Mirroring Service: 资产同步服务，包含 mirror_repo 与 mirror_lfs 两个核心模块，负责国内外仓库及大文件的镜像同步，解决跨网络环境下资产访问缓慢、无法访问的问题。
  • Object Storage (MinIO) & Registry: 平台的物理存储底座，其中 MinIO 负责模型资产文件、数据集等对象的持久化存储，Registry 负责 Space 容器镜像的存储与管理，为平台提供稳定、可靠的存储支撑。

2.4 基础设施依赖层 (Infrastructure)​

  • Databases: 包含 PostgreSQL 与 Redis 两个核心数据库，其中 PostgreSQL 用于存储平台元数据（如用户信息、资产信息、任务配置等），Redis 用于缓存管理与会话管理，提升平台访问响应速度。
  • NATS: 高性能事件总线，支撑微服务之间的异步通信，实现组件间的解耦，提升系统的可扩展性与稳定性，确保各类事件信息的高效传递。
  • Observability: 可观测性组件，整合 Prometheus（监控指标采集与分析）与 Loki（集中式日志收集与查询），实现对平台各组件运行状态、任务执行情况的实时监控与问题排查。

3. 部署方式​

根据不同的业务场景、环境限制及规模需求，CSGHub 提供多种灵活的部署方式，用户可根据自身实际情况选择适配的部署方案，实现平台的快速落地与稳定运行。

  • Docker Compose
    • 技术实现：基于单镜像的“全家桶”部署方案，所有核心组件集成在单个容器内，内部通过多进程管理机制实现组件协同运行，部署配置通过 Compose 编排文件定义。
    • 适用场景：本地快速上手、产品功能演示、开发人员本地调试等轻量化场景，无需复杂的环境配置。
    • 特点：交付流程极简，部署成本低，上手门槛低；但在配置灵活性上以 Compose 编排定义为主，扩展性有限，不适用于大规模部署。
  • Kubernetes (Helm)
    • 技术实现：基于 Helm Chart 的标准化微服务分布式部署方案，各组件以独立 Pod 形式部署，通过 Helm 实现配置管理、版本控制与一键部署。
    • 适用场景：生产环境、高可用集群部署、大规模用户并发访问等场景，需要具备弹性伸缩、组件隔离、故障自愈等能力。
    • 特点：支持 Pod 级别弹性伸缩，可根据业务负载动态调整资源分配；原生集成推理、微调及应用空间等全量功能，稳定性与扩展性强，适配企业级生产需求。
  • 离线部署 —— 即将上线
    • 技术实现：针对无公网访问权限的环境，提供预下载的镜像 Tarball 及离线资源包，支持通过内网私有仓库（Registry）实现 Package 镜像或 K8s 镜像的分发与部署。
    • 适用场景：金融、政企等存在物理隔离的涉密或高安全等级网络环境，无法访问外部互联网资源。
    • 特点：完全脱离公网环境运行，保障数据安全与环境隔离；支持内网私有仓库分发，部署流程适配涉密环境规范。
  • 快速安装
    • 技术实现：基于 K3s 的轻量化 Kubernetes 自动化部署脚本，一键拉起 K3s 运行时环境，并自动完成 CSGHub 平台的初始化部署，无需手动配置 Kubernetes 集群。
    • 适用场景：单机资源环境，但需要具备 Kubernetes 标准调度能力的场景，兼顾轻量化部署与 Kubernetes 平台的优势。
    • 特点：一键式部署，自动化程度高，部署速度快；轻量化运行，资源占用低，无需专业的 Kubernetes 运维经验即可完成部署。

4. 网络访问与端口规范​

4.1 Docker Compose​

多端口直接暴露：由于所有服务运行在同一个容器（及同一个网络命名空间）内，需在宿主机上映射多个端口，用于对应不同组件的访问需求，具体端口规范如下：

  • 平台主入口：端口 80 (Nginx 服务)，承载 Web 门户访问和核心 API 调用，是用户访问平台的主要入口。
  • Git SSH 接入：端口 2222 (Git Over SSH)，专门用于 Git 资产的 SSH 方式接入，避免与宿主机默认 SSH 端口（22 端口）冲突。
  • 身份认证：端口 8000 (Casdoor 服务)，负责处理用户登录、注册及 SSO 单点登录鉴权等相关请求。
  • 编码助手：端口 8001 (前端) 与 8002 (API)，分别对应 CSGShip 服务的前端界面与后端 API 接入，为 IDE 插件提供支撑。
  • 对象存储：端口 9000 (API) 与 9001 (控制台)，分别用于 MinIO 对象存储的 API 调用与管理控制台访问，实现资产文件的管理与操作。

4.2 Kubernetes / Air-gap / Quick Install​

80/443 流量收敛：在 Kubernetes、离线部署及快速安装三种模式下，网络访问由 Ingress 或 Envoy-Gateway 统一管理，实现流量收敛，简化端口配置，具体规范如下：

  • 统一业务入口：平台所有功能（Web 门户、API 调用、身份认证、AI 推理等）均通过标准的 80 (HTTP) 或 443 (HTTPS) 端口访问，无需映射多个端口，简化访问配置。
  • 标准 Git 接入：通过 LoadBalancer 实现端口映射，通常可直接使用标准的 22 端口进行 Git 资产的 SSH 操作，符合用户常规使用习惯，无需记忆特殊端口。