# knowledge

**Repository Path**: gitdogcat_admin/knowledge

## Basic Information

- **Project Name**: knowledge
- **Description**: # KB - 极简知识库系统

一个基于文件系统的轻量级知识库，用 Go 编写，单二进制部署。没有数据库锁死，没有花里胡哨的功能，就是简单可靠的文档管理。

## 为什么做这个

思源笔记太难用了。BUG 没人修，文档管理混乱，数据格式私有。找了一圈替代品，要么太重（Outline 要 Postgres+Redis），要么太 g
eek（纯命令行），要么往"块编辑器/双链图谱"这些花里胡哨的方向卷
- **Primary Language**: TeX/LaTeX
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KB - 极简知识库系统

一个基于文件系统的轻量级知识库，用 Go 编写，单二进制部署。没有数据库锁死，没有花里胡哨的功能，就是简单可靠的文档管理。

## 为什么做这个

思源笔记太难用了。BUG 没人修，文档管理混乱，数据格式私有。找了一圈替代品，要么太重（Outline 要 Postgres+Redis），要么太 geek（纯命令行），要么往"块编辑器/双链图谱"这些花里胡哨的方向卷。

我们的需求很朴素：
- 树状目录 + Markdown 文档
- 全文搜索（中文要能用）
- API 给 Hermes 读写
- 数据就是 `.md` 文件，不锁死在数据库里

找不到，就自己写了一个。

## 特性

- **文件系统即真相**：文档就是目录里的 `.md` 文件，系统挂了数据还在，scp 就能搬走
- **双链 + 反向链接**：`[[文档名]]` 语法，文档互链自动索引，阅读页显示"谁引用了我"
- **链接图谱**：d3 力导向图可视化整个知识网络，一眼看清文档之间的关系
- **业务实体图谱**（v1.3.0）：规则抽取 IP/主机名/服务:端口，实体成为图谱节点，文档挂在实体上
- **LLM 问答**（v1.4.0）：基于知识库的 RAG 问答，接 OpenAI 兼容 endpoint（DashScope/vLLM/Ollama），流式输出
- **悬停预览**（v1.4.0）：鼠标悬停双链显示文档预览，不用跳转就能瞟一眼内容
- **版本历史**：每次修改自动存档（每文档最多 50 版），支持 diff 对比和一键回滚
- **SQLite FTS5 搜索**：trigram 分词支持中文，索引坏了随时重建
- **单二进制部署**：Go 编译，前端 embed，15MB 搞定一切
- **REST API**：Bearer token 认证，Hermes 直接读写
- **Git 自动提交**：可选开启，文档变更自动 commit
- **回收站**：删除不真删，移入 trash 目录防手滑
- **零外部依赖**：前端 JS/CSS 全部本地化（含 d3），不依赖 CDN

## 快速开始

### 二进制运行

```bash
# 生成 token
export KB_TOKEN=$(openssl rand -hex 32)

# 启动（默认端口 6806）
./kb

# 访问 http://localhost:6806
```

### 配置

程序启动时自动读取 `~/.config/kb/config.json`（也可用 `-config` 指定其他路径），环境变量优先级更高、会覆盖文件里的同名项。

```json
{
  "addr": ":6806",
  "docs_dir": "./docs",
  "data_dir": "./data",
  "token": "your-secret-token",
  "git_enabled": false,
  "log_level": "info"
}
```

推荐把配置写进 `~/.config/kb/config.json`（`chmod 600`），改 token 只动这一个文件 + `systemctl --user restart kb` 即可。

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `KB_ADDR` | 监听地址 | `:6806` |
| `KB_DOCS_DIR` | 文档根目录 | `./docs` |
| `KB_DATA_DIR` | 数据目录（索引+回收站） | `./data` |
| `KB_TOKEN` | API Token（必填） | - |
| `KB_GIT_ENABLED` | Git 自动提交 | `false` |
| `KB_LOG_LEVEL` | 日志级别 | `info` |

### API 示例

```bash
# 列出所有文档
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs?recursive=true"

# 读取文档
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs/项目/README.md"

# 创建/更新文档
curl -X PUT -H "Authorization: Bearer $KB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "# 标题\n\n正文"}' \
  "http://localhost:6806/api/docs/项目/新文档.md"

# 搜索
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/search?q=关键词"

# 删除（进回收站）
curl -X DELETE -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs/旧文档.md"
```

