跳到主要内容
版本: 最新版本-3.5

使用 Docker 设置开发环境

此目录为 StarRocks 提供了基于 Docker 的构建工具，它使用官方的 starrocks/dev-env-ubuntu:latest 开发环境镜像。这通过使用标准化的 Ubuntu 环境（预先安装了所有必需的工具链和依赖项）来确保跨不同主机系统的一致构建。

🚀 快速开始​

前提条件​

  • Docker 已安装并运行
  • Docker 可用内存至少为 8GB
  • 至少 20GB 可用磁盘空间

简单命令​

# Open development shell
./docker-dev.sh shell

# Build Frontend only
./docker-dev.sh build-fe

# Build Backend only  
./docker-dev.sh build-be

# Build everything
./docker-dev.sh build-all

# Clean build everything
./docker-dev.sh clean-build

# Run Frontend tests
./docker-dev.sh test-fe

📋 可用工具​

1. build-in-docker.sh - 全功能构建脚本​

主构建脚本，自动传递所有 build.sh 选项

# Basic usage
./build-in-docker.sh                          # Build all (FE + BE)
./build-in-docker.sh --fe                     # Build Frontend only
./build-in-docker.sh --be                     # Build Backend only
./build-in-docker.sh --fe --be --clean        # Clean and build both

# Advanced options
./build-in-docker.sh --be --with-gcov          # Build BE with code coverage
./build-in-docker.sh --fe --disable-java-check-style  # Skip checkstyle
./build-in-docker.sh --be -j 8                 # Build with 8 parallel jobs

# Development
./build-in-docker.sh --shell                  # Interactive shell
./build-in-docker.sh --test                   # Build and run tests

# Custom image
./build-in-docker.sh --image starrocks/dev-env-ubuntu:latest --fe

# Future build.sh options work automatically
./build-in-docker.sh --be --new-future-option

2. docker-dev.sh - 简单包装器​

用于常见任务的快速命令

./docker-dev.sh shell           # Development shell
./docker-dev.sh build-fe        # Build Frontend
./docker-dev.sh build-be        # Build Backend
./docker-dev.sh build-all       # Build everything
./docker-dev.sh clean-build     # Clean and build all
./docker-dev.sh test-fe         # Run FE tests
./docker-dev.sh test-be         # Run BE tests
./docker-dev.sh test-all        # Run all tests

# Pass through any build.sh options
./docker-dev.sh build --be --with-gcov
./docker-dev.sh build --fe --new-option

3. docker-compose.dev.yml - Docker Compose​

用于持久开发环境

# Start development shell
docker-compose -f docker-compose.dev.yml run --rm starrocks-dev

# Build Frontend
docker-compose -f docker-compose.dev.yml run --rm build-fe

# Build Backend
docker-compose -f docker-compose.dev.yml run --rm build-be

# Run tests
docker-compose -f docker-compose.dev.yml run --rm test-fe
docker-compose -f docker-compose.dev.yml run --rm test-be

# Clean up
docker-compose -f docker-compose.dev.yml down -v

🔧 配置​

卷挂载​

Docker 脚本自动挂载

  • 源代码：$(pwd):/workspace - 您的本地存储库
  • Maven 缓存：~/.m2:/tmp/.m2 - Maven 依赖项缓存，用于更快的构建

注意：Maven 缓存在您的主机系统和 Docker 容器之间共享，因此在构建期间下载的依赖项会被持久化并在构建会话之间重复使用。

环境变量​

# Use different Docker image
export STARROCKS_DEV_ENV_IMAGE=starrocks/dev-env-ubuntu:latest

# Additional Docker options
export DOCKER_BUILD_OPTS="--memory=16g --cpus=8"

# Set user ID for file permissions
export UID=$(id -u)
export GID=$(id -g)

自定义构建选项​

支持所有原始的 build.sh 选项

# Backend build types
BUILD_TYPE=Debug ./build-in-docker.sh --be      # Debug build
BUILD_TYPE=Release ./build-in-docker.sh --be    # Release build (default)
BUILD_TYPE=Asan ./build-in-docker.sh --be       # AddressSanitizer build

# Feature flags
./build-in-docker.sh --be --enable-shared-data  # Enable shared data
./build-in-docker.sh --be --with-gcov           # Code coverage
./build-in-docker.sh --be --with-bench          # Benchmarks
./build-in-docker.sh --be --without-avx2        # Disable AVX2

📁 输出和工件​

构建工件在 output/ 目录中创建

output/
├── fe/                 # Frontend artifacts
├── be/                 # Backend artifacts
└── java-extensions/    # Java extensions

Docker 容器挂载您的本地存储库和 Maven 缓存，因此所有构建输出都可以在您的主机系统上使用，并且依赖项会被缓存以加快后续构建。

多用户支持：容器名称包括用户名和用户 ID，以防止在共享开发机器上发生冲突（例如，starrocks-build-username-1001-1234567890）。

自动可扩展性：所有无法识别的选项都会自动传递给 build.sh，因此新的构建选项无需更新 Docker 脚本即可工作。

🐛 故障排除​

常见问题​

  1. 权限问题

    # Fix file permissions
    sudo chown -R $(id -u):$(id -g) output/

    # Or run with correct user
    export UID=$(id -u) GID=$(id -g)
    ./build-in-docker.sh --fe

  2. 内存不足

    # Increase Docker memory limit or reduce parallel jobs
    ./build-in-docker.sh --be -j 2

  3. 找不到 Docker 镜像

    # Pull the image manually
    docker pull starrocks/dev-env-ubuntu:latest

  4. 构建失败

    # Clean build
    ./build-in-docker.sh --clean --fe --be

    # Check logs in interactive shell
    ./build-in-docker.sh --shell

调试模式​

用于调试构建问题

# Open shell and run commands manually
./build-in-docker.sh --shell

# Inside container:
./build.sh --fe --clean
./run-fe-ut.sh

🔍 验证​

测试一切正常

# 1. Test Docker setup
docker --version
docker info

# 2. Test image availability
docker pull starrocks/dev-env-ubuntu:latest

# 3. Test build scripts
./docker-dev.sh shell
# Inside container: exit

# 4. Test simple build
./docker-dev.sh build-fe

📊 性能提示​

  1. 使用并行构建：./build-in-docker.sh --be -j $(nproc)
  2. Maven 缓存：从 ~/.m2 自动挂载，用于更快的依赖项解析
  3. 内存分配：增加 Docker 内存限制以加快构建速度
  4. SSD 存储：为 Docker 存储驱动程序使用 SSD
  5. 持久卷：使用 Docker Compose 实现额外的缓存持久性

🤝 与 IDE 集成​

带有 Dev Containers 的 VS Code​

创建 .devcontainer/devcontainer.json

{
    "name": "StarRocks Dev Environment",
    "image": "starrocks/dev-env-ubuntu:latest",
    "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
    "workspaceFolder": "/workspace",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-vscode.cpptools",
                "redhat.java"
            ]
        }
    }
}

IntelliJ IDEA​

使用 Docker 集成在容器环境中运行构建和测试。

📚 附加资源​

🆘 支持​

如果您遇到问题

  1. 检查上面的故障排除部分
  2. 验证 Docker 设置和镜像可用性
  3. 尝试使用 --clean 标志进行干净构建
  4. 打开一个包含构建日志和系统信息的 Issue