## 前言

最近在研究  [OpenTenBase](https://github.com/OpenTenBase) 的源码与部署，原本以为像 PostgreSQL 一样简单编译即可，结果真正上手后才发现：

**OpenTenBase 的部署复杂度远超预期。**

尤其是：
- GTM 初始化
- CN / DN 节点注册
- pgxc_ctl 配置
- Docker 环境兼容
- 配置依赖问题

踩坑过程一度让我怀疑人生（可以查看我的往期文章[OpenTenBase 5.0 编译与使用实践](https://cloud.tencent.com/developer/article/2567131)）对于学生小白上手一些难度。

于是我决定：**把 OpenTenBase 做成 Debian + Docker 化部署方案，尽可能降低开发与测试门槛。**

---

## 一、为什么 OpenTenBase 难部署

### 1.1 架构复杂度

OpenTenBase 不是单机数据库，而是典型的分布式架构：

![OpenTenBase 集群架构](https://developer.qcloudimg.com/http-save/yehe-11827391/708ac56714a152f7ab9554d11a5b7aba.png)

这就意味着：
- 需要分别初始化 3 种角色
- 需要配置节点注册到 `pgxc_node` 表
- 需要配置 GTM 连接
- 需要配置连接池和转发端口

### 1.2 官方部署的痛点

OpenTenBase 官方仓库的部署流程：

![官方部署流程截图](https://developer.qcloudimg.com/http-save/yehe-11827391/3709cc9d324d18cff2ffb9d07e2b6128.png)

这是纯手动配置，而且：
- 任何一个步骤出错，整个集群无法启动
- 端口冲突、权限问题、配置错误频繁出现
- 多机部署更复杂，需要配置网络和防火墙
- 清理残留文件非常麻烦

### 1.3 开发环境的困境

对于想研究源码的开发者来说：
- 每次修改都要重新编译部署
- 多版本切换困难
- 难以快速搭建测试环境
- Docker 环境兼容性问题

### 1.4 社区反馈

通过在腾讯云开发者社区和OpenTenBase社区高校俱乐部的调查反馈

![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/559e11e21d900e7cfc1067d0c4f03a82.png)（取材于大佬六月的雨在Tencent：https://cloud.tencent.com/developer/article/2565410）

![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/98474df54790828bb886bb8a07e3caf4.png)

同时发现官方存在docker仓库
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/c3d647cf225ec56846438b6b28de0770.png)
但是他是它是针对开发者进行一键化的部署，对于发行版本,比如企业用户的一件部署使用,也有所缺乏。


---

## 二、Debian 化的意义

### 2.1 降低部署门槛

通过 Debian 打包，可以实现：

```bash
# 一键安装
apt install opentenbase

# 自动配置
opentenbase-ctl init

# 一键启动
opentenbase-ctl start
```

**从 14 个步骤 → 3 个命令。**

### 2.2 符合 Linux 发行版标准

Debian 包的优势：
- 依赖自动管理
- 版本控制规范
- 系统集成（systemd、logrotate）
- 升级/卸载自动化
- 多版本并存支持

### 2.3 社区价值

OpenTenBase 社区现状：

![OpenTenBase 社区现状对比图](https://developer.qcloudimg.com/http-save/yehe-11827391/7e9eebf3b1505b391a1a46c5ee33ebe0.png)

这就是为什么我要做 Debian + Docker 化。

---

## 三、Docker 化架构设计

### 3.1 整体架构

![OpenTenBase 社区现状对比图](https://developer.qcloudimg.com/http-save/yehe-11827391/f77b5a34192b8aa292fa94db91c44356.png)


### 3.2 Coordinator / DataNode / GTM 结构

#### GTM（全局事务管理器）

**职责**：
- 分配全局事务 ID（GXID）
- 维护全局事务状态
- 协调分布式事务提交/回滚

**配置**：
```ini
port = 6666
nodename = 'gtm_master'
listen_addresses = '*'
```


#### Coordinator（协调节点）

**职责**：
- 接收客户端 SQL 请求
- SQL 解析和优化
- 路由 SQL 到对应的 DataNode
- 聚合结果返回客户端

**端口规划**：
| 端口 | 用途 |
|------|------|
| 5432 | SQL 连接（对外） |
| 6667 | 连接池 |
| 6669 | 转发端口 |

![Coordinator 端口示意图](https://developer.qcloudimg.com/http-save/yehe-11827391/03e5ad255a6794881674ba45960a2ef1.png)

#### DataNode（数据节点）

**职责**：
- 存储实际数据
- 执行子查询
- 处理事务

**端口规划**：
| 端口 | 用途 |
|------|------|
| 15432 | SQL 连接 |
| 6668 | 连接池 |
| 6670 | 转发端口 |

### 3.3 Docker Compose 集群方案

#### 核心配置

```yaml
version: '3.8'

services:
  gtm:
    image: opentenbase/opentenbase:5.0
    hostname: gtm
    ports:
      - "6666:6666"
    volumes:
      - gtm_data:/var/lib/opentenbase/gtm
    environment:
      - NODE_TYPE=gtm
      - GTM_PORT=6666
      - NODE_NAME=gtm_master
    networks:
      - opentenbase-net
    healthcheck:
      test: ["CMD", "su", "-", "opentenbase", "-c", "pg_isready -p 6666"]
      interval: 10s
      timeout: 5s
      retries: 5

  coordinator:
    image: opentenbase/opentenbase:5.0
    hostname: coordinator
    ports:
      - "5432:5432"
    depends_on:
      gtm:
        condition: service_healthy
    # ... 配置

  dn1:
    image: opentenbase/opentenbase:5.0
    hostname: dn1
    ports:
      - "15432:15432"
    depends_on:
      coordinator:
        condition: service_healthy
    # ... 配置

  dn2:
    image: opentenbase/opentenbase:5.0
    hostname: dn2
    ports:
      - "15433:15433"
    depends_on:
      coordinator:
        condition: service_healthy
    # ... 配置

networks:
  opentenbase-net:
    driver: bridge

volumes:
  gtm_data:
  coord_data:
  dn1_data:
  dn2_data:
```

#### 启动流程

```bash
# 1. 构建镜像
cd docker/runtime
docker build -t opentenbase/opentenbase:5.0 .

# 2. 启动集群
cd compose
docker compose up -d

# 3. 查看状态
docker compose ps
```


---

## 四、deb 打包流程

### 4.1 包结构设计

OpenTenBase 分成 6 个包：

![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/a6c0250f477d5dfb50ddb2526bfb10ac.png)

### 4.2 打包目录结构

```
debian/
├── changelog           # 版本变更日志
├── control             # 包定义和依赖
├── copyright           # 版权信息
├── rules               # 构建规则（Makefile）
├── source/
│   └── format          # 源码格式 (3.0 quilt)
├── patches/
│   ├── 01-bool-stdbool.patch  # gcc-14 兼容性
│   ├── 02-nolic-sharding.patch
│   └── 03-atomic128-x86.patch # 128-bit atomics 修复
├── opentenbase-ctl     # 集群管理脚本
├── opentenbase.conf    # 主配置文件
├── gtm.conf.template   # GTM 配置模板
├── postgresql.conf.coord.template
├── postgresql.conf.dn.template
├── pg_hba.conf.template
├── opentenbase.install      # 元包
├── opentenbase-server.{install,dirs,postinst,prerm}
├── opentenbase-client.{install,postinst,prerm}
├── opentenbase-contrib.install
├── libopentenbase-dev.{install,lintian-overrides}
└── opentenbase-doc.{install,docs}
```

### 4.3 构建流程

```bash
# 1. 克隆源码
git clone https://github.com/OpenTenBase/OpenTenBase.git
cd OpenTenBase

# 2. 复制 debian 目录
cp -r /path/to/debian/ ./

# 3. 应用补丁
cd debian/patches
patch -p1 < 01-bool-stdbool.patch
patch -p1 < 02-nolic-sharding.patch
patch -p1 < 03-atomic128-x86.patch

# 4. 构建包
fakeroot debian/rules binary

# 5. 输出
ls -la ../*.deb
```

![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/28a1aba3493a7c65b4d650bc1528d2ba.png)

---

## 五、踩坑记录

### 踩坑 1：pgxc_ctl 初始化失败

**错误信息**：
```
ERROR: can not get master gtm info from pgxc_node
```

**原因**：
OpenTenBase v5.0 废弃了 `postgresql.conf` 中的 `gtm_host`/`gtm_port` 参数，改用 `pgxc_node` 系统表。

**解决方案**：
```sql
-- 在 Coordinator 上执行
CREATE GTM NODE gtm_master WITH (HOST='127.0.0.1', PORT=6666, PRIMARY);
CREATE NODE coord1 WITH (TYPE='coordinator', HOST='127.0.0.1', PORT=5432, FORWARD=6669);
CREATE NODE dn001 WITH (TYPE='datanode', HOST='127.0.0.1', PORT=15432, FORWARD=6670, PRIMARY, PREFERRED);

-- 重载连接池
SELECT pgxc_pool_reload();

-- 在 Datanode 上执行
EXECUTE DIRECT ON (dn001) 'CREATE GTM NODE gtm_master WITH (HOST=''127.0.0.1'', PORT=6666, PRIMARY)';
```

### 踩坑 2：GTM 无法注册

**错误信息**：
```
could not establish connection to GTM
```

**原因**：
- GTM 启动顺序不对
- 端口冲突
- 网络隔离（Docker 环境）

**解决方案**：
1. 使用 healthcheck 确保 GTM 先启动
2. 使用 Docker network 连接容器
3. 使用 hostname 而非 IP

```yaml
depends_on:
  gtm:
    condition: service_healthy

environment:
  - GTM_HOST=gtm  # 使用 hostname
```

### 踩坑 3：CN 无法连接 DN

**错误信息**：
```
FATAL: could not connect to DN: Connection refused
```

**原因**：
- DN 启动顺序不对
- 节点注册未完成
- 连接池未重载

**解决方案**：
1. 确保 DN 完全启动后再注册
2. 使用 `EXECUTE DIRECT ON` 传播节点信息
3. 调用 `pgxc_pool_reload()` 重载连接池

```bash
# opentenbase-ctl 自动处理这个流程
opentenbase-ctl start
```

![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/427909139d33fcb272c6a063a0b55b45.png)

### 踩坑 4：Ubuntu 依赖问题

**错误信息**：
```
dpkg: dependency problems prevent configuration of opentenbase-server:
```

**原因**：
不同 Ubuntu 版本的包名不同。

**解决方案**：
```makefile
# debian/control
Build-Depends: 
  debhelper-compat (= 13),
  libcli11-dev (>= 2.3.0) | libcli-dev,
  libpqxx-dev (>= 7.8) | libpqxx-7-dev,
```

### 踩坑 5：128-bit atomics 链接错误

**错误信息**：
```
undefined reference to `__sync_val_compare_and_swap_16'
```

**原因**：
Debian 11/12 的 libatomic 不提供 128-bit atomics 支持。

**解决方案**：
使用 `__atomic_compare_exchange_n` 替代 `__sync_val_compare_and_swap`：

```diff
- ret.u128 = __sync_val_compare_and_swap(&ptr->u128, oldval.u128, newval.u128);
+ __atomic_compare_exchange_n(&ptr->u128, &expected.u128, newval.u128,
+                             0, __ATOMIC_SEQ_CST, __ATOMIC_SEQ_CST);
```

---

## 六、性能与资源占用

### 6.1 资源占用测试

**测试环境**：
- CPU: 4 核
- 内存: 4GB（推荐数据库运行内存，2G运行会卡顿）
- 磁盘: 20GB

**结果**：

| 节点 | CPU | 内存 | 磁盘 |
|------|-----|------|------|
| GTM | < 5% | 50MB | 20MB |
| Coordinator | 10-20% | 100MB | 50MB |
| Datanode 1 | 10-20% | 100MB | 50MB |
| Datanode 2 | 10-20% | 100MB | 50MB |
| **总计** | **35-65%** | **350MB** | **170MB** |

---

## 七、使用示例

### 7.1 快速部署
一键部署脚本：
```bash
curl -sLO https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/install.sh
sudo bash install.sh
```
手动模块化按需部署：
```bash
# Download packages for your distro
# Example for Ubuntu 22.04:
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/opentenbase_5.0-1ubuntu1.jammy_all.deb
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/opentenbase-server_5.0-1ubuntu1.jammy_amd64.deb
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/opentenbase-client_5.0-1ubuntu1.jammy_amd64.deb
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/opentenbase-contrib_5.0-1ubuntu1.jammy_amd64.deb
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/libopentenbase-dev_5.0-1ubuntu1.jammy_amd64.deb
wget https://github.com/muzimu217/OpenTenBase-deb/releases/download/v5.0-multi9/opentenbase-doc_5.0-1ubuntu1.jammy_all.deb

sudo dpkg -i *.deb
```

以上内容是软件包的一键部署教程，如果是需要开发数据库的佬友，目前我们这边也是支持Docker Compose 一键集群部署，详情到文章末尾链接，点击跳转到我们的开发维护仓库。
### 7.2 验证数据库

#### 初始化集群

```bash
# 初始化 GTM + Coordinator + Datanode
opentenbase-ctl init
```

#### 启动集群

```bash
# 启动所有节点
opentenbase-ctl start
```

#### 检查状态

```bash
# 查看集群状态
opentenbase-ctl status
```

#### 连接数据库

```bash
# 通过 psql 连接
opentenbase-psql -h 127.0.0.1 -p 5432 -U opentenbase -d postgres
```

#### 停止集群

```bash
# 停止所有节点
opentenbase-ctl stop
```

验证演示平台
https://ide.cloud.tencent.com/dashboard/workspace
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/5c0fee8dc803d1015220c2dd03206971.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/1c403f66bcb92e5d1fb30faafdee4239.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/1fc0783160ea1c4897ef3316b6b386c2.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/aafdaab9e42a0823e666e9df10da04f0.png)

之后这边就按照上处的脚本步骤一步步复制粘贴就可以完成了，推荐使用一键部署
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/3349194d1d76575e9deb9279a4f1776d.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-11827391/c5db3971aa923c389d47b5dd9426f2c9.png)
**完成！！！之后就可以根据这个数据库进行系统的开发和测试了**


---

## 八、后续优化方向

### 8.1 短期目标

- [x] 添加自动化测试（smoke test）
- [x] 规范化 Release
- [x] 添加 VSCode DevContainer
- [x] 完善 CI/CD 流程

### 8.2 中期目标

- [ ] 搭建 APT 仓库
- [ ] 支持多版本并存
- [ ] 添加性能监控
- [ ] 优化 Docker 镜像大小

### 8.3 长期目标

- [ ] 支持 RPM 包
- [ ] 提交到 OpenTenBase 官方
- [ ] 支持跨机部署
- [ ] 添加集群管理 UI

---

## 九、总结

通过 Debian + Docker 化，我们实现了：

1. ✅ **部署时间从 2 小时 → 5 分钟**
2. ✅ **配置步骤从 14 步 → 1 命令**
3. ✅ **支持一键启动完整集群**
4. ✅ **支持多版本切换**
5. ✅ **降低新人入门门槛**

这个项目[OpenTenBase-deb](https://github.com/muzimu217/OpenTenBase-deb) 填补了 OpenTenBase 社区的空白，为 Ubuntu/Debian 用户提供了一个可靠的部署方案。

**(๑・̀ㅂ・́)و✧** 觉得有帮助的佬友可以**点点关注点点赞**QAQ，顺便给我们的项目仓库点亮一个**star**，感谢各位佬友的支持，后续我会将此项目引入学校的**开源组织进行长期的版本更新和维护**。欢迎大家来**提issue和PR**，我会有空就会反馈并实时更新。欢迎大家来监督我，为建设更好的数据库生态一起携手共进(๑•̀ㅂ•́)و✧ 

---

## 参考资料

- OpenTenBase 官方仓库: https://github.com/OpenTenBase/OpenTenBase
- 本项目地址: https://github.com/muzimu217/OpenTenBase-deb
- Debian 打包指南: https://www.debian.org/doc/manuals/maint-guide/

---

**作者**：折腾 OpenTenBase 的开源俱乐部成员
**项目地址**：https://github.com/muzimu217/OpenTenBase-deb
**开源组织**：https://github.com/CDUESTC-OpenAtom-Open-Source-Club
**组织文章推荐**：
- [在 OpenEuler 22.03-LTS-SP4 部署 OpenTenBase V5.0 并集成 opentenbase_ai 插件与国产大模型](https://cloud.tencent.com/developer/article/2566086)
- [OpenTenBase 分布式数据库集群：从部署到管理 - opentenbase_ctl 工具指南](https://cloud.tencent.com/developer/article/2569015) 
- [OpenTenBase 5.0 编译与使用实践](https://cloud.tencent.com/developer/article/2567131)

最近在研究  OpenTenBase 的源码与部署，原本以为像 PostgreSQL 一样简单编译即可，结果真正上手后才发现：

我把 OpenTenBase 做成了 Debian + Docker 一键部署：国产分布式数据库终于不用手搓编译了

数据库

云计算

开发工具

OpenTenBase部署复杂？Debian+Docker化方案让分布式数据库一键部署！通过apt install opentenbase和opentenbase-ctl init等简单命令，原本14个手动步骤缩减为3个命令。Docker Compose集群方案自动配置GTM、Coordinator和DataNode节点，解决端口冲突、依赖管理等痛点。支持Ubuntu/Debian系统，资源占用仅需4核CPU+4GB内存，5分钟即可完成完整集群部署，大幅降低开发测试门槛。

分布式数据库

数据库集群

PostgreSQL

防火墙

路由

Docker

容器

Ubuntu

Debian

Linux

2026采购季 | AI焕新·智启新局

tencentdb-catalog

postgres

tddbms

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenTenBase部署复杂？Debian+Docker化方案让分布式数据库一键部署！通过apt install opentenbase和opentenbase-ctl init等简单命令，原本14个手动步骤缩减为3个命令。Docker Compose集群方案自动配置GTM、Coordinator和DataNode节...

我把 OpenTenBase 做成了 Debian + Docker 一键部署：国产分布式数据库终于不用手搓编译了-腾讯云开发者社区-腾讯云

我把 OpenTenBase 做成了 Debian + Docker 一键部署：国产分布式数据库终于不用手搓编译了

我把 OpenTenBase 做成了 Debian + Docker 一键部署：国产分布式数据库终于不用手搓编译了

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