Local YDB Docker 镜像文档

镜像概述

Local YDB 是一个单节点的 YDB 测试集群 Docker 镜像，专为本地开发、调试 YQL 查询及 CI（持续集成）流程设计。它提供了简单的部署方式，可快速搭建独立的 YDB 环境，无需复杂的集群配置，适合开发人员在本地验证功能或集成到自动化测试流程中。

核心功能与特性

单节点部署：无需复杂集群配置，一键启动完整的 YDB 测试环境
Web 监控界面：内置 Web UI，可直观监控集群状态与指标
多端口支持：包含 gRPC 端口（TLS 与非 TLS）、监控端口及 Kafka 代理端口
数据持久化：支持通过卷挂载持久化存储证书和数据
灵活标签策略：提供多种标签版本，满足稳定版、测试版等不同场景需求

使用场景

本地开发环境：开发人员在本地快速搭建 YDB 环境进行功能开发
YQL 查询调试：直接在本地测试和调试 YQL 查询语句
CI/CD 流程：集成到自动化测试流程中，作为测试环境验证代码变更
功能验证：验证 YDB 新特性或配置变更的效果

使用方法

运行容器

使用以下命令启动 Local YDB 容器：

bash
docker run -d --rm --name ydb-local -h localhost \
  --platform linux/amd64 \
  -p 2135:2135 -p 2136:2136 -p 8765:8765 -p 9092:9092 \
  -v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
  -e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
  -e YDB_KAFKA_PROXY_PORT=9092 \
  ydbplatform/local-ydb:latest

参数说明

参数	说明
`-d`	后台运行容器
`--rm`	容器停止后自动删除
`--name ydb-local`	指定容器名称为 `ydb-local`
`-h localhost`	设置容器主机名为 `localhost`
`--platform linux/amd64`	指定平台为 x86_64（必需，因镜像暂不支持 ARM 原生架构）
端口映射	`-p 2135:2135`（gRPC TLS 端口）、`-p 2136:2136`（gRPC 端口）、`-p 8765:8765`（监控端口）、`-p 9092:9092`（Kafka 代理端口）
卷挂载	`-v $(pwd)/ydb_certs:/ydb_certs`（证书存储）、`-v $(pwd)/ydb_data:/ydb_data`（数据存储）
环境变量	`GRPC_TLS_PORT`（gRPC TLS 端口）、`GRPC_PORT`（gRPC 端口）、`MON_PORT`（监控端口）、`YDB_KAFKA_PROXY_PORT`（Kafka 代理端口）

Apple Silicon 处理器用户注意事项

若使用搭载 Apple Silicon 处理器的 Mac，需通过 Rosetta 模拟 x86_64 CPU 指令集：

使用 colima：执行 colima start --arch aarch64 --vm-type=vz --vz-rosetta 启动
使用 Docker Desktop：确保已安装并启用 Rosetta 2

Web UI 访问

YDB Web 监控界面可通过以下地址访问：
http://localhost:8765

标签命名规则

标签格式	描述
`latest`	对应生产集群测试过的最新稳定版YDB，每个新版本发布时重建。当前 `latest` 标签的 YDB 版本为 24.3.11-hotfix.13
`edge`	下一稳定版的候选版本，正在测试中。包含新功能，但可能不稳定，不适合生产环境。
`trunk`、`main`、`nightly`	主开发分支的最新版本，包含所有近期变更，每日重建。与 `edge` 类似，不适合生产环境。
`XX.Y`	对应主版本 `XX.Y` 中的最新次版本，包含所有补丁。
`XX.Y.ZZ`	对应 YDB 发布版本 `XX.Y.ZZ`。
`XX.Y-slim`、`XX.Y.ZZ-slim`	YDB 压缩二进制版本（包含 `ydbd` 和 `ydb` 命令行工具），镜像体积更小但启动速度较慢，使用 UPX 压缩。