# akengu

**Repository Path**: ahkeng/akengu

## Basic Information

- **Project Name**: akengu
- **Description**: Akengu 是一款轻量级的文档阅读与协作平台，采用 Go + Vue 3 技术栈开发，单二进制部署，零配置启动。支持 Markdown、PDF、DOCX 多格式文档，实时文件扫描、多级目录导航、图表渲染、SEO 优化，内置 AI 对话（混合 RAG 检索 + 查询改写 + 精准引用标注）、即时通讯和 MCP Server，让 AI 工具直接读取和管理文档。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: local-ai, MCP, RAG, knowledge-base, self-hosted

## README

<!-- SPDX-License-Identifier: MIT -->
<!-- Copyright (c) 2026 Ahkeng -->

# Akengu

> AI 时代的知识伴侣 — 文档阅读器 · AI 对话 · 即时通讯 · MCP Server

## 简介

Akengu 是一款轻量级的文档阅读与协作平台，采用 Go + Vue 3 技术栈开发，单二进制部署，零配置启动。支持 Markdown、PDF、DOCX 多格式文档，实时文件扫描、多级目录导航、图表渲染、SEO 优化，内置 AI 对话（混合 RAG 检索 + 查询改写 + 精准引用标注）、即时通讯和 MCP Server，让 AI 工具直接读取和管理文档。

## 核心业务流程

### AI 智能问答流程

```mermaid
flowchart TD
    A[用户提问] --> B[查询改写]
    B --> C[混合搜索]
    C --> D[RRF 融合排序]
    D --> E[可见性过滤]
    E --> F[构建系统提示]
    F --> G[LLM 流式生成]
    G --> H[引用标注 + 锚点跳转]

    C -.-> C1[向量语义搜索]
    C -.-> C2[关键词精确搜索]
    C1 & C2 --> D

    F -.-> F1[角色规则]
    F -.-> F2[文档事实]
    F -.-> F3[文档内容]
    F -.-> F4[引用规则]
    F -.-> F5[标题锚点]
```

### 文档入库流程

```mermaid
flowchart TD
    A[文件变更] --> B[fsnotify 事件]
    B --> C[提取纯文本]
    C --> D[同步文档数据库]
    D --> E[更新搜索索引]
    D --> F[更新向量索引]
    D --> G[清除缓存]
```

### 文档可见性控制

```mermaid
flowchart TD
    A[用户请求文档] --> B{用户类型?}
    B -->|游客| C[仅 public 文档]
    B -->|普通用户| D[public + group 文档]
    B -->|管理员| E[全部文档]
    D --> D1{group 文档?}
    D1 -->|用户组内| D2[可见]
    D1 -->|单独授权| D3[可见]
    D1 -->|均不满足| D4[不可见]
```

## 特性一览

### 文档阅读

- **单二进制部署**：编译出一个可执行文件，配一个 `config.json` 和 `docs/` 目录即可运行，零运维成本
- **多格式支持**：支持 Markdown（goldmark 渲染）、PDF（前端 PDF.js 渲染）、DOCX（通过 XML 解析转 HTML）
- **实时文件扫描**：基于 fsnotify 事件驱动，文件变更毫秒级感知，无需重启服务
- **Vue Router History 模式**：URL 格式 `/guide/deploy`（无 `#` 无 `.md`），支持分享链接、浏览器前进后退
- **多级目录导航**：支持任意层级的目录结构展示
- **章节快速跳转**：自动提取文档标题（h1-h6），支持点击跳转和滚动高亮
- **图表渲染**：支持 Mermaid 流程图、ECharts 数据图表、KaTeX 数学公式
- **主题切换**：支持亮色/暗色主题切换，图标自动适配主题色
- **代码高亮**：基于 Shiki 引擎，支持 100+ 种编程语言的语法高亮
- **全文搜索索引**：倒排索引 + trigram，支持中文子串匹配（bigram 分词），增量更新
- **文件搜索**：实时过滤文件名，支持中文搜索，保留父目录结构
- **当前文档搜索**：关键字高亮，支持上一个/下一个跳转
- **字体大小调整**：内容区字体大小可调（14px~32px），不影响导航和目录区域
- **字体颜色选择**：提供 10 种预设字体颜色，支持恢复默认颜色
- **偏好存储**：基于 localStorage 自动保存用户偏好，下次访问自动恢复
- **隐私协议**：首次访问弹出隐私协议，用户同意后才存储偏好
- **侧栏折叠**：导航栏和章节目录均可独立折叠/展开
- **响应式布局**：自适应不同屏幕尺寸，小屏自动折叠侧栏
- **SEO 优化**：检测 30+ 种搜索引擎和社交媒体爬虫（含百度、搜狗、360、字节、微信、微博、抖音、快手、小红书、知乎、B站），服务端渲染完整 HTML 页面，支持 Open Graph 标签
- **ICP 备案**：页面底部显示公司名称和 ICP 备案号，通过配置文件自定义

