跳至正文

机器翻译。英文版本为权威来源，母语审校尚未完成。

快速入门

安装与自托管

Olivares AI 单个二进制文件的生产安装——无默认凭证、默认启用 TLS、/readyz 和 /livez 探针、SQLite 或最小权限 Postgres

最近更新:

Olivares AI 作为一个内嵌 Web 控制台的静态二进制文件发布。控制平面——观测、治理和审计你基础设施上 AI 代理的部分——在你的边界内运行，可以气隙隔离。本页介绍生产级安装：一台主机、安全默认值、健康探针，以及对多租户部署重要的存储选择。

如果你只想先看看，快速入门可以在大约五分钟内启动一个合成演示资产。本页是真正的生产姿态。

获取二进制文件

这里没有公共下载 URL。你可以通过以下两种方式获取 olivares 二进制文件：

  • 签名的发布产物 ——在运行之前验证它。参见验证发布版本了解签名和溯源链。
  • 从源码构建 ——存储是纯 Go SQLite，因此不需要 C 工具链。task build 生成 ./bin/olivares，内嵌 Web UI 和第一方连接器；olivares version 确认你构建的内容。

无论哪种方式，你最终得到一个文件。安装它并创建一个专用的服务用户，而非以 root 运行。

安全默认值

默认值的选择使全新安装在你触及任何标志之前就是安全的。

默认值行为
凭证无。首次启动时打印一个一次性、单次使用的设置令牌（前缀 olst_）；你使用它来创建第一个管理员。
TLS开启。没有 --tls-cert/--tls-key 时，引擎在数据目录中生成自签名证书并记录其 fingerprint_sha256。--insecure（明文）仅用于本地开发。
绑定回环地址。--listen 默认为 127.0.0.1:8443，gRPC 默认为 127.0.0.1:8444；有意地暴露它们，放在你自己的入口和 TLS 后面。

最小首次启动：

olivares serve \
  --listen 127.0.0.1:8443 \
  --grpc-listen 127.0.0.1:8444 \
  --data-dir /var/lib/olivares

数据目录持有存储、审计签名密钥和 TLS 材料。备份它并使用限制性权限保护它。

领取一次性设置令牌

全新安装没有默认凭证。首次启动时，在没有用户存在的情况下，引擎铸造一个单次使用的设置令牌并仅打印到 stdout——绝不打印到日志：

=== FIRST-BOOT SETUP ===
No users exist yet. Create the first administrator:
  POST /v1/setup  {"token":"olst_…","email":"you@example.com","password":"..."}
This token is shown ONCE and is single-use.
========================

只有令牌的哈希被存储，因此错过的令牌无法恢复，重启也不会重新打印它。在没有用户的全新安装上，从数据目录中删除存储的令牌并重启会铸造一个新的。这种恢复只在没有用户存在时有效，因此它永远不能接管已配置的安装。

创建第一个管理员后，设置端点永久关闭。

健康探针

HTTP 监听器暴露两个具有故意不同语义的探针。将它们连接到匹配的 Kubernetes 探针——混淆这两者会导致重启循环或过时路由。

/livez 是存活性。它不运行任何依赖检查：如果进程能回答，它就是存活的。依赖故障永远不应触发存活性重启。

curl -ks https://127.0.0.1:8443/livez
# {"status":"ok"}

/readyz 是就绪性，它是负载均衡器应该引流的可用性信号。它在两种情况下返回 503，在响应体中加以区分供你的日志使用：

  • 存储不可达 ——{"status":"unavailable","store":"down"}。存储 ping 使用短超时运行，因此卡住的后端会引流实例而非挂起。
  • 不是活跃写入者 ——{"status":"standby","store":"up","leader":false}。在主备集群中，备用节点在这里报告 503，这样 Service 停止向其路由，而不重启它（那是 /livez 的工作——热备必须保持运行以便接管）。当主节点死亡时，备用节点获取领导权，这会翻转为 200，因此流量自动跟随新的主节点。

当引擎就绪时返回 200：

{"status":"ok","store":"up","leader":true,"setup_required":false}

setup_required 为了可观测性而报告，但不会使就绪性失败——刚启动的引擎准备好被设置。在单节点存储上，写入者始终活跃，因此 /readyz 只跟踪存储的可达性。

选择存储

存储通过 --engine 选择。根据拓扑选择，而非偏好。

SQLite（默认）

嵌入式纯 Go SQLite 存储不需要外部依赖，是单节点、实验室、小型资产或气隙安装的正确选择。所有状态都在数据目录中。

Postgres（多租户）

对于多主机或多租户部署，使用 Postgres。不要以超级用户或具有 BYPASSRLS 的角色连接。 租户隔离通过 FORCE ROW LEVEL SECURITY 执行，Postgres 会静默绕过此类角色的所有行级安全——这将只留下应用层谓词在租户之间。引擎拒绝在特权角色上启动，除非你显式传递 --allow-privileged-db-role（仅限单租户或开发环境）。

改为配置一个专用的最小权限角色——NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB。它拥有自己的数据库，因此可以应用模式迁移；FORCE ROW LEVEL SECURITY 即使对表所有者也应用租户策略，因此一个拥有但不绕过的角色保持完全隔离。

olivares serve --engine postgres \
  --dsn "postgres://olivares_app:$DB_PASSWORD@db:5432/olivares?sslmode=verify-full" \
  --data-dir /var/lib/olivares

使用 sslmode=verify-full 和强 SCRAM 密码。真正的跨租户系统读取（组织列表、多租户检查点覆盖）需要一个单独的角色：配置一个 NOSUPERUSER BYPASSRLS 的角色——最小权限但能跨租户读取——并将 --admin-dsn 指向它。对于单租户部署省略它，那些读取就简单地受 RLS 限制。

在你称之为完成之前

两件事决定你的证据是否能在事件中幸存：

  • 将审计签名密钥备份到其他机器上。 它签署仅追加的审计账本；如果丢失，账本将无法再重新验证。引擎在首次启动时发出警告——没有强制托管。
  • 保留账本公钥的离线副本。 离线副本使审计验证在主机被入侵后仍然可靠。

然后安排数据目录的定期备份。

什么运行在哪里

只有控制平面由你放置——如果你选择，可以气隙隔离。收集器（数据平面）始终在你的基础设施上运行。一个值得明确说明的注意事项：Olivares 治理和审计 Claude 使用，但 Claude 推理本身不是自托管的——它访问 Anthropic 的 API（直接或通过 Bedrock、Vertex 或 Foundry）。只有真正自托管的模型才能离线运行。参见诚实与局限页面了解完整边界。

下一步

搜索文档