fix: 修复 11 个代码架构审计问题

H1: AppConfig 自定义 __init__ 改用 from_dict() 类方法 H2: list_collections_with_stats 改为从 ChromaDB 直接查询 H3: RateLimiter 过期 key 自动清理, 防止内存泄漏 M1: delete_by_source 区分 ValueError 与真实异常, 记日志 M2: VectorDB 新增 list_collections() 封装方法 M3: _remove_by_source 异常记日志, 不再静默吞掉 M4: CLI 集合回退支持 MD_VECTOR_DB_COLLECTION 环境变量 L1: DEFAULT_CONFIG_PATH 自动从项目根目录解析 L2: ingest 命令内重复 import 移至模块顶部 L3: 新增死循环回归测试 + 密集分隔符分块测试 L4: 统一 logger 名称为 md-vector-db 删除旧版审计文档测试: 48 passed
2026-07-06 13:16:26 +08:00
parent 7e77c31e16
commit 832201186d
13 changed files with 815 additions and 50 deletions
@@ -95,14 +95,14 @@ uv run md-vector-db serve --port 8000

 ## HTTP API

-| 方法 | 路径 | 需要认证 | 说明 |
-|------|------|----------|------|
-| `GET` | `/` | — | 重定向到 `/docs` (Swagger UI) |
-| `GET` | `/api/v1/health` | — | 健康检查（验证 ChromaDB + Embedder 可用性） |
-| `GET` | `/api/v1/collections` | — | 列出集合和已入库的源文件 |
-| `POST` | `/api/v1/ingest` | API Key | 入库文档（`file_path` 或 `content` + `file_name`，可选 `collection`） |
-| `POST` | `/api/v1/search` | API Key | 语义检索（`query` + `top_k`，可选 `collection`） |
-| `DELETE` | `/api/v1/documents/{file_name}` | API Key | 按文件名删除所有关联 chunks |
+| 方法       | 路径                              | 需要认证 | 说明                                                                          |
+| ---------- | --------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| `GET`    | `/`                             | —       | 重定向到`/docs` (Swagger UI)                                                |
+| `GET`    | `/api/v1/health`                | —       | 健康检查（验证 ChromaDB + Embedder 可用性）                                   |
+| `GET`    | `/api/v1/collections`           | —       | 列出集合和已入库的源文件                                                      |
+| `POST`   | `/api/v1/ingest`                | API Key  | 入库文档（`file_path` 或 `content` + `file_name`，可选 `collection`） |
+| `POST`   | `/api/v1/search`                | API Key  | 语义检索（`query` + `top_k`，可选 `collection`）                        |
+| `DELETE` | `/api/v1/documents/{file_name}` | API Key  | 按文件名删除所有关联 chunks                                                   |

 ### 调用示例

@@ -145,13 +145,13 @@ for r in resp.json()["results"]:

 所有命令均支持 `--config/-c`（配置文件）、`--collection/-C`（集合名，默认 `default`）。

-| 命令 | 说明 |
-|------|------|
-| `ingest <文件路径>` | 入库单个 .md 文件，支持 `-C` 指定集合 |
-| `ingest-dir <目录路径>` | 递归入库目录下所有 .md 文件 |
+| 命令                        | 说明                                                     |
+| --------------------------- | -------------------------------------------------------- |
+| `ingest <文件路径>`       | 入库单个 .md 文件，支持`-C` 指定集合                   |
+| `ingest-dir <目录路径>`   | 递归入库目录下所有 .md 文件                              |
 | `search <查询> -k <数量>` | 语义检索，`-k` 默认 10、最大 100，`--json` JSON 输出 |
-| `stats` | 显示 chunks 总数、源文件列表 |
-| `serve -p <端口>` | 启动 HTTP 服务（默认 8000） |
+| `stats`                   | 显示 chunks 总数、源文件列表                             |
+| `serve -p <端口>`         | 启动 HTTP 服务（默认 8000）                              |

 ---

@@ -189,11 +189,11 @@ MD_VECTOR_API_KEY=secret      # HTTP API 访问密钥（不设置则跳过认证

 ### Provider 速查

-| provider | 默认 API 地址 | 默认模型 | 维度 |
-|----------|--------------|---------|------|
-| `local` | 本地（sentence-transformers） | `BAAI/bge-small-zh-v1.5` | 512 |
-| `openai` | `https://api.openai.com/v1` | `text-embedding-3-small` | 1536 |
-| `dashscope` | 阿里云 DashScope | `text-embedding-v4` | 1536 |
+| provider      | 默认 API 地址                 | 默认模型                   | 维度 |
+| ------------- | ----------------------------- | -------------------------- | ---- |
+| `local`     | 本地（sentence-transformers） | `BAAI/bge-small-zh-v1.5` | 512  |
+| `openai`    | `https://api.openai.com/v1` | `text-embedding-3-small` | 1536 |
+| `dashscope` | 阿里云 DashScope              | `text-embedding-v4`      | 1536 |

 使用 OpenAI 兼容的第三方服务（硅基流动、智谱、DeepSeek 等）只需设置 `provider: openai` 并覆盖 `api_base` 和 `model`:

@@ -260,10 +260,10 @@ uv run pytest tests/ -v --cov=src --cov-report=term-missing  # 覆盖率

 本地嵌入模式自动检测 CUDA 设备，优先使用 GPU。实测性能对比（RTX 4060 Laptop，bge-small-zh-v1.5）：

-| 文件大小 | chunks | CPU 耗时 | GPU 耗时 |
-|----------|--------|----------|----------|
-| 60KB | 320 | 数分钟至卡死 | 0.7s |
-| 96KB | 729 | 卡死 | 1.8s |
+| 文件大小 | chunks | CPU 耗时     | GPU 耗时 |
+| -------- | ------ | ------------ | -------- |
+| 60KB     | 320    | 数分钟至卡死 | 0.7s     |
+| 96KB     | 729    | 卡死         | 1.8s     |

 **GPU 环境前提**：安装 CUDA 版 torch。本项目 `pyproject.toml` 已配置从本地 wheel 目录获取 CUDA 版 torch，`uv sync` 即可。