# https://github.com/yantrikos/yantrikdb-server 项目说明书
生成时间：2026-07-17 21:46:46 UTC
## 目录
- [仓库总览与系统架构](#page-1)
- [HTTP 网关、API 表面与写入路径](#page-2)
- [集群、复制、Raft 与 Oplog 协议](#page-3)
- [部署、运维与 Python / MCP 生态](#page-4)
## 仓库总览与系统架构
### 相关页面
相关主题：[HTTP 网关、API 表面与写入路径](#page-2), [集群、复制、Raft 与 Oplog 协议](#page-3), [部署、运维与 Python / MCP 生态](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [Cargo.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/Cargo.toml)
- [README.md](https://github.com/yantrikos/yantrikdb-server/blob/main/README.md)
- [SERVER_README.md](https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md)
- [DESIGN.md](https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md)
- [crates/yantrikdb-server/src/main.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/main.rs)
- [crates/yantrikdb-server/src/server.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/server.rs)
# 仓库总览与系统架构
## 1. 项目定位
`yantrikdb-server` 是一个面向记忆（memory）写入与读取的 HTTP 网关服务，承担「共享协议表面」（shared protocol surface）的角色：在 `yantrikdb-core` 引擎之上提供版本化的 API，并以 master-token + tenant-namespace 的方式对调用方进行路由与隔离。仓库在生态中的位置决定了它的边界——它**不**负责实现底层引擎逻辑，只负责 wire 协议、租户隔离与版本对齐。
资料来源：[README.md:1-40]() [SERVER_README.md:1-30]() [DESIGN.md:1-25]()
## 2. 工作区与构建布局
工程采用 Cargo workspace 结构，crate 边界显式划分，使 server 与 engine 的升级节奏可以独立：
- 顶层 `Cargo.toml` 声明 workspace，并 pin 引擎依赖版本（v0.10.0 起与 server 版本解耦演进）。
- `crates/yantrikdb-server/src/main.rs` 为二进制入口：解析配置、构建依赖、启动监听。
- `crates/yantrikdb-server/src/server.rs` 承载 HTTP 路由与请求处理管线。
通过 workspace + 版本对齐（chore: realign server version to 0.10.0），server 与 engine 的版本号可以分离——server 是「协议门面」版本，engine 是「能力」版本，二者通过语义化绑定来避免错配。
资料来源：[Cargo.toml:1-30]() [crates/yantrikdb-server/src/main.rs:1-40]() [crates/yantrikdb-server/src/server.rs:1-40]()
## 3. 运行时架构
`main.rs` 启动顺序遵循「先引擎、后路由、最后监听」的三段式：
1. 初始化配置（master token、监听地址、租户映射）。
2. 注入 `yantrikdb-core` 引擎实例（具体版本由 `Cargo.toml` pin 决定）。
3. 构建 HTTP 路由并启动 `server.rs` 中的请求处理循环。
`server.rs` 暴露的路由遵循 `/v1/...` 前缀，并按写入路径与读取路径分组。下表给出核心端点与其在社区讨论中的当前状态：
| 路径 | 类型 | 关键约定 / 已知问题 |
|---|---|---|
| `/v1/remember` | POST | 写入单条记忆；`idempotency_key=` 在 HTTP 模式下当前被消费方拒绝（issue #58，待 #4 协议落地） |
| `/v1/remember` (batch) | POST | 批量写入；每条 item 可携带 per-item `idempotency_key` |
| `/v1/memory` | GET | 当前值读取；master-token 路由在 v0.8.22 修复 |
| `/v1/memories` | GET | 结构化查询原语（`kind` / `drive_id` / `cursor` / `order`），v0.8.23 引入 |
| `/v1/admin/...` | POST | RFC 027 hygiene worker 管理面 |
资料来源：[crates/yantrikdb-server/src/server.rs:40-120]() [SERVER_README.md:20-60]() [DESIGN.md:30-70]()
## 4. 协议表面与生态契约
服务器是 `yantrikdb-mcp`、`yantrikdb-hermes-plugin` 等消费者的**协议中枢**，因此其在「沉默丢弃字段」与「显式拒绝字段」之间必须取后者。当前几个被广泛关注的契约点：
- **idempotency_key 透传（issue #58）**：消费方在 HTTP 模式下拒绝透传 `remember(idempotency_key=)`，遵循生态协议 #6「拒绝优于静默转发」。设计归属为协议层协议 #4。
- **oplog wire format v2（issue #53）**：`OPLOG_FORMAT_VERSION` 在 `entry_to_wire` 中被写入，但**尚无 reader-side 校验门**，也没有迁移注册表——这是有意延后的能力交换后续工作。
- **Python 3.14 支持（issue #43）**：`pip3 install` 因 PyO3 0.23.5 上限为 3.13 而失败，v0.8.20 通过移除 pre-split scaffolding 并将 engine bump 到 v0.7.20 来关闭该 issue。
下列 mermaid 图描述了 server 在一次写入请求中的最小数据流：
```mermaid
flowchart LR
Client[Consumer
yantrikdb-mcp / hermes-plugin] -->|HTTP /v1/remember| Router[server.rs 路由]
Router -->|master-token + tenant ns| Auth[路由与隔离]
Auth -->|调用 core API| Engine[yantrikdb-core engine
v0.10.x]
Engine -->|WriteAdmission| Oplog[(oplog v2
embedding-on-wire)]
Oplog -->|返回条目| Router
Router -->|JSON 响应| Client
```
资料来源：[README.md:30-70]() [SERVER_README.md:50-90]() [DESIGN.md:60-110]() [crates/yantrikdb-server/src/server.rs:80-160]() [Cargo.toml:10-40]()
## 5. 版本对齐与演进路径
- **server 版本号** 与 **engine 版本号** 各自独立演进，但通过 PR 显式「realign」（如 v0.10.0）保持步调一致。
- **OPLOG wire format v2** 承载 embedding 字节（engine v0.10 Item 3），是当前最新协议层特性；其 reader-side 验证是 open follow-up（issue #53）。
- **写路径变更**（v0.8.21）修复了 `remember` 与 `remember_batch` 中的 tenant-namespace 写入错误，是写入正确性的关键节点。
- **读取与运维**（v0.8.23 – v0.8.27）：依次引入 `/v1/memories` 结构化查询、autonomous hygiene worker（RFC 027）、session lifecycle（boot digest + capture）以及 current-value read。
资料来源：[Cargo.toml:1-30]() [DESIGN.md:80-130]() [SERVER_README.md:70-110]() [crates/yantrikdb-server/src/main.rs:30-70]() [crates/yantrikdb-server/src/server.rs:120-180]()
---
## HTTP 网关、API 表面与写入路径
### 相关页面
相关主题：[仓库总览与系统架构](#page-1), [集群、复制、Raft 与 Oplog 协议](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-server/src/http_gateway.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/http_gateway.rs)
- [crates/yantrikdb-server/src/handler.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/handler.rs)
- [crates/yantrikdb-server/src/api/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/mod.rs)
- [crates/yantrikdb-server/src/api/access.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/access.rs)
- [crates/yantrikdb-server/src/api/errors.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/errors.rs)
- [crates/yantrikdb-server/src/auth/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/auth/mod.rs)
- [crates/yantrikdb-server/src/main.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/main.rs)
# HTTP 网关、API 表面与写入路径
`yantrikdb-server` 的 HTTP 网关是整个系统对外暴露的唯一入口,负责把来自 MCP 客户端、`yantrikdb-hermes-plugin` 以及其他生态消费者的请求转换为对底层 `yantrikdb-core` 引擎的调用。网关层不仅承担路由职责,还承担租户命名空间隔离、令牌鉴权、结构化错误响应以及与 oplog v2 写入路径对接的职责。
## 网关入口与路由装配
HTTP 网关通过 `http_gateway.rs` 进行装配,使用 axum 框架构建 `Router`,把 `/v1/remember`、`/v1/remember_batch`、`/v1/memory`、`/v1/memories` 等 v1 端点挂载到统一前缀之下。`main.rs` 在启动时构造共享的 `AppState`,该结构持有引擎句柄、认证模块以及运维所需的 admin surface,然后通过 `with_state` 注入到路由中。`api/mod.rs` 定义了 v1 命名空间下的子模块划分,把访问控制、错误、handler 聚合在同一个模块树内,便于跨版本迭代时保持 API 表面稳定。资料来源:[crates/yantrikdb-server/src/http_gateway.rs:1-120]()、[crates/yantrikdb-server/src/main.rs:40-90]()、[crates/yantrikdb-server/src/api/mod.rs:1-60]()。
| 端点 | 用途 | 涉及关键修复 |
|---|---|---|
| `/v1/remember` | 单条记忆写入 | 租户命名空间修复 (v0.8.21) |
| `/v1/remember_batch` | 批量写入 | 写入侧 tenant-ns 修复 (v0.8.21) |
| `/v1/memory` | 当前值读取 | master-token 路由修复 (v0.8.22) |
| `/v1/memories` | 结构化查询 | kind/drive_id/cursor/order 原语 (v0.8.23) |
## 鉴权与租户命名空间
鉴权由 `auth/mod.rs` 提供,通过 master token 与租户 token 两层机制识别调用方身份。`api/access.rs` 把鉴权结果映射为引擎可识别的租户命名空间标识,确保写入与读取都落入正确的命名空间。社区中曾出现 `/v1/memory` 与 `/v1/memories` 在 master-token 模式下路由错误的回归(v0.8.22),以及写入路径缺少 tenant-namespace 注入导致数据错放的事故(v0.8.21),这两个问题都在 `api/access.rs` 与 `handler.rs` 中得到了对应的修复。资料来源:[crates/yantrikdb-server/src/auth/mod.rs:1-110]()、[crates/yantrikdb-server/src/api/access.rs:1-95]()。
## 写入路径与 oplog v2 集成
写入路径是网关最关键的责任链路。`handler.rs` 中的 `remember` 与 `remember_batch` handler 接收 JSON 请求体,完成字段校验后,调用 `WriteAdmission` 守卫(engine v0.10.0 引入),再把数据交给引擎的 `remember`/`remember_batch` 接口。oplog 写入采用 v2 格式,即在条目中携带 embedding 字节,使得对等节点同步时无需重新计算向量。社区中关于 `/v1/remember` 的 `idempotency_key` 设计(issue #58)目前处于协议层讨论阶段,消费者在 HTTP 模式下主动拒绝该字段以避免网关静默丢弃,这与生态协议约定 #6 一致。资料来源:[crates/yantrikdb-server/src/handler.rs:60-180]()、[crates/yantrikdb-server/src/http_gateway.rs:90-160]()。
```mermaid
sequenceDiagram
participant C as 客户端
participant GW as HTTP 网关
participant A as 鉴权/Access
participant E as yantrikdb-core
participant O as oplog v2
C->>GW: POST /v1/remember {content, meta}
GW->>A: 解析 token,注入 tenant-ns
A-->>GW: 通过/拒绝
GW->>E: WriteAdmission 检查 + remember()
E->>O: entry_to_wire (含 embedding 字节)
O-->>C: 200 OK {id, version}
```
## 错误响应与运维面
`api/errors.rs` 把引擎层、鉴权层、限流层的错误统一映射为 RFC 7807 风格的 JSON 响应,保证客户端可以基于 `type` 与 `code` 字段做幂等重试或降级。运维面(admin surface)在 v0.8.24 之后通过 `/v1/admin/*` 子树暴露,用于驱动 RFC 027 中的自主 hygiene worker。错误处理与鉴权、写入路径三者共同构成网关的稳定性边界。资料来源:[crates/yantrikdb-server/src/api/errors.rs:1-140]()、[crates/yantrikdb-server/src/api/mod.rs:30-80]()。
---
## 集群、复制、Raft 与 Oplog 协议
### 相关页面
相关主题：[HTTP 网关、API 表面与写入路径](#page-2), [部署、运维与 Python / MCP 生态](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-server/src/cluster/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/mod.rs)
- [crates/yantrikdb-server/src/cluster/server.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/server.rs)
- [crates/yantrikdb-server/src/cluster/replication.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/replication.rs)
- [crates/yantrikdb-server/src/cluster/sync_loop.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/sync_loop.rs)
- [crates/yantrikos/yantrikdb-server/src/cluster/peers.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/peers.rs)
- [crates/yantrikdb-server/src/cluster/election.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/cluster/election.rs)
# 集群、复制、Raft 与 Oplog 协议
## 集群模块总览
集群模式由 `cluster/` 目录下的若干子模块组成。`cluster/mod.rs` 是入口，对外暴露 `ClusterServer` 类型与配置装配逻辑；`cluster/server.rs` 负责在节点上绑定 gRPC/HTTP 双协议监听，并把内部 Raft 事件映射成对外的 RPC 接口。`cluster/peers.rs` 维护节点对等表（peer table），包括静态配置的种子节点和动态发现的临时节点。
`cluster/election.rs` 实现了一个基于超时的领导者选举循环。每个 follower 节点在随机的选举超时窗口内等待心跳，若超时则提升自身为 candidate 并向 peers 发送 `RequestVote`。资料来源：[crates/yantrikdb-server/src/cluster/election.rs:1-80]()。该模块并不试图复刻完整 Raft 论文的所有安全细节，而是为单机写入路径提供「单领导者」语义，避免多副本并发写入造成的 embedding 与 payload 不一致。
## 复制与同步循环
复制路径由 `cluster/replication.rs` 与 `cluster/sync_loop.rs` 共同承担。写入请求在 leader 上通过 `WriteAdmission` 校验后，会生成一条 oplog 条目并广播到所有 follower；follower 端由 `sync_loop.rs` 中的 `SyncLoop` 协程持续拉取缺失的 oplog 区间并按序 apply。资料来源：[crates/yantrikdb-server/src/cluster/replication.rs:1-60]()、资料来源：[crates/yantrikdb-server/src/cluster/sync_loop.rs:1-90]()。
```mermaid
flowchart LR
Client -->|remember| Leader
Leader -->|append oplog| Log[(Oplog)]
Leader -->|AppendEntries| F1[Follower 1]
Leader -->|AppendEntries| F2[Follower 2]
F1 -->|ack| Leader
F2 -->|ack| Leader
SyncLoop[SyncLoop] -->|catch-up| Log
```
当 leader 失联时，`election.rs` 中的超时机制会在剩余节点中触发新一轮选举；新 leader 上任后会通过 `sync_loop.rs` 的尾部回放把缺漏条目补齐。资料来源：[crates/yantrikdb-server/src/cluster/sync_loop.rs:90-150]()。这一恢复路径在 v0.8.19 中曾出现回归，是当前版本对集群启动顺序做收紧的原因之一。
## Oplog 线缆格式 v2
Oplog 是节点间同步的唯一载体。v0.10.0 引入的「oplog wire format v2」在条目载荷中新增了 `embedding_bytes` 字段，使得 follower 收到条目后无需再向 embedding 服务回查即可直接落盘。写入侧的 `entry_to_wire` 会一并把 `OPLOG_FORMAT_VERSION` 常量写入每条条目的头部。
资料来源：[crates/yantrikdb-server/src/cluster/replication.rs:60-140]() 描述了 v2 条目的序列化布局。`peers.rs` 在建立出站连接时，会把本地支持的格式版本随握手段一并通告给对端。资料来源：[crates/yantrikdb-server/src/cluster/peers.rs:1-70]()。
## 已知缺陷与跟进项
社区已记录一个明确缺口：`OPLOG_FORMAT_VERSION` 在 v2 中是「**已盖戳但未校验**」的。`entry_to_wire` 写出版本号，但目前没有任何 reader 侧代码读取并据此选择解码器，也没有迁移注册表。这意味着当未来再升到 v3 时，老节点无法显式拒绝不识别的版本号，只能以「未定义行为」静默处理。
资料来源：[issue #53](https://github.com/yantrikos/yantrikdb-server/issues/53) 把该缺口列为 `#52` 的 follow-up，并指定 `yantrikdb-core` 为决策方。短期修复方向是在 `sync_loop.rs` 的 apply 入口处增加 reader-side gate，并把版本号比对失败从「日志告警」升级为「拒绝 apply 并向 peers 返回 capability miss」。资料来源：[crates/yantrikdb-server/src/cluster/sync_loop.rs:150-210]()。
另一个待办来自 issue #58：`/v1/remember` 的 `idempotency_key` 尚未在网关层透传到 oplog，因此重试可能在 leader 切换后产生重复条目。资料来源：[issue #58](https://github.com/yantrikos/yantrikdb-server/issues/58)。该问题与本模块的写入路径直接耦合，需要在 `replication.rs` 的 `WriteAdmission` 阶段引入幂等键的去重窗口。
综上，`cluster/` 子模块共同构成了 yantrikdb-server 的多副本一致性骨架；oplog v2 是其当前线缆契约，后续工作集中在 reader 校验与幂等去重两条线路上。
---
## 部署、运维与 Python / MCP 生态
### 相关页面
相关主题：[仓库总览与系统架构](#page-1), [集群、复制、Raft 与 Oplog 协议](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [docker/Dockerfile.yantrikdb](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/Dockerfile.yantrikdb)
- [docker/Dockerfile.witness](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/Dockerfile.witness)
- [docker/Dockerfile.yql](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/Dockerfile.yql)
- [docker/docker-compose.yml](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/docker-compose.yml)
- [docker/yantrikdb.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/yantrikdb.toml)
- [docker/entrypoint.sh](https://github.com/yantrikos/yantrikdb-server/blob/main/docker/entrypoint.sh)
# 部署、运维与 Python / MCP 生态
## 概述
yantrikdb-server 是 yantrikdb 生态中的网关组件，对外暴露面向 HTTP 的记忆读写 API，内部依赖 Rust 编写的 `yantrikdb-core` 引擎。本页聚焦其**部署形态、运行期运维能力**，以及与 **Python 客户端、MCP 生态**之间的契约与边界，便于运维与集成方准确理解当前版本的可部署性与可互操作性。
资料来源：[docker/Dockerfile.yantrikdb:1-1]()、[docker/docker-compose.yml:1-1]()
## 容器化部署
仓库在 `docker/` 目录下提供三套独立的容器镜像构建文件，分别面向网关主体、witness 副本与 yql 查询层：
- `Dockerfile.yantrikdb`：构建主体网关镜像，是请求入口。
- `Dockerfile.witness`：构建 witness 节点镜像，参与 peer-sync 与对账。
- `Dockerfile.yql`：构建 yql 查询层镜像，提供结构化查询能力。
多组件通过 `docker/docker-compose.yml` 编排启动；运行时配置集中在 `docker/yantrikdb.toml`；启动逻辑封装在 `docker/entrypoint.sh` 中。该结构表明官方推荐的部署形态是**多容器协同**，而不是单进程模式，运维时应同步维护三类镜像的版本对齐。
资料来源：[docker/Dockerfile.witness:1-1]()、[docker/Dockerfile.yql:1-1]()、[docker/yantrikdb.toml:1-1]()、[docker/entrypoint.sh:1-1]()
## 运行时运维特性
近期版本演进围绕"可运维性"主线展开，可按版本归纳如下：
| 版本 | 运维相关变更 |
|------|--------------|
| v0.8.19 | 修复 cluster-mode 启动回归（hotfix，PR #42） |
| v0.8.20 | engine 升 v0.7.20，移除 pre-split scaffolding（关闭 #43） |
| v0.8.21 | `remember` / `remember_batch` 写入侧 tenant-namespace 修复 |
| v0.8.22 | `/v1/memory` 与 `/v1/memories` master-token 路由修复 |
| v0.8.23 | `/v1/memories` 结构化查询原语（kind / drive_id / cursor / order） |
| v0.8.24 | 自治 hygiene worker + admin surface（RFC 027） |
| v0.8.25 | 会话生命周期（boot digest + capture），接入 engine v0.9.0 |
| v0.8.26 | engine pin v0.9.0 → v0.9.4，digest 隔离范围调整 |
| v0.8.28 | 接入 engine v0.10.0（WriteAdmission、embedding-on-wire） |
| v0.10.0 | oplog wire format v2 承载 embedding bytes；server 与 engine 版本号对齐 |
由表可见，运维侧的关键能力集中在三处：**集群模式启动正确性**（v0.8.19）、**租户/令牌路由正确性**（v0.8.21–v0.8.22）、以及**自治清理与会话生命周期**（v0.8.24–v0.8.25）。RFC 027 引入的 hygiene worker 是当前自治运维的核心载体，admin surface 提供运维入口；boot digest 机制则在 v0.8.25 后使会话级一致性校验成为可能。升级到 v0.10.0 时需特别留意 oplog 格式版本已变更——见下一节协议层说明。
资料来源：[docker/yantrikdb.toml:1-1]()、[docker/entrypoint.sh:1-1]()、[docker/docker-compose.yml:1-1]()
## Python 客户端与 MCP 生态
### Python 端安装约束
通过 `pip3 install -U git+https://github.com/yantrikos/yantrikdb-server` 可从源码安装 Python 绑定。该安装路径依赖 PyO3 进行 Rust↔Python 绑定；当宿主 Python 为 **3.14** 时，当前 PyO3（0.23.5）尚不支持，会抛出 "the configured Python interpreter version (3.14) is newer than PyO3's maximum supported version (3.13)" 的编译错误。该问题在 issue #43 中跟踪；v0.8.20 通过移除 pre-split scaffolding 关闭了原始报告，但 Python 3.14 的根本支持仍需等待上游 PyO3 升级，短期可通过 `PYO3_USE_ABI3_FORWARD_COMPAT` 等环境变量规避。
### MCP 生态契约
yantrikdb 的两个上游消费者 `yantrikdb-mcp` 与 `yantrikdb-hermes-plugin` 在 HTTP 模式下**显式拒绝** `remember(idempotency_key=)` 字段。这并非缺陷，而是依据生态协议 #6："宁可拒绝，也不转发一个网关会静默丢弃的字段"。`idempotency_key` 在网关侧的真正接入设计归口于协议 #4，issue #58 是该字段在 `/v1/remember` 及其批处理路径（per-item keys）的共享表面设计首页。运维与集成方在升级到真正支持 idempotency_key 的版本前，应保持上游消费者的"拒绝"行为，避免出现客户端传入而网关丢弃的不一致语义。
### 协议层的运维隐患
oplog wire format v2（PR #52）已在 v0.10.0 中引入，`OPLOG_FORMAT_VERSION` 被写入 wire，但目前**只写不读**：issue #53 明确指出 reader 侧缺少格式版本网关与迁移注册表。这意味着不同版本节点之间的 peer-sync 在格式降级场景下缺少显式协商机制，是当前版本号对齐后仍需关注的运维盲区，建议在跨版本升级前确认所有 peer 的 engine 与 oplog 版本一致。
资料来源：[docker/Dockerfile.yantrikdb:1-1]()、[docker/Dockerfile.witness:1-1]()、[docker/Dockerfile.yql:1-1]()、[docker/yantrikdb.toml:1-1]()、[docker/entrypoint.sh:1-1]()
---
---
## Doramagic 踩坑日志
项目：yantrikos/yantrikdb-server
摘要：发现 25 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue。
## 1. 配置坑 · 来源证据：Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/58 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 依赖 Docker 环境
- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -p 7438:7438 ghcr.io/yantrikos/yantrikdb:latest curl -X POST http://localhost:7438/v1/remember
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -p 7438:7438 ghcr.io/yantrikos/yantrikdb:latest curl -X POST http://localhost:7438/v1/remember`
- 证据：identity.distribution | https://github.com/yantrikos/yantrikdb-server | docker run -p 7438:7438 ghcr.io/yantrikos/yantrikdb:latest curl -X POST http://localhost:7438/v1/remember
## 3. 安装坑 · 失败模式：installation: python3.14 support missing.
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: python3.14 support missing.
- 对用户的影响：Developers may fail before the first successful local run: python3.14 support missing.
- 证据：failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/43 | python3.14 support missing.
## 4. 安装坑 · 来源证据：Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/53 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：python3.14 support missing.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python3.14 support missing.
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/43 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/yantrikos/yantrikdb-server | host_targets=mcp_host, claude_code, claude, cursor
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/yantrikos/yantrikdb-server | README/documentation is current enough for a first validation pass.
## 8. 运行坑 · 运行可能依赖外部服务
- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/yantrikos/yantrikdb-server | matched external service / cloud / webhook / database keyword
## 9. 维护坑 · 失败模式：migration: Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue
- 对用户的影响：Developers may hit a documented source-backed failure mode: Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue
- 证据：failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/58 | Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue
## 10. 维护坑 · 失败模式：migration: Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
- 证据：failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/53 | Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)
## 11. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/yantrikos/yantrikdb-server | no_demo; severity=medium
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/yantrikos/yantrikdb-server | no_demo; severity=medium
## 14. 运行坑 · 失败模式：performance: v0.8.22
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.8.22
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.22
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.22 | v0.8.22
## 15. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server | issue_or_pr_quality=unknown
## 16. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server | release_recency=unknown
## 17. 维护坑 · 失败模式：maintenance: v0.10.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.10.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.10.0 | v0.10.0
## 18. 维护坑 · 失败模式：maintenance: v0.8.19
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.19
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.19
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.19 | v0.8.19
## 19. 维护坑 · 失败模式：maintenance: v0.8.20
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.20
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.20
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.20 | v0.8.20
## 20. 维护坑 · 失败模式：maintenance: v0.8.21
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.21
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.21
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.21 | v0.8.21
## 21. 维护坑 · 失败模式：maintenance: v0.8.23
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.23
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.23
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.23 | v0.8.23
## 22. 维护坑 · 失败模式：maintenance: v0.8.24
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.24
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.24
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.24 | v0.8.24
## 23. 维护坑 · 失败模式：maintenance: v0.8.25
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.25
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.25
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.25 | v0.8.25
## 24. 维护坑 · 失败模式：maintenance: v0.8.26
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.26
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.26
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.26 | v0.8.26
## 25. 维护坑 · 失败模式：maintenance: v0.8.27
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.8.27
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.27
- 证据：failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.27 | v0.8.27