mokeeText/docs

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 用户。

# 启动后端
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 头模拟用户

// 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号