跳到主要内容

Docker Compose

优势​

  • 简化管理：通过 Docker Compose 统一编排所有服务依赖
  • 快速部署：一键启动完整的 CSGHub 服务栈
  • 灵活扩展：支持横向扩展服务实例，按需调整资源配置和服务规模
  • 生产就绪：满足中小企业级应用部署要求

提示： 建议使用 Docker Compose 进行安装。

适用场景​

  • 快速搭建 CSGHub 演示环境
  • 快速验证 CSGHub 功能
  • 开发测试环境部署
  • 中小规模生产环境部署

功能说明​

根据配置复杂度，提供两种启动模式：

  • 基本功能：除模型评测、推理、微调、应用空间、MCP 以外的所有功能功能（以上功能依赖 Kubernetes 集群）。

  • 完整功能：包含 ce/ee 全部功能。

    如果使用完整功能，请配置docker-compose.yml启用 runner以及映射.kube/config文件到容器。注意：请保证.kube/config中的 API Server 地址在容器中可访问。

注意： 使用 IP 地址访问时，MCP 功能将受限（该功能需域名支持）。

系统要求​

硬件要求​

资源类型最低配置推荐配置更多
CPU/内存4 cores 8GB8 cores 16GB
处理器架构-AMD64/ARM64支持x86和ARM架构

软件要求​

组件版本要求验证命令其他依赖
Docker Engine≥ 20.10.0docker --version
Docker Compose≥ 2.0.0docker compose version
Kubernetes1.28+ (可选)kubectl version1. Nvidia GPU支持需要自行安装Nvidia Device Plugin
2. 支持 Dynamic Volume Provisioning

说明： 启用完整功能需要依赖 Kubernetes，否则模型评测、推理、微调，MCP, 应用空间等功能将不可用。

安装部署​

注意： csghub.external_url中默认使用 80 端口号（默认端口号:80可忽略不写），如果修改 ports 80的对外映射端口，务必保证 external_url 中使用相同的端口号。

安装配置说明​

容器说明​

出于用户使用友好的目的我们将原 docker compose 多容器服务融合为单容器，虽然融合为单容器但依然具备多机部署的特性，每个服务都可以单独拆分为独立的容器，在原有基础上更灵活，更易配置。

版本说明​

  • CE 社区免费版本

  • EE 企业版本（建议安装此版本）

    • 包含社区版本的所有功能
    • 企业版功能 - 需要导入 License
    • Starship编码助手 - 默认不起用

  • 初始化参数说明

    由于 csghub 参数量较为庞大，因此在安装示例中仅展示了部分可配置参数，更多参数参见 csghub.yaml.sample。

    所有 docker-compose.yaml 中可配置参数均通过变量CSGHUB_OMNIBUS_CONFIG使用 yaml 格式进行定义传递，且具备最高优先级，如果服务已经启动有两种方式可以继续调整参数：

    • 重新定义 CSGHUB_OMNIBUS_CONFIG 并重启容器
    • 进入到容器中修改/etc/csghub/csghub.yaml 文件，如果修改的参数已经在CSGHUB_OMNIBUS_CONFIG 定义，将不会生效。

    基本参数说明：

    • csghub

      • external_url

        定义访问 CSGHub 示例的 URL，由<scheme>://<domain>:[port]，如果<scheme> 是 http，[port]默认为 80，如果<scheme> 是 https，[port]默认为 443。[port]应该和 ports 对外保留的端口号保持一致，详细可见修改端口号映射。

    • runner

      • enable

        默认为 false，此服务启动后会默认扫描通过 volumes 映射的 .kube/config-* 文件，如果扫描为空可能会运行异常。因此默认禁用了此服务，但是此服务是运行推理、微调等功能的必要组件。请在启用此服务前确认 Kubernetes 集群已经就绪。

      • deploy

        • auto_configure

          默认值 true。此参数作用是在连接到 Kubernetes 集群时初始化 CSGHub 依赖的 Argo Workflow, LWS, KnativeServing 等依赖组件。默认不需要配置。

        • knative.services

          • type

            需要提前定义 KnativeServing kourier 服务对外暴露的类型。仅在第一次初始化时有效，一旦 KnativeServing 已经初始化完成，此参数将不再有效。

          • domain

            定义 KnativeServing 使用的内部域名，主要用于被 CSGHub 内部访问。

          • host

            定义 KnativeServing kourier 服务分配的外部访问地址。

          • port

            定义 KnativeServing kourier 服务分配的外部访问端口。

          更多参考：安装 KnativeServing。

      注意： 如果启用服务，但是 Kubernetes 集群没有就绪，会导致 server 主服务初始化算力资源数据失败，从而主服务无法就绪。

    • 关于 dataflow 容器

      此容器为企业版本数据处理的后台服务，因部分功能在优化阶段且容器复杂度较高，所以目前保持独立部署，可以通过添加此容器并定义server.dataflow.addess来连接到 dataflow。dataflow 使用的数据库默认为 csghub 容器中的内置数据库。

