PostgreSQL - 分布式架构：Citus 的安装与基础使用

Ne0inhk

— 17 min read
PostgreSQL - 分布式架构：Citus 的安装与基础使用
在这里插入图片描述
👋 大家好，欢迎来到我的技术博客！
📚 在这里，我会分享学习笔记、实战经验与技术思考，力求用简单的方式讲清楚复杂的问题。
🎯 本文将围绕PostgreSQL这个话题展开，希望能为你带来一些启发或实用的参考。
🌱 无论你是刚入门的新手，还是正在进阶的开发者，希望你都能有所收获！

文章目录

PostgreSQL - 分布式架构：Citus 的安装与基础使用

在当今数据爆炸的时代，单机数据库早已难以满足海量数据存储与高并发查询的需求。传统的关系型数据库虽然在事务一致性、SQL兼容性方面表现出色，但在横向扩展能力上存在天然瓶颈。为了解决这一问题，PostgreSQL 社区推出了一个强大的扩展插件 —— Citus，它将 PostgreSQL 转变为一个分布式数据库系统，既保留了 PostgreSQL 的强大功能，又具备了近乎线性的水平扩展能力。

Citus 通过将数据分片（Sharding）并分布到多个 PostgreSQL 节点上，实现了对大规模数据集的高效处理。无论是实时分析、多租户 SaaS 应用，还是高吞吐量的 OLTP 场景，Citus 都能提供卓越的性能和可扩展性。本文将带你从零开始，深入理解 Citus 的核心原理，并手把手完成其安装、配置与基础使用，最后通过 Java 应用示例展示如何在实际项目中集成 Citus。

什么是 Citus？

Citus 是一个开源的 PostgreSQL 扩展，它将 PostgreSQL 转换为一个分布式数据库。它不是另一个数据库，而是直接构建在 PostgreSQL 之上，因此完全兼容 PostgreSQL 的语法、工具和生态系统。这意味着你可以在 Citus 中使用熟悉的 psql、pg_dump、窗口函数、JSONB、全文搜索等所有 PostgreSQL 功能。

Citus 的核心思想是 分片（Sharding）。它将一张大表的数据按照某个“分布列”（Distribution Column）进行哈希，然后将不同哈希值范围的数据分配到不同的工作节点（Worker Nodes）上。协调器节点（Coordinator Node）负责接收客户端请求，将查询分解并路由到相应的 Worker 节点，再将结果聚合返回给客户端。

💡 关键优势：无缝扩展：只需添加更多 Worker 节点，即可线性提升存储容量和查询吞吐量。完整 SQL 支持：支持 JOIN、子查询、CTE、窗口函数等复杂 SQL。高可用性：支持分片副本（Replication），实现故障自动切换。与 PostgreSQL 100% 兼容：现有应用几乎无需修改即可迁移。

Citus 最初由加州大学伯克利分校的研究团队开发，后成立公司 Citus Data（现已被 Microsoft 收购），并持续维护开源版本。如今，Citus 已成为构建大规模 PostgreSQL 应用的首选方案之一。

你可以访问 Citus 官方文档 获取最新、最权威的技术资料。

Citus 架构详解

要有效使用 Citus，必须理解其内部架构。Citus 集群通常由两类节点组成：

  1. 协调器节点（Coordinator Node）
    这是客户端连接的入口点。它不存储实际业务数据（除非显式指定），而是负责：
    • 解析 SQL 查询
    • 根据分布列确定目标分片
    • 将查询下推到对应的 Worker 节点
    • 聚合来自多个 Worker 的结果
    • 返回最终结果给客户端
  2. 工作节点（Worker Nodes）
    这些节点存储实际的分片数据。每个 Worker 是一个标准的 PostgreSQL 实例，运行 Citus 扩展。它们只处理被路由到自己的查询片段，并将中间结果返回给 Coordinator。

此外，Citus 还引入了 分片（Shard） 和 分片位置（Shard Placement） 的概念：

  • 分片（Shard）：一张分布式表会被逻辑划分为多个分片，每个分片包含一部分数据。
  • 分片位置（Shard Placement）：每个分片会物理存储在一个或多个 Worker 节点上。若配置了副本（默认 replication_factor=1），则一个分片会有多个副本，分布在不同节点以提高可用性。

