设置与应用数据

English

DuckLocal 会在磁盘上保存一个数据库文件和一个日志文件；应用窗口运行期间还会生成一个小文件，启用在线底图时则会缓存地图瓦片，下载好的更新也会先放在缓存里。其余数据只在会话期间保存在内存中。（仪表盘的审阅评论例外：它们保存在仪表盘文件旁，不在此处，详见用评论审阅。）

存储位置

平台	路径
macOS	~/Library/Application Support/DuckLocal/history.duckdb
Windows	%APPDATA%\DuckLocal\data\history.duckdb
Linux	~/.local/share/ducklocal/history.duckdb

这个 DuckDB 文件里有四张表：查询历史、已注册的数据文件、附加在当前数据库旁边的数据库，以及一张小的键值设置表，存着界面语言和大小、打开的查询和仪表盘标签页、最近的仪表盘列表，以及在线底图和检查更新是否打开。应用运行期间，旁边还会多出一个 .wal 文件（DuckDB 的预写日志）。

你的数据永远不会被复制进去。已注册的文件只记录路径，启动时重新挂载。

窗口运行时，同目录下的 gui-endpoint.json 会记录 ducklocal open 连接窗口所用的回环端口与随机令牌（token）。该文件仅你的系统账户有权读取；退出后遗留的旧 gui-endpoint.json 不会影响后续运行。

同目录下的 logs 文件夹存放窗口的日志 ducklocal.log（以及上一次启动的 ducklocal.previous.log）。DuckLocal 崩溃时，会先在这里写下一份 crash-….log 报告，下次启动时告诉你发生了什么，并提供 显示报告。最多保留最近十份报告。反馈问题时请附上它。打开日志文件夹 可以直接打开这个文件夹：macOS 上在 DuckLocal 菜单里，所有平台上都在状态栏右端版本号的右键菜单里。ducklocal 命令不写日志文件，它的错误直接返回给调用方。

在线底图的瓦片存在系统的缓存目录里：macOS 是 ~/Library/Caches/DuckLocal/tiles，Windows 是 %LOCALAPPDATA%\DuckLocal\cache\tiles，Linux 是 ~/.cache/ducklocal/tiles，每个瓦片服务器一个文件夹。删掉它没有影响——瓦片会直接重新下载。下载好的更新在安装之前，放在同一个缓存目录下的 updates 里。

重启后保留的内容

会记住	位置
已注册的数据文件（路径、视图名、类型）	应用数据文件
查询历史，包括失败记录	应用数据文件
界面语言	应用数据文件
界面大小	应用数据文件
是否已看过新手引导	应用数据文件
侧栏是否收起	应用数据文件
附加在当前数据库旁边的数据库，以及各自是否只读	应用数据文件
打开的查询标签页，及其标题和 SQL	应用数据文件
打开的仪表盘标签页及其标题	应用数据文件
在线底图是否打开	应用数据文件
启动时是否检查更新	应用数据文件
最近打开的仪表盘（侧栏的 仪表盘）	应用数据文件

不会记住	说明
结果面板的内容	仅在内存中，重新运行查询即可
打开的是哪个数据库文件	每次启动都从内存数据库开始，除非选择了数据库文件
窗口大小与位置	固定为 1440×900，最小 960×600
侧栏与结果面板的尺寸	每次启动固定
结果过滤器	仅在内存中
仪表盘里筛选器选中的值	仅在内存中；重新加载标签页时保留
主题	总是以浅色启动，见下文
S3 凭据	按设计仅限当前会话

主题是个例外：语言的切换会保存下来，主题的切换不会，每次启动都是浅色模式。

网络

在你打开之前，DuckLocal 不会自己发出任何网络请求。有两个开关，一开始都是关的；另外就是你直接要求的操作：

请求	什么时候	发出去的内容
在线底图	打开后，每次画地图时	要哪些瓦片，大致能看出你在看哪片区域、放大到哪一级
检查更新	点击版本号时；或打开开关后，每次启动时	向 dl.ducklocal.app 发一次请求，问最新版本号；有新版本时，下载它的安装包
S3	配置并查询 S3 时	你对所配置存储的请求
扩展	点 安装 或 更新，或执行 INSTALL 时	从 DuckDB 扩展仓库下载
SQL 里的远程数据	SQL 写了 https://、s3:// 或远程数据库时，包括打开仪表盘时运行的 SQL。需要已安装相应扩展	SQL 请求的内容，包括写进地址里的任何内容

