diff --git a/README.md b/README.md index af094a2..2c6e831 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,33 @@ # 笔记应用 (Biji App) -这是一个功能完善的全栈笔记应用程序，采用前后端分离架构。前端使用 Vue 3 构建，后端使用 Spring Boot 3 实现。 +![License](https://img.shields.io/badge/license-MIT-blue.svg) +![Java](https://img.shields.io/badge/Java-17-orange.svg) +![Vue](https://img.shields.io/badge/Vue-3-green.svg) +![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.0-brightgreen.svg) + +一个功能完善的全栈笔记应用程序，采用前后端分离架构设计。前端使用 Vue 3 构建，后端基于 Spring Boot 3 实现，为用户提供简洁高效的笔记管理体验。 + +## 📋 目录 + +- [✨ 功能特性](#-功能特性) +- [🛠️ 技术栈](#️-技术栈) +- [📂 项目结构](#-项目结构) +- [🚀 快速开始](#-快速开始) +- [📖 使用指南](#-使用指南) +- [🔧 开发指南](#-开发指南) +- [🤝 贡献指南](#-贡献指南) +- [📄 许可证](#-许可证) ## ✨ 功能特性 (Features) -* **用户认证**: 支持用户注册、登录和 JWT (JSON Web Token) 认证。 -* **Markdown 笔记**: 提供功能强大的 Markdown 编辑器，支持实时预览和丰富的格式化选项。 -* **图片管理**: 支持在笔记中上传、插入和管理图片。 -* **笔记组织**: 用户可以创建分组 (Categories/Groups) 来管理和组织笔记。 -* **回收站**: 提供回收站功能，可以恢复被误删除的笔记或分组。 -* **系统设置**: 提供基本的系统配置功能。 +* **用户认证**: 支持用户注册、登录和 JWT (JSON Web Token) 认证，保障账户安全。 +* **Markdown 笔记**: 提供功能强大的 Markdown 编辑器，支持实时预览、代码高亮、数学公式和丰富的格式化选项。 +* **图片管理**: 支持在笔记中上传、插入和管理图片，提供图片预览和删除功能。 +* **笔记组织**: 用户可以创建分组 (Categories/Groups) 来管理和组织笔记，支持多层级分类。 +* **回收站**: 提供回收站功能，可以恢复被误删除的笔记或分组，避免数据丢失。 +* **系统设置**: 提供基本的系统配置功能，包括主题切换、语言选择等个性化设置。 +* **响应式设计**: 适配桌面和移动设备，提供一致的用户体验。 +* **数据持久化**: 使用 SQLite 数据库存储用户数据，无需额外配置数据库服务。 ## 🛠️ 技术栈 (Tech Stack) @@ -25,13 +43,14 @@ ### 前端 (Frontend - `biji-qianduan`) -* **框架 (Framework)**: Vue 3 +* **框架 (Framework)**: Vue 3 (Composition API) * **构建工具 (Build Tool)**: Vite * **UI 库 (UI Library)**: Element Plus * **状态管理 (State Management)**: Pinia -* **路由 (Routing)**: Vue Router +* **路由 (Routing)**: Vue Router 4 * **Markdown 编辑器**: Vditor / @kangc/v-md-editor * **HTTP 客户端 (HTTP Client)**: Axios (封装在 `src/utils/axios.js` 中) +* **样式处理**: SCSS ## 📂 项目结构 (Project Structure) @@ -55,6 +74,7 @@ │ │ ├── components/ # Vue 组件 │ │ ├── router/ # 路由配置 │ │ ├── stores/ # Pinia 状态管理 +│ │ ├── views/ # 页面视图 │ │ └── utils/ # 工具函数 │ └── package.json # NPM 依赖配置 │ @@ -68,10 +88,10 @@ ### 环境要求 -* JDK 17 -* Maven 3.x -* Node.js 18+ -* pnpm (或 npm/yarn) +* **Java**: JDK 17 或更高版本 +* **构建工具**: Maven 3.6+ 或 Gradle 7.0+ +* **Node.js**: 18.0 或更高版本 +* **包管理器**: pnpm 8.0+ (推荐) 或 npm/yarn ### 后端启动 @@ -82,6 +102,7 @@ ```bash mvn spring-boot:run ``` +5. **验证**: 访问 `http://localhost:8080/doc.html` 查看 API 文档。 ### 前端启动 @@ -98,3 +119,108 @@ pnpm dev ``` 4. **访问应用**: 在浏览器中打开 `http://localhost:5173` (或其他 Vite 指定的端口)。 + +### 生产环境部署 + +> 我使用的部署方式： +> 1、后端部署，使用docker部署后端，并且使用caddy作为反向代理，返代后端 +> 2、在前端，cd biji-qianduan，在.env.production文件添加返代后端的接口地址，之后打包 +> 3、在caddy部署前端打包好的前端文件 + +1. **构建前端**: + 在.env.production文件添加自己后端的接口地址 + ```bash + cd biji-qianduan + pnpm run build:frontend + ``` +2. **构建后端**: + ```bash + cd biji-houdaun + mvn clean package -P prod -D maven.test.skip=true -am docker:build + ``` +3. **运行**: 使用生成的 JAR 文件运行应用: + ```bash + java -jar target/biji-houdaun-0.0.1-SNAPSHOT.jar + ``` + +## 📖 使用指南 + +### 基本功能 + +1. **注册/登录**: 访问应用首页，点击"注册"创建新账户，或使用已有账户登录。 +2. **创建笔记**: 登录后，点击"新建笔记"按钮，输入标题和内容。 +3. **编辑笔记**: 使用 Markdown 语法编辑笔记，支持实时预览。 +4. **管理分组**: 创建、编辑和删除笔记分组，方便组织笔记。 +5. **上传图片**: 在笔记编辑器中点击图片按钮，上传并插入图片。 +6. **回收站**: 删除的笔记和分组会进入回收站，可在30天内恢复。 + +### 高级功能 + +1. **Markdown 语法**: + - 标题: `# 一级标题`, `## 二级标题` + - 列表: `- 无序列表`, `1. 有序列表` + - 代码: `代码` 或 ```代码块``` + - 链接: `[文本](URL)` + - 图片: `![描述](图片URL)` + +2. **快捷键**: + - 保存笔记: `Ctrl + S` + - 加粗: `Ctrl + B` + - 斜体: `Ctrl + I` + - 撤销: `Ctrl + Z` + - 重做: `Ctrl + Y` + +## 🔧 开发指南 + +### 后端开发 + +1. **添加新 API**: + - 在 `controller` 包中创建新的控制器类 + - 在 `service` 包中实现业务逻辑 + - 在 `mapper` 包中定义数据访问接口 + - 在 `entity` 包中创建数据实体类 + +2. **数据库变更**: + - 修改 `sql` 目录下的数据库脚本 + - 更新对应的实体类和映射文件 + +### 前端开发 + +1. **添加新页面**: + - 在 `src/views` 目录下创建新组件 + - 在 `src/router` 中添加路由配置 + - 在 `src/api` 中添加相关的 API 请求方法 + +2. **添加新组件**: + - 在 `src/components` 目录下创建新组件 + - 在需要的地方导入并使用组件 + +3. **状态管理**: + - 在 `src/stores` 目录下创建新的 store + - 在组件中使用 `useStore` 访问状态 + +## 🤝 贡献指南 + +我们欢迎所有形式的贡献！如果您想为 Biji App 做出贡献，请遵循以下步骤： + +1. **Fork 项目**: 点击页面右上角的 Fork 按钮。 +2. **克隆仓库**: `git clone https://github.com/yourusername/biji-app.git` +3. **创建分支**: `git checkout -b feature/your-feature-name` +4. **提交更改**: + ```bash + git add . + git commit -m "Add your feature" + ``` +5. **推送分支**: `git push origin feature/your-feature-name` +6. **提交 Pull Request**: 在 GitHub 上创建 Pull Request。 + +### 开发规范 + +- 遵循项目中现有的代码风格 +- 提交信息应清晰明了，使用英文 +- 每个功能或修复应提交单独的 Pull Request +- 确保所有测试通过后再提交 + +## 📄 许可证 + +本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。 diff --git a/docker/caddy/Caddyfile b/docker/caddy/Caddyfile new file mode 100644 index 0000000..a0b81b0 --- /dev/null +++ b/docker/caddy/Caddyfile @@ -0,0 +1,10 @@ + +主配置文件，在/config目录 + +{ + # 全局选项：可关掉自动 HTTPS（测试环境） + # auto_https off + +} +# 自动引入子配置 +import sites-enabled/*.caddy \ No newline at end of file diff --git a/docker/caddy/biji-houdaun.caddy b/docker/caddy/biji-houdaun.caddy new file mode 100644 index 0000000..6d7fec0 --- /dev/null +++ b/docker/caddy/biji-houdaun.caddy @@ -0,0 +1,56 @@ + +反向代理，后端的反向代理，在/config/caddy.d目录下 + + +xxx.com { # 你的域名 + + # 处理预检请求 + @options method OPTIONS + handle @options { + header Access-Control-Allow-Origin "*" + header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" + header Access-Control-Allow-Headers "Content-Type, Authorization" + header Access-Control-Allow-Credentials "true" + header Access-Control-Max-Age "3600" + respond "" 204 + } + + # 为实际请求添加CORS头部 + header { + Access-Control-Allow-Origin "*" + Access-Control-Allow-Credentials "true" + } + + + + # 反向代理到Gitea服务器的IP和端口 + reverse_proxy http://ip:8084 { #若是后端与caddy在同一个网络，可以直接指定后端的容器名 + + + # 移除后端返回的 CORS 头（防止冲突） + header_down -Access-Control-Allow-Origin + header_down -Access-Control-Allow-Methods + header_down -Access-Control-Allow-Headers + + + + # 传递原始客户端信息 + header_up X-Real-IP {remote_host} + header_up X-Forwarded-For {remote} + header_up X-Forwarded-Proto {scheme} + + # 保持连接活跃（提高性能） + transport http { + keepalive 30s + } + } + + + # 添加安全头部 + header { + X-Frame-Options "DENY" + X-Content-Type-Options "nosniff" + Referrer-Policy "no-referrer-when-downgrade" + } + +} \ No newline at end of file diff --git a/docker/caddy/biji-qianduan.caddy b/docker/caddy/biji-qianduan.caddy new file mode 100644 index 0000000..380ffcc --- /dev/null +++ b/docker/caddy/biji-qianduan.caddy @@ -0,0 +1,24 @@ +前端页面部署，在/config/caddy.d目录下 + +xxx.com { # 你的前端域名 + root * /usr/share/caddy + + # 静态资源：JS、CSS、图片等缓存 1 年 + @static { + path *.js *.css *.png *.jpg *.jpeg *.gif *.ico *.svg *.woff *.woff2 + } + header @static Cache-Control "public, max-age=259200, immutable" + + # HTML 文件不缓存 + @html { + path *.html + } + header @html Cache-Control "no-cache, no-store, must-revalidate" + + # 静态文件需要的 + file_server + + + # 也可以直接在这里反向代理后端 + +} diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 0000000..9ef5ec8 --- /dev/null +++ b/docker/docker-compose.yml @@ -0,0 +1,32 @@ +version: "3.9" + +services: + caddy: + image: caddy:2-alpine + container_name: caddy-rp + restart: unless-stopped + ports: + - "80:80" + - "443:443" + environment: + TZ: "Asia/Shanghai" # 设置时区为上海时区 + volumes: + # 主配置 + - /docker/caddy/volume/config/Caddyfile:/etc/caddy/Caddyfile + # 子配置目录 + - /docker/caddy/volume/config/caddy.d:/etc/caddy/sites-enabled + # 站点文件目录 + - /docker/caddy/volume/html:/usr/share/caddy + # 证书持久化 + - /docker/caddy/volume/caddy_data:/data + - /docker/caddy/volume/caddy_config:/config + + + mybiji: + image: biji-houdaun:0.0.1-SNAPSHOT + container_name: mybiji + restart: unless-stopped + ports: + - "8084:8084" + volumes: + - /docker/biji-houduan/data:/data