在单节点上快速上手（二进制 + systemd）

这是贴近生产形态的首次安装：一台 Linux 主机、一个静态二进制、systemd、内嵌的 SQLite 存储 —— 以及真实的首次运行路径（一个一次性 setup token、默认开启 TLS、无默认凭据、无演示数据）。完成后，你将拥有一个作为加固服务运行的 Olivares AI，并已接入一个真实 source、填充好一张访问图。

它与快速开始在五分钟内演示的是同一个引擎；区别在于姿态。如果你想先即时浏览一番，先做快速开始，然后回到这里进行真正的安装。

本页的每条命令都已按原样针对当前二进制运行过（首次启动横幅、token 恢复路径、pgAudit 接入以及下文的图，都由 scripts/quickstart-smoke.sh 执行，并已为本指南重新验证）。

先决条件

一台带有 systemd 和 curl 的 Linux 主机。
Go 1.26+ 用于构建二进制（存储是纯 Go 的 SQLite，因此无需 C 工具链）。带签名预构建工件的发布会在首次公开发布时提供 —— 在此之前你需从 checkout 构建，而验证一次发布记录了你在它们存在后将使用的信任链。

1. 构建并安装二进制

构建这一个静态工件（引擎 + 内嵌 web UI + 第一方 connectors）：

task build                      # produces ./bin/olivares
./bin/olivares version

安装它并创建服务用户：

sudo install -m 0755 bin/olivares /usr/local/bin/olivares
sudo useradd --system --home /var/lib/olivares --shell /usr/sbin/nologin olivares

2. 将它作为加固的 systemd 服务运行

创建 /etc/systemd/system/olivares.service：

[Unit]
Description=Olivares AI — self-hosted engine for enterprise AI
Documentation=https://olivares.ai/docs
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=olivares
Group=olivares
ExecStart=/usr/local/bin/olivares serve \
  --listen 127.0.0.1:8443 \
  --grpc-listen 127.0.0.1:8444 \
  --data-dir /var/lib/olivares
Restart=on-failure
RestartSec=5

# The data directory holds the SQLite store, the audit signing key and the TLS
# material. StateDirectory creates /var/lib/olivares owned by the service user.
StateDirectory=olivares
StateDirectoryMode=0700
UMask=0077

# Hardening (mirrors the container posture: non-root, read-only, no escalation)
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictRealtime=true
LockPersonality=true
MemoryDenyWriteExecute=true
SystemCallArchitectures=native
CapabilityBoundingSet=
AmbientCapabilities=
ReadWritePaths=/var/lib/olivares

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now olivares

引擎默认绑定 loopback —— 127.0.0.1:8443 是有意为之。之后再将它对外暴露，置于你自己的 ingress 和 TLS 之后，作为一个明确的决定（参见加固）。

3. 领取一次性 setup token

全新安装 没有默认凭据。在首次启动时，引擎会铸造一个一次性 setup token（olst_…），并 仅打印到 stdout —— 在 systemd 下，也就是 journal：

journalctl -u olivares -o cat | sed -n '/FIRST-BOOT SETUP/,/========================/p'

=== FIRST-BOOT SETUP ===
No accounts exist yet. Open the console and create the first administrator
with this one-time token — setup also creates your first organization and
makes that administrator its owner:

  Console:  https://127.0.0.1:8443
  Token:    olst_…

The console serves HTTPS with a self-signed certificate on first boot — your
browser will warn once; that is expected. The token is shown ONCE and is
single-use. Prefer the API? POST /v1/setup {"token":"…","email":"…",
"password":"…"} — add "organization":"…" to name it (default: "Default
Organization"). The reply carries the new organization's tenant_id.
========================

创建第一个管理员并登录：

SETUP="olst_…"        # from the banner above

curl -ksf -X POST https://127.0.0.1:8443/v1/setup \
  -H 'Content-Type: application/json' \
  -d "{\"token\":\"$SETUP\",\"email\":\"you@example.com\",\"password\":\"<strong-password>\"}"

TOKEN="$(curl -ksf -X POST https://127.0.0.1:8443/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"<strong-password>"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')"

4. 创建你的第一个组织

产品中的一切都是租户范围的，因此请创建你的 sources 将上报到的组织：

TENANT="$(curl -ksf -X POST https://127.0.0.1:8443/v1/system/orgs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Production","slug":"prod"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["tenant_id"])')"
echo "tenant: $TENANT"

