MBE 文档中心

🐳 不使用 Docker Desktop GUI 的部署指南

📋 概述

当 Docker Desktop GUI 无法启动时，您仍然可以使用命令行管理 Docker 并部署 MBE 项目。本指南提供完整的解决方案。

✅ Docker Desktop GUI 无法启动时的解决方案

情况 1: Docker daemon 正常运行（推荐）

症状：

  • docker --version 可以运行
  • docker ps 可以列出容器
  • 但 Docker Desktop GUI 无法启动

解决方案： ✅ 直接使用命令行 - Docker daemon 正常运行，无需 GUI

# 检查 Docker 状态
.\scripts\check-docker-status.ps1

# 使用部署脚本
.\scripts\deploy-without-desktop.ps1 -Environment dev

情况 2: Docker daemon 未运行

症状：

  • docker info 报错：Cannot connect to the Docker daemon
  • docker ps 无法执行

解决方案：

方案 A: 通过 WSL2 启动 Docker

# 1. 检查 WSL2
wsl --list --verbose

# 2. 启动 docker-desktop 发行版
wsl -d docker-desktop

# 3. 在 WSL2 中启动 Docker
sudo service docker start

# 4. 返回 Windows，验证
docker ps

方案 B: 安装 Docker Engine for Windows

# 使用 Chocolatey 安装
choco install docker-engine

# 或使用 winget
winget install Docker.DockerEngine

方案 C: 重启 Docker Desktop 服务

# 1. 停止所有 Docker 进程
taskkill /F /IM "Docker Desktop.exe" /T
wsl --shutdown

# 2. 重新启动 Docker Desktop
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

🚀 部署步骤（不使用 Docker Desktop GUI）

1. 检查 Docker 环境

# 运行检查脚本
cd d:\Mises\mbe-monorepo
.\scripts\check-docker-status.ps1

2. 配置环境变量

# 复制环境变量模板
Copy-Item .env.example .env

# 编辑 .env 文件，配置 Cloudflare Tunnel Token
notepad .env

必需配置：

# Cloudflare Tunnel Token（从 Cloudflare Dashboard 获取）
CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoixxxxxx...

# 数据库配置
POSTGRES_PASSWORD=your_password
REDIS_PASSWORD=your_redis_password

# LLM 配置
LLM_PROVIDER=deepseek
LLM_API_KEY=your_api_key

3. 部署服务

开发环境部署

# 使用部署脚本（推荐）
.\scripts\deploy-without-desktop.ps1 -Environment dev

# 或手动部署
docker compose -f docker-compose.dev.yml build
docker compose -f docker-compose.dev.yml up -d
docker compose -f docker-compose.cloudflare.yml up -d

生产环境部署

# 使用部署脚本
.\scripts\deploy-without-desktop.ps1 -Environment prod

# 或手动部署
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.cloudflare.yml up -d

🔍 常用 Docker 命令（无需 GUI）

查看容器状态

# 列出所有容器
docker ps -a

# 查看特定容器
docker ps --filter "name=mbe-api"

# 查看容器详细信息
docker inspect mbe-api-dev

查看日志

# 查看所有服务日志
docker compose -f docker-compose.dev.yml logs

# 查看特定服务日志
docker compose -f docker-compose.dev.yml logs mbe-api

# 实时跟踪日志
docker compose -f docker-compose.dev.yml logs -f mbe-api

# 查看 Cloudflare Tunnel 日志
docker logs mbe-cloudflared

管理容器

# 启动服务
docker compose -f docker-compose.dev.yml start

# 停止服务
docker compose -f docker-compose.dev.yml stop

# 重启服务
docker compose -f docker-compose.dev.yml restart

# 停止并删除容器
docker compose -f docker-compose.dev.yml down

# 停止并删除容器和卷（⚠️ 会删除数据）
docker compose -f docker-compose.dev.yml down -v

进入容器

# 进入 API 容器
docker exec -it mbe-api-dev bash

# 进入数据库容器
docker exec -it mbe-dev-postgres psql -U mbe -d mbe_dev

构建镜像

# 构建镜像
docker compose -f docker-compose.dev.yml build

# 强制重新构建
docker compose -f docker-compose.dev.yml build --no-cache

# 构建特定服务
docker compose -f docker-compose.dev.yml build mbe-api

🏥 健康检查

检查服务状态

# 检查 API 健康状态
curl http://localhost:8001/api/health

# 检查开发环境
curl http://localhost:8001/api/health

# 检查生产环境
curl http://localhost:8000/api/health

检查 Cloudflare Tunnel

# 查看 Tunnel 状态
docker logs mbe-cloudflared

# 检查 Tunnel 连接
# 访问 Cloudflare Dashboard: https://one.dash.cloudflare.com/
# Networks → Tunnels → 查看 Tunnel 状态

🔧 故障排查

问题 1: Docker 命令无法执行

解决方案：

# 检查 Docker 是否安装
where.exe docker

# 检查 PATH 环境变量
$env:PATH -split ';' | Select-String docker

# 如果 Docker 未在 PATH 中，手动添加
$env:PATH += ";C:\Program Files\Docker\Docker\resources\bin"

问题 2: 无法连接到 Docker daemon

解决方案：

# 1. 检查 Docker 服务状态（如果使用 Docker Engine）
Get-Service docker

# 2. 启动 Docker 服务
Start-Service docker

# 3. 或通过 WSL2 启动
wsl -d docker-desktop
sudo service docker start

问题 3: 端口被占用

解决方案：

# 检查端口占用
netstat -ano | findstr :8000

# 停止占用端口的进程
taskkill /PID <PID> /F

# 或修改 docker-compose.yml 中的端口映射

问题 4: Cloudflare Tunnel 无法连接

解决方案：

# 1. 检查 Tunnel Token
docker logs mbe-cloudflared

# 2. 验证 Token 是否正确
# 在 Cloudflare Dashboard 重新生成 Token

# 3. 重启 Tunnel
docker compose -f docker-compose.cloudflare.yml restart cloudflared

📚 相关文档

✅ 检查清单

部署前确保：

  • Docker 命令可用 (docker --version)
  • Docker daemon 运行 (docker info)
  • 环境变量已配置 (.env 文件)
  • Cloudflare Tunnel Token 已设置
  • 端口未被占用
  • 有足够的磁盘空间

提示: 即使 Docker Desktop GUI 无法启动，只要 Docker daemon 正常运行，您就可以完全使用命令行管理所有 Docker 操作。