### AI 对话

- **流式对话**：SSE 实时输出，支持 OpenAI 和 Ollama 两种协议
- **查询改写**：使用 LLM 从用户查询中提取核心关键词及同义词变体，帮助关键词检索跨越同义词鸿沟
- **混合 RAG 检索**：向量语义搜索 + 关键词精确搜索混合，使用 RRF（Reciprocal Rank Fusion）融合排序，兼顾语义理解和精确匹配
- **RAG 模式透明**：每次 AI 回复标注检索模式（混合搜索 / 向量搜索 / 关键词搜索），悬停可查看每个文档的匹配来源、向量相似度、关键词匹配内容
- **精准引用标注**：AI 回答自动标注引用来源，格式 `*【原文片段 源自：[文档路径](akengu://文档路径#锚点ID)】*`，点击引用可直接跳转到对应文档的对应章节
- **智能降级**：向量搜索不可用时自动回退到纯关键词搜索，保证服务可用性
- **多 Provider 支持**：管理员配置公共模型，用户可添加个人专属模型
- **游客/用户模型开关**：管理员可控制公共模型是否对游客和普通用户开放
- **会话管理**：创建、切换、删除、重命名、批量删除对话
- **自动标题归纳**：新对话首次回复后自动生成标题
- **流式中断**：支持中断正在进行的流式输出

### 向量搜索

- **语义搜索**：基于 Embedding API 的向量语义搜索，理解查询意图而非字面匹配
- **混合搜索融合**：向量搜索 + 关键词搜索经 RRF 融合排序，取长补短（详见 AI 对话章节）
- **索引构建进度**：实时显示当前处理文件、已处理文件数、分块数、耗时、预计剩余时间
- **增量更新**：文件变更时自动更新向量索引
- **可配置分块**：分块大小（默认 500 字）和重叠（默认 50 字）可调
- **内存保护**：构建时内存超过 1GB 自动停止
- **文件数量限制**：最多处理 5000 个文件，单文件最多 200 分块，总分块上限 50000

### 即时通讯

- **好友系统**：自动建立全员好友关系，支持在线状态显示、好友分组、拉黑/取消拉黑
- **私聊**：实时消息推送，支持消息撤回（2 分钟内），同步撤回对方消息
- **群聊**：创建/解散群组、邀请/移除成员、消息撤回，异步投递保证可靠性（4 worker + 3 次重试）
- **未读提醒**：私聊和群聊未读计数，SSE 实时推送新消息
- **头像裁剪**：支持图片上传、拖动缩放裁剪，头像更新实时通知好友

### 管理后台

