mirror of
https://github.com/nagisa77/OpenIsle.git
synced 2026-02-25 23:50:51 +08:00
295 lines
9.3 KiB
Markdown
295 lines
9.3 KiB
Markdown
- [前置工作](#前置工作)
|
||
- [启动后端服务](#启动后端服务)
|
||
- [本地 IDEA](#本地-idea)
|
||
- [配置环境变量](#配置环境变量)
|
||
- [配置 IDEA 参数](#配置-idea-参数)
|
||
- [配置 MySQL](#配置-mysql)
|
||
- [Docker 环境](#docker-环境)
|
||
- [配置环境变量](#配置环境变量-1)
|
||
- [构建并启动镜像](#构建并启动镜像)
|
||
- [启动前端服务](#启动前端服务)
|
||
- [配置环境变量](#配置环境变量-2)
|
||
- [安装依赖和运行](#安装依赖和运行)
|
||
- [其他配置](#其他配置)
|
||
- [配置第三方登录以GitHub为例](#配置第三方登录以GitHub为例)
|
||
- [配置Resend邮箱服务](#配置Resend邮箱服务)
|
||
- [API文档](#api文档)
|
||
- [OpenAPI文档](#openapi文档)
|
||
- [部署时间线以及文档时效性](#部署时间线以及文档时效性)
|
||
- [OpenAPI文档使用](#OpenAPI文档使用)
|
||
- [OpenAPI文档应用场景](#OpenAPI文档应用场景)
|
||
|
||
## 前置工作
|
||
|
||
先克隆仓库：
|
||
|
||
```shell
|
||
git clone https://github.com/nagisa77/OpenIsle.git
|
||
cd OpenIsle
|
||
```
|
||
|
||
- 后端开发环境
|
||
- JDK 17+
|
||
- 前端开发环境
|
||
- Node.JS 20+
|
||
|
||
## 启动后端服务
|
||
|
||
启动后端服务有多种方式，选择一种即可。
|
||
|
||
> [!IMPORTANT]
|
||
> 仅想修改前端的朋友可不用部署后端服务。转到 [启动前端服务](#启动前端服务) 章节。
|
||
|
||
### 本地 IDEA
|
||
|
||
```shell
|
||
cd backend/
|
||
```
|
||
|
||
IDEA 打开 `backend/` 文件夹。
|
||
|
||
#### 配置环境变量
|
||
|
||
1. 生成环境变量文件
|
||
|
||
```shell
|
||
cp open-isle.env.example open-isle.env
|
||
```
|
||
|
||
`open-isle.env.example` 是环境变量模板，`open-isle.env` 才是真正读取的内容
|
||
|
||
2. 修改环境变量，留下需要的，比如你要开发 Google 登录业务，就需要谷歌相关的变量，数据库是一定要的
|
||
|
||
|
||
|
||
3. 应用环境文件，选择刚刚的 `open-isle.env`
|
||
|
||
可以在 `open-isle.env` 按需填写个性化的配置，该文件不会被 Git 追踪。比如你想把服务跑在 `8082`（默认为 `8080`），那么直接改 `open-isle.env` 即可：
|
||
|
||
```ini
|
||
SERVER_PORT=8082
|
||
```
|
||
|
||
另一种方式是修改 `.properities` 文件（但不建议），位于 `src/main/application.properties`，该配置同样来源于 `open-isle.env`，但修改 `.properties` 文件会被 Git 追踪。
|
||
|
||
|
||
|
||
#### 配置 IDEA 参数
|
||
|
||
- 设置 JDK 版本为 java 17
|
||
|
||
- 设置 VM Option，最好运行在其他端口，非 `8080`，这里设置 `8081`
|
||
若上面在环境变量中设置了端口，那这里就不需要再额外设置
|
||
|
||
```shell
|
||
-Dserver.port=8081
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
#### 配置 MySQL
|
||
|
||
> [!TIP]
|
||
> 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节
|
||
|
||
1. 本机配置 MySQL 服务（网上很多教程，忽略）
|
||
- 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence
|
||
- [下载地址](https://github.com/leokhoa/laragon/releases)
|
||
|
||
2. 填写环境变量
|
||
|
||
|
||
|
||
```ini
|
||
MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
|
||
MYSQL_USER=<数据库用户名>
|
||
MYSQL_PASSWORD=<数据库密码>
|
||
```
|
||
|
||
3. 执行 [`db/init/init_script.sql`](backend/src/main/resources/db/init/init_script.sql) 脚本，导入基本的数据
|
||
管理员：**admin/123456**
|
||
普通用户1：**user1/123456**
|
||
普通用户2：**user2/123456**
|
||
|
||
|
||
|
||
#### 配置 Redis
|
||
|
||
填写环境变量 `.env` 中的 Redis 相关配置并启动 Redis
|
||
|
||
```ini
|
||
REDIS_HOST=<Redis 地址>
|
||
REDIS_PORT=<Redis 端口>
|
||
```
|
||
|
||
处理完环境问题直接跑起来就能通了
|
||
|
||
|
||
|
||
### Docker 环境
|
||
|
||
#### 配置环境变量
|
||
|
||
```shell
|
||
cd docker/
|
||
```
|
||
|
||
主要配置两个 `.env` 文件
|
||
|
||
- `backend/open-isle.env`：后端环境变量，配置同上，见 [配置环境变量](#配置环境变量)。
|
||
- `docker/.env`：Docker Compose 环境变量，主要配置 MySQL 相关
|
||
```shell
|
||
cp .env.example .env
|
||
```
|
||
|
||
> [!TIP]
|
||
> 使用单独的 `.env` 文件是为了兼容线上环境或已启用 MySQL 服务的情况，如果只是想快速体验或者启动统一的环境，则推荐使用本方式。
|
||
|
||
在指定 `docker/.env` 后，`backend/open-isle.env` 中以下配置会被覆盖，这样就确保使用了同一份配置。
|
||
|
||
```ini
|
||
MYSQL_URL=
|
||
MYSQL_USER=
|
||
MYSQL_PASSWORD=
|
||
```
|
||
|
||
#### 构建并启动镜像
|
||
|
||
```shell
|
||
docker compose up -d
|
||
```
|
||
|
||
如果想了解启动过程发生了什么可以查看日志
|
||
|
||
```shell
|
||
docker compose logs
|
||
```
|
||
|
||
## 启动前端服务
|
||
|
||
> [!IMPORTANT]
|
||
> **⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）**
|
||
|
||
```shell
|
||
cd frontend_nuxt/
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
前端可以依赖本机部署的后端，也可以直接调用线上的后端接口。
|
||
|
||
- 利用预发环境：**（⚠️ 强烈推荐只开发前端的朋友使用该环境）**
|
||
|
||
```shell
|
||
cp .env.staging.example .env
|
||
```
|
||
|
||
- 利用生产环境
|
||
|
||
```shell
|
||
cp .env.production.example .env
|
||
```
|
||
|
||
- 利用本地环境
|
||
|
||
```shell
|
||
cp .env.dev.example .env
|
||
```
|
||
|
||
若依赖本机部署的后端，需要修改 `.env` 中的 `NUXT_PUBLIC_API_BASE_URL` 值与后端服务端口一致
|
||
|
||
### 安装依赖和运行
|
||
|
||
前端安装依赖并启动服务。
|
||
|
||
```shell
|
||
# 安装依赖
|
||
npm install --verbose
|
||
|
||
# 运行前端服务
|
||
npm run dev
|
||
```
|
||
|
||
如此一来，浏览器访问 http://127.0.0.1:3000 即可访问前端页面。
|
||
|
||
## 其他配置
|
||
|
||
### 配置第三方登录以GitHub为例
|
||
|
||
- 修改 `application.properties` 配置
|
||
|
||
|
||
|
||
- 修改 `.env` 配置
|
||
|
||
|
||
|
||
- 配置第三方登录回调地址
|
||
|
||
|
||
|
||
|
||
|
||
### 配置Resend邮箱服务
|
||
|
||
https://resend.com/emails 创建账号并登录
|
||
|
||
- `Domains` -> `Add Domain`
|
||
|
||
|
||
- 填写域名
|
||
|
||
|
||
- 等待一段时间后解析成功，创建 key
|
||
`API Keys` -> `Create API Key`，输入名称，设置 `Permission` 为 `Sending access`
|
||
**Key 只能查看一次，务必保存下来**
|
||
|
||
|
||
|
||
- 修改 `.env` 配置中的 `RESEND_API_KEY` 和 `RESEND_FROM_EMAIL`
|
||
`RESEND_FROM_EMAIL`： **noreply@域名**
|
||
`RESEND_API_KEY`：**刚刚复制的 Key**
|
||
|
||
|
||
## API文档
|
||
|
||
### OpenAPI文档
|
||
https://docs.open-isle.com
|
||
|
||
### 部署时间线以及文档时效性
|
||
|
||
我已经将API Docs的部署融合进本站CI & CD中，目前如下
|
||
|
||
- 每次合入main之后，都会构建预发环境 http://staging.open-isle.com/ ,现在文档是紧随其后进行部署，也就是说代码合入main之后，如果是新增后台接口，就可以立即通过OpenAPI文档页面进行查看和调试，但是如果想通过OpenAPI调试需要选择预发环境的
|
||
- 每日凌晨三点会构建并重新部署正式环境，届时当日合入main的新后台API也可以通过OpenAPI文档页面调试
|
||
|
||
|
||
|
||
👆如图是合入main之后构建预发+docs的情形，总大约耗时4分钟左右
|
||
|
||
### OpenAPI文档使用
|
||
|
||
- 预发环境/正式环境切换，可以通过如下位置切换API环境
|
||
|
||
|
||
|
||
- API分两种，一种是需要鉴权（需登录后的token），另一种是直接访问，可以直接访问的GET请求，直接点击Send即可调试，如下👇，比如本站的推荐流rss: /api/rss: https://docs.open-isle.com/openapi/feed
|
||
|
||
|
||
|
||
- 需要登陆的API，比如关注，取消关注，发帖等，则需要提供token，目前在“API与调试”可获取自身token，可点击link看看👉 https://www.open-isle.com/about?tab=api
|
||
|
||
|
||
|
||
copy完token之后，粘贴到Bear之后, 即可发送调试， 如下👇，大家亦可自行尝试：https://docs.open-isle.com/openapi/me
|
||
|
||
|
||
|
||
#### OpenAPI文档应用场景
|
||
|
||
- 方便大部分前端调试的需求，如果有只想做前端/客户端的同学参与本项目，该平台会大大提高效率
|
||
- 自动化：有自动化发帖/自动化操作的需求，亦可通过该平台实现或调试
|
||
- API文档: https://docs.open-isle.com/openapi
|