# knowledgebase

**Repository Path**: xiaaoke/knowledgebase

## Basic Information

- **Project Name**: knowledgebase
- **Description**: 个人知识管理与协作平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KnowledgeBase 项目

## 项目介绍

KnowledgeBase 是一个知识管理系统，用于个人或团队的笔记与知识库管理。采用前后端分离：**前端** Vue 3 + TypeScript + Vite；**后端** Node.js + TypeScript + Express。支持用户认证、笔记本目录、Markdown 编辑、标签、附件、协作分享、全文搜索与公开笔记浏览等能力。

数据存储通过环境变量 **`DB_TYPE`** 在 **MongoDB** 与 **MySQL** 之间二选一（不会同时作为双写主库使用）。

## 技术栈

### 前端

- Vue 3（Composition API）+ TypeScript + Vite
- Vue Router 4、Pinia
- Element Plus、Sass
- Axios（统一 `api` 封装）
- Markdown：`md-editor-v3`、`markdown-it`、DOMPurify

### 后端

- Node.js + TypeScript、Express 5、`tsx` 开发运行
- 数据库（二选一）：**MongoDB**（Mongoose）或 **MySQL**（Knex + mysql2）
- JWT 认证、`bcryptjs`、**zod** 校验
- 文件上传：`multer`，静态资源目录 `backend/uploads`，URL 前缀 `/uploads`

### 共享包

- `shared/`：前后端共用的类型与请求/响应约定（如 `types.ts`、`response.ts` 等）

## 项目结构

```
knowledgebase/
├── backend/
│   ├── src/
│   │   ├── config/       # 应用、数据库、上传等配置
│   │   ├── controllers/
│   │   ├── middleware/
│   │   ├── models/
│   │   ├── routes/
│   │   ├── services/
│   │   ├── utils/        # 含 mysql.sql 表结构脚本
│   │   ├── app.ts
│   │   └── server.ts
│   ├── uploads/          # 上传文件（运行时生成）
│   ├── package.json
│   └── tsconfig.json
├── frontend/
│   ├── public/
│   ├── src/
│   │   ├── api/          # 接口封装（禁止在视图里直接裸调 axios）
│   │   ├── assets/
│   │   ├── components/
│   │   ├── composables/  # 业务/交互复用
│   │   ├── router/
│   │   ├── stores/       # Pinia（如 auth）
│   │   ├── utils/
│   │   ├── views/
│   │   ├── App.vue
│   │   ├── main.ts
│   │   └── style.scss
│   ├── package.json
│   └── vite.config.ts
├── note/                 # 仓库内技术笔记（非运行时数据）
├── shared/               # workspace 共享 TS 模块
├── package.json
├── pnpm-lock.yaml
└── pnpm-workspace.yaml
```

## 功能特性

### 前端

- 登录 / 注册（支持注册头像上传）
- 笔记本树形目录、笔记列表、新建 / 编辑（Markdown）、详情与分享链接（公开详情可免登录打开）
- 标签管理、归档、回收站
- 协作：邀请协作者、协作列表
- 全文搜索、公开笔记广场（`/public-notes`）
- 个人资料
- 路由守卫（Pinia token）；公开笔记详情单独放行

### 后端

- 认证、用户资料、按邮箱查找用户（协作邀请）
- 笔记本 CRUD、笔记 CRUD（含软删与永久删除）、笔记标签关联
- 附件上传与管理；协作者 CRUD；全局搜索；公开笔记列表与详情 API

## 安装步骤

### 1. 克隆项目

```bash
git clone <项目仓库地址>
cd knowledgebase
```

### 2. 安装依赖

在仓库根目录使用 pnpm（workspace 会安装 `frontend`、`backend` 等子项目依赖；`shared/` 由 TS 路径引用，无需单独发布）：

```bash
pnpm install
```

### 3. 配置环境变量

在 **`backend`** 目录创建 `.env`（变量名需与代码一致）：

```env
# 服务端口（默认 5000）
PORT=5000

# 数据库类型：mongo | mysql（默认 mongo）
DB_TYPE=mongo

# MongoDB（DB_TYPE=mongo 时使用）
MONGO_URI=mongodb://localhost:27017/knowledge_base

# MySQL（DB_TYPE=mysql 时使用；端口代码内固定 3306）
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=knowledge_base

# JWT（生产环境务必修改）
JWT_SECRET=your_jwt_secret

# 可选：生成对外附件/头像完整 URL 时的站点 origin（无末尾斜杠）
# PUBLIC_ORIGIN=http://localhost:5000
```

