Beekeeper Studio 6.1.6 配置与 CLI 参数详解

目标：系统梳理 Beekeeper Studio 6.1.6 的命令行参数与配置体系——CLI 启动参数、bks-flags.conf 旗标文件、三层 ini 配置覆盖机制、default.config.ini 全量参数、用户数据目录结构与日志排障。全部路径与回显在 Ubuntu 22.04 实测采集，配置内容取自应用自带配置文件（v6.1.6）。

一、环境信息

项目	内容
应用版本	Beekeeper Studio 6.1.6 社区版（deb 安装，Ubuntu 22.04 x86_64）
安装目录	`/opt/Beekeeper Studio/`（空格含于目录名）
CLI 入口	`/usr/bin/beekeeper-studio`（bash 包装脚本，指向 `beekeeper-studio-bin`）
应用配置	`/opt/Beekeeper Studio/resources/default.config.ini` + `system.config.ini` + `user.config.ini`
用户数据目录	`~/.config/beekeeper-studio/`
旗标文件	`~/.config/bks-flags.conf`
元数据库	`~/.config/beekeeper-studio/app.db`（SQLite）

二、配置与 CLI 总览

Beekeeper Studio 是 Electron 桌面应用，其「配置」分布在四个层面，理解分层是改对配置的前提：

层面	位置	生效范围	典型用途
启动旗标	`~/.config/bks-flags.conf`	每次启动	Chromium/Electron 底层旗标（Wayland、GPU 等）
应用配置	三层 ini（见第四章）	应用功能行为	界面、连接池、快捷键、插件
用户数据	`~/.config/beekeeper-studio/`	连接/查询/历史	迁移备份、重置应用
CLI 参数	`beekeeper-studio <参数>`	本次启动	直接打开连接或 SQLite 文件

CLI 入口是 bash 包装脚本，核心逻辑是定位安装目录并启动 beekeeper-studio-bin：

head -8 /usr/bin/beekeeper-studio

实测回显：

#!/usr/bin/env bash
# set this for debugging
# set -euxo pipefail

SOURCE="${BASH_SOURCE[0]}"

三、CLI 参数详解

3.1 连接 URL 参数

beekeeper-studio 接受一个连接 URL 作为参数，启动后直接打开该连接（格式 scheme://用户:密码@主机:端口/默认库）。实测三种数据库 scheme（服务端日志验证连接真实建立，详细验证过程见本专栏《Beekeeper Studio 6.1.6 数据库连接与操作实战》第四章）：

# MySQL：连接后 general_log 记录 Connect admin on bkstudio_demo using TCP/IP
beekeeper-studio 'mysql://admin:q1w2e3r4@127.0.0.1:3306/bkstudio_demo'

# PostgreSQL：连接后 pg_stat_activity 出现 usename=admin 的 idle 后端
beekeeper-studio 'postgresql://admin:q1w2e3r4@127.0.0.1:5432/bkstudio_demo'

# Redis / SQL Server / Redshift 等按各 scheme 类推
beekeeper-studio 'redis://127.0.0.1:6379/'

可识别的 URL scheme 与桌面环境注册的协议处理器一致（来源：安装包 beekeeper-studio.desktop 文件 MimeType，查询日期 2026-10-20）：

scheme	数据库
`mysql` / `mariadb` / `tidb`	MySQL 系
`postgresql` / `postgres` / `psql`	PostgreSQL 系（含 CockroachDB `cockroachdb`、Redshift `redshift`）
`sqlite`	SQLite 文件（也可直接传文件路径，见 3.2）
`sqlserver` / `microsoftsqlserver` / `mssql`	SQL Server
`redis` / `rediss`	Redis（明文/TLS）

URL 密码特殊字符需 URL 编码（@→%40、:→%3A、/→%2F）。

3.2 SQLite 文件路径参数

传本地文件路径即按 SQLite 打开（实测）：

beekeeper-studio /root/demo-data.sqlite