- **用户管理**：创建/编辑/删除用户，分配角色
- **角色管理**：自定义角色，配置细粒度权限矩阵（6 大模块：用户、用户组、文档、模型、向量搜索、通用设置，每模块支持 view/create/edit/delete 等操作权限）
- **文档管理**：设置文档可见性（公开/群组/私有），群组模式可指定用户组和具体用户；支持文档导入、删除、目录管理
- **群组管理**：创建群组、分配文档可见性、添加/移除成员
- **模型管理**：配置公共 LLM Provider（OpenAI/Ollama），API Key 脱敏显示
- **向量搜索管理**：构建/重建/删除向量索引，测试 Embedding API 连接，查看索引状态
- **文档事件日志**：查看文档变更事件，支持按日期范围删除，可配置日志保留天数
- **系统设置**：站点名称、ICP 备案号、文件类型、上传限制、系统提示词、游客/用户模型开关等全局配置

### MCP Server

- **Model Context Protocol**：支持 AI 工具直接读取和管理文档
- **5 个工具**：list_docs、read_doc、search_docs、search_content、get_toc
- **资源暴露**：`akengu://docs/{path}` 协议，支持 resources/list 和 resources/read
- **变更通知**：文档变更时自动发送 notifications/resources/list_changed

### 数据安全

- **SQLCipher 加密**：主数据库和用户数据库全量加密，密钥绑定设备指纹
- **每用户独立数据库**：用户数据物理隔离，互不可见，即使服务端管理员也无法直接读取用户聊天记录
- **设备绑定**：密钥与设备硬件指纹绑定，防止数据库被复制到其他机器使用
- **恢复密钥**：首次运行生成恢复密钥（AES-256-GCM 加密存储），设备变更后可通过命令行恢复数据
- **登录安全**：bcrypt 密码哈希、登录限流（5 次/5 分钟，超限封禁 15 分钟）、登录 IP 日志
- **会话管理**：24 小时会话过期，每小时自动清理过期会话
- **用户数据库连接池**：30 分钟不活跃自动关闭用户数据库连接

## 功能演示

### Mermaid 流程图

```mermaid
graph TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作A]
    B -->|否| D[执行操作B]
    C --> E[结束]
    D --> E
```

### Mermaid 时序图

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务器

    Client->>Server: 请求文件列表
    Server->>Server: 扫描目录
    Server-->>Client: 返回文件树

    Client->>Server: 请求文件内容
    Server->>Server: 读取文件
    Server-->>Client: 返回内容
