docs(README): 更新项目文档并添加部署指南

- 在 README.md 中添加了详细的项目结构、快速开始、使用指南、开发指南等内容 - 新增生产环境部署步骤，包括前端和后端的构建
2025-08-06 16:06:35 +08:00
parent 67f189995e
commit 8cdba1c0e6
5 changed files with 261 additions and 13 deletions
--- 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) 文件。
--- a/docker/caddy/Caddyfile
+++ b/docker/caddy/Caddyfile
@@ -0,0 +1,10 @@
+
+主配置文件，在/config目录
+
+{
+    # 全局选项：可关掉自动 HTTPS（测试环境）
+    # auto_https off
+
+}
+# 自动引入子配置
+import sites-enabled/*.caddy
--- a/docker/caddy/biji-houdaun.caddy
+++ 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"
+    }
+
+}
--- a/docker/caddy/biji-qianduan.caddy
+++ 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
+
+
+    # 也可以直接在这里反向代理后端
+
+}
--- a/docker/docker-compose.yml
+++ 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