Back to Details

minikube-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Minikube Setup Skill

Minikube 搭建指南

Quick Start

快速开始

  1. Install Minikube - Follow platform-specific instructions
  2. Start Minikube - With adequate resources for 3 pods
  3. Enable Addons - Ingress for external access
  4. Load Images - Push local images to Minikube registry
  5. Deploy Application - Apply Kubernetes manifests or Helm chart
  1. 安装Minikube - 遵循对应平台的安装说明
  2. 启动Minikube - 分配足够资源以支持3个Pod
  3. 启用插件 - 启用Ingress以支持外部访问
  4. 加载镜像 - 将本地镜像推送至Minikube镜像仓库
  5. 部署应用 - 应用Kubernetes清单文件或Helm Chart

What is Minikube?

什么是Minikube？

Minikube runs a single-node Kubernetes cluster locally for development:
  • Local testing - Test K8s manifests without cloud costs
  • Fast iteration - Build, deploy, test cycles locally
  • Full K8s API - Supports most Kubernetes features
  • Cross-platform - Linux, macOS, Windows
Minikube 在本地运行单节点 Kubernetes 集群，用于开发工作：
  • 本地测试 - 无需云服务成本即可测试K8s清单文件
  • 快速迭代 - 在本地完成构建、部署、测试的循环
  • 完整K8s API - 支持大部分Kubernetes功能
  • 跨平台 - 支持Linux、macOS、Windows

System Requirements

系统要求

ResourceMinimumRecommended
CPUs24+
Memory2GB8GB+
Disk20GB50GB+
Container RuntimeDocker or PodmanDocker
资源最低要求推荐配置
CPU2核4核及以上
内存2GB8GB及以上
磁盘20GB50GB及以上
容器运行时Docker或PodmanDocker

Installation

安装

Linux

Linux

bash
undefined
bash
undefined

Download binary

下载二进制文件

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 sudo install minikube-linux-amd64 /usr/local/bin/minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 sudo install minikube-linux-amd64 /usr/local/bin/minikube

Verify installation

验证安装

minikube version
undefined
minikube version
undefined

macOS

macOS

bash
undefined
bash
undefined

Using Homebrew

使用Homebrew安装

brew install minikube
brew install minikube

Or download binary

或下载二进制文件

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64 sudo install minikube-darwin-amd64 /usr/local/bin/minikube
undefined
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64 sudo install minikube-darwin-amd64 /usr/local/bin/minikube
undefined

Windows

Windows

bash
undefined
bash
undefined

Using Chocolatey

使用Chocolatey安装

choco install minikube
choco install minikube

Or download installer from

或从以下链接下载安装程序

https://github.com/kubernetes/minikube/releases

https://github.com/kubernetes/minikube/releases

undefined
undefined

Starting Minikube

启动Minikube

Basic Start

基础启动

bash
undefined
bash
undefined

Start with defaults (2 CPU, 2GB RAM)

使用默认配置启动（2核CPU，2GB内存）

minikube start
minikube start

Start with more resources (recommended for this project)

使用推荐配置启动（适用于本项目）

minikube start --cpus=4 --memory=8192 --disk-size=50gb
undefined
minikube start --cpus=4 --memory=8192 --disk-size=50gb
undefined

Driver Options

驱动选项

bash
undefined
bash
undefined

Docker driver (default on most systems)

Docker驱动（多数系统默认）

minikube start --driver=docker
minikube start --driver=docker

Podman driver

Podman驱动

minikube start --driver=podman
minikube start --driver=podman

VirtualBox driver

VirtualBox驱动

minikube start --driver=virtualbox
undefined
minikube start --driver=virtualbox
undefined

Start Options

完整启动选项

bash
undefined
bash
undefined

With all recommended options

使用所有推荐选项启动

minikube start
--cpus=4
--memory=8192
--disk-size=50gb
--driver=docker
--container-runtime=docker
undefined
minikube start
--cpus=4
--memory=8192
--disk-size=50gb
--driver=docker
--container-runtime=docker
undefined

Minikube Addons

Minikube 插件

Enable Ingress

启用Ingress

bash
undefined
bash
undefined

Enable ingress controller

启用Ingress控制器

minikube addons enable ingress
minikube addons enable ingress

Verify

验证

kubectl get pods -n ingress-nginx
undefined
kubectl get pods -n ingress-nginx
undefined

Enable Metrics Server

启用Metrics Server