下面是一个典型的 Citus 集群拓扑图：

Client Application

Coordinator Node

Worker Node 1

Worker Node 2

Worker Node 3

Shard 1001, 1002

Shard 1003, 1004

Shard 1005, 1006

在这个图中，客户端连接到 Coordinator，Coordinator 将查询分发到三个 Worker 节点，每个 Worker 存储两个分片。

数据分布策略

Citus 支持三种主要的表类型：

  1. 分布式表（Distributed Table）
    这是最常见的类型。数据根据分布列（如 user_id、tenant_id）进行哈希分片，分散到多个 Worker 上。适用于大表，如订单、日志、事件流等。
  2. 参考表（Reference Table）
    整张表的完整副本被复制到每一个 Worker 节点。适用于小表且需要频繁与分布式表 JOIN 的场景，如国家列表、产品分类等。由于每个 Worker 都有全量数据，JOIN 可以在本地完成，避免跨节点通信。
  3. 本地表（Local Table）
    仅存在于 Coordinator 节点上的普通 PostgreSQL 表。通常用于存储元数据或临时数据，不参与分布式查询。

选择合适的表类型对性能至关重要。例如，在多租户 SaaS 应用中，tenants 表可以作为参考表，而 events 表按 tenant_id 分布，这样每个租户的查询都能高效执行。

安装 Citus

Citus 的安装方式有多种，包括 Docker、包管理器（APT/YUM）、源码编译等。本文推荐使用 Docker Compose 方式，因为它简单、快速，且便于本地开发测试。

⚠️ 注意：生产环境建议使用官方提供的 RPM/DEB 包或云服务（如 Azure Cosmos DB for PostgreSQL）。

使用 Docker Compose 快速搭建

首先，确保你的系统已安装 Docker 和 Docker Compose。

创建一个名为 docker-compose.yml 的文件，内容如下：

version:'3.8'services:coordinator:image: citusdata/citus:12.1container_name: citus_coordinator ports:-"5432:5432"environment:- POSTGRES_DB=citus - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres volumes:- coordinator_data:/var/lib/postgresql/data networks:- citus_network worker1:image: citusdata/citus:12.1container_name: citus_worker1 environment:- POSTGRES_DB=citus - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres volumes:- worker1_data:/var/lib/postgresql/data networks:- citus_network worker2:image: citusdata/citus:12.1container_name: citus_worker2 environment:- POSTGRES_DB=citus - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres volumes:- worker2_data:/var/lib/postgresql/data networks:- citus_network volumes:coordinator_data:worker1_data:worker2_data:networks:citus_network:driver: bridge

这个配置启动了一个 Coordinator 和两个 Worker 节点，所有节点使用相同的 PostgreSQL 用户和密码。

在终端中运行以下命令启动集群：

docker-compose up -d

等待几秒钟，容器就会启动完成。

初始化集群

Citus 需要手动将 Worker 节点注册到 Coordinator。进入 Coordinator 容器：

dockerexec-it citus_coordinator psql -U postgres -d citus

在 psql 中执行以下 SQL 命令，将两个 Worker 添加到集群：

-- 添加 worker1SELECT*from master_add_node('worker1',5432);-- 添加 worker2SELECT*from master_add_node('worker2',5432);
🔍 注意：在较新版本的 Citus（>=11.0）中，函数名已从 master_add_node 改为 citus_add_node。如果你使用的是新版镜像，请使用：

验证集群状态：

SELECT*FROM citus_get_active_worker_nodes();

你应该看到两行输出，分别对应 worker1 和 worker2。

至此，一个包含 1 个 Coordinator 和 2 个 Worker 的 Citus 集群就搭建完成了！🎉

创建分布式表

现在，我们来创建第一张分布式表。假设我们要构建一个用户行为日志系统，记录用户的点击事件。

步骤 1：创建表结构

在 psql 中执行：

CREATETABLE events ( event_id bigserial, user_id integer, event_type text, event_time timestamptz defaultnow(), payload jsonb );

