---
title: "安装"
description: "单个 Docker 镜像在 3000 端口上同时提供 API、MCP 和 Web 界面；单个 /data 数据卷承载全部状态。"
---

# 安装

Notarium 以**单个自包含镜像**的形式交付：一个 Node 进程在同一端口（默认 `3000`）上同时提供 REST API、面向智能体的 MCP 端点和编译好的 Web 界面。无需任何外部服务——不用数据库、不用消息代理、也不用独立的搜索引擎：知识引擎就跑在同一个进程里。全部状态都存放在单个 `/data` 数据卷中：元数据库、派生索引、你的 Markdown 文件（唯一可信来源）以及导出产物。

> [!note] 你需要准备什么
> 只要 **Docker**（或 Docker Desktop）和一个空闲端口即可。无需单独安装 Node、数据库或向量索引——一切都在镜像里。

## 运行镜像

最快的方式是用预构建镜像启动一个容器：

```bash
docker run -d --name notarium \
  -p 3000:3000 \
  -v notarium-data:/data \
  docouno/notarium:latest
```

单个 `/data` 数据卷承载全部状态：元数据库、索引、你的笔记以及导出产物。没有别的要配置的——端口 `3000` 和数据路径 `/data` 都已内置在镜像中。重新创建容器后，数据卷依然保留；`:3000` 左侧的端口可以改成任意一个空闲端口。

`docker run` 后面不用再追加命令：镜像的入口点就是内置的 `notarium` CLI，默认执行 `start`。运维用的命令也都在这套 CLI 里——`backup`、`restore`、`admin`、`healthcheck`、`version`。见[镜像 CLI](/docs/self-hosting/cli/)。

## 使用 Docker Compose

如果这个实例你打算长期留用，写成 compose 文件会更省事：改起来方便，也便于纳入版本控制，而 `restart` 会在宿主机重启后把容器自动拉起来。

```yaml
services:
  notarium:
    image: docouno/notarium:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - notarium-data:/data

volumes:
  notarium-data:
```

把它保存为 `compose.yaml`，用 `docker compose up -d` 启动。命名数据卷 `notarium-data` 独立于容器存在：`docker compose down` 不会动它，只有显式执行 `docker volume rm` 才会把它删掉。

> [!note] 配置也写在这里
> 环境变量写在服务的 `environment:` 块里。如果你更愿意单独用一个文件放它们，就在同一个服务块里再加一行 `env_file: .env`——光把 `.env` 放在 compose 文件旁边，它**并不会**自己进到容器里：Docker Compose 只会把它代入 compose 文件本身的文本。完整清单见[环境变量](/docs/reference/environment-variables/)。

## 首次运行

打开 `http://localhost:3000`，迎接你的是**首次运行的设置界面**。实例默认运行在 `password` 模式，第一位访客会创建**所有者**——唯一拥有管理员权限、并对其所创建空间拥有所有权的账户。没有预置密码；所有者注册完成后，设置流程就此永久关闭。关于各模式的更多说明，见[身份认证](/docs/self-hosting/authentication/)。

## 数据卷

| 数据卷 | 存放内容 | 性质 |
|---|---|---|
| `/data` | 你的 Markdown 文件（`/data/spaces`，每个空间一个文件夹）、元数据库（`/data/meta.db`——标识符、版本历史、用户、访问权限）、引擎的派生索引（`/data/engine`）以及导出产物。 | 文件是唯一可信来源（file-first 原则）；元数据库无法从文件推导得出；索引是派生物，重建一次即可恢复。 |

务必守护好这个数据卷本身：它一旦丢失，你的数据也随之而去。`/data/engine` 里的索引丢了可以从文件重建，但元数据库（`/data/meta.db`——历史、用户、访问权限）和笔记本身（`/data/spaces`）则无处可恢复——给它们做备份是必须的。如何在不停服的前提下取得一份经过校验的备份，见[备份与恢复](/docs/self-hosting/backup/)。

## 从源码构建

如果你在使用 Notarium 仓库，Docker 的统一入口是 `make`：

```bash
cp .env.example .env   # 默认值即可用——无需填写任何内容
make up                # 本地运行生产镜像 → http://localhost:3000
make dev               # 带热重载（HMR）的开发栈
```

常用命令：`make logs`（日志）、`make ps`（状态）、`make down`（停止并移除）、`make sh`（进入容器 shell）。

## 无镜像仓库安装（离线隔离环境）

要部署到隔离环境，可以把镜像当作文件搬过去，无需访问镜像仓库：

```bash
make image                              # 构建镜像
make save                               # 导出为 notarium-<version>.tar.gz
# 将归档文件转移到目标主机，然后：
docker load < notarium-<version>.tar.gz # 加载镜像
```

之后用你自己的 `compose`/`.env` 把它跑起来——镜像仓库坐标并未固化在镜像里。

下一步是按你的需要调整实例：见[配置](/docs/self-hosting/configuration/)。