bash
undefined
bash
undefined

Enable metrics for HPA

启用指标服务以支持HPA

minikube addons enable metrics-server
minikube addons enable metrics-server

Verify

验证

kubectl top pods
undefined
kubectl top pods
undefined

List Available Addons

查看可用插件

bash
undefined
bash
undefined

See all available addons

查看所有可用插件

minikube addons list
minikube addons list

Enable multiple

启用多个插件

minikube addons enable ingress metrics-server registry
undefined
minikube addons enable ingress metrics-server registry
undefined

Managing Minikube

Minikube 管理

Status Check

状态检查

bash
undefined
bash
undefined

Check cluster status

检查集群状态

minikube status
minikube status

Expected output:

预期输出:

type: Control Plane

type: Control Plane

host: Running

host: Running

kubelet: Running

kubelet: Running

apiserver: Running

apiserver: Running

kubeconfig: Configured

kubeconfig: Configured

undefined
undefined

Stop and Start

停止与启动

bash
undefined
bash
undefined

Stop cluster

停止集群

minikube stop
minikube stop

Start again (preserves state)

重新启动（保留集群状态）

minikube start
minikube start

Delete and start fresh

删除集群并重新创建

minikube delete minikube start
undefined
minikube delete minikube start
undefined

Tunnel for External Access

隧道实现外部访问

bash
undefined
bash
undefined

If NodePort doesn't work

如果NodePort无法正常工作

minikube tunnel
minikube tunnel

This runs in foreground - keep separate terminal

此命令在前台运行 - 请使用单独的终端窗口

undefined
undefined

Loading Images to Minikube

向Minikube加载镜像

Why Load Images?

为什么需要加载镜像？

Minikube cannot access local Docker images by default. You must:
  1. Build image locally
  2. Load image into Minikube
  3. Deploy
Minikube 默认无法访问本地Docker镜像。您需要：
  1. 在本地构建镜像
  2. 将镜像加载至Minikube
  3. 部署应用

Load Commands

加载命令

bash
undefined
bash
undefined

Load single image

加载单个镜像

minikube image load todo-frontend:latest
minikube image load todo-frontend:latest

Load multiple images

加载多个镜像

minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest
minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest

Load all images

加载所有相关镜像

docker images --format "{{.Repository}}:{{.Tag}}" | grep todo | xargs minikube image load
undefined
docker images --format "{{.Repository}}:{{.Tag}}" | grep todo | xargs minikube image load
undefined

Image Load Workflow

镜像加载流程

bash
undefined
bash
undefined

Step 1: Build images

步骤1：构建镜像

docker build -t todo-frontend:latest ./frontend docker build -t todo-backend:latest ./backend docker build -t todo-mcp-server:latest -f backend/Dockerfile.mcp ./backend
docker build -t todo-frontend:latest ./frontend docker build -t todo-backend:latest ./backend docker build -t todo-mcp-server:latest -f backend/Dockerfile.mcp ./backend

Step 2: Start Minikube

步骤2：启动Minikube

minikube start
minikube start

Step 3: Load images

步骤3：加载镜像

minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest
minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest

Step 4: Verify

步骤4：验证

minikube image list
undefined
minikube image list
undefined

Applying Kubernetes Manifests

应用Kubernetes清单文件

Using kubectl

使用kubectl

bash
undefined
bash
undefined

Apply all manifests

应用所有清单文件

kubectl apply -f k8s/ -n todo-app
kubectl apply -f k8s/ -n todo-app

Apply single file

应用单个文件

kubectl apply -f k8s/00-namespace.yaml kubectl apply -f k8s/01-configmap.yaml kubectl apply -f k8s/02-secret.yaml
kubectl apply -f k8s/00-namespace.yaml kubectl apply -f k8s/01-configmap.yaml kubectl apply -f k8s/02-secret.yaml

Apply directory

应用目录下所有文件

kubectl apply -R -f k8s/
undefined
kubectl apply -R -f k8s/
undefined

Using Helm

使用Helm

bash
undefined
bash
undefined

Install with values

使用自定义配置安装

helm install todo-app ./helm/todo-app
--namespace todo-app
--create-namespace
-f helm/todo-app/values-dev.yaml
helm install todo-app ./helm/todo-app
--namespace todo-app
--create-namespace
-f helm/todo-app/values-dev.yaml

Or use default values

或使用默认配置安装

