docker-compose 本地部署

本篇讲在本机用 docker-compose 把 CubeStudio 前端、后端、mysql、redis 四个容器跑起来，适合功能体验和后端二次开发调试。

注意：docker-compose 方式不会在本机起一个 k8s 集群。发起真实的 pipeline / notebook / 推理任务仍需连接一个已部署好 CubeStudio 的 k8s 集群（见文末「本地连接 k8s 开发集群」）。要在机器上真正部署一套能调度任务的平台，请看 01-单机 k8s 部署。

前端 / IDE 断点 / 镜像升级等更细的开发流程见 03-本地开发与调试。

参考视频：https://cube-studio.oss-cn-hangzhou.aliyuncs.com/video/dev.mp4

本地机器环境准备

Windows 系统

1. 安装 Docker Desktop：下载 Docker Desktop Installer，安装最新版。Windows 10 需要启用 Hyper-V，安装配置流程可参考在线文档 https://zhuanlan.zhihu.com/p/441965046
2. 安装 PowerShell：之后的脚本需要在 PowerShell 中执行。
3. 安装 python = 3.9.16。
4. git 配置不要修改换行符：git config --global core.autocrlf false。

Mac 系统

1. 安装 Docker Desktop。

Linux 系统

1. 安装 docker / docker-compose。

docker-compose 配置说明

docker-compose 文件在 install/docker/ 目录下（docker-compose.yml，仓库内同时提供 mac / linux 版本）。该 compose 文件已内置 mysql 与 redis 服务，直接启动即可，无需另行手动 docker run：

镜像名以仓库内 install/docker/docker-compose.yml 为准（商业版镜像带 -enterprise 后缀，开源版镜像名去掉该后缀）。后端 myapp 服务通过 MYSQL_SERVICE 环境变量连 mysql:3306 库 kubeflow，通过 REDIS_HOST=redis 连 redis。

后端 myapp 服务的关键环境变量（见 install/docker/docker-compose.yml）：

• STAGE: 'dev'：启动模式。entrypoint.sh 中 dev 跑 python myapp/run.py（监听 80，热更新），build 编译前端，prod 跑 gunicorn。
• MYSQL_SERVICE: 'mysql+pymysql://root:admin@mysql:3306/kubeflow?charset=utf8mb4'
• REDIS_HOST: 'redis' / REDIS_PORT: '6379' / REDIS_PASSWORD: admin
• ENVIRONMENT: DEV
• 可选：POSTGRESQL_SERVICE / KINGBASE_SERVICE / DM_SERVICE（默认注释掉，用 mysql）。元数据库切换见 04-运维管理/元数据库配置.md。

后端配置文件 config.py、project.py 通过挂载注入容器（./config.py:/home/myapp/myapp/config.py），配置项说明见 04-运维管理/配置文件管理.md。

启动 docker-compose

在 install/docker/ 目录下执行：

docker-compose -f docker-compose.yml up

启动后浏览器访问 http://<本机IP>/（前端容器映射 80 端口）。登录首页会自动创建用户并绑定角色（Gamma），可按需为角色授权。

myapp 服务的启动命令默认是 bash -c 'sleep 100000000 && /entrypoint.sh'，即容器起来后先 sleep。这是为了方便调试：可以 docker-compose up -d 起后台，再 docker exec -it docker-myapp-1 bash 进容器手动执行 /entrypoint.sh（首次，含建库初始化）或 python myapp/run.py（后续）。容器名 docker-myapp-1 来自 compose 项目目录名 docker + 服务名 myapp。

首次进入容器后的初始化由 /entrypoint.sh 完成，主要步骤：编译 i18n 翻译产物 → python myapp/create_db.py 建 schema → myapp db upgrade 应用迁移（DM_SERVICE 非空即达梦时跳过此步，改由 create_db.py 建表）→ myapp fab create-admin（用户名 / 密码均为 admin，邮箱 admin@tencent.com）→ myapp init（创建默认角色 / 权限 / 自定义 menu）。后续调试直接 python myapp/run.py 即可。

