Couchbase Bucket操作 #

一、Bucket概述 #

1.1 什么是Bucket #

Bucket（存储桶）是Couchbase中数据存储的顶层容器，类似于关系数据库中的数据库概念。每个Bucket都有独立的内存配额、副本配置和资源管理。

1.2 Bucket类型 #

类型 说明 适用场景
Couchbase 支持持久化、副本、索引 生产环境、需要高可用
Memcached 纯内存缓存，无持久化 缓存层、临时数据
Ephemeral 内存优先，可选持久化 高性能、可接受数据丢失

1.3 层级结构 #

text 
Cluster（集群）
└── Bucket（存储桶）
    ├── Scope（作用域）
    │   └── Collection（集合）
    │       └── Document（文档）
    │
    ├── _default Scope
    │   └── _default Collection
    └── ...

二、创建Bucket #

2.1 Web控制台创建 #

  1. 登录Couchbase Web控制台：http://localhost:8091
  2. 点击左侧菜单"Buckets"
  3. 点击"ADD BUCKET"按钮
  4. 配置Bucket参数：
参数 说明 示例值
Name Bucket名称 my-bucket
Type Bucket类型 Couchbase
Memory Quota 内存配额(MB) 512
Replicas 副本数量 1
Flush 允许清空 Enabled

2.2 命令行创建 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-create \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --bucket-type couchbase \
    --bucket-ramsize 512 \
    --bucket-replica 1 \
    --bucket-eviction-policy valueOnly \
    --enable-flush 1

2.3 REST API创建 #

bash 
curl -X POST http://localhost:8091/pools/default/buckets \
    -u Administrator:your-password \
    -d name=my-bucket \
    -d ramQuotaMB=512 \
    -d replicaNumber=1 \
    -d bucketType=couchbase \
    -d flushEnabled=1

2.4 参数详解 #

内存配额计算：

text 
总内存需求 = Bucket内存 + 索引内存 + 查询内存 + 系统预留

示例：
- 服务器总内存：16GB
- 系统预留：4GB
- 可用内存：12GB
- Data服务：8GB（可分配给多个Bucket）
- Index服务：2GB
- Query服务：2GB

副本配置：

bash 
/opt/couchbase/bin/couchbase-cli bucket-create \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --bucket-type couchbase \
    --bucket-ramsize 512 \
    --bucket-replica 2 \
    --bucket-replica-index 1

三、查看Bucket #

3.1 查看所有Bucket #

命令行：

bash 
/opt/couchbase/bin/couchbase-cli bucket-list \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password

N1QL查询：

sql 
SELECT * FROM system:buckets;

3.2 查看Bucket详情 #

命令行：

bash 
/opt/couchbase/bin/couchbase-cli bucket-get \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket

REST API：

bash 
curl -X GET http://localhost:8091/pools/default/buckets/my-bucket \
    -u Administrator:your-password

3.3 查看Bucket统计信息 #

sql 
SELECT 
    name,
    quota,
    ram,
    ops,
    itemCount,
    dataUsed,
    diskUsed
FROM system:buckets;

四、修改Bucket #

4.1 修改内存配额 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-edit \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --bucket-ramsize 1024

4.2 修改副本数 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-edit \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --bucket-replica 2

4.3 修改淘汰策略 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-edit \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --bucket-eviction-policy fullEviction

淘汰策略选项：

策略 说明 适用场景
valueOnly 只淘汰值，保留元数据 默认策略
fullEviction 淘汰整个文档 内存紧张
noEviction 不淘汰 缓存场景
nruEviction 最近未使用淘汰 Memcached类型

4.4 修改压缩设置 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-edit \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --compaction-db-percentage 30 \
    --compaction-view-percentage 30 \
    --enable-compaction-parallel true

五、清空Bucket #

5.1 启用Flush #

创建Bucket时启用：

bash 
/opt/couchbase/bin/couchbase-cli bucket-create \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --enable-flush 1 \
    ...

修改已有Bucket：

bash 
/opt/couchbase/bin/couchbase-cli bucket-edit \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --enable-flush 1

5.2 执行Flush #

命令行：

bash 
/opt/couchbase/bin/couchbase-cli bucket-flush \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket

REST API：

bash 
curl -X POST http://localhost:8091/pools/default/buckets/my-bucket/controller/doFlush \
    -u Administrator:your-password

N1QL删除所有文档：

sql 
DELETE FROM `my-bucket`.`_default`.`_default`
WHERE type = 'user';

六、删除Bucket #

6.1 命令行删除 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-delete \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket

6.2 REST API删除 #

