quivr 2.0.0-alpha.7 配置参数详解

目标：系统讲解 quivr 2.0.0-alpha.7 单机部署形态下的全部配置参数——安装器 CLI 参数、.env 部署参数、引擎服务环境变量、PostgreSQL 调优参数、Weaviate 索引参数、嵌入服务与演示界面参数、Autoscaler 参数，以及基础设施档位（small/large）与内存覆盖规则，并给出每个参数的实测验证方法与生产配置模板。已在 Ubuntu 24.04（x86_64）+ Docker Engine 29.8 + Docker Compose v5.5.1 环境按《quivr Docker Compose 部署指南》完成部署的栈上逐项实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测：

• 操作系统：Ubuntu 24.04 LTS（x86_64），内核 6.8 系
• Docker Engine：29.8 系，Docker Compose v5.5.1
• quivr 版本：2.0.0-alpha.7（revision 7b5ffe3eaa031ccbb1f49244b76e8b9bf5d11426，API v0，插件引擎 0.2.0）
• 安装目录：/opt/quivr（官方发布包解压目录，下文统一按此路径书写；与部署篇《quivr Docker Compose 部署指南》同一演示安装）
• 演示安装参数：--embedding e5 --project quivr-2-0-0-alpha-7-stack --profile small（默认档）
• Compose 项目：quivr-2-0-0-alpha-7-stack，9 服务栈（api/worker/migrate/postgres/temporal/seaweed/weaviate/embeddings/demo）
• PostgreSQL：17.11（quivr-postgres 封装镜像，实测 SELECT version() 回显 PostgreSQL 17.11 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit）
• Weaviate：1.39.10（rq-8 量化）

💡 说明：quivr 2.0 的配置入口只有一条链路——安装目录的 .env（模式 0600）→ setup.py init 重渲染 compose.yaml → Compose 变量替换 → 各服务环境变量。引擎本身没有独立配置文件，依赖服务的调优也全部通过带 QUIVR_ 前缀的环境变量在每次启动时声明。理解这条链路是理解本文全部参数的前提。

二、前置条件

• 已按《quivr Docker Compose 部署指南》完成 2.0.0-alpha.7 的单机部署，docker compose ps -a 中 7 个常驻服务为 Up (healthy)、migrate 为 Exited (0)。
• 具备安装目录 /opt/quivr 的读写权限与 Docker 权限（.env 与 compose.yaml 均为 0600，属 root 或安装者所有）。
• 演示安装的密钥值（下文示例沿用）：QUIVR_API_KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26、QUIVR_DB_PASSWORD=e888cb59bc4e9f654972692810bad4c66455cd8d2c6e294c647c058a971ce326（仅演示环境实际值；你自己的安装以你的 .env 为准）。

三、参数查看与修改方式

3.1 配置链路总览

单机栈没有分散的配置文件，全部配置按以下链路流动：

.env（0600，唯一编辑入口）
  │  python3 setup.py init   ← 读取 .env，按 release.json 的镜像/模型 digest 重渲染
  ▼
compose.yaml（0600，安装器产物，勿手改）
  │  docker compose up -d    ← Compose 变量替换 ${KEY:-default}
  ▼
各服务环境变量（postgres/temporal/seaweed/weaviate/embeddings 的 env；
              api/worker/migrate 注入同一组引擎变量，QUIVR_ROLE 区分角色）
  │  启动时声明
  ▼
运行态生效值（PostgreSQL SHOW 可查、Weaviate 环境可见、引擎进程 env 可见）

要点：改 .env 之后必须重跑 python3 setup.py init 才会把新值渲染进 compose.yaml，直接改 .env 而不重渲染，对已在运行的栈不产生任何效果。init 幂等：已有合法 .env 时复用既有 9 个密钥，只按新参数重渲染。

3.2 查看安装参数

安装参数即 .env 全部键。查看时注意确认文件权限仍为 0600：

cd /opt/quivr && stat -c "%a %n" .env compose.yaml

实测输出：

600 .env
600 compose.yaml

cd /opt/quivr && cat .env

实测输出（演示安装真实值）：