使用外部数据库（可选）

compose 已内置 mysql / redis。若想连外部 mysql / postgresql，可手动起库并改 myapp 的环境变量：

部署 mysql：

docker run -p 3306:3306 --restart always --name mysql \
  -e MYSQL_ROOT_PASSWORD=admin \
  -v $PWD/docker-add-file/mysqld.cnf:/etc/mysql/conf.d/mysqld.cnf \
  -d mysql:8.0.32

进入 mysql 创建 kubeflow 库并授权：

CREATE DATABASE IF NOT EXISTS kubeflow DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
use mysql;
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
flush privileges;

部署 postgresql：

docker run -p 5432:5432 --name postgres -e POSTGRES_PASSWORD=admin -d postgres:11.5

然后在 docker-compose.yml 的 myapp 服务里启用对应的 POSTGRESQL_SERVICE / KINGBASE_SERVICE / DM_SERVICE 环境变量（默认注释）。详见 04-运维管理/元数据库配置.md。

镜像构建（可忽略，不参与开发可直接用线上镜像）

构建命令以仓库内各 Dockerfile 头部注释为准：

# 构建基础镜像（含基础环境）
docker build --network=host \
  -t ccr.ccs.tencentyun.com/cube-studio/kubeflow-dashboard:base-python3.9-20260601 \
  -f install/docker/Dockerfile-base .

# 用基础镜像构建后端生产镜像
docker build --network=host \
  -t ccr.ccs.tencentyun.com/cube-studio/kubeflow-dashboard-enterprise:2026.07.01 \
  -f install/docker/Dockerfile .

# 构建前端镜像
docker build --network=host \
  -t ccr.ccs.tencentyun.com/cube-studio/kubeflow-dashboard-frontend-enterprise:2026.07.01 \
  -f install/docker/dockerFrontend/Dockerfile .

镜像名 / tag 已按 install/docker/Dockerfile、install/docker/Dockerfile-base、install/docker/dockerFrontend/Dockerfile 头部实际命令校正：商业版后端 / 前端镜像带 -enterprise 后缀，基础镜像 tag 为 base-python3.9-20260601。镜像构建更细的说明见 06-二次开发/镜像构建/镜像构建总览.md。

镜像拉取（不参与开发可直接用线上镜像）

docker pull ccr.ccs.tencentyun.com/cube-studio/kubeflow-dashboard-enterprise:2026.07.01
docker pull ccr.ccs.tencentyun.com/cube-studio/kubeflow-dashboard-frontend-enterprise:2026.07.01

本地连接 k8s 开发集群

docker-compose 只起前后端 + 数据库，要调度真实任务还得连一个 k8s 集群：

1. 需要先在 k8s 开发集群上部署过一遍 CubeStudio，本地才能连上去调度。
2. 把集群 kubeconfig 放到 install/docker/kubeconfig/ 下，按 $ENVIRONMENT-kubeconfig 命名（仓库内已有 dev-kubeconfig / prod-kubeconfig / cloud-kubeconfig / npu-kubeconfig）。compose 已把该目录挂到容器 /home/myapp/kubeconfig。

修改 minio 地址

把远端 k8s 上 kubeflow 命名空间下的 minio 服务改为 NodePort 类型，然后修改 install/docker/config.py 中的 MINIO_HOST 为 minio 服务的 ip:nodeport。

config.py 中 MINIO_HOST 默认值为 minio.kubeflow:9000（见 install/docker/config.py:1302），是集群内访问地址；本地 docker-compose 连远端 minio 时需改为 NodePort 暴露的 ip:nodeport。

下一步

• 在本机 IDE 里给后端打断点、前端本机开发与容器内编译、前后端镜像升级、常见问题：见 03-本地开发与调试。
• 在机器上真正以 k8s 形态部署完整平台：见 01-单机 k8s 部署。

镜像名 / 端口 / 环境变量 / 命令以源码（install/docker/docker-compose.yml、install/docker/entrypoint.sh、install/docker/config.py）为准，本篇仅供导航与上手。