存储配置：PostgreSQL、Redis 与 Qdrant

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：deploy/.env.example、crates/cheng-storage/src、crates/cheng-storage/src/janitor、crates/cheng-storage/src/artifact_store.rs、crates/cheng-vector/src

ChengOS 有四个存储，它们的必需程度并不相同：

PostgreSQL 是真相来源，其余是对它的加速或扩展。

PostgreSQL

DATABASE_URL=postgres://user:password@127.0.0.1:5432/master_router
DATABASE_MAX_CONNECTIONS=10
DATABASE_MIN_CONNECTIONS=1
DATABASE_CONNECTION_TIMEOUT=30

主机名取决于你的部署模式，这也是最常见的配置错误：

智能体记忆节点除了 URL 之外还需要拆开的连接信息，因为它们自己开连接：

DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=master_router
DB_USER=tianai_db
DB_PASSWORD=…

DB_INSTALL_MODE 决定原生安装如何提供数据库：

RUN_MIGRATIONS=true 时迁移在启动时执行，也可以用 Diesel 手动执行——见开发环境搭建。

Redis

REDIS_URL=redis://:password@127.0.0.1:6379
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
# REDIS_DB=0
REDIS_MAX_CONNECTIONS=10
REDIS_MIN_CONNECTIONS=1
REDIS_CONNECTION_TIMEOUT=30

ENABLE_REDIS=false        # 原生／hybrid 安装

Redis 承载调度器的温层队列和分布式执行锁，以及智能体记忆节点和缓存。没有它，定时和智能体记忆无法工作；系统其余部分照常。

与 PostgreSQL 一样，智能体记忆节点读取的是与 REDIS_URL 分开的 REDIS_HOST / REDIS_PORT / REDIS_PASSWORD。

Valkey 可以直接替代 Redis。

Qdrant

QDRANT_URL=http://127.0.0.1:6334      # gRPC 端口，不是 6333
ENABLE_QDRANT=false

注意端口：6334 是 Qdrant 的 gRPC 端点，ChengOS 连的就是它。指向 6333（HTTP 端口）会失败。

部署模式有本地 Docker、云端和自托管；云端与需要认证的自托管要提供 API 密钥，use_https 和连接超时（默认 30 秒）也可配置。

除了普通向量检索，ChengOS 还用到 Qdrant 的两项能力：

• 具名向量——同一个点里放着维度不同的 parent_vec（384）、child_vec（1024）和 context_vec（256）。见 RAG 管线设计。
• 内建的 BM25 全文检索，正是它让混合检索模式无需第二套搜索引擎即可实现。

集合命名为 kb_<workspace_id>_<kb_id>，因此工作区之间不会撞车——见知识库。

产物存储

大文件不放数据库。产物存储在磁盘上保存不可变对象：

<artifact_root>/
  objects/
    <artifact-id>/
      <safe-filename>
      metadata.json
  tmp/
    <写入中的文件>

写入协议值得了解，因为它解释了你能观察到的行为：

1. 字节先写进临时文件。
2. 对文件做哈希。
3. 原子重命名进 objects/<id>/。
4. 此后数据库行才变为可读。

注册失败会移除待定对象。因此不存在「数据行指向不存在的字节」的窗口；上传中途崩溃留下的是 tmp/ 里的垃圾，而不是一个损坏的对象。

解析是工作区范围的，且解析出的路径会被校验落在规范化的产物根目录之内，从而挫败路径穿越与符号链接逃逸。

根目录默认是 CHENG_WORKSPACE_ROOT/artifacts，回退到 ./workspaces/artifacts。

工作区级的产物设置——单文件上限、单次请求总量、LLM 预览预算、保留策略——会覆盖引擎默认值。见知识库与工作区上下文。

数据生命周期：清道夫

后台清道夫实行三阶段策略：软删除（可恢复）、冷备份（后续增强），然后硬删除。

默认值：

此外还有孤儿产物清理、用于避免大事务的批大小、清理间隔，以及一个dry-run 模式：只报告会删什么而不真删。

清道夫使用独立的连接池，其连接上限低于主连接池，因此清理绝不会饿死业务流量；它的阻塞工作跑在 spawn_blocking 上，不会占用 Tokio 线程。

在任何可能觉得默认保留期过于激进的部署上，先跑一次 dry-run。

密钥

CREDENTIAL_MASTER_KEY_1=<64 位十六进制>   # openssl rand -hex 32
JWT_SECRET=<64 位十六进制>
POSTGRES_PASSWORD=…                       # openssl rand -hex 16
REDIS_PASSWORD=…

CREDENTIAL_MASTER_KEY_1 是凭证保险库的 AES-256-GCM 密钥，数字后缀是为轮换准备的。丢了它，所有已存凭证都不可恢复——请与数据库分开备份，因为只有数据库备份是恢复不出一个可用系统的。

容量调优

先用默认值。引擎自身的并发是 CPU 核数 × 3，因为多数节点是 I/O 密集的，所以你先撞上的通常是数据库连接数而不是核心数。

下一步

• 环境变量参考——所有变量。
• 部署模式——你该用哪套主机名。
• RAG 管线设计——真正用到 Qdrant 的地方。