必须用go.etcd.io/bbolt导入并设0600权限打开数据库：db, err := bbolt.open("data.db", 0600, nil)，旧路径github.com/boltdb/bolt已归档，go mod tidy会报错；务必defer db.close()防止锁死。
怎么正确 import 和 open BoltDB
2026年起必须用 go.etcd.io/bbolt，旧路径 github.com/boltdb/bolt 已归档，go mod tidy 会直接报错：module github.com/boltdb/bolt: not found。别试兼容层或本地缓存，Go 1.21+ 默认拒绝加载弃用模块。
安装命令是：go get go.etcd.io/bbolt@latest。打开数据库时权限必须设为 0600 —— BoltDB 文件是裸数据文件，不设权限等于把用户密码、token 等全暴露给同组其他用户。
db, err := bbolt.Open("data.db", 0600, nil) 失败常见原因就三个，按顺序排查：
- 文件被其他进程占用（比如上一次 panic 没
defer db.Close()，锁没释放） - 路径不存在且父目录不可写（
data.db所在目录需提前os.MkdirAll） - 权限掩码写成
600（缺前导零）或0o600（Go 不认八进制字面量前缀）
为什么 Update 和 View 必须严格分离
BoltDB 底层用单写多读锁机制：同一时刻只允许一个 Update 事务执行写操作，但允许多个并发 View 执行只读操作。混用不是风格问题，是硬性限制。
在 View 中调 b.Put() 不会报错，但返回 nil，键值根本没存进去（静默失败）；若调 tx.CreateBucket() 则直接 panic: invalid operation on read-only transaction。
高频读场景下，把查询塞进 Update 会导致写事务排队阻塞，QPS 断崖下跌。典型错误写法：
db.Update(func(tx *bbolt.Tx) error {
b := tx.Bucket([]byte("users"))
// 这里只是查，却占着写锁
if v := b.Get([]byte("alice")); v != nil {
// ...
}
return nil
})
应改为：
db.View(func(tx *bbolt.Tx) error {
b := tx.Bucket([]byte("users"))
if v := b.Get([]byte("alice")); v != nil {
// ...
}
return nil
})
桶名、键、值全得是 []byte，绕不过去
所有字符串参数必须显式转成 []byte：[]byte("users")，不能传 "users"（编译失败），也不能传 string([]byte("users"))（类型不匹配）。
结构体、int、bool 等类型不能直接存 —— BoltDB 只认字节切片。常见错误：
-
b.Put([]byte("user1"), &u)→ 编译报错：cannot use &u (type *User) as type []byte -
b.Put([]byte("count"), 42)→ 运行 panic：cannot convert int to []byte
正确做法是序列化：
- 存结构体：
data, _ := json.Marshal(u); b.Put([]byte("user1"), data) - 存小整数当 key（如 ID）：
key := make([]byte, 8); binary.BigEndian.PutUint64(key, uint64(123))，避免strconv.Itoa(123)导致字典序错乱 - 读出来后判空用
v == nil，不是len(v) == 0（Get()返回nil表示 key 不存在）
初始化桶和数据的坑：CreateBucketIfNotExists 是默认选择
新手常手写判断逻辑：if b := tx.Bucket([]byte("logs")); b == nil { tx.CreateBucket([]byte("logs")) } —— 并发下两个事务同时通过判断，第二个 CreateBucket 就会因 bucket 已存在而返回 bucket already exists 错误。
tx.CreateBucketIfNotExists([]byte("logs")) 内部带原子性检查，返回 *bbolt.Bucket 和 nil error，可直接链式调用：tx.Bucket([]byte("logs")).Put(...)。
初始化种子数据必须走程序，不能手动编辑 .db 文件 —— 它是 mmap 映射的二进制 B+ 树文件，含页头、自由列表、校验和等结构，文本编辑器改完必坏，报 invalid page type 或 checksum error。
务必在 main() 或初始化函数末尾加 defer db.Close()：BoltDB 对文件加独占锁，不 Close 会导致后续进程卡死在 Open() 上，现象是 timeout acquiring lock。