前端在 **`frontend`** 目录可配置 API 基地址（默认与后端一致）：

```env
# frontend/.env.development 等
VITE_API_BASE_URL=http://localhost:5000/api
```

### 4. 数据库初始化

- **MySQL**：执行 `backend/src/utils/mysql.sql` 创建库表（库名默认 `knowledge_base`，与 `MYSQL_DATABASE` 一致）。
- **MongoDB**：首次连接时会使用对应数据库，集合由应用模型创建。

## 运行项目

### 启动后端

```bash
cd backend
pnpm dev
```

默认监听 **`http://localhost:5000`**（与前端 `VITE_API_BASE_URL` 默认一致）。

### 启动前端

```bash
cd frontend
pnpm dev
```

开发服务器默认 **`http://localhost:5173`**。

## API 概览

以下为当前路由挂载方式下的主要接口（除特别说明外需携带 `Authorization: Bearer <token>`）。

### 认证 ` /api/auth`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/register-avatar` | 注册前上传头像，返回 `/uploads/...` URL |
| POST | `/register` | 注册（支持 JSON 或 multipart） |
| POST | `/login` | 登录，返回 JWT（有效期代码内为 7d） |

### 笔记 `/api/notes`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 笔记列表 |
| GET | `/:id` | 笔记详情 |
| POST | `/` | 创建 |
| PUT | `/:id` | 更新 |
| DELETE | `/:id` | 软删除 |
| DELETE | `/:id/permanent` | 永久删除 |
| POST | `/:noteId/tags/:tagId` | 笔记关联标签 |
| DELETE | `/:noteId/tags/:tagId` | 移除关联 |
| GET | `/:noteId/attachments` | 该笔记附件列表 |
| GET | `/:noteId/collaborators` | 该笔记协作者列表 |

### 用户 `/api/users`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/lookup` | 按邮箱查询用户（协作等） |
| GET | `/profile` | 当前用户资料 |
| PUT | `/profile` | 更新资料 |

### 笔记本 `/api/notebooks`

标准 REST：`GET /`、`GET /:id`、`POST /`、`PUT /:id`、`DELETE /:id`。

### 标签 `/api/tags`

同上。

### 附件 `/api/attachments`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 附件列表 |
| GET | `/:id` | 单个附件 |
| GET | `/note/:noteId` | 某笔记附件 |
| POST | `/` | 上传（字段名 `file`） |
| PUT | `/:id` | 更新 |
| DELETE | `/:id` | 删除 |

### 协作 `/api/collaborations`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/me` | 当前用户收到的协作列表 |
| GET | `/note/:noteId` | 某笔记协作者 |
| GET | `/:id` | 单条协作关系 |
| POST | `/` | 创建 |
| PUT | `/:id` | 更新 |
| DELETE | `/:id` | 删除 |

### 搜索与公开笔记 `/api`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/search` | 全局搜索（需登录） |
| GET | `/public-notes` | 公开笔记列表（无需登录） |
| GET | `/public-notes/:id` | 公开笔记详情（无需登录） |

静态资源：`GET /uploads/<文件名>`。

## 项目文档

`note/` 目录为仓库内技术笔记，例如 MongoDB / MySQL / Node.js 等指南，与线上笔记数据无关。

## 开发说明

- TypeScript 严格模式；前后端分别可在各自目录配置 ESLint。
- 后端当前 **`package.json` 未提供 `build` 脚本**，开发使用 `tsx` 直接运行；若需生产构建，可自行增加 `tsc` 编译步骤并用 `node dist/server.js`（或继续使用 `tsx` / PM2 等，按部署环境选择）。
- 前端生产构建：`cd frontend && pnpm build`，产物在 `frontend/dist`。

## 部署提示

### 前端

```bash
cd frontend
pnpm build
```

将 `dist` 部署到静态托管或反向代理到网关。

### 后端

配置好 `.env` 与数据库后，使用进程管理器运行 Node 进程（示例：在具备编译产物或 `tsx` 的前提下由 PM2 托管）。生产环境务必设置强随机 **`JWT_SECRET`**，并按需配置 **`PUBLIC_ORIGIN`** 以便头像与附件 URL 正确。

## 许可证

ISC

## 贡献

欢迎提交 Issue 和 Pull Request。

## 联系方式

如有问题，请联系项目维护者。