---
title: "镜像 CLI"
description: "镜像是一台开箱即用的设备：notarium 入口点，start、backup、restore、admin 等命令，以及输出流与退出码的契约。"
---

# 镜像 CLI

镜像自己就知道该怎么启动：`docker run` 后面不用再补一条命令，默认就会把服务端拉起来。参数只替换命令本身，所以一次性操作读起来很自然——`docker run … IMAGE restore`。

面向运维者的命令则用 `docker exec` 送进正在运行的容器，名字都很短：

```bash
docker exec notarium backup
docker exec -it notarium admin list
```

## 命令

| 命令 | 作用 | 通常如何调用 |
|---|---|---|
| `start` | 以 PID 1 的身份运行 HTTP/MCP 服务端 | 镜像的默认命令 |
| `backup` | 流式输出一份已校验的在线 ZIP | `docker exec notarium backup`，外加[运维手册](/docs/self-hosting/backup/)里的安全发布步骤 |
| `backup verify` | 校验归档，不改动任何东西 | `docker exec -i notarium backup verify < 文件` |
| `restore` | 把归档装入一个空的数据根目录 | 在全新数据卷上跑一个一次性容器 |
| `admin` | 绕开界面恢复访问权 | `docker exec -it notarium admin …` |
| `healthcheck` | 探测本地的 `/api/health` | Docker 的 `HEALTHCHECK` |
| `version` | 版本、提交、构建时间以及源码链接（`--json` 供脚本使用） | 技术支持与兼容性核对 |
| `help` / `--help` | 说明整个 CLI 或某一条具体命令 | 任意容器 |

`start` 留在前台，容器信号因此能直接抵达服务端——`docker stop` 会让它干净地停下。刻意没有停止和重启这类命令：那是编排器的活儿。数据库结构迁移在启动时自动应用，永远不必单独跑一条命令。

## 输出流与退出码

- 流式模式下（不带 `--output`），`backup` 往 stdout **只**写 ZIP 字节；诊断信息和最终汇总走 stderr。带上 `--output FILE` 时，归档写入该文件，stdout 只输出一份 JSON 汇总——别把它重定向进 `.zip`，落进去的并不是归档。
- `backup verify`、`restore` 以及非交互式的 `admin` 命令把结果打印到 stdout。
- 错误走 stderr，退出码非零。未知命令、未知选项、重复给出的选项以及缺少取值的选项一律**报错退出**，而不会被悄悄忽略。
- 在 Docker 下，规范的传输通道是 **stdin 和 stdout**。`backup` 的 `--output FILE` 与 `verify`/`restore` 的 `--input FILE` 是成对的，为的是容器本就能看到相应目录的那类场景。`--output` 还有个讨喜的副作用：命令自己写临时文件、校验归档，再原子地发布出去，且不覆盖任何已有文件——于是你不必再写一层 shell 包装。
- 每条命令都有 `--help`；`notarium --version` 等价于 `notarium version`。

## 构建标识

`version` 会准确打印出你正在运行的究竟是什么——任何关于兼容性的讨论、任何一次升级，都从这里开始：

```bash
docker run --rm docouno/notarium:latest version
docker compose exec notarium version --json
```

`version --json` 把同样的内容装进一个对象返回——`version`、`commit`、`builtAt` 和 `source`（指向确切源码修订的链接）——所以「当前部署的是什么」这项检查可以直接嵌进部署流水线。构建里确实没有的东西会如实返回 `null`：这些值从不臆造，因此可以放心依赖。同样的信息在界面里也能看到——**Settings → About**。

> [!important] 版本标签不可变
> 已发布的版本标签永远只对应一个具体镜像：`:0.1.0` 绝不会挪到另一个构建上。所以在生产环境里请固定到某个版本，而不是 `:latest`。发布的镜像面向 `linux/amd64` 构建；其他架构请从源码自行构建。

## 健康检查

只有当本地的 `/api/health` 端点报告健康时，`healthcheck` 才返回零退出码。它是为 Docker 的 `HEALTHCHECK` 指令和编排器探针准备的——不需要任何外部依赖，宿主机上也不需要 `curl`。

## 恢复访问

`admin` 是主机的运维者边界。修改密码的常规途径都在应用里（自己的密码在界面中改，别人的则通过管理员签发的一次性链接）。CLI 管的是另一类事：**强制**设定密码而无需出示当前密码，以及带外签发一名管理员。这两项操作刻意没有 HTTP 路径——因为压根没有可出示的东西——所以它们只属于能访问主机的人。

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

完整的命令清单及其含义——见[身份认证](/docs/self-hosting/authentication/#恢复访问)。

## 下一步

- [备份与恢复](/docs/self-hosting/backup/)——`backup`、`backup verify` 和 `restore` 背后的运维手册。
- [身份认证](/docs/self-hosting/authentication/)——`admin` 能做什么，以及你何时会需要它。
- [安装](/docs/self-hosting/install/)——镜像的运行与数据卷。