346 lines
13 KiB
Markdown
346 lines
13 KiB
Markdown
# MoKeeText 项目文档
|
||
|
||
## 概述
|
||
|
||
**MoKeeText** 是一个 Web 端富文本笔记管理应用，同时具备网站账号密码管理功能，集成 Mokee Gateway 统一登录网关。
|
||
|
||
### 核心功能
|
||
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| 📝 **笔记编辑** | 基于 Tiptap 的增强型富文本编辑器，支持文字颜色、图片粘贴/拖拽上传、表格、代码高亮、任务列表 |
|
||
| 🔐 **网站管理** | 按文件夹分类管理网站及其登录账号密码 |
|
||
| 🔗 **分享链接** | 笔记可生成分享链接，支持 7天/30天/1年/永久 四种有效期 |
|
||
| 📥 **智能导入** | 自动解析粘贴的网站账号信息，一键导入 |
|
||
| 🖼️ **图片上传** | 粘贴/拖拽图片自动上传，存数据库 LONGBLOB，点击全屏预览 |
|
||
| 👤 **统一登录** | 接入 Mokee Gateway，通过网关转发用户身份，支持 API 级数据隔离 |
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 | 版本 |
|
||
|----|------|------|
|
||
| 后端框架 | FastAPI (Python) | ≥0.115 |
|
||
| 服务器 | Uvicorn | ≥0.30 |
|
||
| ORM | SQLAlchemy | ≥2.0 |
|
||
| 数据库 | MySQL | 8.0 |
|
||
| 前端框架 | Vue 3 + Vite | 3.5 / 8.x |
|
||
| 路由 | Vue Router | 4.6 |
|
||
| 编辑器 | Tiptap | 3.27 |
|
||
| 代码高亮 | highlight.js (lowlight) | - |
|
||
| HTTP 客户端 | Axios（生产）/ fetch（本地开发） | 1.18 |
|
||
| 容器化 | Docker + Docker Compose | - |
|
||
| Web 服务器 | Nginx (Alpine) | - |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
mokeeText/
|
||
├── backend/ # 后端 — FastAPI 应用
|
||
│ ├── app.py # 入口：CORS、中间件、路由注册
|
||
│ ├── models.py # SQLAlchemy 数据模型（6 张表）
|
||
│ ├── config.py # 数据库连接配置（环境变量）
|
||
│ ├── logger.py # 日志系统（按天轮转，保留 30 天）
|
||
│ ├── init_db.py # 建表脚本
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── Dockerfile # 后端 Docker 镜像
|
||
│ ├── .dockerignore
|
||
│ ├── routes/ # API 路由
|
||
│ │ ├── notes.py # 笔记 CRUD + 分享 + 移动
|
||
│ │ ├── websites.py # 网站/账号/文件夹 CRUD + 排序
|
||
│ │ ├── import_api.py # 智能导入解析
|
||
│ │ ├── upload.py # 图片上传/读取
|
||
│ │ └── share.py # 公开分享查看页
|
||
│ └── middleware/
|
||
│ └── user_context.py # 网关用户上下文中间件
|
||
│
|
||
├── frontend/ # 前端 — Vue 3 SPA
|
||
│ ├── index.html # Vite 入口 HTML
|
||
│ ├── package.json # 前端依赖
|
||
│ ├── vite.config.js # Vite 构建配置
|
||
│ ├── nginx.conf # Nginx 配置
|
||
│ ├── Dockerfile.frontend # 前端 Nginx Docker 镜像
|
||
│ ├── .dockerignore
|
||
│ ├── .env / .env.production # 环境变量
|
||
│ ├── src/
|
||
│ │ ├── main.js # Vue 入口 → 挂载 Router + v-permission
|
||
│ │ ├── App.vue # 根组件：左导航 + 顶栏 + UserChip + 底栏
|
||
│ │ ├── router.js # Vue Router 配置 + 路由守卫
|
||
│ │ ├── utils/request.js # Axios 实例 + 拦截器
|
||
│ │ ├── composables/useApi.js # 双模式 API（dev fetch / prod axios）
|
||
│ │ ├── directives/permission.js # v-permission 按钮权限指令
|
||
│ │ ├── views/
|
||
│ │ │ ├── NotesView.vue # 笔记：文件夹侧边栏 + 列表 + 编辑器
|
||
│ │ │ ├── WebsitesView.vue # 网站管理：列表 + CRUD 弹窗
|
||
│ │ │ └── SharesView.vue # 分享管理
|
||
│ │ └── components/
|
||
│ │ ├── NoteEditor.vue # Tiptap 增强编辑器
|
||
│ │ ├── Modal.vue # 通用弹窗组件
|
||
│ │ ├── ConfirmModal.vue
|
||
│ │ └── PromptModal.vue
|
||
│ └── static/
|
||
│ ├── dist/ # Vite 构建产物（Nginx 托管）
|
||
│ ├── js/vendor/ # Tiptap UMD 扩展文件
|
||
│ ├── css/
|
||
│ └── uploads/
|
||
│
|
||
├── deploy/ # 部署
|
||
│ ├── docker-compose.yml # 双容器编排
|
||
│ ├── deploy.py # 日常部署脚本
|
||
│ └── migrate_server.py # 服务器迁移脚本（一次性）
|
||
│
|
||
├── docs/ # 文档
|
||
│ ├── README.md # 本文档
|
||
│ ├── DEPLOY.md # 部署文档
|
||
│ └── superpowers/ # 设计规范 + 实施计划
|
||
│
|
||
└── memory/ # 会话记忆
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### ER 图
|
||
|
||
```
|
||
folders ──┬── notes ──┬── note_tags ── tags
|
||
│
|
||
└── websites ── accounts
|
||
|
||
uploads（独立，图片存 DB）
|
||
```
|
||
|
||
### 表结构
|
||
|
||
#### folders — 文件夹（笔记和网站共用）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| name | VARCHAR(100) | 文件夹名称 |
|
||
| type | ENUM('note','website') | 类型 |
|
||
| parent_id | INT FK→folders.id | 父文件夹（树形结构） |
|
||
| sort_order | INT | 排序 |
|
||
| created_by | VARCHAR(100) | 创建者账号 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
|
||
#### notes — 笔记
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| title | VARCHAR(500) | 标题 |
|
||
| content | TEXT | Tiptap 输出的 HTML |
|
||
| folder_id | INT FK→folders.id | 所属文件夹 |
|
||
| created_by | VARCHAR(100) | 创建者 |
|
||
| updated_by | VARCHAR(100) | 最后修改者 |
|
||
| share_token | VARCHAR(64) UNIQUE | 分享令牌 |
|
||
| share_expires_at | DATETIME | 分享过期时间 |
|
||
| created_at / updated_at | DATETIME | 时间戳 |
|
||
|
||
#### tags — 标签
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| name | VARCHAR(50) UNIQUE | 标签名 |
|
||
| color | VARCHAR(20) | 颜色 |
|
||
|
||
#### note_tags — 笔记-标签关联（多对多）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| note_id | INT FK | 笔记 ID |
|
||
| tag_id | INT FK | 标签 ID |
|
||
|
||
#### websites — 网站
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| name | VARCHAR(200) | 网站名称 |
|
||
| url | VARCHAR(500) | 网址 |
|
||
| folder_id | INT FK | 所属文件夹 |
|
||
| created_by / updated_by | VARCHAR(100) | 操作者 |
|
||
| created_at / updated_at | DATETIME | 时间戳 |
|
||
|
||
#### accounts — 账号
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| website_id | INT FK | 所属网站 |
|
||
| username | VARCHAR(500) | 用户名 |
|
||
| password | VARCHAR(500) | 密码（明文，待加密） |
|
||
| remark | TEXT | 备注 |
|
||
| sort_order | INT | 排序 |
|
||
| created_by / updated_by | VARCHAR(100) | 操作者 |
|
||
|
||
#### uploads — 上传文件
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT PK | 自增主键 |
|
||
| filename | VARCHAR(255) | 原始文件名 |
|
||
| content_type | VARCHAR(100) | MIME 类型 |
|
||
| data | LONGBLOB | 二进制数据（最大 4GB） |
|
||
| size | INT | 文件大小（字节） |
|
||
| created_by | VARCHAR(100) | 上传者 |
|
||
| created_at | DATETIME | 上传时间 |
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
所有接口均以 `/api/` 为前缀。除分享页和图片读取外，所有操作需要网关注入用户身份。
|
||
|
||
### 笔记
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/notes` | 获取笔记列表（支持 `?folder_id=` 筛选） |
|
||
| POST | `/api/notes` | 创建笔记 |
|
||
| GET | `/api/notes/{id}` | 获取笔记详情 |
|
||
| PUT | `/api/notes/{id}` | 修改笔记 |
|
||
| DELETE | `/api/notes/{id}` | 删除笔记 |
|
||
| PUT | `/api/notes/{id}/move` | 移动笔记到文件夹 |
|
||
| POST | `/api/notes/{id}/share` | 生成分享链接 |
|
||
|
||
### 文件夹
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/folders` | 获取文件夹列表（支持 `?type=note\|website`） |
|
||
| POST | `/api/folders` | 创建文件夹 |
|
||
| PUT | `/api/folders/{id}` | 重命名文件夹 |
|
||
| DELETE | `/api/folders/{id}` | 删除文件夹 |
|
||
|
||
### 网站与账号
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/websites` | 获取网站列表（支持 `?folder_id=`） |
|
||
| POST | `/api/websites` | 创建网站 |
|
||
| PUT | `/api/websites/{id}` | 修改网站 |
|
||
| DELETE | `/api/websites/{id}` | 删除网站 |
|
||
| GET | `/api/websites/{id}/accounts` | 获取账号列表 |
|
||
| POST | `/api/websites/{id}/accounts` | 创建账号 |
|
||
| PUT | `/api/accounts/{id}` | 修改账号 |
|
||
| DELETE | `/api/accounts/{id}` | 删除账号 |
|
||
| PUT | `/api/accounts/sort` | 账号排序 |
|
||
|
||
### 文件
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/upload/image` | 上传图片（网关鉴权） |
|
||
| GET | `/api/file/{id}` | 读取图片（公开，无需鉴权） |
|
||
|
||
### 分享
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/share/{token}` | 公开查看分享的笔记（不走网关） |
|
||
| GET | `/api/shares` | 获取我的分享列表 |
|
||
| DELETE | `/api/shares/{note_id}` | 取消分享 |
|
||
|
||
### 智能导入
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/import/parse` | 解析粘贴的文本，提取网站+账号信息 |
|
||
|
||
---
|
||
|
||
## 认证架构
|
||
|
||
```
|
||
┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
|
||
│ 浏览器 │ ──→ │ 统一登录页 │ ──→ │ Mokee │ ──→ │ FastAPI │
|
||
│ │ │ login.user. │ │ Gateway │ │ 后端 │
|
||
│ │ │ zgitm.com │ │ gw.server. │ │ :4006 │
|
||
│ │ │ │ │ zgitm.com │ │ │
|
||
└─────────┘ └──────────────┘ └──────┬───────┘ └──────────┘
|
||
│
|
||
注入 X-User-* 头
|
||
X-User-Id, X-User-Account,
|
||
X-User-Roles, X-System-Code ...
|
||
```
|
||
|
||
### 请求流程
|
||
|
||
1. **用户访问** → 前端路由守卫检查 Cookie 中是否有 `token`
|
||
2. **无 Token** → 重定向到 `login.user.zgitm.com` 统一登录
|
||
3. **登录成功** → 网关设置 Cookie，用户回到应用
|
||
4. **API 请求** → Axios 拦截器从 Cookie 取 Token 放入 Authorization 头
|
||
5. **网关转发** → 验证 Token 后注入 `X-User-*` 系列请求头
|
||
6. **后端中间件** → `UserContextMiddleware` 提取请求头存入 `request.state.user`
|
||
7. **业务路由** → 通过 `UserContext.get_user_id()` 获取当前用户，按 `created_by` 过滤数据
|
||
|
||
### 本地开发模式
|
||
|
||
设置环境变量 `DEV_MODE=true` 或添加请求头 `X-Dev-Mock-User`，后端绕过网关认证，使用默认 admin 用户。
|
||
|
||
```bash
|
||
# 启动后端
|
||
cd backend
|
||
DEV_MODE=true uvicorn app:app --port 4006
|
||
|
||
# 启动前端（另一个终端）
|
||
cd frontend
|
||
npx vite
|
||
```
|
||
|
||
---
|
||
|
||
## 前端架构
|
||
|
||
### 路由
|
||
|
||
| 路径 | 组件 | 说明 |
|
||
|------|------|------|
|
||
| `/` | → 重定向 | 默认到 /notes |
|
||
| `/notes` | NotesView | 笔记编辑器（文件夹 + 列表 + 编辑器） |
|
||
| `/websites` | WebsitesView | 网站账号管理 |
|
||
| `/shares` | SharesView | 分享链接管理 |
|
||
|
||
### API 调用模式
|
||
|
||
前端通过 `useApi()` 组合式函数发起请求，自动适配环境：
|
||
|
||
- **生产环境**：使用 Axios 实例，拦截器自动携带 Token → 请求走网关
|
||
- **本地开发**：使用 fetch，添加 `X-Dev-Mock-User` 头模拟用户
|
||
|
||
```js
|
||
// composables/useApi.js
|
||
import { useApi } from '@/composables/useApi'
|
||
const { get, post, put, del } = useApi()
|
||
const notes = await get('/api/notes')
|
||
```
|
||
|
||
### 图片处理
|
||
|
||
- **上传**：粘贴/拖拽 → `POST /api/upload/image`（走网关，带 Token）
|
||
- **显示**：`<img src="https://mokeetext.server.zgitm.com/api/file/{id}">`（走后端直连，公开读取）
|
||
- **预览**：点击图片 → 全屏灯箱，带关闭按钮
|
||
|
||
### UI 特性
|
||
|
||
- 左侧可收起导航栏（展开 "mokee编辑器"，收起 "M"）
|
||
- 文件夹侧边栏可收起
|
||
- 笔记列表 + 编辑器双栏布局
|
||
- Ctrl+S 保存，顶部 toast 提示
|
||
- 弹窗全部为 Vue 组件（非浏览器 alert/confirm）
|
||
- 移动端响应式适配（768px 断点）
|
||
- 顶栏右侧「切换系统」按钮 → 跳转网关系统选择页
|
||
|
||
---
|
||
|
||
## 生产环境
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 服务器 | 101.132.183.138 (腾讯云) |
|
||
| 前端地址 | https://mokeetext.zgitm.com |
|
||
| 后端地址 | https://mokeetext.server.zgitm.com |
|
||
| 数据库 | MySQL 10.20.1.122:3306/mokeetext |
|
||
| 日志路径 | /data/mokee/mokeetext/logs（按天轮转，保留 30 天） |
|
||
| ICP 备案 | 湘ICP备19021539号 |
|