打开后窗口标题即为 demo-data.sqlite - Beekeeper Studio - Free Version，左侧 Entities 面板列出库内表。.sqlite、.db、.sqlite3 后缀文件与 sqlite:// URL 均可。

3.3 无参数启动与单实例行为

无参数执行 beekeeper-studio 打开主界面。应用启用单实例锁：已有实例在跑时，再次执行会把新传入的 URL/文件参数转交已有实例处理，不产生第二个窗口进程。

3.4 不存在的常规开关

实测确认 --version、--help 未实现为独立开关：在无图形会话的终端执行会直接按图形应用启动并报错：

[ERROR:ui/ozone/platform/x11/ozone_platform_x11.cc:249] Missing X server or $DISPLAY
[ERROR:ui/aura/env.cc:257] The platform failed to initialize.  Exiting.

这是 Electron GUI 应用的标准行为，不代表安装损坏。版本确认用 dpkg -l beekeeper-studio 或应用底部状态栏。

3.5 bks-flags.conf 旗标文件

Chromium/Electron 层旗标写入 ~/.config/bks-flags.conf，每行一个旗标，启动时自动加载（来源：官方 Linux 安装文档，查询日期 2026-10-20）：

touch ~/.config/bks-flags.conf
echo "--ozone-platform-hint=auto" >> ~/.config/bks-flags.conf
echo "--enable-features=UseOzonePlatform" >> ~/.config/bks-flags.conf

旗标	用途
`--ozone-platform-hint=auto` + `--enable-features=UseOzonePlatform`	Wayland 原生模式（含分数缩放支持）
`--disable-features=WaylandWpColorManagerV1`	修复 Wayland 下颜色异常（橙变黄/灰发黑）
其他 Chromium 旗标	如 GPU/输入法相关，按需逐行追加

修改后重启应用生效。X11 用户无需此文件。

四、三层 ini 配置体系

应用功能配置采用三层覆盖体系，后层覆盖前层同名键：

层	文件	角色
1	`/opt/Beekeeper Studio/resources/default.config.ini`	出厂默认值（随版本更新）
2	`/opt/Beekeeper Studio/resources/system.config.ini`	系统级覆盖（管理员定制）
3	`/opt/Beekeeper Studio/resources/user.config.ini`	用户级覆盖（个人定制，优先级最高）

出厂状态实测：第 2、3 层文件只有一行注释，即全部行为等于 default 层：

cat "/opt/Beekeeper Studio/resources/system.config.ini"
cat "/opt/Beekeeper Studio/resources/user.config.ini"

实测回显（两个文件内容相同）：

;override default config here

应用启动时会尝试把 default 配置复制到用户配置目录缓存（首启日志实测回显）：

19:27:10.415 [info]  [MAIN] (BksConfig)        › Loading configs.
19:27:10.416 [debug] [MAIN] (BksConfig)        › Loading config default.config.ini.
19:27:10.417 [info]  [MAIN] (BksConfig)        › Copying bundled config default.config.ini to /root/.config/beekeeper-studio/default.config.ini.

⚠️ 注意：改配置的标准做法是把要覆盖的段与键写进 user.config.ini（保持文件为合法 ini 格式，段名与键名照抄 default），而不是直接改 default.config.ini——后者会在版本升级时被覆盖丢失。system/user 层改动重启应用生效。

五、default.config.ini 参数分类详解

以下参数全部取自 v6.1.6 应用自带 default.config.ini（逐段实测读取）。改任何一项：把段名+键复制到 user.config.ini 写新值即可。

5.1 [general] 全局行为

键	默认值	说明
checkForUpdatesInterval	86400000	更新检查间隔，毫秒（24 小时）
checkForUpdatesDisabled	false	是否禁用自动更新检查
workspaceSyncInterval	10000	工作区同步间隔，毫秒（5 秒）
downloadUserAgent	`Mozilla/5.0 (compatible; Beekeeper Studio) ...`	下载用 UA

5.2 [security] 安全与断连策略