COMPOSE_PROJECT_NAME=quivr-2-0-0-alpha-7-stack
QUIVR_EMBEDDING=e5
QUIVR_MODEL_REVISION=614241f622f53c4eeff9890bdc4f31cfecc418b3
QUIVR_INFRASTRUCTURE_PROFILE=small
QUIVR_ORGANIZATION=quivr
QUIVR_OFFLINE=0
QUIVR_DB_PASSWORD=e888cb59bc4e9f654972692810bad4c66455cd8d2c6e294c647c058a971ce326
QUIVR_API_KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26
QUIVR_OPERATOR_KEY=33917015c924cf6018bc6311c3606ca86f672a561a00ce849b7b924239d5f6e4
QUIVR_CURSOR_KEY=beab1f7dd52a78becd2d8e8d05bd50eadb47ff732794ac19f3fda5ce032cef3b
QUIVR_CREDENTIAL_KEY=c5b0a312a9ef82004e5017162e6e4de530cacf6a98f7a3bb707d059e219ff811
S3_ACCESS_KEY=afc4b3acbf1c5808ca77472ef0b3512d6bd29fd26ea97dedae350ec4c72976ef
S3_SECRET_KEY=be511df66dc1990cfbac5fcf996110f3f162c77345ccbb79d1bf0bc24261e23d
EMBED_API_KEY=d024cdda0f926f0952465e3232f5924fdce3570eee593e394dace45bcf6e63d8
DEMO_PASSWORD=92f9b75229e6dd3f22ebd2b19ad975d57c3c8764b53c104c8b75ac6e0640f897

⚠️ 注意：.env 含 9 个生成密钥，不要粘贴到工单、聊天或提交进版本库；发布包 .env.example 顶部注释同样写着「setup.py init generates secrets in .env (0600). Do not commit it.」

3.3 查看运行态生效值

引擎服务（api/worker/migrate）——进入服务查看实际注入的环境变量（env 输出按字典序过滤排序，QUIVR_ROLE 应为该服务角色）：

cd /opt/quivr && docker compose exec api env | grep -E '^(QUIVR|DATABASE_URL|TEMPORAL|WEAVIATE|TEI_URL|EMBED|S3_)' | sort

实测输出（e5 路线；输出含真实密钥，此处逐行照抄）：

DATABASE_URL=postgres://quivr:e888cb59bc4e9f654972692810bad4c66455cd8d2c6e294c647c058a971ce326@postgres:5432/quivr?sslmode=disable
QUIVR_API_KEY=08dee2d53f038fd455294fdad3bf59240c9be17d3723a2ae8f189e91fdc6ad26
QUIVR_CREDENTIAL_KEY=c5b0a312a9ef82004e5017162e6e4de530cacf6a98f7a3bb707d059e219ff811
QUIVR_CURSOR_KEY=beab1f7dd52a78becd2d8e8d05bd50eadb47ff732794ac19f3fda5ce032cef3b
QUIVR_DEMO_ADMIN=1
QUIVR_DEMO_CONNECTORS=1
QUIVR_DEMO_PLUGINS=1
QUIVR_OPERATOR_KEY=33917015c924cf6018bc6311c3606ca86f672a561a00ce849b7b924239d5f6e4
QUIVR_ORGANIZATION=quivr
QUIVR_ROLE=api
QUIVR_SINGLE_MACHINE=1
QUIVR_WORKER_BULK_SLOTS=1
QUIVR_WORKER_LIVE_SLOTS=1
S3_ACCESS_KEY=afc4b3acbf1c5808ca77472ef0b3512d6bd29fd26ea97dedae350ec4c72976ef
S3_ENDPOINT=http://seaweed:8333
S3_SECRET_KEY=be511df66dc1990cfbac5fcf996110f3f162c77345ccbb79d1bf0bc24261e23d
TEI_URL=http://embeddings:80
TEMPORAL_ADDRESS=temporal:7233
WEAVIATE_URL=http://weaviate:8080

💡 说明：这是 e5 嵌入路线的实际注入——TEI_URL=http://embeddings:80，且没有 EMBED_URL/EMBED_API_KEY/QUIVR_DEMO_EMBEDDING/QUIVR_DEMO_CORE_INGEST 四个键（它们是 gemma 路线专属，见 7.4 与 7.5）。把回显与第七章逐项对照，是核对「配置是否真的生效」最直接的手段。

