---
title: "身份认证"
description: "password 与 none 两种模式、服务端会话、邀请与重置，以及通过 CLI 恢复管理员。"
---

# 身份认证

Notarium 的身份认证是内置的，完全跑在元数据库之上——不依赖外部 IdP，不用 JWT，也不用 SMTP。模式由 `AUTH_MODE` 变量选定，它决定了到底有没有登录这一环。

## `password` 模式（默认）

默认即安全：完整的多用户身份认证。

- **首次启动。** 在全新实例上，第一位访客通过首次运行的设置界面创建所有者（主机管理员，同时是已配置各空间的所有者）。没有预置密码；该账户一旦注册完成，设置界面便永久关闭。
- **会话。** 登录会创建一个**服务端会话**——数据库里的一行记录，而不是 JWT。它存放在 HttpOnly 的 `nt_session` cookie 中，采用 30 天的滑动 TTL，在 HTTPS 下会带上 `Secure` 标志。吊销即时生效：禁用某用户或修改密码会立即中断其活跃会话。
- **需要一个元数据库。** 它默认就在——`DATA_DIR` 下的 SQLite，无需任何配置。只有当你要迁移到外部 Postgres 时才会去动 `META_DB_URL`。参见[数据库](/docs/self-hosting/database/)。

## `none` 模式

单一的全权限主体——运维者会有意开启此模式，用于桌面端、本地开发或受信内网。认证路由返回 `404`，不存在登录 UI，认证也不需要元数据库。

> [!danger] 不要把 `none` 实例暴露到网络
> 在 `none` 模式下，任何能访问到端口的人都将获得对全部数据的完整访问权——包括智能体的 MCP 端点。请仅在隔离或受信的网络中使用它。

## 角色与访问

对数据的访问由空间成员资格授予，共有三种角色：

| 角色 | 权限 |
|---|---|
| `reader` | 读取空间内的一切。 |
| `writer` | 编辑笔记。 |
| `owner` | 管理成员资格。 |

**主机管理员**标志赋予对用户和空间的管控权，但要**读取某个具体空间的数据**，仍然需要在其中拥有成员资格。关于该模型的更多内容——见[访问模型](/docs/concepts/access-model/)。

## 邀请与密码重置

Notarium 没有 SMTP——账户的初次交接靠的是一条由管理员亲手转交的**一次性链接**。一套机制，两种用途：

- **邀请**——添加一个无密码的用户；链接有效期 7 天。
- **密码重置**——链接有效期 24 小时；一经接受即终止旧会话。

令牌承载于 URL 片段中（`/invite#<token>`），因此绝不会落入访问日志。同一用户同一时刻只有一条这样的有效链接，而管理员也永远不会知道别人的密码。

## 面向智能体的令牌

AI 智能体使用形如 `Authorization: Bearer ntp_…` 的个人访问令牌（PAT）进行认证，带有 `read` 或 `write` 作用域，并可选地收窄到特定空间。密钥**只会展示一次**。签发令牌及其他管理操作仅在会话内可用——泄露的 PAT 无法提权。详情——见[连接智能体](/docs/agents/connect/)与[安全与可见性](/docs/agents/security/)。

## 恢复访问

既然重置链接只能由管理员签发，那么弄丢唯一管理员的密码就意味着失去访问权。出路是直接对元数据库操作的 **admin CLI**。它是镜像内置命令之一，所以调用很短，直接送进正在运行的容器：

```bash
docker compose exec notarium admin create-admin <user> --random

# 裸 docker run 的情况：
docker exec -it notarium admin create-admin <user> --random
```

不必停服：WAL 模式下的 SQLite 容得下第二个写入者，Postgres 就更不在话下。元数据库由 CLI 自行定位，逻辑与服务端一致（`META_DB_URL`，或由 `DATA_DIR` 推导出的根目录）；路径不对时它会直接报错退出，而不是悄悄建出一个「没有用户」的空库。

可用命令：

| 命令 | 作用 |
|---|---|
| `list` | 列出用户。 |
| `passwd <user> [--password <pw> \| --random]` | 修改密码。 |
| `create-admin <user> [--random] [--display "Name"]` | 创建管理员。 |
| `grant <user> <space> <owner\|writer\|reader>` | 在某空间中授予角色。 |

不带标志时，密码会从 stdin 读取并关闭回显，因此不会进入命令历史。`setPassword`/`createAdmin` **只能从 CLI** 调用——它们没有 HTTP 路径：这是主机的运维者边界。镜像的其余命令见[镜像 CLI](/docs/self-hosting/cli/)页面。