# QuickNote

**Repository Path**: lianglong666/quick-note

## Basic Information

- **Project Name**: QuickNote
- **Description**: 网页版快速便签，支持置顶，共享，多用户数据隔离。支持图片，代码，表格等多种格式。可快速查看，，创建便签。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickNote · 快速便签

> 卡片式便签 Web 应用,首格固定"新建"。支持富文本(文字大小)、图片(点击上传 / **拖拽上传 / 粘贴上传**)、代码块、表格、用户登录、主题配置。
> 技术栈:**Java 17 + Spring Boot 3.3 + MyBatis-Plus 3.5 + MySQL 5.7/8 + React 18 + Vite 5 + TypeScript + TipTap 2**

---

## 目录结构

```
QuickNote/
├── backend/                # Spring Boot 后端
│   ├── pom.xml
│   ├── maven-settings.xml  # 项目级 Maven 镜像(阿里云)
│   └── src/main/
│       ├── java/com/quicknote/
│       │   ├── QuickNoteApplication.java
│       │   ├── common/      # R、BizException、全局异常、UserContext
│       │   ├── config/      # WebMvc (CORS) + MyBatis-Plus 拦截器 + AuthInterceptor
│       │   ├── controller/  # NoteController、ImageController、AuthController、ThemeController
│       │   ├── dto/         # NoteSaveRequest、NoteVO、ImageUploadVO、UserLoginRequest 等
│       │   ├── entity/      # Note、NoteImage、User
│       │   ├── mapper/      # NoteMapper、NoteImageMapper、UserMapper
│       │   └── service/     # NoteService、ImageService、UserService
│       └── resources/
│           ├── application.yml
│           ├── application-dev.yml
│           └── logback-spring.xml  # 日志配置(控制台 + 文件 + LongLog 远程推送)
├── frontend/               # React + Vite 前端
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── .npmrc              # 走 npmmirror(国内镜像)
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── api/index.ts
│       ├── store/          # auth.ts、notes.ts、theme.ts、toast.ts
│       ├── editor/         # TipTap 编辑器 + 工具栏 + 字号扩展
│       ├── components/     # NoteCard、NoteEditor、NewNoteCard、AuthGate 等
│       └── styles/global.css
├── sql/                    # 数据库脚本
│   ├── schema.sql
│   ├── upgrade-20260609-add-user.sql
│   ├── upgrade-20260609-add-shared.sql
│   └── upgrade-20260611-add-theme.sql
├── deploy/
│   └── nginx-quicknote.conf
├── docker-compose.yml      # 一键起 MySQL
├── REQUIREMENTS.md         # 需求文档(v0.2)
├── appender-接入指南.md     # LongLog Appender 接入指南
└── README.md
```

---

## 快速开始

### 0. 环境要求

| 组件 | 版本 | 说明 |
| --- | --- | --- |
| JDK | 17+ | 后端运行 |
| Maven | 3.8+ | 项目级 `maven-settings.xml` 已配好阿里云镜像 |
| Node | 18+ | 前端构建 |
| MySQL | 5.7 / 8.x | 本地装或通过 `docker-compose.yml` 启动 |

### 1. 启动 MySQL

**方案 A: Docker(推荐)**

```bash
cd D:\Project10\QuickNote
docker compose up -d mysql
```

自动起 `mysql:5.7` 容器,密码 `123456`,自动建库建表。

**方案 B:已有 MySQL 实例**

```bash
mysql -uroot -p < sql/schema.sql
```

**方案 C:远端 MySQL**

`application-dev.yml` 已配 `192.168.0.23:3306`,账号 `root` / 密码 `123456`,库 `quicknote`。

### 2. 安装 LongLog Appender(前置条件)

后端依赖 `longlog-appender-jdk8` 推送日志到 LongLog 平台,需先从 LongLog 项目安装到本地 Maven 仓库:

```bash
cd <LongLog 项目>/longlog-appender
mvn clean install -DskipTests
```

> 如果不接入日志平台,可以在 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 中注释掉 `<appender-ref ref="LONGLOG"/>` 那一行。

### 3. 启动后端

```bash
cd backend
mvn -s ./maven-settings.xml spring-boot:run
```

默认端口 **9500**,接口前缀 `/api/v1`。

### 4. 启动前端

```bash
cd frontend
npm install
npm run dev
```

默认端口 **5173**,浏览器访问 <http://localhost:5173>,Vite 已把 `/api/*` 代理到 `http://localhost:9500`。

**局域网内通过 IP 访问**(手机/其他电脑):

- Vite dev server 默认绑定 `0.0.0.0`,启动后日志会输出 `Network: http://192.168.x.x:5173/`
- 后端 Spring Boot 绑 `0.0.0.0:9500`,局域网内 `http://<你的IP>:9500` 可访问
- 手机/同网段设备直接访问 `http://<你的IP>:5173` 即可
- **注意:Windows 防火墙首次可能弹出"是否允许 Java / Node.js 访问网络",要点"允许"**

---

## 配置说明

### 后端 `application.yml`

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| server.port | 9500 | 后端端口 |
| quicknote.upload.dir | `D:/Project10/QuickNote/backend/uploads` | 图片本地存储目录(可通过 `UPLOAD_DIR` 环境变量覆盖) |
| spring.profiles.active | dev | 当前激活的 profile |

### 后端 `application-dev.yml`