5. 接入你的第一个真实 source

Sources 在一个由 OLIVARES_SOURCES_CONFIG 命名的、运维方拥有的 JSON 文件中声明，在引擎启动前读取。下面是 PostgreSQL pgAudit source（clean-tier 的 R/RW 信号 —— 关于 Postgres 侧的设置见 pgAudit 指南）：

sudo tee /etc/olivares/sources.json >/dev/null <<JSON
{"sources":[{
  "name": "salesdb-pgaudit",
  "kind": "pgaudit",
  "tenant": "$TENANT",
  "config": { "log_path": "/var/log/postgresql/postgresql.csv", "format": "csvlog" }
}]}
JSON
sudo chmod 0600 /etc/olivares/sources.json && sudo chown olivares: /etc/olivares/sources.json

用一个 drop-in 将服务指向它，然后重启：

sudo systemctl edit olivares

[Service]
Environment=OLIVARES_SOURCES_CONFIG=/etc/olivares/sources.json
ReadOnlyPaths=/etc/olivares

sudo systemctl restart olivares
journalctl -u olivares -o cat | grep "ingest: wired source"

ingest: wired source (in-process fast-path) name=salesdb-pgaudit kind=pgaudit

如果什么都没接入，引擎会如实说明，而不是在一张空图上看起来健康 —— 关于确切的警告及其各自的含义，参见故障排查。

6. 到达图

curl -ksf "https://127.0.0.1:8443/v1/m/accessmap/graph?limit=200" \
  -H "Authorization: Bearer $TOKEN" -H "X-Olivares-Tenant: $TENANT" | python3 -m json.tool

curl -ksf "https://127.0.0.1:8443/v1/m/accessmap/drift" \
  -H "Authorization: Bearer $TOKEN" -H "X-Olivares-Tenant: $TENANT" | python3 -m json.tool

同一张图也会渲染在 https://127.0.0.1:8443 处内嵌的 web UI 中（从工作站访问时，请隧道转发：ssh -L 8443:127.0.0.1:8443 <host>）。

7. 在你认为完成之前

数据目录中有两个工件决定了你的证据能否在事故中存续 —— 请现在就处理它们，而不是事后：

| 工件 | 为何重要 | 操作 | |---|---|---| | audit-signing.key | 签署 append-only 的审计账本。若丢失，账本将无法再被重新验证。引擎仅在首次启动时警告 —— 没有强制的密钥托管。 | 今天就把它在主机外备份，权限为 0600。 | | 账本公钥 | 公钥的一份 主机外 副本，是在主机被攻陷后使验证仍能抵抗攻击者的关键。 | curl -ksf https://127.0.0.1:8443/v1/audit/pubkey 并将结果保存在主机外。 |

然后安排真正的备份 —— olivares dr backup 会生成一个加密的、对账本连续性安全的备份包；备份与恢复指南是完整流程，包括恢复演练。

健康与监控

引擎在 HTTP 监听器上暴露 /livez（进程存活）、/readyz（存储可达 —— 这是可用性 SLI）和 /metrics（Prometheus）：

curl -ks https://127.0.0.1:8443/readyz
# {"leader":true,"setup_required":false,"status":"ok","store":"up"}

关于指标集、SLO 目标和随附的告警规则，参见用 Prometheus 监控。

后续步骤

接入更多信号：connector 指南 —— pgAudit、CloudTrail、Claude Code、eBPF，以及目录的其余部分。
加固部署：安全加固 —— 暴露、collectors 的 mTLS、审批。
治理：治理与审批 —— RBAC、策略，以及决策记录保证。