PostgreSQL 调优参数——QUIVR_POSTGRES_* 键由 quivr-postgres 镜像的启动脚本在每次启动时翻译成 PostgreSQL 配置，最终生效值用 psql 的 SHOW 核对：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -At \
  -c "SHOW max_connections;" -c "SHOW work_mem;" -c "SHOW random_page_cost;" \
  -c "SHOW effective_io_concurrency;" -c "SHOW checkpoint_timeout;" \
  -c "SHOW wal_compression;" -c "SHOW jit;" -c "SHOW synchronous_commit;" \
  -c "SHOW commit_delay;" -c "SHOW commit_siblings;" -c "SHOW shared_buffers;" \
  -c "SHOW maintenance_work_mem;"

实测输出（每行一条，顺序与命令一致）：

256
4MB
1.1
200
15min
lz4
on
on
100
5
8012MB
512MB

对照解读：前 10 项与 QUIVR_POSTGRES_* 显式声明一一对应（256/4MB/1.1/200/15min/lz4/on/on/100/5）；shared_buffers 与 maintenance_work_mem 未在 small 档声明，由启动脚本按内存预算推导（本机约 32 GiB，shared_buffers 推导为内存的 25% 即 8012 MiB，maintenance_work_mem 推导落在 16–512 MiB 区间上限 512 MB），推导规则详见 8.3。

Weaviate 参数：

cd /opt/quivr && docker compose exec weaviate env | grep -E '^(AUTH|AUTOSCHEMA|DEFAULT|PERSIST|ASYNC|RAFT|GOMEMLIMIT)' | sort

实测输出：

ASYNC_INDEXING=false
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true
AUTOSCHEMA_ENABLED=false
DEFAULT_QUANTIZATION=rq-8
DEFAULT_VECTORIZER_MODULE=none
GOMEMLIMIT=1700MiB
PERSISTENCE_DATA_PATH=/var/lib/weaviate
PERSISTENCE_MEMTABLES_MAX_SIZE_MB=200
RAFT_BOOTSTRAP_TIMEOUT=600

PostgreSQL 版本与统计扩展（参数核对时的基线信息）：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -c "SELECT extname, extversion FROM pg_extension ORDER BY extname;"

实测输出：

      extname       | extversion
--------------------+------------
 pg_stat_statements | 1.11
 plpgsql            | 1.0
(2 rows)

3.4 修改参数的固定流程

任何可修改参数（.env 中除密钥外的部署参数）的变更都要走同一条三步流程：

cd /opt/quivr
# 1) 编辑 .env（保持 0600；不要引入引号、注释以外的花哨写法，值必须是字面量）
chmod 600 .env && vi .env
# 2) 重跑 init 重渲染 compose.yaml（幂等，不会重新生成密钥）
python3 setup.py init
# 3) 应用变更（compose 检测到渲染结果变化会按需重建受影响服务）
docker compose up -d

实测验证（把 QUIVR_API_PORT 从 8080 改为 18080 的场景为例，改完 init 后渲染产物里映射段立即变化）：

cd /opt/quivr && grep -A1 '"ports"' compose.yaml | head -8

实测输出（输出节选，ports 已按新值渲染）：

  "ports": [
    "127.0.0.1:18080:8080"
  ],

⚠️ 注意：init 会整体重写 compose.yaml，任何对渲染产物的手工编辑都会在下次 init 时丢失；持久化定制应固化到自己的部署脚本或安装参数里。密钥类 9 个键（QUIVR_DB_PASSWORD、QUIVR_API_KEY、QUIVR_OPERATOR_KEY、QUIVR_CURSOR_KEY、QUIVR_CREDENTIAL_KEY、S3_ACCESS_KEY、S3_SECRET_KEY、EMBED_API_KEY、DEMO_PASSWORD）与 QUIVR_EMBEDDING/COMPOSE_PROJECT_NAME/QUIVR_MODEL_REVISION 对已有数据的安装是锁定项（见 6.3、6.4），不要改。

