# https://github.com/lanterndata/lantern 项目说明书

生成时间：2026-07-08 15:41:05 UTC

## 目录

- [Lantern 概述与系统架构](#page-1)
- [核心 HNSW 索引与向量操作](#page-2)
- [CLI 守护进程、嵌入生成与外部索引](#page-3)
- [构建、部署、版本升级与常见故障](#page-4)

<a id='page-1'></a>

## Lantern 概述与系统架构

### 相关页面

相关主题：[核心 HNSW 索引与向量操作](#page-2), [CLI 守护进程、嵌入生成与外部索引](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lanterndata/lantern/blob/main/README.md)
- [CHANGELOG.md](https://github.com/lanterndata/lantern/blob/main/CHANGELOG.md)
- [Cargo.toml](https://github.com/lanterndata/lantern/blob/main/Cargo.toml)
- [lantern_hnsw/CMakeLists.txt](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/CMakeLists.txt)
- [lantern_hnsw/src/hnsw/delete.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/delete.c)
- [lantern_extras/lantern_extras.control](https://github.com/lanterndata/lantern/blob/main/lantern_extras/lantern_extras.control)
- [lantern/src/main.rs](https://github.com/lanterndata/lantern/blob/main/lantern/src/main.rs)
- [lantern_cli/Cargo.toml](https://github.com/lanterndata/lantern/blob/main/lantern_cli/Cargo.toml)
</details>

# Lantern 概述与系统架构

Lantern 是一个面向 PostgreSQL 的开源向量数据库扩展，提供高性能的近似最近邻（ANN）搜索能力，并围绕 HNSW（Hierarchical Navigable Small World）图索引构建了完整的生态体系。仓库整合了核心 C++ 实现、PostgreSQL 扩展层、Rust 编写的守护进程与外部索引服务，以及独立的 CLI 工具，形成"数据库内索引 + 外部加速 + 异步任务调度"的多层架构。

## 项目定位与核心能力

Lantern 的核心定位是：在 PostgreSQL 内部直接提供生产可用的向量检索能力。其核心实现位于 `lantern_hnsw` 子模块，采用 CMake 构建（参见 [lantern_hnsw/CMakeLists.txt](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/CMakeLists.txt)），提供了 HNSW 索引的构建、查询与维护 API。维护过程中需要响应 VACUUM 操作，例如在删除回收时调用 `vacuum_delay_point()`（[lantern_hnsw/src/hnsw/delete.c:42](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/delete.c)）。

PostgreSQL 用户层封装由 `lantern_extras` 子目录承担，它作为 `CREATE EXTENSION lantern_extras` 的安装入口，定义扩展元信息（[lantern_extras/lantern_extras.control](https://github.com/lanterndata/lantern/blob/main/lantern_extras/lantern_extras.control)）。与社区版 pgvector 不同，Lantern 强化了四项能力：内建 PQ（Product Quantization）压缩、外部建索引（External Indexing）、自动参数调优（Autotune）以及异步嵌入生成。

## 模块组成与职责划分

仓库按照职责拆分为四个互相关联的工作区，每个工作区拥有独立的构建系统：

| 目录 | 语言 | 主要职责 |
|------|------|----------|
| `lantern_hnsw` | C++ | HNSW 图算法核心，含构建、查询、删除、距离计算 |
| `lantern_extras` | C/SQL | PostgreSQL 扩展层，SQL 函数、操作符类、索引 AM hook |
| `lantern` | Rust | 异步守护进程，执行 embedding/autotune/external-indexing 后台任务 |
| `lantern_cli` | Rust | 独立外部索引服务与运维工具，可与 PostgreSQL 通过 TCP+SSL 通信 |

Rust 工作区根 [`Cargo.toml`](https://github.com/lanterndata/lantern/blob/main/Cargo.toml) 通过 `members` 字段声明子 crate；其中 [`lantern/src/main.rs`](https://github.com/lanterndata/lantern/blob/main/lantern/src/main.rs) 是守护进程的入口，负责消费任务队列并路由到对应的 feature gate。在 v0.5.0 中，embedding、autotune、external-indexing 三大作业被显式 feature-gate 化（参见 CHANGELOG 中 PR #349 的描述）。CLI 子项目独立维护依赖与发布节奏（[lantern_cli/Cargo.toml](https://github.com/lanterndata/lantern/blob/main/lantern_cli/Cargo.toml)）。

## 运行时架构与数据流

下图描述一次典型的"查询向量→HNSW 检索→结果返回"的端到端流程，并体现了外部索引与守护进程的协作：

```mermaid
flowchart LR
    Client[SQL 客户端] -->|SQL 查询| PG[(PostgreSQL)]
    PG --> Extras[lantern_extras<br/>SQL/索引 AM]
    Extras --> HNSW[lantern_hnsw<br/>HNSW C++ 核心]
    HNSW -->|候选结果| Extras
    Extras -->|结果集| PG
    PG --> Client
    Daemon[lantern 守护进程] -. 异步作业 .-> PG
    CLI[lantern_cli 外部服务] -. TCP/SSL .-> Extras
    CLI -. 索引文件 chunk .-> HNSW
```

在外部索引模式下，PostgreSQL 不直接构建大向量集，而是由 `lantern_cli` 通过 TCP socket（支持 SSL，见 v0.3.2 发布说明）将索引文件以 chunk 形式回传，最终由数据库写入并标注元素位宽（PR #334）。守护进程侧的 embedding、autotune、external-indexing 任务通过 feature gate 控制启停，避免在不需要此能力的部署上引入额外开销。

## 版本演进与生态边界

Lantern 当前最新版本为 v0.5.0（[CHANGELOG.md](https://github.com/lanterndata/lantern/blob/main/CHANGELOG.md)），主要里程碑包括：

- **v0.3.0**：移除 blockmap，`hnswbuild` 单一 WAL 写入（PR #318、#319），写入路径更紧凑。
- **v0.3.1**：流式 HNSW 索引 SELECT（PR #322），大结果集不必全量物化。
- **v0.3.2 / v0.3.3 / v0.3.4**：连续重构外部索引链路，逐步演进出 socket 协议、SSL、外部索引路由与头信息中的元素位宽字段（PR #324 / #327 / #333 / #334）。
- **v0.4.0**：`lantern_extras` 合并进入主仓库，并开始为 `lantern_cli` 产出 macOS 二进制（PR #339 / #340）。
- **v0.5.0**：升级依赖、引入 PostgreSQL 17 支持（PR #348），并将守护进程关键作业 feature-gate 化。

需要注意的是，社区也暴露了一些边界条件：当前实现对向量维度设有上限（参考 issue #374 的报错信息："vector dimension 3072 is too large. LanternDB currently supports up to 2000dim vectors"），且在 PostgreSQL 18 beta 中由于 `vacuum_delay_point` 函数签名变化，构建会失败（issue #375），此外 macOS 与 Homebrew PostgreSQL 的组合构建也曾出现 `os error 22`（issue #370）。这些限制体现了项目仍在持续演进以匹配上游 PostgreSQL 与新兴嵌入模型。

资料来源：

- [README.md:1-1]()
- [CHANGELOG.md:1-1]()
- [Cargo.toml:1-1]()
- [lantern_hnsw/CMakeLists.txt:1-1]()
- [lantern_hnsw/src/hnsw/delete.c:42-42]()
- [lantern_extras/lantern_extras.control:1-1]()
- [lantern/src/main.rs:1-1]()
- [lantern_cli/Cargo.toml:1-1]()

---

<a id='page-2'></a>

## 核心 HNSW 索引与向量操作

### 相关页面

相关主题：[Lantern 概述与系统架构](#page-1), [CLI 守护进程、嵌入生成与外部索引](#page-3), [构建、部署、版本升级与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [lantern_hnsw/src/hnsw.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw.c)
- [lantern_hnsw/src/hnsw/build.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/build.c)
- [lantern_hnsw/src/hnsw/scan.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/scan.c)
- [lantern_hnsw/src/hnsw/insert.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/insert.c)
- [lantern_hnsw/src/hnsw/delete.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/delete.c)
- [lantern_hnsw/src/hnsw/external_index.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/external_index.c)
</details>

# 核心 HNSW 索引与向量操作

## 概述

Lantern 的核心是一个 PostgreSQL 扩展，封装了 HNSW（Hierarchical Navigable Small World）图结构以实现高效的近似最近邻（ANN）检索。`lantern_hnsw/src/hnsw/` 目录下的源码模块负责索引的元数据注册、构建、扫描、插入、删除以及外部索引路由等关键路径，向上层 SQL 操作符（如 `<->` 距离运算）提供底层支撑。

整个子系统围绕 `HnswHandle` 句柄运行：每个 `USING lantern_hnsw` 索引对应一份序列化的图元数据，存储在 PostgreSQL 的 `relfilenode` 中。运行时通过共享内存或文件 IO 访问节点链表与层级结构。`hnsw.c` 负责索引 AM（access method）的注册与生命周期管理，`build.c` 完成图的批量构建，`insert.c`/`delete.c` 负责增量维护，`scan.c` 实现近邻搜索，`external_index.c` 则提供独立进程构建索引的可选路径。

## 索引构建

构建流程由 `lanshbuild` 与 `HnswBuild` 等入口触发：

- **元数据初始化**：`build.c` 根据 `IndexInfo` 与表元组数据读取所有向量，写入 `HnswMetadata` 与节点数组 `nodes`，并通过 `pq_params` 启用可选的乘积量化压缩。资料来源：[lantern_hnsw/src/hnsw/build.c:1-120]()
- **图构建**：采用 HNSW 标准算法，逐层维护 `M` 个邻居，节点按层级（level）插入到上层"高速公路"中。资料来源：[lantern_hnsw/src/hnsw/build.c:120-260]()
- **单次 WAL 写入**：v0.3.0 引入的 `hnswbuild single wal pass`（PR #319）将构建产物在一次 WAL 刷新中落盘，减少 checkpoint 压力并加速崩溃恢复。资料来源：[lantern_hnsw/src/hnsw/build.c:260-340]()
- **消除 blockmap**：v0.3.0 同步移除旧版 blockmap 间接寻址层（PR #318），直接以偏移定位节点，简化寻址路径。

构建接口同时兼容外部索引模式：当外部索引守护进程可用时，`build.c` 会把数据通过 TCP socket 分块发送，由外部进程完成图构建再回传索引文件。资料来源：[lantern_hnsw/src/hnsw/external_index.c:1-180]()

## 插入与查询

- **增量插入**：`insert.c` 中 `HnswInsertTuple` 在已有图结构上定位入口节点，按概率决定目标层级，向下逐层贪心搜索并维护候选堆，最终在 `ef_construction` 范围内回填邻居指针。资料来源：[lantern_hnsw/src/hnsw/insert.c:1-200]()
- **流式查询**：`scan.c` 中的 `HnswScan` 利用流式候选堆（streaming heap）返回 top-k，避免一次性分配大缓冲。v0.3.1 通过 PR #322 引入 `streaming hnsw index selects`，显著降低高维查询的内存占用。资料来源：[lantern_hnsw/src/hnsw/scan.c:1-160]()
- **距离计算**：支持 L2、内积与余弦距离，由 SQL 层 `<->`、`<#>`、`<=>` 算子映射到底层 `HnswDistance` 函数。资料来源：[lantern_hnsw/src/hnsw/scan.c:160-260]()

## 删除与回收

`delete.c` 实现基于 tombstone 的软删除：标记节点为已删除但保留其邻居引用，扫描时通过可见性过滤跳过已删除节点。VACUUM 阶段调用 `vacuum_delay_point()` 让出 CPU 资源。资料来源：[lantern_hnsw/src/hnsw/delete.c:1-80]()

> **注意**：在 PostgreSQL 18 beta 1 中，`vacuum_delay_point()` 的签名变更为 `vacuum_delay_point(bool is_analyze)`，当前源码未传递该参数，导致编译失败（社区 Issue #375）。升级到 PG18 需要在 `delete.c:42` 处显式传入参数。资料来源：[lantern_hnsw/src/hnsw/delete.c:40-45]()

## 外部索引模式

`external_index.c` 提供一种"独立进程构建"路径：

- **TCP/SSL 通信**：v0.3.2（PR #324、#327）引入基于 socket 的外部索引传输，并支持 SSL。v0.3.4（PR #333、#334）通过 `StoreExternalIndexNodes` 重构，将索引文件分块接收并由路由器调度。资料来源：[lantern_hnsw/src/hnsw/external_index.c:180-360]()
- **头部协议**：v0.3.4 起头部消息包含向量元素位数（`element_bits`）与压缩参数，便于异构客户端解码。资料来源：[lantern_hnsw/src/hnsw/external_index.c:120-180]()
- **已知问题**：在 macOS 15.2 + Homebrew PostgreSQL 16 上构建外部索引时报 `os error 22 (EINVAL)`（社区 Issue #370），通常与 socket 路径权限或字节序不匹配有关。

## 已知限制与社区反馈

| 限制项 | 当前状态 | 来源 |
| --- | --- | --- |
| 最大向量维度 | 2000（社区 Issue #374 请求提升至 3072 以支持 OpenAI text-embedding-3-large） | `hnsw.c` 中维度上限常量 |
| PostgreSQL 版本 | 已支持至 PG17（v0.5.0）；PG18 beta1 编译失败 | `delete.c:42` |
| 平台 | macOS 构建链存在权限/库路径问题（Issue #352、#370） | `build.c`/`external_index.c` |
| 文档 | lantern.dev 历史 404 已修复（Issue #371） | — |

总体而言，Lantern 的核心 HNSW 模块通过分层职责清晰的文件组织，将图构建、增量维护、查询与外部索引解耦，配合持续的单 WAL 写入与流式扫描优化，已形成一个面向生产环境的向量检索内核。

---

<a id='page-3'></a>

## CLI 守护进程、嵌入生成与外部索引

### 相关页面

相关主题：[核心 HNSW 索引与向量操作](#page-2), [构建、部署、版本升级与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [lantern_cli/src/main.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/main.rs)
- [lantern_cli/src/cli.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/cli.rs)
- [lantern_cli/src/daemon/mod.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/mod.rs)
- [lantern_cli/src/daemon/embedding_jobs.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/embedding_jobs.rs)
- [lantern_cli/src/daemon/client_embedding_jobs.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/client_embedding_jobs.rs)
- [lantern_cli/src/daemon/autotune_jobs.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/autotune_jobs.rs)
- [lantern_cli/src/daemon/external_index.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/external_index.rs)
- [lantern_cli/src/daemon/daemon_jobs.rs](https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/daemon_jobs.rs)
- [lantern_extras/src/external_index_client.c](https://github.com/lanterndata/lantern/blob/main/lantern_extras/src/external_index_client.c)
- [lantern_hnsw/src/hnsw/external_index.c](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/src/hnsw/external_index.c)
</details>

# CLI 守护进程、嵌入生成与外部索引

## 1. 角色与整体拓扑

`lantern_cli` 是 Lantern 在 PostgreSQL 之上的辅助 Rust 命令行程序。它同时承担两个角色：一是普通 CLI，为运维与开发者提供子命令入口；二是常驻守护进程，定期轮询数据库中由 `lantern_extras` 创建的后台任务表，并把外部能力（嵌入模型推理、自动参数调优、HNSW 外部索引构建）接到 PostgreSQL 内。守护进程的总入口在 `lantern_cli/src/main.rs` 中分发到 `daemon::run`，并依据子模块编排多种作业。`资料来源：[lantern_cli/src/main.rs:1-40]()`、`资料来源：[lantern_cli/src/daemon/mod.rs:1-60]()`。

子命令层（`lantern_cli/src/cli.rs`）负责解析 `daemon`、`create-external-index` 等顶层命令；运行时层则把每个拉取到的 job 通过 trait 调度到对应实现。v0.5.0 在守护进程内部为嵌入、autotune、外部索引三类作业增加了 feature-gate，使最小部署可以仅启用需要的子集。`资料来源：[lantern_cli/src/cli.rs:20-80]()`

```mermaid
flowchart LR
  PG[(PostgreSQL<br/>lantern_extras jobs)] -->|轮询 job 表| Daemon[lantern_cli 守护进程]
  Daemon -->|HTTP 调用| EmbedAPI[OpenAI / 其他嵌入服务]
  Daemon -->|TCP+TLS| ExtIdx[外部 HNSW 索引进程]
  EmbedAPI --> Daemon --> PG
  ExtIdx -->|索引字节流| Daemon --> PG
```

## 2. 守护进程核心与作业调度

`lantern_cli/src/daemon/mod.rs` 定义了守护进程主体：初始化数据库连接池、按可配置周期 `tick` 拉取作业、根据 `job_type` 字段路由到不同的处理模块，并把结果写回 job 表。v0.2.6 修复了 async 任务中的 `job_id` 传递问题，使同一 job 的日志与状态始终对应同一记录。`资料来源：[lantern_cli/src/daemon/mod.rs:60-160]()`

`lantern_cli/src/daemon/daemon_jobs.rs` 提供通用 trait `DaemonJob` 与共享工具（重试、退避、状态写入）。所有具体作业类型都实现该 trait，从而让守护进程主体保持轻量。`资料来源：[lantern_cli/src/daemon/daemon_jobs.rs:1-90]()`

## 3. 嵌入生成任务

服务端侧任务（由 PostgreSQL 中其他 worker 调度，守护进程执行实际 HTTP 调用）位于 `embedding_jobs.rs`：守护进程读取待生成嵌入的行，使用配置中的 provider、模型名、API key 拼装请求，将结果写回向量列。客户端侧任务（用户主动发起、要求守护进程反向通知 PG）位于 `client_embedding_jobs.rs`：常用于桌面或远端客户端把外部文本上传到 PG 后让 PG 触发嵌入流水线。`资料来源：[lantern_cli/src/daemon/embedding_jobs.rs:1-120]()`、`资料来源：[lantern_cli/src/daemon/client_embedding_jobs.rs:1-100]()`。

需要注意的是，向量维数受 PostgreSQL 扩展限制；社区已报告 OpenAI `text-embedding-3-large` 输出的 3072 维超出当前 2000 维上限，必须先用降维或截断方案（参见 issue #374）。`资料来源：[lantern_cli/src/daemon/embedding_jobs.rs:60-95]()`

## 4. 自动调参与外部索引

`autotune_jobs.rs` 通过对一组候选 `(ef_construction, M, ef_search, pq)` 参数跑小规模搜索，自动挑选召回/时延平衡最佳的组合，并回写为索引选项。`资料来源：[lantern_cli/src/daemon/autotune_jobs.rs:1-110]()`。

外部索引是 v0.3.0 之后的关键能力：构建 HNSW 时可选择把计算卸载到独立进程，通过 TCP（可选 TLS）把向量流式推给 `lantern-cli create-external-index` 工作进程，索引构建完毕后再将字节流回写到 PostgreSQL。这一能力的客户端实现在 `lantern_extras/src/external_index_client.c`，服务端路由与连接管理在 `lantern_cli/src/daemon/external_index.rs` 与 `lantern_hnsw/src/hnsw/external_index.c`。`资料来源：[lantern_cli/src/daemon/external_index.rs:1-140]()`、`资料来源：[lantern_extras/src/external_index_client.c:1-160]()`。

v0.3.4 引入外部索引路由器并重构 `StoreExternalIndexNodes`，允许以分块方式从 socket 接收索引文件；v0.3.3 修复了 `fd` 泄漏问题。社区已在 MacOS 15.2 + Homebrew PostgreSQL 16 上反馈 `os error 22`（issue #370），常见原因是非 Unix 套接字或临时目录路径包含符号链接，建议在本地构建时改用 `cmake -DMARCH_NATIVE=ON` 并显式设置临时目录为绝对路径。

## 5. 常见限制与运维提示

- 向量维数硬上限 2000（issue #374）：若使用新版 OpenAI 大模型需先降维。
- PostgreSQL 18 beta 1 构建失败（issue #375）：源码中 `vacuum_delay_point()` 在 PG18 需要 `is_analyze` 参数，等待上游适配。
- MacOS 本地构建失败（issue #352）：建议使用官方 release 的 macOS 二进制，或按 README 在干净的 Xcode CLT 环境下重新生成 cmake 缓存。
- 守护进程作业通过 feature-gate 控制：仅启用所需 job 类型可显著降低空闲时内存占用。

---

<a id='page-4'></a>

## 构建、部署、版本升级与常见故障

### 相关页面

相关主题：[Lantern 概述与系统架构](#page-1), [核心 HNSW 索引与向量操作](#page-2), [CLI 守护进程、嵌入生成与外部索引](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [lantern_hnsw/CMakeLists.txt](https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/CMakeLists.txt)
- [docker/Dockerfile](https://github.com/lanterndata/lantern/blob/main/docker/Dockerfile)
- [docker/Dockerfile.pg](https://github.com/lanterndata/lantern/blob/main/docker/Dockerfile.pg)
- [ci/scripts/build.sh](https://github.com/lanterndata/lantern/blob/main/ci/scripts/build.sh)
- [ci/scripts/build-linux.sh](https://github.com/lanterndata/lantern/blob/main/ci/scripts/build-linux.sh)
- [ci/scripts/build-mac.sh](https://github.com/lanterndata/lantern/blob/main/ci/scripts/build-mac.sh)
</details>

# 构建、部署、版本升级与常见故障

本页面向开发者与运维人员介绍 Lantern 扩展的本地构建、Docker 容器化部署、CI 流程以及与 PostgreSQL 兼容性相关的常见问题与版本升级注意事项。

## 1. 从源码构建扩展

Lantern 的 C 核心位于 `lantern_hnsw/` 目录，使用 CMake 组织编译流程。顶层 `CMakeLists.txt` 定义了与 PostgreSQL 头文件、依赖库（usearch、pgvector 等子模块）的链接方式，并对外暴露若干选项如 `MARCH_NATIVE`，用于启用本地 CPU 指令集优化。资料来源：[lantern_hnsw/CMakeLists.txt:1-60]()

### Linux / macOS 本地构建步骤

推荐流程为先克隆包含子模块的仓库，再通过 CMake 配置与构建：

```bash
git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern
cmake -DMARCH_NATIVE=ON -S lantern_hnsw -B build
make -C build install -j
```

CI 脚本中同样采用上述思路：先使用 `apt-get`（Linux）或 `brew`（macOS）安装 PostgreSQL 客户端头文件，再调用 `cmake` 与 `make` 进行安装。资料来源：[ci/scripts/build-linux.sh:1-40]()、[ci/scripts/build-mac.sh:1-30]()

### PostgreSQL 版本兼容

`build.sh` 会检测 `PG_VERSION` 环境变量并对不同主版本（PG14～PG18）执行不同编译路径，源代码中也针对 `PG_VERSION_MAJOR` 进行条件编译。资料来源：[ci/scripts/build.sh:1-50]()

需要注意：当前发行版（v0.5.0）已正式支持 PG17，但 **PG18 仍处于 beta 阶段**——社区已有 issue 报告在 PG18 beta1 上 `lantern_hnsw/src/hnsw/delete.c` 调用 `vacuum_delay_point()` 时缺少新增的 `is_analyze` 参数而编译失败。临时方案是回退到 PG17 或在源码侧补齐参数。资料来源：[issue #375]()

## 2. Docker 镜像部署

仓库提供两条 Docker 构建路径，分别面向「完整产品镜像」与「纯 PG 基础镜像」。

| 文件 | 用途 | 基础镜像 |
| --- | --- | --- |
| `docker/Dockerfile` | 一体化 Lantern + PostgreSQL 镜像 | `lanterndata/lantern-pg` |
| `docker/Dockerfile.pg` | 仅构建 PG 基础镜像（供上层扩展复用） | `postgres:16` 等 |

`Dockerfile` 先 `COPY` 本地已构建的 `.so` 与 `.control` 文件，再执行 `CREATE EXTENSION lantern;` 完成初始化；`Dockerfile.pg` 则负责在官方 PG 镜像上预装编译工具链与开发头文件。资料来源：[docker/Dockerfile:1-40]()、[docker/Dockerfile.pg:1-30]()

通过这种分层，CI 可以仅在 PG 基础镜像变更时触发重编，从而加速发布流程。

## 3. CI/CD 流程

持续集成由 GitHub Actions 驱动，其核心入口是 `ci/scripts/build.sh`，该脚本：

1. 安装 PostgreSQL 开发包与构建工具；  
2. 拉取 `pgvector` 等子模块并预先安装；  
3. 调用 CMake 生成 Makefile 并执行 `make install`；  
4. 复制产物到 `build/` 下的产物目录供打包。  

资料来源：[ci/scripts/build.sh:10-80]()

随后工作流会针对 `ubuntu-22.04`、`macos-14` 等多种 runner 运行相同的构建步骤，并对 PostgreSQL 14/15/16/17 四个版本执行回归测试。Linux 与 macOS 分别由 `build-linux.sh` 与 `build-mac.sh` 处理包管理差异（apt vs brew）。资料来源：[ci/scripts/build-linux.sh:1-50]()、[ci/scripts/build-mac.sh:1-40]()

## 4. 版本升级路径与常见故障

### 升级建议

- **小版本升级（如 v0.4.x → v0.5.0）**：通常只需 `ALTER EXTENSION lantern UPDATE;`，需确保新版本 `.so` 已通过 `make install` 部署到 PostgreSQL 扩展目录。  
- **跨 PostgreSQL 主版本升级**：必须先在目标版本上重新构建并安装 Lantern，再通过 `pg_upgrade` 迁移数据；建议在测试环境验证后再切换。  
- **PR #348** 明确将 PG17 支持合入主干，因此升级到 v0.5.0 后可正式启用 PG17。

### 已知问题速查

| 现象 | 触发条件 | 解决方案 |
| --- | --- | --- |
| 编译报 `too few arguments to function 'vacuum_delay_point'` | PG18 beta1 | 回退 PG17 或等待官方补丁（issue #375） |
| `vector dimension 3072 is too large` | 向量维度 >2000 | 当前硬上限 2000，issue #374 跟踪中 |
| 外部索引报 `os error 22` | macOS 15.2 + Homebrew PG16 | 参考 issue #370，确认 socket/文件描述符权限 |
| 文档 404 | 临时性站点故障 | 已恢复（issue #371，状态 closed） |

资料来源：[issue #375]()、[issue #374]()、[issue #370]()、[issue #371]()

## 5. 故障排查建议

1. **先确认版本匹配**：`SELECT extversion FROM pg_extension WHERE extname='lantern';` 与 PostgreSQL 主版本对齐。  
2. **检查子模块**：`git submodule status` 必须全部为 `+` 头，否则 `usearch` 缺失会导致链接失败。  
3. **查看构建日志**：CMake 输出中的 `Found PostgreSQL` 行可定位头文件与库路径错误。  
4. **善用 `--features`**：v0.5.0 起 daemon 中的 embedding / autotune / external-indexing 已特性门控，可在编译时裁剪。

资料来源：[ci/scripts/build.sh:30-90]()

> 本页内容仅覆盖 `lantern_hnsw`、`docker/` 与 `ci/scripts/` 三个目录所反映的构建与部署相关逻辑；如需了解扩展功能 SQL 接口，请参阅其它 wiki 页面。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：lanterndata/lantern

摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：os error 22 when indexing。

## 1. 安装坑 · 来源证据：os error 22 when indexing

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：os error 22 when indexing
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lanterndata/lantern/issues/370 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15`
- 证据：identity.distribution | https://github.com/lanterndata/lantern | docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15

## 3. 安装坑 · 来源证据：Build failure with PostgreSQL 18 beta 1

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Build failure with PostgreSQL 18 beta 1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lanterndata/lantern/issues/375 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 来源证据：Build is failing in local in MacOS

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Build is failing in local in MacOS
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lanterndata/lantern/issues/352 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/lanterndata/lantern | README/documentation is current enough for a first validation pass.

## 6. 运行坑 · 来源证据：Documentation on lantern.dev is giving 404

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Documentation on lantern.dev is giving 404
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lanterndata/lantern/issues/371 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 运行坑 · 来源证据：Vector dimension 3072 is too large. LanternDB currently supports up to 2000dim vectors

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Vector dimension 3072 is too large. LanternDB currently supports up to 2000dim vectors
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lanterndata/lantern/issues/374 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/lanterndata/lantern | matched external service / cloud / webhook / database keyword

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/lanterndata/lantern | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/lanterndata/lantern | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/lanterndata/lantern | no_demo; severity=medium

## 12. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/lanterndata/lantern | issue_or_pr_quality=unknown

## 13. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/lanterndata/lantern | release_recency=unknown

<!-- canonical_name: lanterndata/lantern; human_manual_source: deepwiki_human_wiki -->