完整 API 文档见 [docs/api.md](docs/api.md)。

## 部署

### 直接二进制（推荐）

```bash
# 下载或编译
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o kb ./cmd/kb

# 上传到服务器
scp kb user@server:/opt/kb/

# 写配置文件（程序启动时自动读取）
sudo mkdir -p /root/.config/kb
sudo tee /root/.config/kb/config.json << 'EOF'
{
  "addr": ":6806",
  "docs_dir": "/opt/kb/docs",
  "data_dir": "/opt/kb/data",
  "token": "your-token-here",
  "git_enabled": false,
  "log_level": "info"
}
EOF
sudo chmod 600 /root/.config/kb/config.json

# 创建 systemd 服务（无需 EnvironmentFile）
sudo tee /etc/systemd/system/kb.service << 'EOF'
[Unit]
Description=KB Knowledge Base
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/kb
ExecStart=/opt/kb/kb
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now kb
```

### 普通用户部署（无 sudo）

适合共享服务器或没有 root 权限的环境（如 Oracle Cloud 的 opc 用户）。配置写 `~/.config/kb/config.json`，服务用 `systemctl --user` 管理：

```bash
# 安装到 home 目录
mkdir -p ~/kb/{docs,data}
cp kb ~/kb/

# 1. 配置文件（程序启动自动读取）
mkdir -p ~/.config/kb
cat > ~/.config/kb/config.json << EOF
{
  "addr": ":6806",
  "docs_dir": "$HOME/kb/docs",
  "data_dir": "$HOME/kb/data",
  "token": "$(openssl rand -hex 32)",
  "git_enabled": false,
  "log_level": "info"
}
EOF
chmod 600 ~/.config/kb/config.json

# 2. 用户级 unit（%h 自动展开为 home，无需改路径）
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/kb.service << 'EOF'
[Unit]
Description=KB Knowledge Base
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/kb
ExecStart=%h/kb/kb
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

# 3. 启动（顺序不能反：先写 unit 文件，再 daemon-reload）
systemctl --user daemon-reload
systemctl --user enable --now kb

# 4. 常驻：注销登录后服务不被回收（需一次性 sudo）
sudo loginctl enable-linger $USER

# 验证
curl http://localhost:6806/api/health
```

常见报错 `Failed to enable unit: Unit file kb.service does not exist.` 不是权限问题，是第 2 步的 unit 文件没创建（或没 daemon-reload）。改 token 只需编辑 `~/.config/kb/config.json` 后 `systemctl --user restart kb`。

### 容器部署

```bash
# 构建镜像
podman build -t kb:latest -f Containerfile .

# 运行
podman run -d \
  --name kb \
  --restart unless-stopped \
  -p 6806:6806 \
  -v /data/kb/docs:/data/docs:Z \
  -v /data/kb/db:/data/db:Z \
  -e KB_TOKEN=your-token \
  kb:latest
```

更多部署选项见 [docs/deployment.md](docs/deployment.md)。

## 从思源迁移

```bash
# 导出思源文档
python3 scripts/export-from-siyuan.py

# 复制到 KB 文档目录
cp -r scripts/siyuan-export/* docs/

# 重建索引
curl -X POST -H "Authorization: Bearer $KB_TOKEN" \
  http://localhost:6806/api/reindex
```

## 项目结构

```
kb/
├── cmd/kb/           # 主程序入口
├── internal/
│   ├── api/          # REST API 处理器
│   ├── config/       # 配置加载
│   ├── search/       # SQLite FTS5 搜索
│   └── store/        # 文件系统存储 + Git
├── web/              # 前端（Alpine.js 单页）
├── scripts/          # 部署和迁移脚本
└── docs/             # 项目文档
```

## 技术栈

- **后端**：Go 1.24+，标准库优先，唯一外部依赖是 `modernc.org/sqlite`（纯 Go SQLite）
- **前端**：Alpine.js + Marked.js + github-markdown-css（全部本地化，无 CDN）
- **存储**：文件系统 + SQLite FTS5（仅索引）
- **部署**：systemd 或 Podman

##  License

MIT License - 详见 [LICENSE](LICENSE)

## 致谢

- [思源笔记](https://github.com/siyuan-note/siyuan) — 虽然难用，但导出的 markdown 格式帮了大忙
- [SQLite FTS5](https://www.sqlite.org/fts5.html) — trigram 分词让中文搜索变得简单