默认安装​

  • docker-compose.yml

    services:
      csghub:
        image: opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/omnibus-csghub:v1.10.0-${EDITION:-ee}
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com" # 访问 CSGHub 实例域名，建议使用域名方式配置
            runner:														          # 仅使用完整功能时需要，基本功能安装可移除此项
              enable: true										          # 是否启用 Runner 服务，禁用则仅能使用基础功能
              deploy:
                knative:
                  services:
                    - type: "NodePort"        # 如果 Kubernetes 集群不支持 LoadBalancer，可以使用 NodePort
                      domain: "app.internal"	# 自定义 Knative Serving 内部域名
                      host: "192.168.18.10"   # 暴露 kourier 服务的 EXTERNAL-IP
                      port: 30123							# 自定义端口号，type=LoadBalancer, 请指定为 80
        ports:
          - '80:80'					# Nginx
          - '2222:2222'     # Git Over SSH
          - '5000:5000'     # Container Registry
          - '8000:8000'     # Casdoor
          - '9000:9000'     # Minio
          - '9001:9001'     # Minio Admin UI
        volumes:
          - ./csghub/etc:/etc/csghub
          - ./csghub/logs:/var/log/csghub
          - ./csghub/data:/var/opt/csghub
          - ./csghub/.kube:/etc/csghub/.kube
        restart: always
        shm_size: '256m'

  • 启动服务

    docker compose up -d && docker compose ps

  • 停止服务

    docker compose down

启用 Dataflow​

services:
  csghub:
      ......
      CSGHUB_OMNIBUS_CONFIG: |
        ......
        server:
          dataflow:
            address: "http://dataflow:8000"  # Dataflow 地址
        ......

  dataflow:                                 # Dataflow 为 CSGHub 数据集处理模块，可按需启用
    image: opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/dataflow:latest
    environment:
      CSGHUB_ENDPOINT: "http://csghub.example.com"
      DATABASE_HOSTNAME: "csghub"
      DATABASE_PORT: "5432"
      DATABASE_USERNAME: "dataflow"
      DATABASE_PASSWORD: "8f444970fcde559c"
      DATABASE_DB: "dataflow"
      DATA_DIR: "/data"
      MAX_WORKERS: 50
      RAY_ADDRESS: "auto"
      RAY_ENABLE: false
      RAY_LOG_DIR: "/var/log/dataflow"
      API_SERVER: "0.0.0.0"
      API_PORT: 8000
      AZURE_OPENAI_ENDPOINT: "$AZURE_OPENAI_ENDPOINT"
      AZURE_OPENAI_API_KEY: "$AZURE_OPENAI_ENDPOINT"
      OPENAI_API_VERSION: "$OPENAI_API_VERSION"
      AZURE_MODEL: "$AZURE_MODEL"
      ENABLE_OPENTELEMETRY: false
    volumes:
      - ./csghub/data/dataflow:/data
      - ./csghub/logs/dataflow:/var/log/dataflow
    restart: always

启用 Starship​

services:
  csghub:
    ......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        ......
        starship:
          enable: true			# 启用 Starship 编码助手
    ports:
      ......
      - '8001:8001'     # Starship Portal
      - '8002:8002'     # Starship-API Admin Console
      ......

安装CE版本​

  • 启动服务

    EDITION=ce docker compose up -d && docker compose ps

    其他同 EE 版本。

实例访问​

  1. 实例 URL

    见 docker-compose.yml 中的 csghub.external_url。

  2. 登录 csghub 容器

    docker compose ps && docker exec -it <container> bash

  3. 查看默认管理员账户密码

    cat /etc/csghub/init_root_password

