# openStarProxy

**Repository Path**: StarDB/openstarproxy

## Basic Information

- **Project Name**: openStarProxy
- **Description**: StarDB分布式计算引擎
- **Primary Language**: Go
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StarDB
[[GPLv3]](LICENSE)
[[Latest Release: v6.6.0]](https://gitee.com/StarDB/openstarproxy/tree/v6.6.0)

## 一、项目说明
StarDB 是一款**云原生、可水平扩展的分布式 MySQL 兼容数据库系统**，专为解决大规模 MySQL 部署面临的分片扩容、连接风暴、高可用运维等核心痛点而设计。它在保留 MySQL 完整关系型特性（事务、JOIN、二级索引、标准 SQL）的同时，兼具 NoSQL 数据库的弹性扩展能力，无需大幅改造现有 MySQL 应用即可实现规模化部署。

## 二、核心特性
- **水平扩展能力**：StarDB 通过通用分片技术实现无限扩展。它允许应用程序代码和数据库查询无需感知数据在多个数据库服务器上的分布。随着业务增长，您可以随时拆分和合并分片，整个切换过程只需几秒钟。

- **云原生架构**：基于云原生原则构建，StarDB 在容器化环境和Kubernetes中高效运行。提供内置的连接池、查询路由和负载均衡功能。

- **MySQL完全兼容**：StarDB 完全兼容MySQL协议，让您可以无需修改地使用现有的MySQL驱动程序、ORM和工具。在支持大部分MySQL语法和功能的同时，增加了强大的分片能力。

- **高可用性保障**：StarDB 包含内置的故障转移和复制管理功能。它可以自动检测主节点故障并提升新的主节点，确保最小的停机时间和数据一致性。

- **智能连接池与查询优化**：StarDB 提供智能连接池和查询路由，减少连接开销并提升性能。它可以重写查询以在分片数据库中高效执行。

- **运维简化**：StarDB 通过在线架构变更、自动备份和监控集成等功能简化数据库运维。提供CLI工具和基于Web的管理界面。

## 三、部署架构
StarDB 采用**分层分布式架构**，核心分为「前端接入层」、「控制平面」、「数据平面」三层，底层依托 MySQL 提供数据持久化，整体架构解耦且可独立扩容，具体如下：

### 1. 整体架构分层
| 架构分层       | 核心组件                | 核心职责                                                                 |
|----------------|-------------------------|--------------------------------------------------------------------------|
| 前端接入层     | starproxy                  | 统一数据库入口，解析 SQL、分片路由、结果合并，为应用提供单库访问视图，兼容 MySQL 协议 |
| 控制平面       | starctld、starha、ZooKeeper/etcd | 集群拓扑管理、分片配置维护、主从故障自动恢复、运维操作执行（分片拆分/合并、主从切换） |
| 数据平面       | staragent、MySQL | 每个 staragent 绑定一个 MySQL 实例，负责连接复用、数据复制、分片逻辑落地，支持主/从/只读节点角色 |

### 2. 核心部署拓扑
- **单集群部署**：适用于中小规模业务，所有组件部署在同一集群，通过 ZooKeeper starproxy 提供负载均衡入口。
- **多数据中心部署**：适用于大规模高可用需求，跨地域部署数据平面节点，控制平面统一管控，支持数据异地容灾与读写分离。
- **Kubernetes 云原生部署**：推荐生产环境采用，通过operator实现集群的自动化部署、扩缩容与运维，兼容 Helm 包管理。

### 3. 关键特性与架构优势
- 透明分片：应用无需感知数据分布，分片调整（拆分/合并）对应用无侵入。
- 高可用：自动主从切换、故障节点隔离，保证数据不丢失且服务不中断。
- 资源隔离：不同业务可映射到独立分片或 Keyspace，避免资源竞争。
- 连接优化：staragent 实现 MySQL 连接复用，解决高并发下的连接风暴问题。

## 三、如何编译
StartDB 核心使用 Go 语言开发（部分组件含 Java 客户端实现），支持 Linux、macOS 系统编译，暂不支持 Windows 原生编译（可通过 WSL 兼容）。

### 1. 前置依赖准备
#### 必备依赖
- Go 1.19+（推荐 Go 1.21，需符合当前 StartDB 版本的 Go 兼容要求）
- Git
- Make
- GCC/G++（用于编译 CGO 依赖与部分底层组件）

#### 可选依赖（按需安装）
- Docker & Docker Compose：用于本地测试与镜像构建
- Kubernetes & kubectl：用于云原生部署验证
- MySQL 开发包（libmysqlclient-dev）：用于增强 MySQL 兼容性
- ZooKeeper/etcd：用于本地集群拓扑存储

#### 依赖安装示例（macOS 环境）
macOS 推荐使用 Homebrew 包管理器安装依赖，未安装 Homebrew 的用户可先执行以下命令安装：
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
安装必备依赖：
```bash
# 更新 Homebrew 包索引
brew update

# 安装必备工具链
brew install git make gcc go

# 验证安装结果
git --version
make --version
gcc --version
go version
```

### 2. 源码克隆
```bash
# 克隆 StarDB 源码仓库
git clone git@coding.jd.com:openStarDB/open_stardb_proxy.git
cd StarDBProxy
```

### 3. 编译方式
 StarDB 提供 `make` 命令行工具实现一键编译，支持全量编译与单个组件编译。

#### 方式一：全量编译（推荐，生成所有核心组件与工具）
```bash
# 全量编译，编译产物输出到 ./bin 目录
make build
```

#### 方式二：单个组件编译（按需编译，节省时间）
```bash
# 示例：仅编译 sqlparser 模块
make sqlparser
```

#### 方式三：Debug模式（方便运行调试）
```bash
# 示例：Debug
make debug
```

### 4. 编译验证
```bash
# 查看编译产物（./bin 目录下包含所有核心组件）
ls ./bin

# 验证 starproxy 版本
./bin/starproxy --version

# 验证 staragent 版本
./bin/staragent --version
```

## 四、单元测试
Vitess 单元测试覆盖核心组件的核心逻辑，基于 Go 原生 `testing` 包实现，支持全量单元测试与单个包/组件的单元测试。

### 1. 前置准备
确保已完成源码克隆与依赖安装，编译环境正常（无需完整编译产物，单元测试会自动编译所需依赖）。

### 2. 全量单元测试
```bash
# 运行所有单元测试
make test

# 运行特定包的测试
make unit_test PACKAGE=starproxy
make unit_test PACKAGE=staragent

# 也可以使用go test发起
go test -failfast ./go/star/starproxy/planbuilder ./go/star/starproxy/engine ./go/star/starproxy/shards ./go/star/sqlparser/ -v -coverprofile=cover.out
```

### 3. 单个包/组件单元测试
```bash
# 示例：测试单个测试用例（-run 指定用例名称正则）
go test -run TestParseNextValid ./go/vt/sqlparser/
```

### 4. 单元测试结果说明
- 测试通过：终端输出 `ok` 后跟对应包路径与测试耗时。
- 测试失败：终端输出 `FAIL` 后跟对应包路径，同时打印错误详情与堆栈信息，可根据提示排查问题。
- 测试报告：默认无额外报告输出，如需生成测试覆盖率报告，可添加 `-coverprofile` 参数

## 五、集成测试
StarDB 集成测试用于验证组件间的协同工作能力、与 MySQL 的兼容性以及分布式场景下的功能完整性，分为「本地集成测试」与「容器化集成测试」两种方式。

### 1. 前置准备
- 完成源码克隆、依赖安装，确保 Docker & Docker Compose 已安装并启动（容器化集成测试必备）。
- 本地环境需预留足够端口（默认占用 15306、15991 等端口，避免端口冲突）。

### 2. 方式一：本地集成测试（基于内置 MySQL 模拟集群）
```bash
# 运行集成测试
make site_integration_test

# 运行端到端测试
make e2e_test

# 也可以使用go test发起
go run test.go -docker=false -flavor=mysql80 -tag="split-table" -print-log=true -debug
```

### 3. 集成测试注意事项
- 集成测试耗时较长（全量测试通常需要 30 分钟以上），建议在集群测试环境运行。
- 测试过程中会创建临时数据库与数据，测试完成后会自动清理。
- 若测试失败，可查看对应组件的日志排查问题。


## 六、贡献指南
我们致力于构建一个开放、友好的环境，让所有贡献者都能参与到这个激动人心的项目中来。无论您是修复小错误还是开发重大新功能，您的贡献都非常宝贵。
### 1. 贡献前准备
- 熟悉项目的核心架构、功能特性与使用场景。
- 了解当前待解决的问题与开发计划。
- 与核心开发者交流，明确贡献方向。

### 2. 搭建开发环境
参考项目 README.md 中的 **编译指南**，完成本地开发环境的搭建，确保能正常编译、运行单元测试与集成测试。

### 3. 贡献类型与方式
#### 代码贡献
##### （1）选择贡献任务
- **自选题任务**：如果你发现项目的 Bug 或有新功能想法，可先在 Issues 中创建议题，与大家讨论方案的可行性，避免重复开发。
##### （2）分支规范
- **主分支**：`main` 分支为开发分支，包含最新的开发代码；稳定版本会发布在带有版本号的标签分支（如 `v6.3.x`）。
- **分支命名**：从 `main` 分支创建个人开发分支，命名格式建议为：
  - 修复 Bug：`fix-[issue-id]-[bug-description]`（例：`fix-1234-connection-leak`）
  - 新功能开发：`feature-[issue-id]-[feature-name]`（例：`feature-5678-starproxy-cache`）
  
##### （3）代码规范
- 遵循 Go 语言官方规范（[Effective Go](https://go.dev/doc/effective_go)），确保代码风格统一。
- 新增代码必须配套**单元测试**，覆盖率不低于项目平均水平；涉及功能变更的代码，需补充**集成测试**。
- 代码提交前运行 `make lint` 检查代码风格，确保无语法错误与格式问题。

##### （4）提交 Commit 信息
Commit 信息需清晰描述变更内容，格式建议为：
```
fix #issue-id  // 关联对应的 Issue 编号
[模块名]: 简短描述变更内容（不超过 50 字符）
详细描述变更的原因、实现方案、影响范围（可选）
```
示例：
```
fix #1234
starproxy: 优化分片路由算法的性能

1. 减少路由规则的重复计算，提升查询效率 20%；
2. 修复边界条件下的路由错误问题。
```
### 4. Pull Request 流程
1. **Fork 仓库**：点击仓库页面的 `Fork` 按钮，将仓库复制到个人账号下。
2. **克隆仓库**：将个人 Fork 的仓库克隆到本地：
3. **创建开发分支**：基于 `master` 分支创建新的开发分支。
4. **开发与测试**：完成代码编写后，运行单元测试与集成测试，确保所有测试用例通过。
5. **推送分支**：将开发分支推送到个人 Fork 仓库：
   ```bash
   git push origin [你的分支名]
   ```
6. **创建 Pull Request**：
   - 打开个人 Fork 仓库页面，点击 `Compare & pull request` 按钮；
   - 目标分支选择 `master`，填写 Pull Request 描述，说明变更内容、解决的问题、测试情况；
   - 提交 Pull Request，等待社区评审。
7. **评审与修改**：
   - 项目维护者会对 Pull Request 进行评审，提出修改意见；
   - 根据评审意见在本地修改代码，重新推送分支，Pull Request 会自动更新；
   - 评审通过后，维护者会将你的代码合并到主分支。
### 5. 邮件列表
讨论邮件列表：[stardb@starever.net.cn](mailto:stardb@starever.net.cn)
   
---
StarDB —— 让 MySQL 轻松支撑海量业务，拥抱云原生分布式架构。