这是一张标准的 PostgreSQL 表，尚未分布式化。

步骤 2：将其转换为分布式表

我们需要选择一个分布列（Distribution Column）。理想情况下，该列应具有高基数（High Cardinality）且查询中经常用于过滤或 JOIN。在这里，user_id 是一个合理的选择，因为大多数查询会按用户维度进行分析。

执行以下命令：

SELECT create_distributed_table('events','user_id');

这条命令会：

  • 在所有 Worker 节点上创建 events 表的分片
  • 根据 user_id 的哈希值将数据路由到不同分片
  • 更新 Coordinator 的元数据，使其知道如何路由查询

步骤 3：插入测试数据

INSERTINTO events (user_id, event_type, payload)VALUES(1,'click','{"page": "/home"}'),(2,'view','{"product_id": 101}'),(1,'purchase','{"amount": 99.99}'),(3,'click','{"page": "/profile"}');

Citus 会自动将这些行根据 user_id 分配到不同的 Worker 节点。

步骤 4：查询数据

执行简单查询：

SELECT*FROM events WHERE user_id =1;

Citus 会识别出 user_id = 1 只可能存在于某一个分片（或其副本），因此只会向该分片所在的 Worker 发送查询，效率极高。

再试试聚合查询：

SELECT user_id,count(*)FROM events GROUPBY user_id;

Coordinator 会将 GROUP BY 下推到每个 Worker，每个 Worker 计算局部聚合，Coordinator 再合并结果。这种“分而治之”的策略使得即使面对十亿级数据，也能在秒级返回结果。

参考表的使用

假设我们有一个 products 表，存储商品信息：

CREATETABLE products ( product_id integerPRIMARYKEY, name text, price numeric);INSERTINTO products VALUES(101,'Laptop',999.99),(102,'Mouse',19.99);

如果我们希望在查询 events 时能 JOIN products（例如，通过 payload->>'product_id' 关联），就需要将 products 设为参考表，这样每个 Worker 都有完整的 products 数据，JOIN 可在本地完成。

执行：

SELECT create_reference_table('products');

现在，我们可以安全地执行跨表 JOIN：

SELECT e.user_id, p.name, e.event_time FROM events e JOIN products p ON(e.payload->>'product_id')::int= p.product_id WHERE e.event_type ='view';

Citus 会自动优化此查询，避免昂贵的跨节点数据移动。

Citus 中的索引与性能优化

在分布式环境中，索引的设计尤为重要。Citus 支持在分布式表上创建普通索引、唯一索引、部分索引等，但有一些限制：

  • 唯一约束：只能在分布列上定义唯一索引（或包含分布列的复合唯一索引）。因为唯一性检查需要跨所有分片，成本极高，Citus 默认禁止非分布列的全局唯一约束。
  • 外键：不支持跨分布式表的外键。但参考表可以被分布式表引用（因为参考表在所有节点都有副本）。

创建索引示例

为 events 表的 event_time 列创建索引，加速时间范围查询：

CREATEINDEX idx_events_time ON events (event_time);

Citus 会在每个分片上创建该索引，因此查询如：

SELECT*FROM events WHERE event_time >'2024-01-01'AND user_id =1;

将同时利用 user_id 的分片路由和 event_time 的索引，实现极致性能。

分区表 + 分布式表

Citus 还支持将分区表（Partitioned Table） 与分布式表结合使用。例如，你可以按月对 events 表进行范围分区，再按 user_id 分布。这样既能利用分区裁剪（Partition Pruning），又能水平扩展。

-- 创建分区父表CREATETABLE events_partitioned ( event_id bigserial, user_id integer, event_type text, event_time timestamptz defaultnow(), payload jsonb )PARTITIONBY RANGE (event_time);-- 转换为分布式表SELECT create_distributed_table('events_partitioned','user_id');-- 创建子分区CREATETABLE events_2024_01 PARTITIONOF events_partitioned FORVALUESFROM('2024-01-01')TO('2024-02-01');CREATETABLE events_2024_02 PARTITIONOF events_partitioned FORVALUESFROM('2024-02-01')TO('2024-03-01');