没有遥测。除了你运行的 SQL，这些请求都不会带上你的任何一行数据。SQL 写什么就做什么：地址里可以带上表里的值。所以装了 httpfs 之后，你不信任的人发来的 .dash 文件，在打开时就可能把数据发出去。Network and privacy（英文）列出了所有网络路径，以及如何自行验证。

在线底图

地图（仪表盘里的，或查询结果 图表 标签页里的）可以在点的下面画 OpenStreetMap 瓦片。显示 → 在线底图（OpenStreetMap） 打开或关闭它，选择会被记住（设置表里的 map_tiles，值为 on 或 off）。它默认关闭。发出去的只是要哪些瓦片——大致能看出你在看哪片区域、放大到哪一级——不会带上任何一行数据。

下载遵守 OpenStreetMap 基金会的瓦片使用政策：带可识别的 User-Agent，同时最多两个请求，缓存的瓦片一周内直接复用，不批量预取，地图上标注出处。用量较大时，可以在设置表里把 map_tile_url 设成别的服务器的 {z}/{x}/{y} URL 模板。

检查更新

状态栏最右边是 DuckLocal 的版本号，例如 DuckLocal 0.3.0。点击它，会去 dl.ducklocal.app 查询最新版本：

• 已是最新：你用的就是最新版。
• 正在下载 v0.3.1…：有新版本，DuckLocal 正在下载。解包之前，会用发布时公布的大小和 SHA-256 校验安装包；在 macOS 上，还会核对它和正在运行的应用是同一个签名。
• 重启以更新到 v0.3.1：新版本已经就绪。点击它会退出、安装并重新打开；不点的话，下次退出 DuckLocal 时安装。
• 有新版本 v0.3.1：这份 DuckLocal 没法自己安装新版本，比如你自己编译的版本，或者放在它没有写入权限的文件夹里。点击它下载安装包，按你当初安装的方式装新版即可。
• 检查更新失败：鼠标悬停可以看到原因（没联网、代理拦截、下载的文件和校验值不符等），点击重试。

更新来自 dl.ducklocal.app：安装包和 GitHub Release 上的完全相同，只是放在一个在中国大陆也下载得快的镜像上。

在 macOS 上，DuckLocal 菜单里有同样的 检查更新…，还有 启动时检查更新：每次启动时检查一次。这个开关默认关闭（设置表里的 update_check，值为 on 或 off）。打开之前，只有你点击时才会检查。

语言

标题栏中的 EN / 中 按钮会立即切换界面语言，并记录这一选择。

首次运行时（还没存下任何设置），语言取自系统区域设置：LC_ALL 或 LANG 中含 zh 就用中文，否则用英文。已存的值无法识别时，回退到中文。

有少量字符串刻意不翻译：DuckLocal、S3 和 EXPLAIN 按钮标签、EN / 中 切换，以及凭据占位符。引擎和网络的错误消息原样显示，不论界面是什么语言，始终是英文。

主题

太阳/月亮按钮在浅色与深色主题之间切换。没有主题选择器，也没有可编辑的主题文件，只有这两种模式。

界面大小

文字、图标和控件一起缩放，共四档：

大小	界面文字	编辑器文字
小	13px	12px
默认	14px	13px
大	16px	15px
特大	18px	17px

在标题栏的 Aa 按钮里选择，或用 ⌘+（放大）、⌘−（缩小）、⌘0（复原）逐档切换。这几个快捷键无论焦点在哪里都有效，SQL 编辑器里也一样。所选大小会被记住，切换明暗主题后也不变。

你拖动过的面板尺寸，以及仪表盘图表的高度，仍以像素计：这些由你自己调整，不随界面缩放。

重置

想从头开始（清空查询历史、已注册的文件、附加的数据库、记住的标签页和所有设置），就退出 DuckLocal，删除它的应用数据目录：

rm -rf ~/Library/Application\ Support/DuckLocal   # macOS
rm -rf ~/.local/share/ducklocal                  # Linux

Windows 上删除 %APPDATA%\DuckLocal。

下次启动时会重新创建这个目录。你的数据文件完全不受影响，删掉的只是 DuckLocal 自己的记录。

疑难排查

症状、原因与解决办法都整理在常见问题排查页面。