数据库配置说明

K8M 支持多种数据库后端，包括 SQLite、MySQL、PostgreSQL。

1. 选择数据库类型

• sqlite：适合本地开发和轻量级部署。
• mysql：适合生产环境，支持高并发和大数据量。
• postgresql：适合对事务和一致性有更高要求的场景。

通过如下方式指定数据库类型：

• 环境变量：

  DB_DRIVER=sqlite  # 或 mysql、postgresql
  

• 启动参数：

  --db-driver=sqlite  # 或 mysql、postgresql
  

---

2. SQLite 配置

基础配置

可以通过以下方式配置 SQLite：

1. 基本配置 - 仅指定数据库文件路径：

   • 环境变量：

     SQLITE_PATH=./data/k8m.db
     

   • 启动参数：

     --sqlite-path=./data/k8m.db
     

2. 高级配置 - 自定义完整的 DSN 参数：

   • 环境变量：

     SQLITE_DSN="file:./data/k8m.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"
     

   • 启动参数：

     --sqlite-dsn="file:./data/k8m.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"
     

   优先级说明：

   • 如果设置了 SQLITE_DSN，将优先使用此配置
   • 如果同时设置了 SQLITE_DSN 和 SQLITE_PATH，系统会给出警告并优先使用 SQLITE_DSN
   • 如果都未设置，将使用默认的优化配置（例如：默认路径 ./data/k8m.db，默认 DSN file:./data/k8m.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)）
   • 更多DSN参数，请参考https://github.com/glebarez/go-sqlite?tab=readme-ov-file#connection-string-examples
   • https://github.com/mattn/go-sqlite3/blob/3392062c729d77820afc1f5cae3427f0de39e954/sqlite3.go#L908

并发写入优化

为了降低多并发写入时出现 "database is locked" 的风险，K8M 已在内部启用了以下优化：

1. WAL (Write-Ahead Logging) 模式
2. busy_timeout 设置为 5000ms

注意事项

1. 目录权限: 启动前请确保数据库文件所在目录 (如 ./data) 已存在且具备正确的读写权限。
2. 并发限制: SQLite 适合轻量级应用场景。如果您的应用场景涉及大量并发写入，建议考虑使用 MySQL 或 PostgreSQL。
3. 数据备份: 由于启用了 WAL 模式，请使用以下 SQLite 命令进行安全备份：

   # 方法一：使用 .backup 命令（推荐）
   sqlite3 ./data/k8m.db '.backup ./data/k8m.db.backup'
   
   # 方法二：使用 VACUUM INTO 命令（SQLite 3.27.0 及以上版本）
   sqlite3 ./data/k8m.db 'VACUUM INTO "./data/k8m.db.backup"'
   

   注意：在 WAL 模式下，不建议直接使用 cp 命令复制数据库文件，这可能导致备份不完整或不一致。如果必须使用 cp，需要：

   1. 暂停所有数据库写入操作
   2. 同时备份 -wal 和 -shm 文件
   3. 确保备份期间没有新的写入

   因风险较高，强烈建议使用上述 SQLite 原生备份命令。

---

3. MySQL 配置

支持如下参数：

环境变量	启动参数	说明	默认值
MYSQL_HOST	--mysql-host	主机	127.0.0.1
MYSQL_PORT	--mysql-port	端口	3306
MYSQL_USER	--mysql-user	用户名	root
MYSQL_PASSWORD	--mysql-password	密码	""
MYSQL_DATABASE	--mysql-database	数据库名	k8m
MYSQL_CHARSET	--mysql-charset	字符集	utf8mb4
MYSQL_COLLATION	--mysql-collation	排序规则	utf8mb4_general_ci
MYSQL_QUERY	--mysql-query	额外参数	parseTime=True&loc=Local
MYSQL_LOGMODE	--mysql-logmode	日志模式	false

示例：

DB_DRIVER=mysql
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=yourpassword
MYSQL_DATABASE=k8m
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_general_ci
MYSQL_QUERY=parseTime=True&loc=Local
MYSQL_LOGMODE=false

---

4. PostgreSQL 配置

支持如下参数：

环境变量	启动参数	说明	默认值
PG_HOST	--pg-host	主机	127.0.0.1
PG_PORT	--pg-port	端口	5432
PG_USER	--pg-user	用户名	postgres
PG_PASSWORD	--pg-password	密码	""
PG_DATABASE	--pg-database	数据库名	k8m
PG_SSLMODE	--pg-sslmode	SSL模式	disable
PG_TIMEZONE	--pg-timezone	时区	Asia/Shanghai
PG_LOGMODE	--pg-logmode	日志模式	false

示例：

DB_DRIVER=postgresql
PG_HOST=127.0.0.1
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=yourpassword
PG_DATABASE=k8m
PG_SSLMODE=disable
PG_TIMEZONE=Asia/Shanghai
PG_LOGMODE=false

---

5. 配置优先级说明

1. 启动参数（如 --mysql-host）优先级最高。
2. 环境变量（如 MYSQL_HOST）次之。
3. 若未设置，使用内置默认值。

---

6. 其他说明

• 所有数据库参数均可通过环境变量或启动参数配置。
• 推荐生产环境使用 MySQL 或 PostgreSQL。
• 日志模式（logmode）为 true 时，SQL 语句会输出到日志，便于调试。
• 配置变更后需重启服务生效。

如需更多帮助，请参考 .env.example 文件或源码注释。