```

### ECharts 折线图

```echarts
{
  "title": { "text": "月度访问量" },
  "tooltip": {},
  "xAxis": {
    "type": "category",
    "data": ["1月", "2月", "3月", "4月", "5月", "6月"]
  },
  "yAxis": { "type": "value" },
  "series": [{
    "data": [120, 200, 150, 280, 180, 320],
    "type": "line",
    "smooth": true
  }]
}
```

### KaTeX 数学公式

行内公式：$E=mc^2$

块级公式：

$$
\int_{a}^{b} f(x) \, dx = F(b) - F(a)
$$

### 代码高亮

```go
func main() {
    fmt.Println("Hello, Akengu!")
}
```

## 应用场景

- **技术文档中心**：为开发团队提供项目文档、API 文档、架构设计文档的在线阅读平台，替代重量级 Wiki 系统
- **企业知识库**：将企业内部规章制度、操作手册、培训材料以 Markdown 组织，通过目录扫描实时更新
- **AI 辅助开发**：通过内置 MCP Server，AI 编程工具（Trae IDE、Cursor、Claude Desktop）可直接读取文档，实现 AI 辅助代码生成、文档问答、知识检索
- **团队协作**：内置即时通讯，讨论文档时无需切换到其他社交工具
- **教育教学**：教师将课件、讲义以 Markdown 编写后放入 docs 目录，学生通过浏览器即可阅读
- **个人笔记管理**：开发者、写作者将本地 Markdown 笔记集中管理，通过章节目录和翻页导航快速定位内容
- **产品手册发布**：软件产品将用户手册以 Markdown 维护，随产品一起打包分发，用户本地启动即可离线阅读

## 技术栈

### 后端

| 技术 | 版本 | 说明 | 协议 |
|------|------|------|------|
| Go | 1.25+ | HTTP 服务、目录扫描、静态文件服务 | BSD 3-Clause |
| goldmark | 1.8+ | Markdown 转 HTML（SEO 爬虫渲染） | MIT |
| fsnotify | 1.8+ | 文件系统事件监听 | BSD 3-Clause |
| go-sqlcipher | 4.4+ | SQLCipher 加密 SQLite 驱动 | Apache-2.0 |
| ledongthuc/pdf | - | PDF 文本提取 | Apache-2.0 |

### 前端

| 技术 | 版本 | 说明 | 协议 |
|------|------|------|------|
| Vue | 3.5+ | 组合式 API、TypeScript | MIT |
| Vue Router | 4.5+ | History 模式路由 | MIT |
| Vite | 6.1+ | 构建工具 | MIT |
| TypeScript | 5.x | 类型系统 | Apache-2.0 |
| markdown-it | 14.1+ | Markdown 解析 | MIT |
| Mermaid | 11.4+ | 流程图渲染 | MIT |
| ECharts | 5.5+ | 数据图表渲染 | Apache-2.0 |
| KaTeX | 0.16+ | 数学公式渲染 | MIT |
| Shiki | 1.24+ | 代码语法高亮 | MIT |
| DOMPurify | 3.4+ | XSS 防护 | Apache-2.0 |
| vue-pdf-embed | - | PDF 文件渲染 | MIT |

## 部署指南

### 环境要求

| 依赖 | 版本 | 用途 |
|------|------|------|
| Go | 1.25+ | 后端编译（需启用 CGO） |
| Node.js | 20+ | 前端构建 |
| GCC | - | CGO 编译依赖（Windows 下需 MinGW-w64） |

### 快速构建

项目提供 `build.bat` 构建脚本，支持交互式多平台构建：

```bash
# Windows 下运行
.\build.bat
```

构建菜单：

```
==========================================
      Akengu Build Script
==========================================

Select target platform(s):

  0 - Build ALL platforms
  1 - Windows (x86/64)
  2 - Ubuntu (x86/64)
  3 - Ubuntu (Arm64)
  4 - UOS / Deepin
  5 - EulerOS

  Q - Quit
==========================================
```

选择 Windows 平台时，会提示输入版本号（默认沿用上次版本），构建完成后自动打包为 `akengu-win-{版本号}.zip`。

### 手动构建

```bash
# 构建前端
cd web && npm install && npm run build

# 编译后端（Windows）
cd server && go build -o ../akengu.exe .