四、参数总览

quivr 2.0.0-alpha.7 的全部参数按入口与作用面分为五类：

关键解读：.env 是人工唯一的编辑入口；引擎变量与依赖服务调优变量都由安装器按档位自动渲染，一般不需要手工干预；Autoscaler 参数只在 Railway/平台编排形态生效，单机 Compose 栈不含 autoscaler 服务。

五、安装器 setup.py 参数详解

setup.py 是官方发布包内的唯一安装器，三个子命令共用同一组选项。先看帮助回显：

cd /opt/quivr && python3 setup.py --help

实测输出：

usage: setup.py [-h] [--directory DIRECTORY] [--release RELEASE]
                [--project PROJECT] [--embedding {gemma,e5}]
                [--profile {small,large}] [--secret-file KEY=PATH]
                [--mirror MIRROR] [--source SOURCE]
                {init,prepare,upgrade}

Initialize one protected environment and render a standalone image-only stack.

positional arguments:
  {init,prepare,upgrade}

options:
  -h, --help            show this help message and exit
  --directory DIRECTORY
  --release RELEASE
  --project PROJECT
  --embedding {gemma,e5}
  --profile {small,large}
  --secret-file KEY=PATH
  --mirror MIRROR
  --source SOURCE

💡 说明：argparse 对子命令 init/prepare/upgrade 输出的是同一份全局帮助（python3 setup.py init --help 回显与上面完全相同），子命令差异见 5.1–5.3。

5.1 子命令 init：初始化并渲染安装

init 在安装目录生成/复用 .env（0600）并按 release 事实渲染 compose.yaml 与 release.json，输出固定一行：

cd /opt/quivr && python3 setup.py init --embedding e5 --project quivr-2-0-0-alpha-7-stack

实测输出（exit 0）：

Ready: one Compose file and protected .env; model cache preparation is a separate install step.

init 的内部校验规则（实测触发路径）：

• .env 必须是权限 0600 的普通文件，拒绝符号链接；键名必须匹配 [A-Z][A-Z0-9_]* 且不重复，值必须是字面量（禁引号、$、反引号等字符）；
• 9 个密钥缺失时自动生成（secrets.token_hex(32)，64 位十六进制）；注入密钥的 --secret-file 文件同样要求 0600 普通文件、内容 64 位十六进制；
• QUIVR_API_KEY 与 QUIVR_OPERATOR_KEY 相同直接拒绝；
• --embedding 只接受 gemma|e5，--profile 只接受 small|large；
• 可选内存覆盖 QUIVR_POSTGRES_MEMORY_MB/QUIVR_WEAVIATE_MEMORY_MB 必须是不小于 128 的十进制整数 MiB，Weaviate 的 GOMEMLIMIT 按其 85% 自动推导；
• 已初始化（x-quivr-initialized: true）的目录里换 --embedding 或 --project 被拒绝——模型与项目名对已有安装锁定。

5.2 子命令 prepare：准备模型缓存

prepare 把 QUIVR_EMBEDDING 锁定版本的嵌入模型下载到 <project>-model-cache 命名卷（卷带 quivr.model=<模型> 标签防串模型），并做校验和验证；模型已就绪时重跑只做校验：

cd /opt/quivr && python3 setup.py prepare

实测输出（缓存已就绪，exit 0）：

Ready: one Compose file and protected .env; model cache preparation is a separate install step.

离线/内网场景的两个选项：--mirror <URL> 经镜像源下载模型；--source <DIR> 直接使用本地模型源目录（以只读方式挂进下载容器）。

5.3 子命令 upgrade：按新发布包滚动升级

upgrade 与 init 参数相同，区别在于执行完初始化后自动编排停启顺序：先停 api worker demo，移除一次性的 migrate 容器，再 docker compose up -d 让新版本栈滚动起来（等价于手工执行 stop → rm -f migrate → up -d 三步）。2.0.0-alpha 各版本间官方明确不支持原地升级（alpha.7 相对 alpha.6 及更早为 BREAKING），upgrade 只用于同版本流内的滚动重启或后续兼容版本。

5.4 共用选项一览

