使用旧版 go-couchbase 客户端时，常见因认证参数误传（如将集群用户名当作 bucket 用户名）导致 GetBucketWithAuth 报“bucket 不存在”错误；正确做法是将 bucket 名作为用户名传入，且建议迁移到官方推荐的 gocb 客户端。
使用旧版 go-couchbase 客户端时，常见因认证参数误传（如将集群用户名当作 bucket 用户名）导致 `getbucketwithauth` 报“bucket 不存在”错误；正确做法是将 bucket 名作为用户名传入，且建议迁移到官方推荐的 gocb 客户端。
在 Couchbase 的 Go 生态中，go-couchbase 是一个早期、已逐步弃用的社区/内部客户端，而 gocb（即 couchbase/gocb）是官方主推、持续维护的现代 SDK。你遇到的 "bucket 'events' doesn't exist" 错误，并非 bucket 真实缺失，而是认证失败触发的误导性提示——这是 go-couchbase 库的一个典型行为：当 bucket 用户名或密码不匹配时，它不会明确报“认证失败”，而是返回 bucket 未找到（bucket not found），极易造成排查偏差。
关键原因在于 GetBucketWithAuth(bucketName, username, password) 方法的语义：
- ✅ 第一个参数 bucketName：目标 bucket 名（如 "events"）；
- ✅ 第二个参数 username：必须是该 bucket 的访问用户名，而非集群管理员用户名；Couchbase Server 6.5+ 启用 RBAC 后，bucket 级用户默认与 bucket 同名（即 "events"）；
- ✅ 第三个参数 password：对应 bucket 用户的密码（若 bucket 无独立密码，则为空字符串 ""）。
因此，你原代码中：
cbBucket, err := cbPool.GetBucketWithAuth("events", "username", "password")
应修正为：
cbBucket, err := cbPool.GetBucketWithAuth("events", "events", "") // 假设 events bucket 未设置独立密码
// 或（若已为 events bucket 创建了专用用户，如 user_events）
// cbBucket, err := cbPool.GetBucketWithAuth("events", "user_events", "secret123")
⚠️ 重要注意事项：
- go-couchbase 不支持 Couchbase Server 7.0+ 的新协议特性（如 Query V2、Analytics、Eventing），且自 2021 年起已停止功能更新；
- 其连接模型（pool → bucket）与现代 RBAC 权限体系耦合较深，调试成本高；
- 官方文档与社区支持已全面转向 gocb。
✅ 强烈推荐迁移至 gocb（v2+），代码更简洁、错误更明确、功能更完整：
package main
import (
"fmt"
"log"
"github.com/couchbase/gocb/v2"
)
func main() {
// 连接集群（自动处理 TLS、配置轮询等）
cluster, err := gocb.Connect("couchbase://address", gocb.ClusterOptions{
Username: "admin", // 集群管理员或具备 bucket 权限的 RBAC 用户
Password: "password",
})
if err != nil {
log.Fatalf("Failed to connect: %v", err)
}
// 获取 bucket（自动处理认证与配置加载）
bucket := cluster.Bucket("events")
if err := bucket.WaitUntilReady(5, nil); err != nil {
log.Fatalf("Bucket not ready: %v", err)
}
// 获取集合（Collection）进行操作（Couchbase 7.0+ 推荐方式）
collection := bucket.DefaultCollection()
// ... 执行 CRUD 操作
}
总结：go-couchbase 的 GetBucketWithAuth 要求严格遵循 “bucket 名即用户名” 的认证约定；但与其花费时间适配过时接口，不如直接升级至 gocb——它提供清晰的错误分类（如 authentication failure 明确报错）、开箱即用的负载均衡、以及对最新 Couchbase 功能的完整支持。迁移成本低，长期维护性与稳定性显著提升。