# 编译后端（Linux）
cd server && GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -o ../akengu .
```

也可使用 Makefile：

```bash
make build    # 构建前端 + 后端
make dev      # 开发模式
make clean    # 清理构建产物
```

### 配置文件

`config.json` 配置说明：

```json
{
  "port": 2900,
  "docs": "",
  "static": "",
  "icp": "",
  "ssl": false,
  "domain": "",
  "certFile": "",
  "keyFile": "",
  "exclude": ["web", "server", "release", "certs"],
  "allowedOrigins": []
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| port | 服务端口 | 2900 |
| docs | 文档目录，为空时使用 `{配置目录}/docs` | 空 |
| static | 前端静态文件目录，为空时使用 `{配置目录}/web/dist` | 空 |
| icp | ICP 备案号，显示在底部版权区 | 空 |
| ssl | 是否启用 Go 内置 TLS | false |
| domain | 域名 | 空 |
| certFile | SSL 证书文件路径 | 空 |
| keyFile | SSL 私钥文件路径 | 空 |
| exclude | 扫描时排除的目录名列表，与内置默认排除项（`node_modules`、`.git`）合并 | [] |
| allowedOrigins | CORS 允许的来源列表，为空时允许所有来源 | [] |

> **注意**：站点名称、公司信息、文件类型限制（默认 `.md`、`.docx`、`.pdf`）、上传限制、系统提示词等设置通过管理后台配置，存储在数据库中，不在 `config.json` 里。

配置加载优先级（从高到低）：

1. 命令行参数（`-port`、`-docs`、`-static`、`-recover`）
2. 环境变量（`PORT`、`DOCS_DIR`、`STATIC_DIR`、`DOMAIN`、`ICP`）
3. 工作目录下的 `config.json`
4. 可执行文件目录下的 `config.json`
5. 默认值

### 运行方式

#### 生产模式

```bash
# 使用配置文件运行
./akengu

# 命令行参数优先级高于配置文件
./akengu -port 3000 -docs ./mydocs -static ./web/dist

# 数据恢复（设备变更时使用恢复密钥）
./akengu -recover <recovery-key>
```

访问 http://localhost:2900 即可使用。

首次运行时，系统会：
1. 自动生成管理员账户，密码打印在控制台（仅显示一次，请及时保存）
2. 生成数据恢复密钥（仅显示一次，请妥善保存）
3. 在文档目录下创建 `.akengu/` 数据目录

#### 开发模式

```bash
# 终端1：启动前端开发服务器
cd web && npm run dev

# 终端2：启动后端服务
cd server && go run .
```

### SSL/HTTPS 配置

Akengu 支持两种 HTTPS 方案：

#### 方案一：Caddy 反向代理（推荐，公网场景）

项目根目录提供 `Caddyfile` 模板，Caddy 自动申请和续期 Let's Encrypt 证书：

```bash
# 先启动 Akengu（保持默认 HTTP 模式）
./akengu

# 再启动 Caddy
caddy run --config Caddyfile
```

#### 方案二：Go 内置 TLS（内网场景）

生成自签名证书并在 `config.json` 中配置：

```json
{
  "port": 443,
  "ssl": true,
  "certFile": "./certs/server.crt",
  "keyFile": "./certs/server.key"
}
```

## MCP Server

Akengu 内置 MCP（Model Context Protocol）Server，支持 AI 工具直接读取和管理文档。

### 启动方式

```bash
# MCP Server 模式（stdio 传输）
akengu mcp

# 开发环境
cd server && go run . mcp
```

### 暴露工具

| 工具名 | 功能 | 参数 |
|--------|------|------|
| `list_docs` | 列出所有文档 | 无 |
| `read_doc` | 读取文档原始内容 | `path`（文件相对路径） |
| `search_docs` | 按关键字搜索文档（文件名） | `keyword`（搜索关键字） |
| `search_content` | 全文内容搜索，返回匹配行及上下文 | `keyword`（搜索关键字）、`context`（上下文行数，默认 2） |
| `get_toc` | 获取文档目录结构（h1-h6） | `path`（文件相对路径） |

### 暴露资源

| URI 格式 | 说明 |
|----------|------|
| `akengu://docs/{path}` | 文档资源，MIME 类型 `text/markdown` |

### 变更通知

文档变更时自动发送：
- `notifications/resources/list_changed`
- `notifications/tools/list_changed`

### AI 工具配置

#### Trae IDE

在项目 `.trae/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "akengu": {
      "command": ["akengu", "mcp"]
    }
  }
}
```

#### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "akengu": {
      "command": "akengu",
      "args": ["mcp"]
    }
  }
}
```

#### Cursor

在 Cursor 设置的 MCP 配置中添加：

```json
{
  "akengu": {
    "command": "akengu",
    "args": ["mcp"]
  }
}
```

## API 接口

### 文档相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/files` | GET | 获取文件列表（树形结构） |
| `/api/file?path=xxx` | GET | 获取文件内容（Markdown 原文） |
| `/api/raw?path=xxx` | GET | 获取原始文件（PDF/DOCX 二进制流） |
| `/api/config` | GET | 获取站点配置 |
| `/api/search` | GET | 全文内容搜索 |
| `/api/documents` | GET | 获取用户可见文档列表 |