关键差异与选择建议：--project 与 --embedding 是「一次定型」参数——进入有数据状态后不可改（改了只能全新安装并重发内容）；--profile 与两个内存覆盖键是「可演进」参数，扩容时改后重跑 init 即可。升级密钥注入用 --secret-file，例如保留对外 API Key 重建安装：

umask 077 && openssl rand -hex 32 > /protected/api-key
python3 setup.py init --secret-file QUIVR_API_KEY=/protected/api-key

六、.env 部署参数详解

6.1 .env.example 全文与逐项含义

发布包自带的 .env.example 是参数全集的可读底稿，实测原文：

# setup.py init generates secrets in .env (0600). Do not commit it.
COMPOSE_PROJECT_NAME=quivr
QUIVR_EMBEDDING=gemma
# QUIVR_MODEL_REVISION is recorded by setup.py from the release; preserve it.
QUIVR_ORGANIZATION=quivr
QUIVR_INFRASTRUCTURE_PROFILE=small
# Isolate dependencies/worker/embeddings; API/demo keep a port-publishing bridge.
QUIVR_OFFLINE=0
# Gemma and e5 are initial installation choices. Existing cache identity is fixed.
QUIVR_EMBEDDING_THREADS=4
QUIVR_EMBEDDING_CPUS=4
QUIVR_EMBEDDING_MEMORY=4g
QUIVR_WORKER_LIVE_SLOTS=1
QUIVR_WORKER_BULK_SLOTS=1
QUIVR_API_PORT=8080
QUIVR_DEMO_PORT=3000
# Optional overrides in MiB; setup.py init re-renders limits and index GOMEMLIMIT.
# QUIVR_POSTGRES_MEMORY_MB=4096
# QUIVR_WEAVIATE_MEMORY_MB=12288
# Generated/read from 0600 files: QUIVR_DB_PASSWORD, QUIVR_API_KEY,
# QUIVR_OPERATOR_KEY, QUIVR_CURSOR_KEY, QUIVR_CREDENTIAL_KEY, S3_ACCESS_KEY,
# S3_SECRET_KEY, EMBED_API_KEY, DEMO_PASSWORD (64 hexadecimal characters each).

6.2 部署参数逐项详解

6.3 生成密钥一览（9 个，0600 保护）

6.4 锁定项与可演进项小结

• 锁定（对已有数据的安装，init 直接拒绝变更）：COMPOSE_PROJECT_NAME、QUIVR_EMBEDDING、QUIVR_MODEL_REVISION；
• 可演进（改后重跑 init + up -d 即可）：QUIVR_INFRASTRUCTURE_PROFILE、QUIVR_ORGANIZATION、QUIVR_OFFLINE、QUIVR_EMBEDDING_THREADS/CPUS/MEMORY、QUIVR_WORKER_LIVE_SLOTS/BULK_SLOTS、QUIVR_API_PORT、QUIVR_DEMO_PORT、QUIVR_POSTGRES_MEMORY_MB、QUIVR_WEAVIATE_MEMORY_MB；
• 密钥：可整体带入（init 复用既有 .env，或 --secret-file 注入），但不建议轮换 QUIVR_CREDENTIAL_KEY/QUIVR_CURSOR_KEY（涉及已加密数据与游标签名的可读性）。

七、引擎服务环境变量详解

api、worker、migrate 三个服务运行同一个 quivr-core 镜像，靠 QUIVR_ROLE 区分角色，注入同一组引擎变量。以下按功能分组逐项说明（默认值以 small 档渲染为准）。

7.1 角色与模式

7.2 数据与依赖服务地址

7.3 密钥类

7.4 嵌入路线变量（gemma/e5 差异）

7.5 并发与演示开关

验证方式见 3.3（docker compose exec api env 实测回显与上表逐项对应）。

八、PostgreSQL 调优参数详解

quivr-postgres 是「postgres:17.11-alpine + quivr 调优入口」的封装镜像：启动脚本在每次启动时把 QUIVR_POSTGRES_* 环境变量翻译成 PostgreSQL 配置（命令行参数优先级高于既有 ALTER SYSTEM 值），持久卷与官方镜像初始化保持不变。

