From 690aae3577c573f4d5c42ada5f2532a63eb3d7ea Mon Sep 17 00:00:00 2001 From: Palm Civet Date: Wed, 3 Sep 2025 14:14:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=20contributing=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 204 +++++++++++------- .../contributing}/backend_img.png | Bin .../contributing}/backend_img_2.png | Bin .../contributing}/backend_img_3.png | Bin .../contributing}/backend_img_4.png | Bin .../contributing}/backend_img_5.png | Bin .../contributing}/backend_img_6.png | Bin .../contributing}/backend_img_7.png | Bin .../contributing}/fontend_img.png | Bin .../contributing}/github_img.png | Bin .../contributing}/github_img_2.png | Bin .../contributing}/resources_img.png | Bin backend/open-isle.env.example | 1 + docker/docker-compose.yaml | 41 ++++ 14 files changed, 173 insertions(+), 73 deletions(-) rename {contributing_img => assets/contributing}/backend_img.png (100%) rename {contributing_img => assets/contributing}/backend_img_2.png (100%) rename {contributing_img => assets/contributing}/backend_img_3.png (100%) rename {contributing_img => assets/contributing}/backend_img_4.png (100%) rename {contributing_img => assets/contributing}/backend_img_5.png (100%) rename {contributing_img => assets/contributing}/backend_img_6.png (100%) rename {contributing_img => assets/contributing}/backend_img_7.png (100%) rename {contributing_img => assets/contributing}/fontend_img.png (100%) rename {contributing_img => assets/contributing}/github_img.png (100%) rename {contributing_img => assets/contributing}/github_img_2.png (100%) rename {contributing_img => assets/contributing}/resources_img.png (100%) create mode 100644 docker/docker-compose.yaml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbdefccf7..e5cafb6ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,149 @@ -#### **⚠️注意：仅想修改前端的朋友可不用部署后端服务** +- [前置工作](#前置工作) +- [启动后端服务](#启动后端服务) + - [本地 IDEA](#本地-idea) + - [环境变量配置](#环境变量配置) + - [配置参数](#配置参数) + - [配置 MySQL](#配置-mysql) + - [Docker 环境](#docker-环境) + - [环境变量配置](#环境变量配置-1) + - [构建并启动镜像](#构建并启动镜像) +- [启动前端服务](#启动前端服务) + - [环境变量配置](#环境变量配置-2) + - [安装依赖和运行](#安装依赖和运行) +- [其他配置](#其他配置) -## 如何部署 +## 前置工作 -> Step1 先克隆仓库 +先克隆仓库： ```shell git clone https://github.com/nagisa77/OpenIsle.git cd OpenIsle ``` -> Step2 后端部署 +## 启动后端服务 -```shell -cd backend +启动后端服务有多种方式，选择一种即可。 + +> [!IMPORTANT] +> 仅想修改前端的朋友可不用部署后端服务。转到 [启动前端服务](#启动前端服务) 章节。 + +### 本地 IDEA + +IDEA 打开 `backend/` 文件夹。 + +#### 环境变量配置 + +1. 生成环境变量文件 + + ```shell + cp open-isle.env.example open-isle.env + ``` + + `open-isle.env.example` 是环境变量模板，`open-isle.env` 才是真正读取的内容 + +2. 修改环境变量，留下需要的，比如你要开发 Google 登录业务，就需要谷歌相关的变量，数据库是一定要的 + + ![环境变量](assets/contributing/backend_img_7.png) + +3. 应用环境文件，选择刚刚的 `open-isle.env` + +可以在 `open-isle.env` 按需填写个性化的配置，该文件不会被 Git 追踪。比如你想把服务跑在 `8082`（默认为 `8080`），那么直接改 `open-isle.env` 即可： + +```ini +SERVER_PORT=8082 ``` -以IDEA编辑器为例，IDEA打开backend文件夹。 +另一种方式是修改 `.properities` 文件（但不建议），位于 `src/main/application.properties`，该配置同样来源于 `open-isle.env`，但修改 `.properties` 文件会被 Git 追踪。 -- 设置VM Option，最好运行在其他端口，非8080，这里设置8081 -- 设置jdk版本为java 17 +![配置数据库](assets/contributing/backend_img_5.png) + +#### 配置参数 + +- 设置 JDK 版本为 java 17 +- 设置 VM Option，最好运行在其他端口，非 `8080`，这里设置 `8081` + + ```shell + -Dserver.port=8081 + ``` + +![配置1](assets/contributing/backend_img_3.png) + +![配置2](assets/contributing/backend_img_2.png) + +#### 配置 MySQL + +1. 本机配置 MySQL 服务（网上很多教程，忽略） + + + 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence + + [下载地址](https://github.com/leokhoa/laragon/releases) + + > [!TIP] + > 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节 + +2. 填写环境变量 + + ![环境变量](assets/contributing/backend_img_6.png) + + ```ini + MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC + MYSQL_USER=<数据库用户名> + MYSQL_PASSWORD=<数据库密码> + ``` + +3. 执行 db/init.sql 脚本，导入基本的数据 + + ![初始化脚本](assets/contributing/resources_img.png) + +4. 处理完环境问题直接跑起来就能通了 + + ![运行画面](assets/contributing/backend_img_4.png) + +### Docker 环境 +#### 环境变量配置 + +同上，见 [环境变量配置](#环境变量配置) + +#### 构建并启动镜像 ```shell --Dserver.port=8081 +cd docker +docker compose up -d ``` -![配置1](contributing_img\backend_img_3.png) -![配置2](contributing_img\backend_img_2.png) - -- 本机配置MySQL服务（网上很多教程，忽略） - + 可以用Laragon,自带MySQL包括Nodejs,版本建议6.x，7以后需要Lisence - + 下载地址(https://github.com/leokhoa/laragon/releases) -- 设置环境变量.env 文件 或.properties 文件（二选一） - -1. 环境变量文件生成 - -```shell -cp open-isle.env.example open-isle.env -``` - -修改环境变量，留下需要的，比如你要开发Google登录业务，就需要谷歌相关的变量，数据库是一定要的 - - -![环境变量](contributing_img\backend_img_7.png) -应用环境文件， 选择刚刚的`open-isle.env` - -![环境变量](contributing_img\backend_img_6.png) - -1. 直接修改 .properities 文件 - -位置src/main/application.properties, 数据库需要修改标红处，其他按需修改 - -![配置数据库](contributing_img\backend_img_5.png) - -执行db/init.sql脚本，导入基本的数据 -![初始化脚本](contributing_img\resources_img.png) - -处理完环境问题直接跑起来就能通了 - -![运行画面](contributing_img\backend_img_4.png) - -> Step3 前端部署 +## 启动前端服务 **⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）** -前端可以依赖本机部署的后端，也可以直接调用线上的后端接口 - ```shell -cd ../frontend_nuxt/ +cd frontend_nuxt/ ``` -copy环境.env文件 +### 环境变量配置 +前端可以依赖本机部署的后端，也可以直接调用线上的后端接口。 -利用预发环境 -**(⚠️强烈推荐只部署前端的朋友使用该环境)** -```shell -cp .env.staging.example .env -``` +- 利用预发环境：**(⚠️强烈推荐只部署前端的朋友使用该环境)** -利用生产环境 -```shell -cp .env.production.example .env -``` + ```shell + cp .env.staging.example .env + ``` -利用本地环境 -```shell -cp .env.dev.example .env -``` +- 利用生产环境 + ```shell + cp .env.production.example .env + ``` -前端安装编译运行 +- 利用本地环境 + + ```shell + cp .env.dev.example .env + ``` + +### 安装依赖和运行 + +前端安装编译并启动服务 ```shell # 安装依赖 @@ -102,15 +156,19 @@ npm run dev 如此一来，浏览器访问 http://127.0.0.1:3000 即可访问前端页面 ## 其他配置 -1. 配置第三方登录 -这里以github为例 -修改application.properties配置 -![后端配置](contributing_img\backend_img.png) +配置第三方登录，这里以 GitHub 为例 -修改.env配置 -![前端](contributing_img\fontend_img.png) +- 修改 `application.properties` 配置 -配置第三方登录回调地址 -![github配置](contributing_img\github_img.png) -![github配置2](contributing_img\github_img_2.png) \ No newline at end of file + ![后端配置](assets/contributing/backend_img.png) + +- 修改 `.env` 配置 + + ![前端](assets/contributing/fontend_img.png) + +- 配置第三方登录回调地址 + + ![github配置](assets/contributing/github_img.png) + + ![github配置2](assets/contributing/github_img_2.png) \ No newline at end of file diff --git a/contributing_img/backend_img.png b/assets/contributing/backend_img.png similarity index 100% rename from contributing_img/backend_img.png rename to assets/contributing/backend_img.png diff --git a/contributing_img/backend_img_2.png b/assets/contributing/backend_img_2.png similarity index 100% rename from contributing_img/backend_img_2.png rename to assets/contributing/backend_img_2.png diff --git a/contributing_img/backend_img_3.png b/assets/contributing/backend_img_3.png similarity index 100% rename from contributing_img/backend_img_3.png rename to assets/contributing/backend_img_3.png diff --git a/contributing_img/backend_img_4.png b/assets/contributing/backend_img_4.png similarity index 100% rename from contributing_img/backend_img_4.png rename to assets/contributing/backend_img_4.png diff --git a/contributing_img/backend_img_5.png b/assets/contributing/backend_img_5.png similarity index 100% rename from contributing_img/backend_img_5.png rename to assets/contributing/backend_img_5.png diff --git a/contributing_img/backend_img_6.png b/assets/contributing/backend_img_6.png similarity index 100% rename from contributing_img/backend_img_6.png rename to assets/contributing/backend_img_6.png diff --git a/contributing_img/backend_img_7.png b/assets/contributing/backend_img_7.png similarity index 100% rename from contributing_img/backend_img_7.png rename to assets/contributing/backend_img_7.png diff --git a/contributing_img/fontend_img.png b/assets/contributing/fontend_img.png similarity index 100% rename from contributing_img/fontend_img.png rename to assets/contributing/fontend_img.png diff --git a/contributing_img/github_img.png b/assets/contributing/github_img.png similarity index 100% rename from contributing_img/github_img.png rename to assets/contributing/github_img.png diff --git a/contributing_img/github_img_2.png b/assets/contributing/github_img_2.png similarity index 100% rename from contributing_img/github_img_2.png rename to assets/contributing/github_img_2.png diff --git a/contributing_img/resources_img.png b/assets/contributing/resources_img.png similarity index 100% rename from contributing_img/resources_img.png rename to assets/contributing/resources_img.png diff --git a/backend/open-isle.env.example b/backend/open-isle.env.example index ab3549c04..59274a758 100644 --- a/backend/open-isle.env.example +++ b/backend/open-isle.env.example @@ -5,6 +5,7 @@ SERVER_PORT=8080 MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC MYSQL_USER=<数据库用户名> MYSQL_PASSWORD=<数据库密码> +MYSQL_ROOT_PASSWORD=<数据库 root 用户密码> # === JWT === JWT_SECRET= diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml new file mode 100644 index 000000000..909d04f65 --- /dev/null +++ b/docker/docker-compose.yaml @@ -0,0 +1,41 @@ +services: + # MySQL service + mysql: + image: mysql:8.0 + container_name: openisle-mysql + restart: always + env_file: + - ../backend/open-isle.env + ports: + - '3306:3306' + volumes: + - mysql-data:/var/lib/mysql + - ../backend/src/main/resources/db/init/init_script.sql:/docker-entrypoint-initdb.d/init.sql + networks: + - openisle-network + + # Java spring boot service + springboot: + image: maven:3.9-eclipse-temurin-17 + container_name: openisle-springboot + working_dir: /app + volumes: + - ../backend:/app + - maven-repo:/root/.m2 + ports: + - '8080:8080' + env_file: + - ../backend/open-isle.env + depends_on: + - mysql + command: mvn clean spring-boot:run -Dmaven.test.skip=true + networks: + - openisle-network + +networks: + openisle-network: + driver: bridge + +volumes: + mysql-data: + maven-repo: