# 知识库博客

**Repository Path**: lkq55421/knowledge-base-blog

## Basic Information

- **Project Name**: 知识库博客
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档博客 Web 服务

一个基于 Python 标准库构建的轻量级文档浏览与全文检索 Web 应用，用于管理和搜索 Markdown 格式的学习笔记与技术文档。零外部依赖，双击即可启动。

> 当前收录 **211 篇** 文档，**16 个分类**，约 **197 万字**。

## 功能特性

- **全文检索** — 基于 SQLite FTS5 trigram 分词，支持中文子串匹配，毫秒级响应
- **智能分类** — 文件名关键词 + 内容关键词双重匹配，自动归入 16 个分类
- **增量导入** — 通过文件 mtime 判断变更，仅处理新增/修改的文件，秒级启动
- **暗色/亮色主题** — 自动检测系统偏好，支持手动切换，偏好本地持久化
- **章节导航** — 文章页自动提取右侧 TOC，滚动时高亮当前章节
- **代码高亮** — 内置 Prism.js，支持主流编程语言语法着色
- **响应式布局** — 侧边栏抽屉式菜单，适配桌面和移动端
- **键盘快捷键** — `Ctrl+K` 快速聚焦搜索框

## 快速启动

### Windows（双击）

```
双击 web-app/start.bat
```

### 命令行

```bash
cd web-app
python3 server.py
```

### 打开浏览器

```
http://localhost:8080
```

> **环境要求**: Python 3.10+（内置 `sqlite3` + `http.server`，无需安装第三方包）

## 项目结构

```
web-app/
├── server.py              # 主服务程序（HTTP 服务 + 数据库 + 全文索引）
├── start.bat              # Windows 启动脚本
├── start.vbs              # Windows 无窗口启动脚本
├── README.md              # 本文件
├── docs/                  # 项目文档
│   ├── 技术文档.md         # 详细技术文档
│   └── 优化方案.md         # 功能优化路线图
├── data/
│   ├── docs.db            # SQLite 数据库（运行时自动生成）
│   └── server.log         # 运行日志
└── static/                # 前端静态资源
    ├── index.html         # 单页应用入口
    ├── css/
    │   ├── style.css      # 主题样式（暗色/亮色）
    │   └── prism-tomorrow.css  # 代码高亮主题
    └── js/
        ├── app.js         # 前端 SPA 逻辑
        └── prism.min.js   # 代码高亮引擎
```

## 系统架构

```
┌──────────────────────────────────────────────────────────┐
│                     客户端 (浏览器)                       │
│  index.html  |  style.css (暗/亮主题)  |  app.js (SPA)   │
└──────────────────────────┬───────────────────────────────┘
                           │ HTTP/1.1
┌──────────────────────────▼───────────────────────────────┐
│                Python http.server (8080)                  │
│  DocHandler: API 路由 → JSON 响应 → 静态文件服务          │
└──────────────────────────┬───────────────────────────────┘
                           │ sqlite3 (WAL 模式)
┌──────────────────────────▼───────────────────────────────┐
│                   SQLite 数据库                           │
│  categories (分类表) | documents (文档表) | docs_fts (FTS5)│
└──────────────────────────────────────────────────────────┘
```

## API 接口

| 接口 | 参数 | 说明 |
|------|------|------|
| `GET /api/stats` | — | 统计信息（文档数、分类数、总字数） |
| `GET /api/categories` | — | 分类列表（含文档计数） |
| `GET /api/documents` | `category`, `page`, `limit` | 文档列表，支持分类筛选和分页 |
| `GET /api/search` | `q`, `page`, `limit` | 全文搜索（FTS5 trigram） |
| `GET /api/document` | `id` | 文档详情（含 HTML 渲染内容） |
| `GET /api/sync` | — | 增量同步（仅处理新增/变更文件） |
| `GET /api/reindex` | — | 全量重建索引 |
| `GET /api/recategorize` | `id`, `slug` | 手动修正文档分类 |

## 文档导入

### 增量导入（默认）

启动时自动执行。通过对比文件 `mtime` 判断是否变更：

- **mtime 未变** → 直接跳过
- **mtime 变更** → 删除旧记录，重新索引
- **新文件** → 自动分类并导入

### 全量重建

访问 `http://localhost:8080/api/reindex` 触发。清空所有数据后重新扫描。

### 扫描范围

1. `docs/` 子目录：按目录结构决定分类
2. 根目录 `*.md` 文件：自动智能分类

## 智能分类

内置 16 个分类，采用**双重匹配策略**：

1. **文件名关键词匹配** — 检查文件名是否包含分类关键词
2. **内容关键词匹配** — 取前 500 字内容进行匹配
3. **兜底** — 未匹配则归入「其他」

当前分类：AI与机器学习、移动端开发、Java与JVM、数据库与存储、大数据与分布式、前端与Web、架构与设计、操作系统与底层、哲学与人文、管理与经营、数学与算法、面试与求职、工具与实践、教育与考试、网络与安全、其他。

### 添加新分类

编辑 `server.py` 中的 `CATEGORY_RULES` 列表：

```python
CATEGORY_RULES = [
    # (slug, 显示名, icon, [关键词列表])
    ("newcat", "新分类", "🆕", ["关键词1", "关键词2"]),
    # ... 其他分类（other 必须放最后作为兜底）
]
```

## 前端交互

| 操作 | 说明 |
|------|------|
| `Ctrl+K` | 聚焦搜索框 |
| `Enter` | 执行搜索 |
| `Escape` | 清空搜索，返回首页 |
| 主题切换 | 点击右上角 ☀️/🌙 按钮 |
| 章节导航 | 文章页右侧自动显示 TOC |
| 返回顶部 | 滚动超过 400px 显示 ↑ 按钮 |

## 配置说明

编辑 `server.py` 顶部的配置常量：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `PORT` | `8080` | 服务端口 |
| `DB_PATH` | `data/docs.db` | 数据库文件路径 |
| `DOCS_SRC` | `../` | Markdown 文件扫描根目录 |
| `DOCS_CATEGORIES_DIR` | `../docs` | 分类文档目录 |

## 技术栈

- **后端**: Python 3.10+ 标准库（`http.server` + `sqlite3`）
- **全文检索**: SQLite FTS5（trigram tokenizer，支持中文）
- **前端**: 纯 HTML/CSS/JS，零框架依赖
- **Markdown 渲染**: 内置转换器（标题、代码块、表格、列表、引用）
- **代码高亮**: Prism.js

## 性能指标

| 指标 | 数值 |
|------|------|
| 启动时间（增量） | < 1 秒 |
| 启动时间（全量） | < 3 秒 |
| 搜索响应 | 毫秒级 |
| 内存占用 | ~50MB |
| 数据库大小 | ~20MB（211 篇文档） |