键	默认值	说明
disconnectOnSuspend	false	系统休眠时断开数据库连接
disconnectOnLock	false	屏幕锁定时断开
disconnectOnIdle	false	用户空闲时断开
lockMode	disabled	应用锁：`disabled` / `pin`（PIN 码锁屏，minPinLength=6）
idleThresholdSeconds	300	空闲判定阈值（秒）
idleCheckIntervalSeconds	30	空闲检查周期
activityReportIntervalSeconds	5	渲染进程活动上报周期
activityEvents[]	mousedown / keydown	计入「用户活动」的 DOM 事件
minPinLength	6	PIN 最短长度
allowRuntimeExtensions	false	是否允许 SQLite 运行时加载扩展（执行任意原生代码，默认拒绝）
disableSshConfigMatchExec	false	读取 `~/.ssh/config` 时是否跳过 `Match exec` 段

💡 说明：生产环境建议开启 disconnectOnIdle=true 并将 idleThresholdSeconds 调小，降低闲置会话占用数据库连接的风险；共享电脑上建议 lockMode=pin。

5.3 [ui.*] 界面行为

[ui.general]：

键	默认值	说明
binaryEncoding	hex	二进制数据显示格式：`hex` / `base64`

[ui.layout]：

键	默认值	说明
mainContentMinWidth	200	主内容区最小宽度（像素）
primarySidebarMinWidth	150	主侧栏最小宽度
secondarySidebarMinWidth	150	副侧栏最小宽度
defaultGlobalSidebarItem	tables	首次连接时全局侧栏选中页：`tables` / `queries` / `history`

[ui.queryEditor] 查询编辑器：

键	默认值	说明
maxResults	50000	结果集渲染上限（行）
defaultFormatter	bk-default	SQL 格式化器
primaryQueryAction	submitTabQuery	主运行键行为：运行全部/选中（另一可选值 submitCurrentQuery 仅运行当前查询）
secondaryQueryAction	submitCurrentQuery	副运行键行为

[ui.queryEditor.autocomplete] 自动补全：

键	默认值	说明
keywordCasing	preserve	关键字大小写：preserve（跟随输入）/ upper / lower
quoteIdentifiers	auto	补全标识符的引号策略：auto / always
disableKeywordCompletion	false	禁用 SQL 关键字补全
disableSchemaCompletion	false	禁用表/列（schema）补全

[ui.tableTable] 数据网格：

键	默认值	说明
pageSize	100	每页行数
largeFieldWidth	300	长字段列宽
maxColumnWidth / minColumnWidth	1000 / 100	列宽上下限
maxInitialWidth / defaultColumnWidth	500 / 125	初始最大宽 / 默认宽
editTrigger	doubleclick	单元格进入编辑的触发方式：doubleclick / click

[ui.connectionSidebar] 连接侧栏 / [ui.export] 导出 / [ui.tableList] / [ui.tableTriggers]：

键	默认值	说明
recentConnectionsLimit	10	Recent 连接列表最多显示条数
errorNoticeTimeout	60000	导出错误提示展示时长（毫秒，1 分钟）
itemHeight（tableList）	22.8	表列表项高（像素）
maxColumnWidth（tableTriggers）	300	触发器视图列宽上限

六、数据库连接参数（[db.*] 段）

6.1 [db.default] 全库默认

键	默认值	说明
allowSkipToLastPage	false	允许跳到表格末页（需额外 count 查询，可能昂贵）
maxReservedConnections	2	手动事务最多同时占用连接数（须小于连接池上限）
maxConnections	8	连接池上限
manualTransactionTimeout	600000	手动提交模式事务无活动自动回滚时限（10 分钟）
autoRollbackWarningWindow	60000	自动回滚前的警告窗口（1 分钟）
autocompleteQuoteCharacter	0	补全引号字符：0/−1 按数据库惯例（PG 双引号、MySQL 反引号、MSSQL 方括号）

[db.default.paramTypes] 参数风格： positional = true（? 开启）；named[]、numbered[]、quoted[] 默认空。

6.2 各数据库覆盖值