helm install todo-app ./helm/todo-app --namespace todo-app
undefined
helm install todo-app ./helm/todo-app --namespace todo-app
undefined

Accessing Services

访问服务

Port Forwarding

端口转发

bash
undefined
bash
undefined

Forward service to local port

将服务端口转发至本地端口

kubectl port-forward svc/frontend 8080:80 -n todo-app
kubectl port-forward svc/frontend 8080:80 -n todo-app

Access at http://localhost:8080

通过以下地址访问：http://localhost:8080

undefined
undefined

Minikube Service Command

Minikube Service命令

bash
undefined
bash
undefined

Open service in browser

在浏览器中打开服务

minikube service frontend -n todo-app
minikube service frontend -n todo-app

Get URL without opening

获取服务URL但不打开浏览器

minikube service frontend -n todo-app --url
undefined
minikube service frontend -n todo-app --url
undefined

Minikube IP

Minikube IP

bash
undefined
bash
undefined

Get Minikube IP

获取Minikube的IP地址

minikube ip
minikube ip

Access NodePort services

访问NodePort类型服务

http://$(minikube ip):<nodeport>

http://$(minikube ip):<nodeport>

undefined
undefined

Dashboard

仪表盘

bash
undefined
bash
undefined

Start dashboard

启动仪表盘

minikube dashboard
minikube dashboard

Access at: http://127.0.0.1:5xxxx

访问地址：http://127.0.0.1:5xxxx

Open in browser with URL

获取仪表盘URL并在浏览器中打开

minikube dashboard --url
undefined
minikube dashboard --url
undefined

Troubleshooting Minikube

Minikube 故障排查

Issue: Minikube won't start

问题：Minikube无法启动

bash
undefined
bash
undefined

Check prerequisites

检查前置条件

minikube check
minikube check

Common fixes:

常见修复方案:

1. Update minikube

1. 更新Minikube

2. Restart Docker Desktop

2. 重启Docker Desktop

3. Delete .minikube directory: rm -rf ~/.minikube

3. 删除.minikube目录：rm -rf ~/.minikube

4. Try different driver

4. 尝试使用其他驱动

undefined
undefined

Issue: Images not found

问题：镜像未找到

bash
undefined
bash
undefined

Verify image is loaded

验证镜像是否已加载

minikube image list
minikube image list

If not loaded, re-run load command

如果未加载，重新运行加载命令

minikube image load todo-frontend:latest
undefined
minikube image load todo-frontend:latest
undefined

Issue: Pods in Pending state

问题：Pod处于Pending状态

bash
undefined
bash
undefined

Check resources

检查资源使用情况

kubectl top nodes
kubectl top nodes

Check events

查看事件

kubectl describe pod <pod-name> -n todo-app
kubectl describe pod <pod-name> -n todo-app

May need to increase Minikube resources

可能需要增加Minikube资源

minikube stop minikube start --cpus=4 --memory=8192
undefined
minikube stop minikube start --cpus=4 --memory=8192
undefined

Issue: CrashLoopBackOff

问题：CrashLoopBackOff状态

bash
undefined
bash
undefined

View logs

查看日志

kubectl logs <pod-name> -n todo-app
kubectl logs <pod-name> -n todo-app

View previous logs

查看之前的日志

kubectl logs <pod-name> -n todo-app --previous
kubectl logs <pod-name> -n todo-app --previous

Describe pod for events

查看Pod详情及事件

kubectl describe pod <pod-name> -n todo-app
undefined
kubectl describe pod <pod-name> -n todo-app
undefined

Issue: Ingress not working

问题：Ingress无法工作

bash
undefined
bash
undefined

Verify ingress addon

验证Ingress插件状态

minikube addons list | grep ingress
minikube addons list | grep ingress

Enable if missing

如果未启用，启用插件

minikube addons enable ingress
minikube addons enable ingress

Add host entry (for todo.local)

添加主机映射（以todo.local为例）

echo "$(minikube ip) todo.local" | sudo tee -a /etc/hosts
undefined
echo "$(minikube ip) todo.local" | sudo tee -a /etc/hosts
undefined

Integration with Project

与项目集成

Todo Project Minikube Workflow

Todo项目Minikube工作流

bash
undefined
bash
undefined

1. Start Minikube with adequate resources

1. 使用足够资源启动Minikube

minikube start --cpus=4 --memory=8192 --disk-size=50gb
minikube start --cpus=4 --memory=8192 --disk-size=50gb