配置说明（从高到低）​

  1. 环境变量配置
    • CSGHUB_OMNIBUS_CONFIG 作用: 通过 Docker Compose 启动时注入动态配置参数 特点: 具有最高优先级，会覆盖其他配置源的相同参数 使用场景: 适合临时调整或容器化部署时的参数注入
  2. 主配置文件
    • /etc/csghub/csghub.yaml 内容: 完整参数集合，支持所有可配置项 建议: 仅需按需修改关键参数，未配置项自动继承默认值 权限: 建议保留系统默认权限（通常需 root 权限修改）
  3. 默认配置基准
    • /opt/csghub/etc/csghub/default.yaml 作用: 提供所有参数的基准默认值 特点:
      • 优先级最低，仅当其他配置未定义时生效
      • 不建议直接修改（升级时可能被覆盖）
      • 可作为配置模板参考

更多配置见 csghub.yaml.sample。

服务管理​

  • csghub-ctl

    CommandDescription
    --help查看帮助
    reconfigure刷新所有服务配置文件并按需重启服务
    start启动服务
    restart重启服务
    stop停止服务
    reload重载服务
    tail跟踪服务日志
    status查看服务状态

  • csghub-psql: 快速访问 csghub_server 数据库

常见问题​

关于 .kube/config​

.kube/config文件作为访问 Kubernetes 集群的重要配置文件，在 CSGHub 运行时会依赖此文件。

关于外置服务​

默认情况下以下组件会通过runner.deploy.autoConfigure=true来进行自动配置，此配置需要依赖启动服务时传入的runner.deploy.knative.services[]参数。如果存在一些原因无法完整自动配置，可以尝试通过以下方式手动安装配置：

修改端口号映射​

目前对外暴露的端口号一共有以下：

  • '80:80' # Nginx

  • '2222:2222' # Git Over SSH

  • '5000:5000' # Container Registry

  • '8000:8000' # Casdoor

  • '8001:8001' # Starship Portal

  • '8002:8002' # Starship-API Admin Console

  • '9000:9000' # Minio

  • '9001:9001' # Minio Admin UI

  • 修改 Nginx 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com:8080" 
        ports:
          - '8080:80'   # 仅修改对外端口号
       ......

  • 修改 Git Over SSH 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            gitlab_shell:
              ssh_port: 22222
        ports:
          - '22222:22222'   # 修改内外端口号
       ......

  • 修改 Container Registry 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com:8080" 
            runner:
              registry:
                prefix: "csghub.example.com:5001/csghub/"
        ports:
          - '5001:5000'   # 仅修改对外端口号
       ......

  • 修改 Casdoor 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            casdoor:
              listen: "127.0.0.1:8005"
        ports:
          - '8005:8005'   # 修改内外端口号
       ......

  • 修改 Starship 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: | 
            starship:
              listen: 
                frontend: "127.0.0.1:8006"
                api: "127.0.0.1:8007"
        ports:
          - '8006:8006'   # 修改内外端口号 
          - '8007:8007'   # 修改内外端口号
       ......

  • 修改 Minio 端口号

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com:8080" 
            server:
              s3: 
                endpoint: "csghub.example.com:9005"
                internal_endpoint: "127.0.0.1:9000"
            portal:
              s3:
                endpoint: "csghub.example.com:9005"
            registry:
              storage:
                s3:
                  regionendpoint: "http://csghub.example.com:9005"
        ports:
          - '9005:9000'   # 仅修改对外端口号
          - '9006:9001'   # 仅修改对外端口号
       ......

登录失败：位置登录错误，请联系管理员​

此问题最常见原因主要有以下两方面：

  1. 文件docker-compose.yml 中添加了字段 hostname 为访问域名。

    services:
      csghub:
        image: opencsghq/omnibus-csghub:v1.10.0-ce
        hostname: "xxx" # 移除此参数，或保证此参数和 external_url 中定义域名不一致

  2. 宿主机 hosts 域名解析到了127.0.0.1。

    请确保external_url中定义的域名解析到非127.0.0.1以及localhost地址。

问题反馈​

如遇使用过程中遇到任何问题可以通过方式提交反馈：