v6.1.6 内置专属参数段的数据库（实测自 default.config.ini，段名即类型小写）：

段	差异参数（默认值）
[db.mysql] / [db.mariadb]	connectTimeout=3600000（毫秒）、allowSkipToLastPage=true、maxConnections=10
[db.postgres]	connectionTimeout=15000、idleTimeout=20000、allowSkipToLastPage=true；paramTypes：positional=false、numbered[]='$'
[db.sqlite]	allowSkipToLastPage=true；paramTypes：positional=true、numbered[]='?'、named[]=':' 与 '@'
[db.cockroachdb] / [db.redshift]	connectionTimeout=15000、idleTimeout=20000、maxConnections=5
[db.sqlserver]	maxConnections=10；paramTypes：named[]=':'
[db.oracle]	maxConnections=4
[db.snowflake]	connectionTimeout=60000、idleTimeout=60000
[db.dynamodb]	cursorFetchTimeout=30000、columnSampleSize=50
[db.tidb] / [db.starrocks] / [db.greengage] / [db.bigquery] / [db.cassandra] / [db.firebird] / [db.clickhouse] / [db.mongodb] / [db.duckdb] / [db.sqlanywhere] / [db.trino] / [db.surrealdb] / [db.bedrock]	各自 allowSkipToLastPage / paramTypes / 超时项（详见文件内注释）

覆盖示例：把 MySQL 连接池调大并允许跳末页，写入 user.config.ini：

[db.mysql]
maxConnections = 20
allowSkipToLastPage = true

七、快捷键配置（[keybindings.*] 段）

快捷键全部可配置，段按功能区划分（默认值实测见本专栏《Beekeeper Studio 6.1.6 数据库连接与操作实战》第十章速查表），自定义示例——把「保存」改为 Ctrl+Shift+S：

[keybindings.general]
save = ctrlOrCmd+shift+s

说明：

ctrlOrCmd 自动映射 Linux/Windows 的 Ctrl 与 macOS 的 Cmd；altOrCmd、ctrlOrCmd+shift+… 同理；
支持一键多值：数组形式（如 refresh[] = f5 与 refresh[] = ctrlOrCmd+r 并存）；
改完重启应用生效；插件键位在 [keybindings.plugins.<插件名>] 段（如 bks-ai-shell 的 new-tab-dropdown-item = ctrlOrCmd+l）。

八、插件系统与其他段

8.1 [pluginSystem]

键	默认值	说明
disabled	true	插件系统总开关（社区版出厂关闭）
communityDisabled	true	社区插件功能（安装/仓库拉取/加载）开关
allow[]	bks-ai-shell、bks-er-diagram	disabled=true 时仅白名单插件可装可载

8.2 [plugins.*] 与 [azure]

键	默认值	说明
[plugins.bks-ai-shell] disabled	false	内置 AI Shell 插件开关
[plugins.bks-er-diagram] disabled	false	内置 ER 图插件开关
[azure] azSQLLoginScope	`https://ossrdbms-aad.database.windows.net`	Azure AD 登录 scope
[azure] ssoPrompt	select_account	Azure SSO 行为

九、用户数据目录详解

首次启动生成 ~/.config/beekeeper-studio/，实测目录内容与角色：

ls ~/.config/beekeeper-studio/

实测回显：

.key
app.db
demo.db
driver-deps
logs
plugins
Cache  Code Cache  Crashpad  DIPS  DawnGraphiteCache  DawnWebGPUCache
Dictionaries  GPUCache  Local Storage  Network Persistent State  Preferences
Shared Dictionary  Trust Tokens  blob_storage

路径	角色
`app.db`	应用元数据库（SQLite，约 220KB 起）：全部核心业务数据
`.key`	应用级加密密钥（224 字节），用于加密 app.db 中保存的密码/口令
`demo.db`	内置演示数据库（首次启动的 Demo Database 连接指向它）
`logs/`	日志目录（main.log、utility.log）
`plugins/`、`driver-deps/`	插件与数据库驱动依赖的落盘位置
其余	Chromium/Electron 标准缓存与状态文件（Cache、GPUCache 等）