bash 
curl -X DELETE http://localhost:8091/pools/default/buckets/my-bucket \
    -u Administrator:your-password

6.3 注意事项 #

text 
删除Bucket前请注意：
1. 删除操作不可恢复
2. 建议先备份重要数据
3. 删除后索引和视图也会被删除
4. 确保没有应用正在使用该Bucket

七、Bucket配置详解 #

7.1 内存配额规划 #

text 
单节点配置示例（16GB内存）：

┌────────────────────────────────────────┐
│           16GB 总内存                   │
├────────────────────────────────────────┤
│  系统预留: 4GB                         │
├────────────────────────────────────────┤
│  Data服务: 8GB                         │
│  ├── Bucket A: 4GB                     │
│  └── Bucket B: 4GB                     │
├────────────────────────────────────────┤
│  Index服务: 2GB                        │
├────────────────────────────────────────┤
│  Query服务: 1GB                        │
├────────────────────────────────────────┤
│  其他服务: 1GB                         │
└────────────────────────────────────────┘

7.2 副本配置 #

text 
副本数量建议：

节点数 >= 3：副本数 = 1 或 2
节点数 = 2：副本数 = 1
节点数 = 1：副本数 = 0（开发环境）

注意：副本数不能超过节点数-1

7.3 淘汰策略选择 #

text 
valueOnly（默认）
├── 保留文档Key在内存
├── 淘汰Value以释放内存
└── 适合：需要快速访问所有Key

fullEviction
├── 淘汰整个文档（Key+Value）
├── 最大化内存利用
└── 适合：内存紧张、数据量大

noEviction
├── 不淘汰任何数据
├── 内存满时拒绝写入
└── 适合：缓存场景、数据不能丢失

八、Bucket监控 #

8.1 Web控制台监控 #

访问 http://localhost:8091 -> Buckets -> 选择Bucket

监控指标：

指标 说明
ops/sec 每秒操作数
memory used 内存使用量
disk used 磁盘使用量
items 文档数量
connections 连接数

8.2 命令行监控 #

bash 
/opt/couchbase/bin/couchbase-cli bucket-get \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --json

8.3 REST API监控 #

bash 
curl -X GET http://localhost:8091/pools/default/buckets/my-bucket/stats \
    -u Administrator:your-password

8.4 关键指标 #

sql 
SELECT 
    name,
    ram/1024/1024 AS ram_mb,
    quota/1024/1024 AS quota_mb,
    ops,
    itemCount,
    dataUsed/1024/1024 AS data_mb,
    diskUsed/1024/1024 AS disk_mb
FROM system:buckets;

九、Bucket最佳实践 #

9.1 命名规范 #

text 
推荐命名：
- 使用小写字母
- 使用连字符分隔单词
- 语义化命名

示例：
my-app-data
user-profiles
product-catalog
session-cache

9.2 内存规划 #

text 
内存配额建议：

1. 预留足够的内存给操作系统
2. 考虑工作集大小（活跃数据）
3. 预留增长空间
4. 考虑副本的内存开销

公式：
Bucket内存 >= 工作集大小 × 1.5

9.3 副本策略 #

text 
生产环境：
- 至少3个节点
- 副本数 >= 1
- 启用自动故障转移

开发环境：
- 单节点即可
- 副本数 = 0

9.4 多Bucket设计 #

text 
按业务分离：

Cluster
├── users-bucket（用户数据）
├── products-bucket（产品数据）
├── orders-bucket（订单数据）
└── cache-bucket（缓存数据）

优点：
- 独立资源配置
- 隔离故障影响
- 灵活的权限控制

十、常见问题 #

10.1 内存不足 #

bash 
错误：RAM quota specified is greater than free RAM

解决方案：
1. 减少Bucket内存配额
2. 增加服务器内存
3. 调整其他服务内存配置

10.2 副本数超限 #

bash 
错误：Number of replicas cannot be greater than number of nodes - 1

解决方案：
1. 减少副本数
2. 增加集群节点数

10.3 Bucket无法删除 #

bash 
检查：
1. 是否有应用连接
2. 是否有正在进行的操作
3. 查看日志排查原因

强制删除：
/opt/couchbase/bin/couchbase-cli bucket-delete \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --force

十一、总结 #

Bucket操作要点：

操作 命令/方法
创建 bucket-create
查看 bucket-list, bucket-get
修改 bucket-edit
清空 bucket-flush
删除 bucket-delete

最佳实践：

  1. 合理规划内存配额
  2. 生产环境配置副本
  3. 选择合适的淘汰策略
  4. 定期监控Bucket状态
  5. 按业务分离Bucket

下一步，让我们学习Scope与Collection操作！

最后更新：2026-03-27