8.1 small 档声明键（11 项）

💡 技术拓展：synchronous_commit 不止 on 一档，常见取值对比——

取值	提交返回时机	风险
on	本地 WAL 落盘	无（默认持久级）
remote_write	本地落盘 + 备库收到 WAL（未落盘）	备库崩溃可能丢已确认提交
remote_apply	本地落盘 + 备库已重放	延迟最高、可见性最严格
off	返回即可，WAL 异步落盘	崩溃可丢最近几百毫秒提交

quivr 的摄取回执与游标推进都建立在「确认即持久」的语义上，因此官方把该键锁死为 on，组合提交窗口（commit_delay/commit_siblings）在保持持久性的同时合并小事务的 WAL 刷盘。

8.2 large 档追加键（7 项）

large 档在上述 11 项基础上追加（infrastructure.json 的 x-quivr.profiles.large.postgres.environment）：

8.3 未显式声明时的推导默认值

启动脚本对内存/WAL 类键有完整推导规则（官方 deploy/compose/README.md 口径），这是核对实测值时最需要的一张表：

关键解读：没有内存限额（cgroup 不封顶）时脚本会用宿主内存做推导——宿主上还跑着其他服务时，务必通过 Compose 限额（档位决定）或 QUIVR_POSTGRES_MEMORY_MB 显式给预算，避免 shared_buffers 把内存推导得过大。四种内存调优覆盖键（SHARED_BUFFERS/EFFECTIVE_CACHE_SIZE/WORK_MEM/MAINTENANCE_WORK_MEM）要求带 kB/MB/GB/TB 单位的正整数；改预算后需重启 PostgreSQL 生效。

8.4 验证与巡检查询

除 3.3 的 SHOW 系列外，日常巡检可直接查 pg_settings 与统计扩展。查看消耗最高的语句（track=all 已就位）：

cd /opt/quivr && docker compose exec postgres psql -U quivr -d quivr -c "SELECT query, calls, ROUND(total_exec_time::numeric,1) AS total_ms FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 3;"

实测输出（输出节选，队列指标维护类语句居首）：

                                              query                                               | calls  | total_ms
--------------------------------------------------------------------------------------------------+--------|----------
 WITH wanted AS (                                                                                +|  92001 | 189805.2
          SELECT source,stripe FROM unnest($1::text[]) sources(source)                           +|        |
          CROSS JOIN generate_series($2,$3) stripes(stripe)                                       +|        |
          ORDER BY source,stripe                                                                  +|        |
  )                                                                                               +|        |
  INSERT INTO queue_metric_totals(source,stripe)                                                  +|        |
          SELECT source,stripe FROM wanted                                                        +|        |
          ON CONFLICT(source,stripe) DO NOTHING                                                    |        |
 INSERT INTO queue_backlog_totals(stripe,queue)                                                  +|  92077 | 130798.1
  SELECT s,q FROM generate_series($1,$2) s CROSS JOIN (VALUES($3),($4)) queues(q)                +|        |
  ORDER BY s,q ON CONFLICT DO NOTHING                                                             |        |
 SELECT parallel,epoch,published_through,sampled_through,sample_xid::text,                       +| 968400 |  32029.4
  (SELECT CASE WHEN is_called THEN last_value ELSE last_value-$1 END FROM change_event_positions)+|        |
  FROM change_journal_publication WHERE singleton                                                 |        |
(3 rows)

九、Weaviate 索引参数详解

Weaviate 由 quivr 官方声明全部参数（引擎自己负责 schema 与向量化，索引只做存储与检索）：

运行态核对方式见 3.3（env 回显）；索引侧元信息可用栈内 HTTP 元端点确认：

cd /opt/quivr && docker compose exec api python -c "import urllib.request,json;print(json.load(urllib.request.urlopen('http://weaviate:8080/v1/meta'))['license'])"

实测输出：

{'documentationHref': 'https://docs.weaviate.io/deploy/enterprise', 'edition': 'community'}

⚠️ 注意：官方 infrastructure.md 明确 large 档的 ASYNC_INDEXING=true 与 memtable 调大未经基准验证，属「对象重型导入的操作起点」；内存规划按「磁盘上的索引数据 + 压缩向量缓存与图 + 运行/导入/重建余量」估算，64 GB 是起点分配而非容量保证。