### 认证相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/logout` | POST | 用户登出 |
| `/api/auth/me` | GET | 获取当前用户信息 |
| `/api/auth/change-password` | POST | 修改密码 |

### AI 对话相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/chat` | POST | SSE 流式对话 |
| `/api/chat/sessions` | GET | 获取会话列表 |
| `/api/chat/sessions` | POST | 创建会话 |
| `/api/chat/sessions/{id}` | DELETE | 删除会话 |
| `/api/chat/sessions/{id}/messages` | GET | 获取会话消息 |
| `/api/chat/sessions/{id}/auto-title` | POST | 自动生成会话标题 |
| `/api/chat/messages/{id}` | DELETE | 删除单条消息 |

### 用户相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/user/providers` | GET | 获取用户专属 Provider 列表 |
| `/api/user/providers` | POST | 添加用户专属 Provider |
| `/api/user/providers/{id}` | PUT/DELETE | 编辑/删除用户专属 Provider |
| `/api/user/providers/{id}/default` | PUT | 设置默认 Provider |
| `/api/user/avatar` | POST | 上传头像 |
| `/api/uploads/{path}` | GET | 访问上传文件 |

### 好友相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/friends` | GET | 获取好友列表 |
| `/api/friends/online` | GET | 获取在线好友 |
| `/api/friends/{id}/move` | PUT | 移动好友到分组 |
| `/api/friends/{id}/block` | PUT | 拉黑好友 |
| `/api/friends/{id}/unblock` | PUT | 取消拉黑 |

### 私聊相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/chat/private/{id}` | GET | 获取私聊消息 |
| `/api/chat/private/{id}/read` | PUT | 标记私聊已读 |
| `/api/chat/private/{id}/revoke/{msgId}` | PUT | 撤回私聊消息 |
| `/api/chat/private/unread` | GET | 获取私聊未读数 |

### 群聊相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/chat/groups` | GET/POST | 获取/创建群聊 |
| `/api/chat/groups/unread` | GET | 获取群聊未读数 |
| `/api/chat/groups/{id}` | GET/DELETE | 获取/删除群聊 |
| `/api/chat/groups/{id}/members` | GET/POST | 获取/添加群成员 |
| `/api/chat/groups/{id}/members/{userId}` | DELETE | 移除群成员 |
| `/api/chat/groups/{id}/messages` | GET | 获取群聊消息 |
| `/api/chat/groups/{id}/read` | PUT | 标记群聊已读 |
| `/api/chat/groups/{id}/online` | GET | 获取群在线成员 |
| `/api/chat/groups/{id}/revoke/{msgId}` | PUT | 撤回群聊消息 |

### 管理后台

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/admin/users` | GET/POST | 用户列表/创建用户 |
| `/api/admin/users/list` | GET | 用户列表（分页） |
| `/api/admin/users/{id}` | PUT/DELETE | 编辑/删除用户 |
| `/api/admin/users/{id}/reset-password` | PUT | 重置用户密码 |
| `/api/admin/roles` | GET/POST | 角色列表/创建角色 |
| `/api/admin/roles/{id}` | PUT/DELETE | 编辑/删除角色 |
| `/api/admin/roles/{id}/permissions` | GET/PUT | 获取/设置角色权限 |
| `/api/admin/permissions` | GET | 获取权限定义列表 |
| `/api/admin/documents` | GET | 文档列表 |
| `/api/admin/documents/list` | GET | 文档列表（分页） |
| `/api/admin/documents/{id}` | PUT | 编辑文档 |
| `/api/admin/documents/{id}/visibility` | PUT | 设置文档可见性 |
| `/api/admin/documents/delete` | DELETE | 删除文档文件 |
| `/api/admin/documents/events` | GET | 文档事件日志 |
| `/api/admin/dirs` | GET | 获取目录树 |
| `/api/admin/dirs/create` | POST | 创建目录 |
| `/api/admin/dirs/delete` | DELETE | 删除目录 |
| `/api/admin/import` | POST | 导入文档文件 |
| `/api/admin/groups` | GET/POST | 群组列表/创建群组 |
| `/api/admin/groups/list` | GET | 群组列表（分页） |
| `/api/admin/groups/{id}/members` | POST | 添加群组成员 |
| `/api/admin/groups/{id}/members/{userId}` | DELETE | 移除群组成员 |
| `/api/admin/providers` | GET/POST | 模型列表/添加模型 |
| `/api/admin/providers/{id}` | PUT/DELETE | 编辑/删除模型 |
| `/api/admin/providers/{id}/default` | PUT | 设置默认模型 |
| `/api/admin/settings` | GET/PUT | 系统设置 |
| `/api/admin/embedding/status` | GET | 获取向量索引状态 |
| `/api/admin/embedding/config` | GET/PUT | 向量搜索配置 |
| `/api/admin/embedding/rebuild` | POST | 重建向量索引 |
| `/api/admin/embedding/index` | DELETE | 删除向量索引 |
| `/api/admin/embedding/test` | POST | 测试 Embedding API 连接 |
| `/api/llm/config` | GET | 获取 LLM 配置（模型列表） |

### SSE 事件

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/events` | GET | SSE 事件流（消息通知、好友上线等） |