9.1 app.db 核心表（实测 schema 摘录）

sqlite3 ~/.config/beekeeper-studio/app.db '.tables'

实测回显：

BK_MIGRATIONS          hidden_schemas         tabs
cloud_credential       installation_ids       tabulator_persistence
connection_folder      license_keys           token_cache
connection_pins        pins                   used_connection
encrypted_plugin_data  plugin_data            used_query
favorite_query         query_audit            user_pins
formatter_presets      query_folder           user_setting
hidden_entities        saved_connection

关键表职责：

表	职责
saved_connection	已保存连接全字段（connectionType、host、port、username、defaultDatabase、path、url、password、ssl、sslCaFile/sslCertFile/sslKeyFile、sslRejectUnauthorized、sshEnabled、sshHost/Port/Mode/Keyfile/Username、sshBastion*、socketPath、readOnlyMode、trustServerCertificate、windowsAuthEnabled、connectionFolderId、labelColor 等）
used_connection	最近打开的连接（RECENT 列表数据源，含 options JSON）
favorite_query / query_folder / query_audit	收藏查询、查询文件夹、查询审计
user_setting	应用设置键值（section、key、userValue、defaultValue、linuxDefault、macDefault）
tabs / tabulator_persistence	Tab 状态与表格视图持久化
connection_folder	连接文件夹（v6.1.0 起社区版功能）
license_keys / cloud_credential	许可与云凭据（付费版场景）

迁移要点：换机迁移必须同时拷贝 app.db 与 .key（缺 .key 则已存密码无法解密）；彻底重置应用删除整个目录即可。

十、日志与排障

日志位于 ~/.config/beekeeper-studio/logs/，分两个文件：

文件	内容
main.log	主进程日志（连接生命周期、错误）
utility.log	工具进程日志（插件、后台任务、配置加载）

实测 utility.log 样例（插件注册表检查）：

[2026-10-19 19:24:24.853] [error] (PluginManager)             › Failed to check for updates for plugin "bks-er-diagram" PluginSystemError: Plugin "bks-er-diagram" not found in registry.
    at PluginRegistry.findEntry (/opt/Beekeeper Studio/resources/app.asar/dist/utility.js:669732:11)
    ...

💡 说明：断网环境下启动出现上述插件检查报错属预期行为（无法访问插件仓库），不影响功能。排障时优先看 main.log 的连接错误与 utility.log 的配置加载行（BksConfig 前缀，见第四章实测日志）。

十一、注意事项

配置生效条件：ini 与 flags 改动均需重启应用；多实例并存时以先启动实例的配置为准（单实例锁）。
升级兼容：default.config.ini 随版本更新，仅以 user.config.ini 承载自定义；app.db 结构由内置迁移（BK_MIGRATIONS 表）自动升级，降级版本可能不识别新库结构——降级前备份用户目录。
敏感信息：密码只落 app.db（经 .key 加密），不出现在 ini 与日志；导出连接配置（JSON 侧栏等付费功能）时注意脱敏。
Flatpak 版路径差异：Flatpak 安装的用户数据在沙箱路径（~/.var/app/io.beekeeperstudio.Studio/config/beekeeper-studio/），且 SQLite 文件访问需 flatpak override 授权（见安装篇 FAQ）。
Snap 版限制：SSH 密钥需 snap connect 授权、SSH Agent 不可用（见安装篇 7.4 节）。

十二、参考链接

官方 Linux 安装文档（bks-flags.conf 来源）：https://docs.beekeeperstudio.io/installation/linux/
官方文档站：https://docs.beekeeperstudio.io/
GitHub 仓库（default.config.ini 随源码发布）：https://github.com/beekeeper-studio/beekeeper-studio
本专栏姊妹篇：《Beekeeper Studio 6.1.6 介绍与选型指南》、《Ubuntu 22.04 安装 Beekeeper Studio 6.1.6 指南》、《Beekeeper Studio 6.1.6 数据库连接与操作实战》