这种组合特别适合时间序列数据，既能高效删除旧数据（DROP TABLE events_2023_12），又能快速查询近期数据。

Java 应用集成 Citus

现在，让我们看看如何在 Java 应用中使用 Citus。由于 Citus 完全兼容 PostgreSQL 协议，我们可以直接使用标准的 JDBC 驱动，无需任何特殊客户端库。

依赖配置

在 Maven 项目中，添加 PostgreSQL JDBC 驱动依赖：

<dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><version>42.7.3</version></dependency>

数据源配置

使用 Spring Boot 为例，配置 application.yml：

spring:datasource:url: jdbc:postgresql://localhost:5432/citus username: postgres password: postgres driver-class-name: org.postgresql.Driver

注意：连接地址指向 Coordinator 节点（本例中是 localhost:5432）。

实体类与 Repository

定义 Event 实体：

importjakarta.persistence.*;importjava.time.LocalDateTime;@Entity@Table(name ="events")publicclassEvent{@Id@GeneratedValue(strategy =GenerationType.IDENTITY)privateLong eventId;privateInteger userId;privateString eventType;privateLocalDateTime eventTime;privateString payload;// JSON 字符串// getters and setters}

创建 Spring Data JPA Repository：

importorg.springframework.data.jpa.repository.JpaRepository;importorg.springframework.data.jpa.repository.Query;importorg.springframework.stereotype.Repository;importjava.util.List;@RepositorypublicinterfaceEventRepositoryextendsJpaRepository<Event,Long>{List<Event>findByUserId(Integer userId);@Query("SELECT e FROM Event e WHERE e.eventTime > :since AND e.userId = :userId")List<Event>findRecentByUser(@Param("since")LocalDateTime since,@Param("userId")Integer userId);}

服务层示例

importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.stereotype.Service;importjava.time.LocalDateTime;importjava.util.List;@ServicepublicclassEventService{@AutowiredprivateEventRepository eventRepository;publicvoidlogEvent(Integer userId,String eventType,String payload){Event event =newEvent(); event.setUserId(userId); event.setEventType(eventType); event.setPayload(payload); event.setEventTime(LocalDateTime.now()); eventRepository.save(event);// 自动路由到正确分片}publicList<Event>getUserEvents(Integer userId){return eventRepository.findByUserId(userId);// 高效单分片查询}publicList<Event>getRecentUserEvents(Integer userId,LocalDateTime since){return eventRepository.findRecentByUser(since, userId);}}

批量插入优化

对于高吞吐写入场景（如日志收集），建议使用批量插入：

@AutowiredprivateJdbcTemplate jdbcTemplate;publicvoidbatchInsertEvents(List<Event> events){String sql ="INSERT INTO events (user_id, event_type, event_time, payload) VALUES (?, ?, ?, ?)"; jdbcTemplate.batchUpdate(sql,newBatchPreparedStatementSetter(){@OverridepublicvoidsetValues(PreparedStatement ps,int i)throwsSQLException{Event e = events.get(i); ps.setInt(1, e.getUserId()); ps.setString(2, e.getEventType()); ps.setTimestamp(3,Timestamp.valueOf(e.getEventTime())); ps.setString(4, e.getPayload());}@OverridepublicintgetBatchSize(){return events.size();}});}

Citus 会自动将批量中的每条记录路由到对应的分片，实现并行写入。

处理分布式事务

Citus 不支持跨分片的分布式事务（即 ACID 事务跨越多个分片）。如果你的业务操作涉及多个 user_id 的数据更新，需要谨慎设计：

  • 最佳实践：尽量将相关数据放在同一个分片内（例如，按 tenant_id 分布，确保一个租户的所有数据在同一分片）。
  • 补偿机制：对于必须跨分片的操作，可采用 Saga 模式或最终一致性方案。

例如，在转账场景中，如果 account 表按 user_id 分布，那么从用户 A 转账给用户 B 就涉及两个分片。此时应避免使用数据库事务，而改用消息队列+幂等操作来保证一致性。

监控与运维

Citus 提供了丰富的视图和函数用于监控集群状态。

查看分片分布

SELECT*FROM citus_shards;

显示每张分布式表的分片 ID、大小、所在节点等信息。

查看查询计划

使用 EXPLAIN 查看 Citus 如何执行查询：

EXPLAIN(ANALYZE, VERBOSE)SELECTcount(*)FROM events WHERE user_id =1;

输出会显示查询是否被下推到 Worker，以及网络传输开销。

扩容 Worker 节点

当数据增长时，可以动态添加新 Worker：

SELECT citus_add_node('new_worker',5432);

然后重新平衡分片：

SELECT rebalance_table_shards('events');

Citus 会自动将部分分片迁移到新节点，实现负载均衡。

备份与恢复

由于 Citus 基于 PostgreSQL，可以使用 pg_dump 备份 Coordinator 的元数据，但不能直接备份整个集群数据。推荐使用 Citus 提供的 citus_backup 工具（需单独安装），或在应用层实现逻辑备份。

常见问题与最佳实践

1. 如何选择分布列？

  • 高基数：避免数据倾斜（Skew）。例如，不要用性别（只有男/女）作为分布列。
  • 查询友好：大多数查询应包含分布列的过滤条件。
  • JOIN 高频：如果经常与另一张表 JOIN，考虑使用相同的分布列（共置，Colocation）。

2. 数据倾斜怎么办？

如果某些 user_id 的数据量远大于其他（如超级用户），会导致分片大小不均。解决方案：

  • 对热点用户单独处理（如拆分为子表）
  • 使用复合分布列（如 (user_id, event_type)）
  • 启用自适应分片（Citus 企业版功能）

3. 是否支持全文搜索、GIS？

是的！因为 Citus 基于 PostgreSQL，所以 tsvector、PostGIS 等扩展均可使用。只需在所有 Worker 节点上安装相应扩展：

-- 在 Coordinator 上执行CREATE EXTENSION postgis;SELECT run_command_on_workers('CREATE EXTENSION postgis;');

4. 与 Greenplum、TimescaleDB 的区别？

  • Greenplum：基于 PostgreSQL 的 MPP 数据库，更适合 OLAP，SQL 兼容性略弱。
  • TimescaleDB：专注于时间序列数据的 PostgreSQL 扩展，支持自动分区，但不提供水平分片。
  • Citus：通用型分布式 PostgreSQL，兼顾 OLTP 与 OLAP，SQL 兼容性最强。

想深入了解 Citus 与其他分布式数据库的对比，可以阅读 Citus 官方博客 中的技术文章。

总结

Citus 为 PostgreSQL 插上了分布式翅膀，让开发者既能享受关系型数据库的成熟生态，又能应对海量数据的挑战。通过本文，我们完成了：

  • ✅ 理解 Citus 的核心架构与数据分布原理
  • ✅ 使用 Docker Compose 快速搭建本地 Citus 集群
  • ✅ 创建分布式表与参考表，并执行高效查询
  • ✅ 在 Java 应用中无缝集成 Citus，实现高性能读写
  • ✅ 掌握索引优化、监控运维等关键实践

无论你是构建实时分析平台、多租户 SaaS 应用，还是物联网数据管道，Citus 都是一个值得信赖的选择。它的“PostgreSQL 原生”特性大大降低了学习和迁移成本，而强大的水平扩展能力则为未来业务增长提供了坚实基础。

🌟 最后建议：在生产环境中，务必进行充分的压力测试，合理设计分布列，并监控分片均衡性。Citus 的威力，只有在正确的使用方式下才能完全释放。

Happy Sharding! 🚀

🙌 感谢你读到这里！
🔍 技术之路没有捷径，但每一次阅读、思考和实践，都在悄悄拉近你与目标的距离。
💡 如果本文对你有帮助，不妨 👍 点赞、📌 收藏、📤 分享 给更多需要的朋友！
💬 欢迎在评论区留下你的想法、疑问或建议，我会一一回复，我们一起交流、共同成长 🌿
🔔 关注我，不错过下一篇干货！我们下期再见！✨

Read more

如何通过 3 个简单步骤在 Windows 上本地运行 DeepSeek

如何通过 3 个简单步骤在 Windows 上本地运行 DeepSeek

它是免费的——社区驱动的人工智能💪。         当 OpenAI 第一次推出定制 GPT 时，我就明白会有越来越多的人为人工智能做出贡献，并且迟早它会完全由社区驱动。         但从来没有想过它会如此接近😂让我们看看如何在 Windows 机器上完全免费使用第一个开源推理模型！  步骤 0：安装 Docker 桌面         我确信很多人已经安装了它，所以可以跳过，但如果没有 — — 这很简单，只需访问Docker 的官方网站，下载并运行安装 👍         如果您需要一些特定的设置，例如使用 WSL，那么有很多指导视频，请查看！我将继续下一步。 步骤 1：安装 CUDA 以获得 GPU 支持         如果您想使用 Nvidia 显卡运行 LLM，则必须安装 CUDA 驱动程序。（嗯……是的，它们需要大量的计算能力）         打开CUDA 下载页面，

By Ne0inhk
在 VSCode 中本地运行 DeepSeek，打造强大的私人 AI

在 VSCode 中本地运行 DeepSeek，打造强大的私人 AI

本文将分步向您展示如何在本地安装和运行 DeepSeek、使用 CodeGPT 对其进行配置以及开始利用 AI 来增强您的软件开发工作流程，所有这些都无需依赖基于云的服务。  步骤 1：在 VSCode 中安装 Ollama 和 CodeGPT         要在本地运行 DeepSeek，我们首先需要安装Ollama，它允许我们在我们的机器上运行 LLM，以及CodeGPT，它是集成这些模型以提供编码辅助的 VSCode 扩展。 安装 Ollama Ollama 是一个轻量级平台，可以轻松运行本地 LLM。 下载Ollama 访问官方网站：https://ollama.com * 下载适合您的操作系统（Windows、macOS 或 Linux）的安装程序。 * 验证安装 安装后，打开终端并运行： ollama --version  如果 Ollama 安装正确，

By Ne0inhk
DeepSeek-R1是真码农福音？我们问了100位开发者……

DeepSeek-R1是真码农福音？我们问了100位开发者……

从GitHub Copilot到DeepSeek-R1，AI编程工具正在引发一场"效率革命"，开发者们对这些工具的期待与质疑并存。据Gartner预测，到2028年，将有75%的企业软件工程师使用AI代码助手。 眼看着今年国产选手DeepSeek-R1凭借“深度思考”能力杀入战场，它究竟是真码农福音还是需要打补丁的"潜力股"？ ZEEKLOG问卷调研了社区内来自全栈开发、算法工程师、数据工程师、前端、后端等多个技术方向的100位开发者（截止到2月25日），聚焦DeepSeek-R1的代码生成效果、编写效率、语法支持、IDE集成、复杂代码处理等多个维度，一探DeepSeek-R1的开发提效能力。 代码生成效果：有成效但仍需提升 * 代码匹配比例差强人意 在代码生成与实际需求的匹配方面，大部分开发者（58人）遇到生成代码与实际需求完全匹配无需修改的比例在40%-70%区间，12人遇到代码匹配比例在70%-100%这样较高的区间。 然而，有30人代码匹配比例低于40%。这说明DeepSeek-R1在代码生成方面有一定效果，但在部分复杂或特定场景下，仍有很大的提升空间。

By Ne0inhk
AI+游戏开发：如何用 DeepSeek 打造高性能贪吃蛇游戏

AI+游戏开发：如何用 DeepSeek 打造高性能贪吃蛇游戏

文章目录 * 一、技术选型与准备 * 1.1 传统开发 vs AI生成 * 1.2 环境搭建与工具选择 * 1.3 DeepSeek API 初步体验 * 二、贪吃蛇游戏基础实现 * 2.1 游戏结构设计 * 2.2 初始化游戏 * 2.3 DeepSeek 生成核心逻辑 * 三、游戏功能扩展 * 3.1 多人联机模式 * 3.2 游戏难度动态调整 * 3.3 游戏本地保存与回放 * 3.4 跨平台移植 * 《Vue.js项目开发全程实录/软件项目开发全程实录》 * 编辑推荐 * 内容简介 * 作者简介 * 目录 一、

By Ne0inhk