# 设置与应用数据

> 了解 DuckLocal 的本地存储路径、跨启动保留的状态项、联网行为（在线地图底图与版本更新检查）、界面缩放、主题与语言配置以及应用重置方法。

Source: https://ducklocal.app/docs/zh/settings-and-data

**[English](../settings-and-data.md)**

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

## 存储位置 {#where-things-are-stored}

| 平台 | 路径 |
| --- | --- |
| 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`](cli.md#show-work-in-the-running-window) 连接窗口所用的回环端口与随机令牌（token）。该文件仅你的系统账户有权读取；退出后遗留的旧 `gui-endpoint.json` 不会影响后续运行。

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

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

## 重启后保留的内容

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

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

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

## 网络 {#network}

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

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

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

## 在线底图 {#online-base-map}

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

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

## 检查更新 {#update-check}

状态栏最右边是 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](https://github.com/JetSquirrel/DuckLocal/releases/latest) 上的完全相同，只是放在一个在中国大陆也下载得快的镜像上。

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

## 语言

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

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

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

## 主题

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

## 界面大小 {#interface-size}

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

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

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

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

## 重置

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

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

Windows 上删除 `%APPDATA%\DuckLocal`。

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

## 疑难排查

症状、原因与解决办法都整理在[常见问题排查](troubleshooting.md)页面。