---
title: "配置"
description: "关键环境变量概览：端口、认证模式、元数据库、空间拓扑、搜索。"
---

# 配置

Notarium 通过**环境变量**配置——镜像里不会固化任何密钥或路径。默认值面向零配置：全新实例无需任何设置就能跑起来。本页概述关键变量；完整清单连同确切取值与默认值见[参考手册](/docs/reference/environment-variables/)。

配置既可以通过 `docker run` 的 `-e` 标志传入，也可以写进 `.env` 文件（从 `.env.example` 复制而来）。Docker 栈会把 `.env` 原样传入容器。

## 关键变量

| 变量 | 用途 | 默认值 |
|---|---|---|
| `DATA_DIR` | 唯一的数据调节项：其余一切都由这个根目录派生——元数据库、索引、笔记、产物。未设置 → 采用可用的默认值。 | `/data`（Docker）；`~/.local/share/notarium`（宿主机） |
| `PORT` | 后端监听的端口（`/api`、`/mcp` 以及 Web 界面）。 | `3000` |
| `AUTH_MODE` | 认证模式：`password` 或 `none`。 | `password` |
| `META_DB_URL` | 元数据库：`sqlite:<path>` 或 `postgres://…`。可选——仅在使用外部 Postgres 时才设置；默认是 `DATA_DIR` 下的 SQLite。 | `sqlite:<DATA_DIR>/meta.db` |
| `SPACES_ROOT` | 作为根目录，其下每个空间就是一个文件夹；支持从界面创建空间。可选——仅当笔记存放在 `DATA_DIR` 之外时使用。 | `<DATA_DIR>/spaces` |
| `VECTOR_SEARCH` | `on`/`off`——语义（向量）搜索。 | 已发布镜像中为 `off`（代码中为 `on`） |

每个主题都有各自的专页：[身份认证](/docs/self-hosting/authentication/)（`AUTH_MODE`）、[数据库](/docs/self-hosting/database/)（`META_DB_URL`）、[语义搜索](/docs/self-hosting/search-setup/)（`VECTOR_SEARCH` 及模型参数）。

## 空间拓扑

定义空间有两种方式：

- **`SPACES_ROOT`**——零配置：每个空间都是指定根目录下的一个文件夹。空间在首次运行时创建，也可以用界面里的“New space…”按钮创建。这是 Docker 栈的默认方式。
- **`SPACES_CONFIG`**——显式且固定的拓扑（内联 JSON 或指向 JSON 文件的路径）。适合空间集合由运维方定好、不从界面创建的场景。

关于空间与项目的模型，参见[核心概念](/docs/concepts/spaces-and-projects/)。

## 智能体认证（OAuth）

除了个人令牌（PAT），Notarium 还能通过 **OAuth** 为 MCP 连接器授权——这样智能体（例如 Claude 连接器）就能自己完成认证，无需手动粘贴令牌。这不需要单独配置：客户端会动态注册。位于反向代理之后时，请设置 `PUBLIC_BASE_URL`（例如 `https://notes.example.com`）——为 OAuth 元数据提供一个稳定的外部地址；不设置的话，地址会从代理的转发头推导得出。同样在代理之后，`TRUST_PROXY` 也值得一并设置，好让登录和放行新连接器的限流按客户端的真实 IP 计数，而不是按代理的地址——参见[生产环境](/docs/self-hosting/production/)。关于接入智能体的更多内容，参见[连接智能体](/docs/agents/connect/)。

> [!tip] 完整参考
> 搜索相关的变量（`EMBED_MODEL`、`EMBED_DIMENSIONS`、`EMBED_CPU_MEM_ARENA` 等）、同步间隔以及其他精细调节项，都汇总在[环境变量](/docs/reference/environment-variables/)页的表格里。

下一步：配置[身份认证](/docs/self-hosting/authentication/)，需要的话再启用[语义搜索](/docs/self-hosting/search-setup/)。