用 Docker Compose 上手

仓库在 deploy/compose/ 下随附一个 Compose 栈：一个加固的单节点部署（嵌入式 SQLite、零外部依赖）， 外加两个 overlay——一个 Postgres 多租户 override 和一个灾难恢复备份 profile。本教程带你从 up -d 到一个已配置且带备份的 control plane。

容器包装的是与其他每种安装相同的单一二进制文件；仅打包方式不同。下面的命令是该栈自己有文档记录的入口点 （deploy/compose/*.yml），它们驱动的首次运行流程，与单节点教程中 针对二进制端到端验证过的流程相同。

Olivares 0.4

下一个版本是 0.4，其 GitHub 发行尚未发布。以下命令描述计划中的产物。发布前请从源码构建，发布后也应在使用前验证每个产物。观测到的发布状态记录在 docs/releases/0.4-install-surfaces.json。

1. 启动单节点栈（SQLite）

1. 启动它：

   如果 AppArmor 管控用户命名空间的创建，请先在 Docker 守护进程所在主机上按 deploy/compose/README.md 中的“Session confinement on AppArmor hosts”完成配置，再启动服务。

   docker compose -f deploy/compose/docker-compose.yml up --wait --wait-timeout 120

   你按设计会得到：

   属性	值
   端口	8443（HTTPS：REST + web UI）、8444（gRPC）——发布在所有主机接口上，因为这是一台服务器。在 .env 中设置 OLIVARES_BIND=127.0.0.1 可将其限制在本机
   数据	命名卷 olivares-data → /var/lib/olivares（SQLite 存储、审计签名密钥、TLS 材料）
   加固	以 65532:65532 运行，root 只读，丢弃所有 capability，no-new-privileges，tmpfs /tmp
   健康检查	直接执行内置的 olivares readyz 命令——无需 shell、curl 或 wget。只有本地 /readyz 返回 HTTP 200 才算健康

2. 询问引擎它在哪里，并从日志中读取一次性安装 token：

   # where the console answers, and whether setup is still pending. It runs the binary
   # directly and needs no shell.
   docker compose -f deploy/compose/docker-compose.yml exec olivares olivares first-boot
   
   # the one-time setup token, printed once at first boot
   docker compose -f deploy/compose/docker-compose.yml logs olivares \
     | sed -n '/FIRST-BOOT SETUP/,/========================/p'

3. 创建第一个管理员、登录，并创建你的组织——与 单节点教程中 完全一样（API 相同；TLS 证书在首次启动时自签名，因此引导阶段用 curl -k）：

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

当前契约与托管环境资格验证

Compose 就绪契约。 本地、封闭的 HTTP/TLS fixture 验证探针的三种结果： 200 → rc 0，收到非 200 响应 → rc 1，输入、TLS 或传输失败 → rc 2。 在该提交的手动调度工作流成功之前，Docker 资格仍未测量；仓库中存在工作流， 并不能证明其 Docker 运行已经发生。

错过了 token？

重启不会重新打印它（只存储了它的 hash）。在尚无管理员存在期间，你可以在不重启任何东西的情况下铸造一个替代 token——正在运行的引擎会立即接受它，而先前的 token 随即失效：

docker compose -f deploy/compose/docker-compose.yml exec olivares \
  olivares first-boot --new-token

四条命令，以及为什么每条都需要 `-f`

这套 stack 自己命名了 Compose 项目，因此引擎容器叫 olivares（而不是 compose-olivares-1）， override 的服务叫 olivares-postgres-1 和 olivares-backup-1。Compose 仍然在当前工作目录 中寻找 compose 文件，而这个文件位于 deploy/compose/——所以在仓库根目录直接执行 docker compose ps 会回答 “no configuration file provided”。每次都传 -f，或者执行一次 export COMPOSE_FILE=deploy/compose/docker-compose.yml。

docker compose -f deploy/compose/docker-compose.yml exec olivares olivares first-boot
docker compose -f deploy/compose/docker-compose.yml logs olivares
docker compose -f deploy/compose/docker-compose.yml ps
docker compose -f deploy/compose/docker-compose.yml down

olivares quickstart 是本地二进制的路径，而不是这里的路径：这里服务器已经在运行 （容器的命令是 serve），quickstart 会在容器内再启动第二个引擎。

2. 接入数据源

数据源在一个由 OLIVARES_SOURCES_CONFIG 命名的运算符文件中声明 （接入数据源）。对于容器，用一个小的 override 挂载该文件并设置变量：

# deploy/compose/docker-compose.sources.yml (yours — not shipped)
services:
  olivares:
    environment:
      OLIVARES_SOURCES_CONFIG: /etc/olivares/sources.json
    volumes:
      - ./sources.json:/etc/olivares/sources.json:ro

docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.sources.yml up -d
docker compose -f deploy/compose/docker-compose.yml logs olivares | grep "ingest: wired source"

记住 sources.json 内部的路径是容器路径——例如一个 pgAudit 日志尾部，需要把 Postgres 日志目录也 以只读方式挂载进容器。

3. 加密的 DR 备份（backup profile）

该栈随附一个一次性（one-shot）备份服务，它产出一个加密的、ledger 连续性安全的 bundle （olivares dr backup）：

将口令保存在仓库和镜像之外的私密文件中，并在这台主机之外的安全位置保留一份副本： 没有口令，任何备份包都无法恢复。让备份容器以只读方式访问该文件 （镜像以 UID 65532 运行）：

sudo install -d -o 65532 -g 65532 -m 0700 /srv/olivares-dr
sudo install -o 65532 -g 65532 -m 0400 /path/to/private-passphrase /srv/olivares-dr/dr-pass

BACKUP_TS="$(date -u +%Y%m%dT%H%M%SZ)" \
docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.backup.yml \
               -f - --profile backup run --rm backup <<'YAML'
services:
  backup:
    volumes:
      - /srv/olivares-dr/dr-pass:/run/secrets/dr-pass:ro
YAML

把该命令包进宿主机 cron 以获得定时 RPO，并将 olivares-backups 卷镜像到异地——同主机备份不是灾难恢复， 而且口令必须与 bundle 分开传输（3-2-1）。完整流程，包括恢复演练（olivares dr verify），见 备份与恢复。

4. 可选：Postgres 多租户 override

对于多租户拓扑，叠加 Postgres override。它会启动一个 Postgres 16，配置最小权限的 olivares_app 角色 （无 superuser、无 BYPASSRLS——引擎拒绝针对一个特权角色启动，因为行级安全是租户兜底），并让引擎指向它：

覆盖文件还会创建 olivares_admin，这是一个独立的 NOSUPERUSER BYPASSRLS 角色，对引擎表只有只读访问权限。引擎通过 --admin-dsn 使用它进行跨租户读取， 包括首次设置。

首先设置三个不同的密码。此 Compose 演示只允许使用 A-Z a-z 0-9 . _ ~ -， 然后启动栈：

cp deploy/compose/.env.example deploy/compose/.env
# set three distinct passwords in deploy/compose/.env:
# POSTGRES_SUPERUSER_PASSWORD, OLIVARES_DB_PASSWORD, OLIVARES_ADMIN_PASSWORD

docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.postgres.yml up -d

compose 的 Postgres 是一个演示拓扑

该 override 在 compose 网络内以 sslmode=disable 连接——用于评估没问题，不适合生产。 生产级 Postgres 部署使用带 sslmode=verify-full 的 TLS 和一个 DSN secret——那就是 Kubernetes/Helm 路径。

健康

curl -ks https://localhost:8443/readyz
# {"leader":true,"setup_required":false,"status":"ok","store":"up"}
curl -ks https://localhost:8443/metrics | grep olivares_store_up

下一步

• 接入真实信号： connector 指南。
• 调度并演练备份： 备份与恢复。
• 监控它： Prometheus 指标、SLO 与告警。
• 要走向多节点？ 用 Helm 的 Kubernetes， 包括 HA 与 collectors DaemonSet。