---
title: "导出"
description: "将空间或文件夹打包为由 Markdown 文件组成的单个 ZIP 归档下载——结构与身份完整保留，无任何丢失。"
---

# 导出

导出会把整个空间、或单个文件夹，打包为一个由 Markdown 文件组成的 ZIP 归档下载。由于你的文件才是事实来源（file-first 原则），导出直接从磁盘读取文件，而非从索引重建：归档里装的是**真实文件**，包括每个文件 frontmatter 中的 `notarium-id`。

正因如此，导出是**可逆的**——你可以用[导入](/docs/import-export/import/)把它还原回来，或迁移到另一个实例，而不丢失结构、身份或日期。导出并不真的是「把数据搬出去」；它只是把磁盘上本就以文件形式存在的内容打包起来的一种便捷方式。

## 如何导出

导出位于空间设置的 **Export** 标签页：

- 点击按钮会排入一个任务，随后你会看到进度条——笔记数量确定后即显示百分比——以及一个 **Cancel** 按钮。
- 就绪后归档会自动下载；旁边还会保留 **Download .zip**（再次下载）和 **Export again**（重新导出）按钮。
- 离开标签页再回来是安全的：回到页面时，你会再次看到正在运行的任务，或一个可供下载的文件。

你也可以从文件树的右键菜单导出**单个文件夹**——即 **Export folder** 项。这是同一个任务，只是范围收窄到某个子树；进度会显示在一条带取消按钮的常驻提示里。

## 选项

两种导出路径都接受同一组参数：

| 参数 | 取值 | 作用 |
|---|---|---|
| `scope` | `user`（默认）· `all` | `user`——仅你的笔记；`all`——空间里的全部内容，包括智能体的记忆挂载点（`.notarium/memory`）。 |
| `frontmatter` | `keep`（默认）· `strip` | `keep` 原样写入文件；`strip` 切除 YAML 块——一份便于阅读的干净副本。 |
| `folder` | 路径 | 将导出范围收窄到某个子树（即 **Export folder** 所做的事）。 |

> [!warning] `frontmatter=strip` 会破坏重新导入
> 切除 frontmatter 会得到一份有损副本：连同 YAML 块一起，`notarium-id` 和标签也会丢失。这样的归档便于把笔记交给他人阅读，但你无法再无损地把它导入回来。需要搬迁数据时，请保持 `keep`（默认值）。

> [!important] 导出不是实例备份
> 即便用了 `scope=all`，导出归档里装的也只有空间的 Markdown 文件。它不含元数据库：没有账号、没有访问权限、没有版本历史、没有任务状态。你无法用它恢复一个实例。备份是另一项独立操作，由镜像内置的命令执行——参见[备份与恢复](/docs/self-hosting/backup/)。

## 底层如何运作

导出以流式方式构建，因此任意大的知识库都不会驻留在内存里：

- **默认为异步任务。** 当主机带有元数据库（自托管的常态）时，导出是一个持久任务：后台工作进程把 ZIP 组装进产物存储，并以支持断点续传的方式提供成品文件。关闭标签页、掉线或服务器重启都不会中断导出。
- **下载不做缓冲。** 浏览器把成品归档直接流式写入磁盘，文件名取自响应头——大知识库不会驻留在标签页的内存里。
- **取消即停工。** 被取消的下载会停止拉取笔记——服务器不会白白地继续读取整个知识库。

```mermaid
flowchart LR
  notes[(Markdown 笔记)] -->|从磁盘读取| worker[后台工作进程]
  worker -->|ZIP| artifact[任务产物]
  artifact -->|下载| user([浏览器])
```

> [!note] 无元数据库时的导出
> 在没有元数据库的主机上（仅 `AUTH_MODE=none` 模式下才没有）不存在任务层：导出走同步流式路径——同一个 ZIP 在单个请求内以直接下载的形式提供，没有进度、也没有断点续传。改变的只是投递方式，结果是一样的。

## 边界

- **一次一个空间。** 空间是各自带访问控制的隔离存储；要导出多个，就逐个分别导出。
- **产物有 TTL。** 成品 ZIP 只保留有限时间（默认 7 天），之后由垃圾回收器移除；在过期之前你可以反复下载它。
- **二进制附件不会被导出。** 归档装的是笔记文本——Markdown 文件。
- **能取消，但不能暂停。** 任务可以取消；没有暂停与恢复。

## 下一步

- [导入](/docs/import-export/import/)——把归档还原回来，或将知识库迁移到另一个实例。
- [章节概览](/docs/import-export/)——为什么 file-first 让导入和导出都很省事。