## SEO 与安全

### 爬虫检测

服务端检测 30+ 种主流搜索引擎和社交媒体爬虫的 User-Agent（含百度、搜狗、360、字节、微信、微博、抖音、快手、小红书、知乎、B站），自动渲染完整 HTML 页面。

### 安全机制

- **路径安全**：禁止 `..` 路径穿越，验证请求路径在文档目录范围内
- **XSS 防护**：Markdown 渲染输出经 DOMPurify 清洗
- **CORS 支持**：可配置允许的来源列表
- **安全响应头**：X-Content-Type-Options、X-Frame-Options、X-XSS-Protection 等
- **认证中间件**：JWT Token 认证，登录限流
- **RAG 可见性过滤**：RAG 检索结果按用户文档可见性过滤，用户只能检索到有权访问的文档

## 项目结构

```
akengu/
├── server/                  # Go 后端
│   ├── main.go              # 入口（Web 服务 / MCP 模式）
│   ├── config.go            # 配置解析
│   └── internal/
│       ├── handler/         # HTTP 处理器
│       │   ├── handler.go   # 核心入口与中间件
│       │   ├── deps.go      # 共享依赖定义
│       │   ├── router.go    # 路由注册
│       │   ├── auth.go      # 认证
│       │   ├── chat_svc.go  # AI 对话 + RAG
│       │   ├── doc_svc.go   # 文档服务 + SEO
│       │   ├── social_svc.go # 即时通讯
│       │   ├── admin_svc.go # 管理后台
│       │   ├── embedding.go # 向量搜索管理
│       │   └── events.go    # SSE 事件推送
│       ├── store/           # 数据层
│       │   ├── db.go        # 数据库核心（SQLCipher + Schema 迁移）
│       │   ├── user.go      # 用户管理
│       │   ├── chat.go      # 聊天数据
│       │   ├── doc.go       # 文档数据与可见性
│       │   ├── role.go      # RBAC 角色与权限
│       │   ├── friend.go    # 好友关系
│       │   ├── group.go     # 群聊数据
│       │   ├── provider.go  # LLM Provider
│       │   ├── nav.go       # 目录扫描与工具函数
│       │   └── session.go   # 会话管理
│       ├── search/          # 全文搜索引擎（倒排索引 + trigram）
│       ├── embedding/       # 向量搜索与索引（RRF 融合）
│       ├── extract/         # 文档内容提取（MD/PDF/DOCX）
│       ├── mcp/             # MCP Server（JSON-RPC）
│       └── watcher/         # 文件监控（fsnotify）
├── web/                     # Vue 3 前端
│   └── src/
│       ├── views/           # 页面视图（reader / admin）
│       ├── components/      # UI 组件
│       ├── composables/     # 组合式函数
│       ├── styles/          # 样式文件
│       ├── types/           # TypeScript 类型
│       └── router/          # 路由配置
├── build.bat                # 构建脚本
├── Makefile                 # Make 构建
├── Caddyfile                # Caddy 反向代理配置
└── config.json              # 运行配置
```