十、嵌入服务与演示界面参数

10.1 嵌入服务（embeddings）

gemma 与 e5 两条路线的镜像不同（quivr-cpu-embeddings / quivr-tei），但上述环境变量结构一致；e5 路线的入口与健康检查随镜像切换（http://localhost/health）。

10.2 演示界面（demo）

十一、Autoscaler 参数（平台/Railway 形态）

Autoscaler 是 quivr 官方平台编排形态里的批量 worker 伸缩器（128 MiB / 0.25 vCPU），单机 Compose 栈不含该服务；参数在 infrastructure.json 的 x-quivr.autoscaler.environment 声明，Railway large 档默认启用（backend=railway，可覆盖为 kubernetes）：

十二、基础设施档位与内存覆盖

12.1 small / large 全对照

关键解读：large 面向百万文档级机器（官方起步建议 32 GiB RAM / 16 vCPU / 1 TiB SSD），启用路径是 .env 改 QUIVR_INFRASTRUCTURE_PROFILE=large 后重跑 python3 setup.py init 再 docker compose up -d；若沿用 small 机器只做内存升级，用 12.2 的两个覆盖键即可。

12.2 内存覆盖键与校验规则

百万文档档官方示例（small 基础上只覆盖内存）：.env 加 QUIVR_POSTGRES_MEMORY_MB=4096 与 QUIVR_WEAVIATE_MEMORY_MB=12288 → 重跑 init（索引 GOMEMLIMIT 自动推导为 10444MiB 量级）→ docker compose up -d。

十三、生产配置模板

13.1 small 档标准模板（16 GiB RAM / 4 vCPU / SSD，≤10 万文档）

COMPOSE_PROJECT_NAME=quivr
QUIVR_EMBEDDING=gemma
QUIVR_ORGANIZATION=quivr
QUIVR_INFRASTRUCTURE_PROFILE=small
QUIVR_OFFLINE=0
QUIVR_EMBEDDING_THREADS=4
QUIVR_EMBEDDING_CPUS=4
QUIVR_EMBEDDING_MEMORY=4g
QUIVR_WORKER_LIVE_SLOTS=1
QUIVR_WORKER_BULK_SLOTS=1
QUIVR_API_PORT=8080
QUIVR_DEMO_PORT=3000
QUIVR_DB_PASSWORD=<init 生成，64 hex>
QUIVR_API_KEY=<init 生成，64 hex>
QUIVR_OPERATOR_KEY=<init 生成，64 hex>
QUIVR_CURSOR_KEY=<init 生成，64 hex>
QUIVR_CREDENTIAL_KEY=<init 生成，64 hex>
S3_ACCESS_KEY=<init 生成，64 hex>
S3_SECRET_KEY=<init 生成，64 hex>
EMBED_API_KEY=<init 生成，64 hex>
DEMO_PASSWORD=<init 生成，64 hex>

适用说明：默认档把 PostgreSQL 预算 1 GiB、索引 2 GiB（GOMEMLIMIT 1700MiB）、嵌入 4 GiB/4 核；密钥行全部交给 setup.py init 自动生成，人工只填前 12 行。批量导入期间可将 QUIVR_WORKER_BULK_SLOTS 提到 2–4，导入完成后改回。

13.2 large 档 / 百万文档模板（32 GiB 起 RAM / NVMe SSD）

COMPOSE_PROJECT_NAME=quivr
QUIVR_EMBEDDING=gemma
QUIVR_ORGANIZATION=quivr
QUIVR_INFRASTRUCTURE_PROFILE=large
QUIVR_OFFLINE=0
QUIVR_EMBEDDING_THREADS=8
QUIVR_EMBEDDING_CPUS=8
QUIVR_EMBEDDING_MEMORY=8g
QUIVR_WORKER_LIVE_SLOTS=2
QUIVR_WORKER_BULK_SLOTS=4
QUIVR_API_PORT=8080
QUIVR_DEMO_PORT=3000
QUIVR_POSTGRES_MEMORY_MB=4096
QUIVR_WEAVIATE_MEMORY_MB=12288
QUIVR_DB_PASSWORD=<init 生成，64 hex>
（其余 8 个密钥行同 13.1）