2. Enable required addons

2. 启用所需插件

minikube addons enable ingress metrics-server
minikube addons enable ingress metrics-server

3. Build Docker images

3. 构建Docker镜像

docker build -t todo-frontend:latest ./frontend docker build -t todo-backend:latest ./backend docker build -t todo-mcp-server:latest -f backend/Dockerfile.mcp ./backend
docker build -t todo-frontend:latest ./frontend docker build -t todo-backend:latest ./backend docker build -t todo-mcp-server:latest -f backend/Dockerfile.mcp ./backend

4. Load images into Minikube

4. 将镜像加载至Minikube

minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest
minikube image load todo-frontend:latest todo-backend:latest todo-mcp-server:latest

5. Create namespace

5. 创建命名空间

kubectl create namespace todo-app
kubectl create namespace todo-app

6. Create secrets

6. 创建密钥

kubectl create secret generic backend-secrets
--from-literal=GEMINI_API_KEY=${GEMINI_API_KEY}
--from-literal=BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
-n todo-app
kubectl create secret generic backend-secrets
--from-literal=GEMINI_API_KEY=${GEMINI_API_KEY}
--from-literal=BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
-n todo-app

7. Apply manifests

7. 应用清单文件

kubectl apply -f k8s/ -n todo-app
kubectl apply -f k8s/ -n todo-app

8. Verify deployment

8. 验证部署

kubectl get pods -n todo-app kubectl get svc -n todo-app
kubectl get pods -n todo-app kubectl get svc -n todo-app

9. Access application

9. 访问应用

minikube service frontend -n todo-app
undefined
minikube service frontend -n todo-app
undefined

Cleanup

清理

bash
undefined
bash
undefined

Stop Minikube

停止Minikube

minikube stop
minikube stop

Delete cluster

删除集群

minikube delete
minikube delete

Clear all data

清理所有数据

rm -rf ~/.minikube
rm -rf ~/.minikube

Delete namespace

删除命名空间

kubectl delete namespace todo-app
undefined
kubectl delete namespace todo-app
undefined

Verification Checklist

验证清单

After Minikube setup:
  • Minikube is running (
    minikube status
    )
  • kubectl is configured
  • Ingress addon is enabled
  • All images are loaded (
    minikube image list
    )
  • Namespace 
    todo-app
    exists
  • Secrets are created
  • All pods are Running
  • All services have endpoints
  • Application is accessible in browser
  • Frontend can connect to backend
  • Backend can connect to MCP server
完成Minikube搭建后：
  • Minikube 正在运行（
    minikube status
    ）
  • kubectl 已配置完成
  • Ingress插件已启用
  • 所有镜像已加载（
    minikube image list
    ）
  • 命名空间
    todo-app
    已存在
  • 密钥已创建
  • 所有Pod处于Running状态
  • 所有服务已分配端点
  • 应用可在浏览器中访问
  • 前端可连接至后端
  • 后端可连接至MCP服务器

Common Commands Reference

常用命令参考

bash
undefined
bash
undefined

Daily workflow

日常工作流

minikube start # Start cluster kubectl get pods -n todo-app # Check status minikube dashboard # Open dashboard minikube service frontend -n todo-app # Access app
minikube start # 启动集群 kubectl get pods -n todo-app # 检查状态 minikube dashboard # 打开仪表盘 minikube service frontend -n todo-app # 访问应用

Debugging

调试

kubectl logs -f deployment/backend -n todo-app # View logs kubectl describe pod <pod-name> -n todo-app # Debug pod kubectl exec -it <pod-name> -n todo-app -- sh # Shell in pod
kubectl logs -f deployment/backend -n todo-app # 查看日志 kubectl describe pod <pod-name> -n todo-app # 调试Pod kubectl exec -it <pod-name> -n todo-app -- sh # 进入Pod终端

Cleanup

清理

minikube stop # Stop cluster minikube delete # Delete cluster
undefined
minikube stop # 停止集群 minikube delete # 删除集群
undefined

Next Steps

下一步

After successful Minikube deployment:
  1. Test all application features
  2. Verify AI chatbot works end-to-end
  3. Prepare for cloud deployment (Phase 5)
  4. Review Helm charts for production use
成功部署Minikube后：
  1. 测试应用的所有功能
  2. 验证AI聊天机器人端到端运行正常
  3. 准备云环境部署（第5阶段）
  4. 为生产环境优化Helm Chart

References

参考资料