## 对用户的经济价值

### 降低知识获取成本

| 场景 | 传统方式 | 用 Akengu |
|------|---------|-----------|
| 查找文档中的某个配置 | 翻文档/搜索/问同事 | AI 对话直接问，RAG 精准定位 |
| 新人熟悉项目文档 | 逐篇阅读 | 问 AI "项目怎么部署"，直接得到答案 |
| 跨文档关联查询 | 手动翻多篇 | 混合搜索一次命中多个相关文档 |

AI + RAG 把"读文档"变成"问文档"，知识获取从主动搜索变为被动获取，效率提升数倍。

### 降低工具成本

| 需求 | 传统组合 | Akengu |
|------|---------|--------|
| 文档站 + AI 问答 + 团队 IM | GitBook + ChatGPT + 飞书 | 一个工具 |
| 自托管文档 + 加密存储 | Confluence + 额外加密方案 | 免费开源 |
| 向量搜索 + 关键词搜索 | ElasticSearch + Milvus | 内置，零配置 |

一个单文件 exe 替代 3-4 个工具，省去多工具的授权费、运维成本和学习成本。

### 降低合规与安全成本

| 场景 | 传统代价 | Akengu |
|------|---------|--------|
| 文档含商业机密，不能上云 | 自建 GitBook + Nginx + 权限系统 | 单文件部署，数据不出服务器 |
| 用户数据隔离要求 | 复杂的权限系统 + 审计 | 每用户独立加密数据库 |
| 设备丢失，数据泄露 | 依赖全盘加密 | SQLCipher + 设备指纹绑定 |

对有数据安全要求的团队（金融、医疗、法律、政府），自托管 + 加密 = 零合规成本。

### 提升开发者效率（MCP）

| 场景 | 传统方式 | 用 Akengu MCP |
|------|---------|---------------|
| 在 IDE 中查 API 文档 | 切浏览器搜索 | AI 编程工具直接调用，不离开 IDE |
| 写代码时查项目规范 | 翻 wiki | Cursor/Windsurf 自动获取文档上下文 |

MCP 让文档成为 AI 编程工具的"眼睛"，开发者不用手动查文档，AI 自动参考项目文档写代码。

### 降低部署运维成本

| 对比 | 传统文档站 | Akengu |
|------|-----------|--------|
| 部署 | Docker/Node.js/数据库/反向代理 | 1 个 exe |
| 运维 | 多组件监控升级 | 单文件替换 |
| 依赖 | Node.js/Python/MySQL/Redis | 零依赖 |
| 硬件 | 2C4G 起步 | 1C1G 可跑（SQLite） |

运维成本从"专人维护"降到"替换一个文件"，小团队/个人零运维负担。

### 内容资产增值

| 场景 | 价值 |
|------|------|
| 技术博客 + 内部文档合一 | 一份内容，对外 SEO 引流，对内知识管理 |
| 30+ 爬虫 UA 识别（含国内平台） | 中文互联网 SEO 效果好，免费获客 |
| 文档可见性控制 | 公开内容引流，私有内容保护 |

文档不再只是"存着"，而是可以对外引流的内容资产。

## 开源说明

- **作者**：Ahkeng
- **邮箱**：ahkeng@zdco.ltd
- **协议**：MIT License
- **SPDX**：SPDX-License-Identifier: MIT
- **版权**：Copyright (c) 2026 Ahkeng

任何个人或组织均可免费使用、修改和分发本软件，包括商业用途，唯一要求是在分发时保留原始版权声明和许可声明。协议全文详见 [LICENSE](LICENSE) 文件。

---

> 本文档由 Akengu 自动渲染