适用说明：32 GB 级机器建议 PostgreSQL 预算 4 GiB、索引 12 GiB（GOMEMLIMIT 自动推导约 10444MiB）；QUIVR_WORKER_BULK_SLOTS=4 配合导入窗口，注意连接预算——官方口径单 API + 单 live + 八 bulk、每池 16 连接即 160 连接，须小于 max_connections(500) 扣预留后的可用数。ASYNC_INDEXING 由 large 档自动置 true，批量写入时向量可见性存在滞后，检索验证应在回执 resolved 之后进行。

十四、常见问题

14.1 改了 .env 但不生效

链路断在渲染步：.env 只是参数源，compose.yaml 不重渲染就不会把新值带进服务。执行 python3 setup.py init（幂等）→ docker compose up -d，再用 3.3 的运行态查看命令核对（docker compose exec api env / psql SHOW / weaviate env）。

14.2 init 报「installation model revision cannot change」或「installation model/project cannot change」

已有数据的安装锁定了 QUIVR_MODEL_REVISION、QUIVR_EMBEDDING 与 COMPOSE_PROJECT_NAME，三者任一变更都会被拒绝。换模型/换项目名只能全新安装（新目录 + 新项目名 → init → prepare → up -d → 经 add-content API 重发原文）。

14.3 init 报「service memory budget must be at least 128 MiB」

QUIVR_POSTGRES_MEMORY_MB/QUIVR_WEAVIATE_MEMORY_MB 填了小于 128 或非纯数字的值。改为不小于 128 的十进制整数 MiB 后重跑 init。

14.4 init 报「API and operator keys must differ」

--secret-file 注入时把 QUIVR_API_KEY 与 QUIVR_OPERATOR_KEY 注成了同一个值。两把密钥职责不同（应用 / 运维），分别生成注入即可。

14.5 想确认 PostgreSQL 参数真的生效了

用 3.3 的 psql -At -c "SHOW ..." 系列逐项核对；QUIVR_POSTGRES_* 未显式声明的键（shared_buffers/maintenance_work_mem/WAL 尺寸）按 8.3 的推导表核对实测值。注意启动脚本在每次启动时重新声明配置，ALTER SYSTEM 改的值重启后会被覆盖——持久调整走 QUIVR_POSTGRES_* 键而不是 ALTER SYSTEM。

14.6 Weaviate 端口有匿名访问，安全吗

栈内 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true 是官方示例形态的前提：weaviate 服务只在 stack 内部网络，未发布任何宿主端口，外部不可达。不要把它加进 ports 或改绑公网。

14.7 端口与网络隔离怎么配

QUIVR_API_PORT/QUIVR_DEMO_PORT 改对外端口；QUIVR_OFFLINE=1 渲染时把 stack 网络置为 internal（依赖与 worker 无外网出口），api/demo 保留 access 发布网络。远程访问建议 SSH 隧道或自备 TLS 代理（官方 run-quivr behind TLS 指引），不要把映射改成 0.0.0.0 裸奔。

十五、参考链接

1. 官方单机部署文档（配置链路依据）：https://docs.quivr.thevibecompany.co/run-quivr/single-machine （查询日期 2026-10-22）
2. 部署与配置总览：https://docs.quivr.thevibecompany.co/run-quivr/deploy （查询日期 2026-10-22）
3. quivr-postgres 调优口径（源码内官方说明 deploy/compose/README.md、deploy/infrastructure.md，v2.0.0-alpha.7 源码包）
4. PostgreSQL 17 运行时配置：https://www.postgresql.org/docs/17/runtime-config-resource.html
5. Weaviate 环境变量文档：https://weaviate.io/developers/weaviate/config-refs/env-vars
6. 站内延伸阅读：产品认知与选型见《quivr 介绍与选型指南》；部署全流程见《quivr Docker Compose 部署指南》；命令与工具速查见《quivr 2.0.0-alpha.7 常用 CLI 命令与工具详解》