SQLite不适合多实例微服务共享存储，因其文件级锁机制和单进程设计导致跨进程写入竞争、database is locked错误及连接泄漏风险；正确用法限于单实例本地状态缓存，需设SetMaxOpenConns(1)、启用WAL模式并全局复用*sql.DB。
SQLite 不适合直接用于多实例 Golang 微服务的共享存储，但可作为单实例服务的轻量本地状态缓存或离线数据层 —— 关键是必须规避并发写入、文件锁竞争和连接泄漏。
为什么 database/sql + mattn/go-sqlite3 在微服务里容易出问题
微服务通常部署多个副本，而 SQLite 是文件级数据库，不支持网络访问或分布式事务。多个进程（或容器）同时打开同一 test.db 文件时，会触发 database is locked 或 unable to open database file 错误。即使只读，若某实例以 rw 模式打开，其他实例仍可能被阻塞。
- 默认连接池（
SetMaxOpenConns(0)即无限制）在高并发下易耗尽文件描述符 -
PRAGMA journal_mode = WAL能缓解读写冲突，但无法解决跨进程写入竞争 - Docker 容器中未挂载持久化卷时，
.db文件重启即丢失
正确用法：仅限单实例 + 本地状态场景
适用于配置中心客户端缓存、设备端离线日志暂存、CLI 工具内置存储等明确“单进程+单机”场景。此时需显式控制连接生命周期和并发策略。
- 设置连接池上限：
db.SetMaxOpenConns(1)（SQLite 本身不支持并行写入，开多个连接无意义） - 启用 WAL 模式提升并发读性能：
_, _ = db.Exec("PRAGMA journal_mode = WAL") - 使用
sqlite3.Open("file:my.db?_busy_timeout=5000&_journal_mode=WAL", ...)在 DSN 中传参更可靠 - 避免在 HTTP handler 中反复
sql.Open，应全局复用*sql.DB
常见错误与修复示例
以下代码会导致 database is locked：
立即学习“go语言免费学习笔记（深入）”；
func badHandler(w http.ResponseWriter, r *http.Request) {
db, _ := sql.Open("sqlite3", "./data.db") // 每次请求新建连接池
defer db.Close() // 可能来不及释放
db.Exec("INSERT INTO logs ...") // 多个请求争抢写锁
}
应改为：
var db *sql.DB // 全局变量
func init() {
var err error
db, err = sql.Open("sqlite3", "file:./data.db?_busy_timeout=5000&_journal_mode=WAL")
if err != nil { panic(err) }
db.SetMaxOpenConns(1)
db.SetMaxIdleConns(1)
}
func goodHandler(w http.ResponseWriter, r *http.Request) {
_, err := db.Exec("INSERT INTO logs (msg) VALUES (?)", r.URL.Path)
if err != nil {
http.Error(w, err.Error(), 500)
return
}
}
替代方案比硬上 SQLite 更实际
如果微服务需要“本地存储”只是为了解决启动依赖或降级能力，优先考虑：
- 用
embed.FS静态加载预置配置（如config.json），避免运行时 I/O - 用内存 Map +
sync.RWMutex存临时状态，配合定期序列化到磁盘（非实时一致性要求下） - 真正需要持久化时，改用轻量级网络数据库如
LiteFS（SQLite 的分布式封装）或BadgerDB（纯 Go 键值库，无文件锁问题）
SQLite 的文件锁机制和进程隔离边界，在微服务语境下不是配置问题，而是模型错配 —— 它不是“微型数据库”，而是“单进程嵌入式引擎”。强行接入，90% 的坑都源于忽略这点。