| 配置项 | 值 |
| --- | --- |
| 数据库地址 | `jdbc:mysql://192.168.0.23:3306/quicknote` |
| 数据库账号 | `root` |
| 数据库密码 | `123456` |

### 前端 `vite.config.ts`

- 代理 `/api` → `http://192.168.0.113:9500`(局域网内其他设备可直接访问)

---

## 日志接入 (LongLog)

后端已集成 LongLog Appender,日志会同时输出到:

1. **控制台** — 启动后终端可见
2. **滚动文件** — `./logs/quicknote.log`,按天切割,保留 7 天,单文件最大 50MB
3. **LongLog 平台** — 通过 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 配置推送

### 配置方式

日志推送配置全部写在 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 中:

| 参数 | 当前值 |
| --- | --- |
| endpoint | `http://192.168.0.113:8080/api/logs/ingest` |
| projectId | 6 |
| logSourceName | `quicknote-backend` |
| batchSize | 100 |
| flushInterval | 3000ms |
| maxQueueSize | 10000 |
| maxRetries | 2 |

### 关闭远程推送

注释掉 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 第 52 行即可:

```xml
<!-- <appender-ref ref="LONGLOG"/> -->
```

### 安全提醒

`accessKeyId` 和 `secretKey` 目前直接写在 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 中。如果需要推送到远程代码仓库,建议:

1. 创建 `application-local.yml` 文件(已在 `.gitignore` 中排除)
2. 将凭据移到该文件中
3. 在 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 中通过 `<springProperty>` 引用

---

## API 一览

### 鉴权接口

| Method | Path | 说明 |
| --- | --- | --- |
| POST | `/api/v1/auth/register` | 用户注册(需 username/password/email) |
| POST | `/api/v1/auth/login` | 用户登录(需 username/password) |
| POST | `/api/v1/auth/logout` | 用户登出 |
| GET | `/api/v1/auth/me` | 获取当前登录用户信息 |

### 便签接口

| Method | Path | 说明 |
| --- | --- | --- |
| GET | `/api/v1/notes?q=xxx&archived=true/false` | 列表查询(可选关键字 + 归档过滤) |
| GET | `/api/v1/notes/page?q=xxx&page=1&size=20` | 分页查询 |
| GET | `/api/v1/notes/{id}` | 详情 |
| POST | `/api/v1/notes` | 新建 |
| PUT | `/api/v1/notes/{id}` | 更新 |
| PATCH | `/api/v1/notes/{id}/sort?sortOrder=N` | 更新排序 |
| DELETE | `/api/v1/notes/{id}` | 删除 |

### 图片接口

| Method | Path | 说明 |
| --- | --- | --- |
| POST | `/api/v1/images/upload` | 上传图片(multipart/form-data) |
| GET | `/api/v1/images/raw/{yyyyMM}/{uuid}.{ext}` | 读取图片 |
| DELETE | `/api/v1/images/{id}` | 删除图片 |

### 主题接口

| Method | Path | 说明 |
| --- | --- | --- |
| GET | `/api/v1/theme` | 获取当前用户主题配置 |
| PUT | `/api/v1/theme` | 更新主题配置(背景图/透明度等) |

---

## 核心功能

| 能力 | 说明 |
| --- | --- |
| 卡片 CRUD | 新建/编辑/删除/排序,首格固定为"+ 新建" |
| 用户系统 | 注册/登录/登出,Session 保持登录态 |
| 文字大小 | 工具栏 XS/S/M/L/XL(12/14/16/20/28 px),作用于选区 |
| 图片 | 上传/粘贴,落本地磁盘,数据库只存路径 |
| 代码块 | TipTap `codeBlock` + lowlight,支持 JS/TS/Java/Python/Go/SQL 等高亮 |
| 表格 | 工具栏一键插入 3×3 表格,可增删行列 |
| 颜色 | 6 种背景色区分卡片 |
| 主题 | 自定义背景图、透明度、缩放偏移 |
| 搜索 | 顶栏搜标题或正文(纯文本 `LIKE`) |
| 日志推送 | 异步批量推送到 LongLog 平台 |

---

## 待办(未实现)

- [ ] 拖拽排序(dnd-kit 已装,UI 待接)
- [ ] 全文搜索(当前 `LIKE`,需优化)
- [ ] 标签 / 归档
- [ ] 对象存储(OSS/MinIO)替代本地磁盘
- [ ] i18n

---

## 常见问题

**Q: 后端启动报错"Communications link failure"?**

A: MySQL 没启动,或端口/密码不对。`docker ps` 看下容器在不在。

**Q: 前端 npm install 慢?**

A: `.npmrc` 已配 `registry.npmmirror.com`(淘宝镜像)。

**Q: Maven 下载依赖慢或失败?**

A: 用 `mvn -s ./maven-settings.xml` 强制走项目级阿里云镜像。

**Q: 编译报错找不到 `org.zhida.appender.LongLogAppender`?**

A: 需要先从 LongLog 项目安装 appender:
```bash
cd <LongLog 项目>/longlog-appender
mvn clean install -DskipTests
```
或者注释掉 [logback-spring.xml](file:///d:/Project10/QuickNote/backend/src/main/resources/logback-spring.xml) 中的 LONGLOG appender-ref。

**Q: 日志推送到 LongLog 失败?**

A: 检查应用日志中是否有 `[LongLog]` 相关的 ERROR 输出。常见原因:
- endpoint 地址不可达
- accessKeyId / secretKey 错误
- LongLog 服务未启动