个人博客2.0
前置技术
核心技术栈：
- 全栈框架：Astro
- 向量数据库：LanceDB [核心知识库/长期记忆]
- 边缘状态库：Upstash for Redis [高频交互承载/留言缓冲池]
- AI模型层：BAAI/bge-m3[向量分析]，glm-4.5-air[AI搜索,AI审核]，glm-5.1[AI辅助开发]
一、框架概述
1.1 核心理念
**BlogX_x 是一个现代化的个人数字花园系统，遵循以下核心理念：
-
VibeCoding - 注重用户体验和交互感受，极简黑白美学
-
SpecCoding - 严格的数据结构定义和类型约束
-
Harness Design - 完整的工具链和自动化流程
1.2 技术栈架构
┌─────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ 首页 │ 文章详情 │ 知识库 │ │
│ │ (AI搜索) │ (内容展示) │ (浏览) │ │
│ └──────────────┴──────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 应用层 (Astro) │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ 页面路由 │ API 端点 │ 组件库 │ │
│ │ (SSR) │ (后端) │ (React) │ │
│ └──────────────┴──────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ LanceDB │ Vercel KV │ Markdown │ │
│ │ (向量DB) │ (缓存) │ (源文件) │ │
│ └──────────────┴──────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 外部服务 │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ GLM AI │ SiliconFlow │ Obsidian │ │
│ │ (对话/审核) │ (向量嵌入) │ (知识源) │ │
│ └──────────────┴──────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────┘
二、架构设计详解
2.1 数据流处理管道
2.1.1 Obsidian 同步流程
Obsidian Vault
↓
sync-obsidian-kb.mjs (脚本)
├─ 扫描 .md 文件
├─ 解析 frontmatter
├─ 转换 wikilinks → markdown links
├─ 计算 content hash
└─ 增量同步到 src/content/knowledge-base/
↓
Astro Content Collections
├─ 验证 schema
├─ 生成类型定义
└─ 构建内容索引
↓
LanceDB 向量索引
├─ 提取文本内容
├─ 调用 SiliconFlow 生成向量
├─ 存储到 LanceDB
└─ 建立相似度索引
2.1.2 AI 搜索流程
用户输入查询
↓
前端校验 + 频率限制
↓
POST /api/ai-search
├─ 服务端频率限制检查
├─ 调用 SiliconFlow 生成查询向量
├─ LanceDB 相似度检索 (top-10)
├─ 调用 GLM-4.5-AIR 生成回答
└─ 返回 { answer, results }
↓
前端渲染
├─ 显示 AI 生成的回答
├─ 展示相关文章卡片
└─ 提供跳转链接
2.2 功能模块详解
2.2.1 AI 搜索模块
文件位置: src/pages/api/ai-search.ts
核心功能:
-
语义向量检索 (LanceDB)
-
AI 对话生成 (GLM-4.5-AIR)
-
频率限制 (IP + 全局)
-
结果排序和去重
API 接口:
POST /api/ai-search
Content-Type: application/json
{
"query": "如何优化 Astro 性能？",
"limit": 10
}
Response:
{
"answer": "AI 生成的对话式回答...",
"results": [
{
"id": "post-1",
"title": "Astro 性能优化指南",
"description": "...",
"url": "/posts/astro-performance",
"similarity": 0.92
}
],
"timestamp": 1713950400000
}
频率限制策略:
-
前端: 30秒内最多1次请求
-
IP级: 5分钟内最多3次请求 (滑动窗口)
-
全局: 每分钟最多50次请求 (滑动窗口)
2.2.2 知识图谱模块
文件位置: src/components/KnowledgeGraph.tsx
核心功能:
-
自动构建内容关系网络
-
基于向量相似度的连接
-
交互式可视化展示
-
响应式适配
数据结构:
interface GraphNode {
id: string;
label: string;
type: 'post' | 'knowledge' | 'note';
url: string;
size: number; // 基于相关度
}
interface GraphLink {
source: string;
target: string;
similarity: number; // 0-1
}
interface GraphData {
nodes: GraphNode[];
links: GraphLink[];
}
相似度阈值: 0.7 (可配置)
最大连接数: 每个节点最多5条边
响应式: 手机端 (< 768px) 隐藏图谱
2.2.3 留言功能模块
文件位置:
-
src/components/FunMessages.tsx- 趣味留言墙 -
src/components/IdeaBox.tsx- 点子收集箱
趣味留言墙:
-
用户提交 → AI 审核 → 自动展示
-
水平飘动动画 (15秒)
-
最多同时展示 20 条
-
5秒轮询更新
点子收集箱:
-
用户提交 → 待审核 → 管理员审核 → 展示
-
支持实现状态标记 (✓ / ○)
-
管理员后台管理
-
支持备注功能
2.2.4 MCP 服务模块
文件位置:
-
scripts/kb-mcp-server.mjs- stdio 模式 -
scripts/kb-mcp-http-server.mjs- HTTP 模式
支持的工具:
// 搜索知识库
{
"name": "search_knowledge_base",
"description": "搜索知识库内容",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "number" }
}
}
}
// 读取条目
{
"name": "read_entry",
"description": "读取特定知识库条目",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string" }
}
}
}
// 列表条目
{
"name": "list_entries",
"description": "列出所有知识库条目",
"inputSchema": {
"type": "object",
"properties": {
"category": { "type": "string" }
}
}
}
三、开发流程与最佳实践
3.1 内容创建流程
3.1.1 创建博客文章
# 1. 在 src/content/posts/ 创建 markdown 文件
touch src/content/posts/my-article.md
# 2. 添加 frontmatter
---
title: "我的文章标题"
date: 2026-04-24
description: "文章简短描述，用于 SEO 和列表展示"
tags: ["astro", "前端", "性能"]
coverImage: "/images/cover.jpg"
isDraft: false
---
# 文章内容
...
# 3. 构建时自动生成路由
# 访问: /posts/my-article
3.1.2 同步 Obsidian 知识库
# 1. 配置 .env
OBSIDIAN_KB_PATH="/path/to/obsidian/vault"
LOCAL_KB_CONTENT_DIR="src/content/knowledge-base"
# 2. 运行同步脚本
npm run sync-kb
# 3. 检查变更
git diff src/content/knowledge-base/
# 4. 暂存并提交
npm run sync-kb:stage
git commit -m "chore: sync obsidian knowledge base"
3.2 向量索引管理
3.2.1 初始化向量数据库
# 1. 配置 LanceDB 环境变量
LANCEDB_URI="db://your-db-uri"
LANCEDB_API_KEY="sk_your-api-key"
SF_TOKEN="hf_your-siliconflow-token"
# 2. 初始化索引
npm run init-db
# 3. 脚本流程
# - 读取所有 markdown 文件
# - 提取文本内容
# - 调用 SiliconFlow 生成向量 (1024维)
# - 存储到 LanceDB
# - 建立相似度索引
3.2.2 增量更新
# 自动检测变更
npm run init-db
# 脚本会：
# 1. 计算现有文件的 hash
# 2. 对比 LanceDB 中的记录
# 3. 仅更新变更的文件
# 4. 删除已移除的条目
3.3 部署流程
3.3.1 本地构建验证
# 1. 构建生产版本
npm run build
# 2. 预览构建结果
npm run preview
# 3. 检查构建产物
ls -la .vercel/output/
3.3.2 Vercel 部署
# 1. 连接 GitHub 仓库
# 2. 配置环境变量
# - LANCEDB_URI
# - LANCEDB_API_KEY
# - SF_TOKEN
# - GLM_API_KEY
# - OBSIDIAN_KB_PATH (可选)
# 3. 自动部署
# - 推送到 main 分支
# - Vercel 自动触发构建
# - 部署到生产环境
# 4. 验证部署
# - 检查 https://your-domain.vercel.app
# - 测试 AI 搜索功能
# - 验证知识图谱加载