jiazhizhong/OpenIsle
1
0
Fork 0
mirror of https://github.com/nagisa77/OpenIsle.git synced 2026-02-06 23:21:16 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
180c45bf2dc104e0881f7c0c7c0cae603be3b2ff
OpenIsle/CONTRIBUTING.md
Tim 07c6b53f82 docs: document redis and rabbitmq setup
2025-09-18 17:48:32 +08:00

12 KiB
Raw Blame History

前置工作

先克隆仓库：

git clone https://github.com/nagisa77/OpenIsle.git
cd OpenIsle
  • 后端开发环境
    • JDK 17+
  • 前端开发环境
    • Node.JS 20+

启动后端服务

启动后端服务有多种方式，选择一种即可。

Important

仅想修改前端的朋友可不用部署后端服务。转到 启动前端服务 章节。

本地 IDEA

cd backend/

IDEA 打开 backend/ 文件夹。

配置环境变量

  1. 生成环境变量文件

    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 即可：

SERVER_PORT=8082

另一种方式是修改 .properities 文件（但不建议），位于 src/main/application.properties，该配置同样来源于 open-isle.env，但修改 .properties 文件会被 Git 追踪。

配置数据库

配置 IDEA 参数

  • 设置 JDK 版本为 java 17

  • 设置 VM Option，最好运行在其他端口，非 8080，这里设置 8081 若上面在环境变量中设置了端口，那这里就不需要再额外设置

    -Dserver.port=8081

配置1

配置2

配置 MySQL

Tip

如果不知道怎么配置数据库可以参考 Docker 环境 章节

  1. 本机配置 MySQL 服务（网上很多教程，忽略）

    • 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 6.x，7 以后需要 Lisence
    • 下载地址

  2. 填写环境变量

    环境变量

    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 脚本，导入基本的数据 管理员：admin/123456 普通用户1：user1/123456 普通用户2：user2/123456

    初始化脚本

配置 Redis

后端的登录态缓存、访问频控等都依赖 Redis，请确保本地有可用的 Redis 实例。

  1. 启动 Redis 服务（已有服务可跳过）

    docker run --name openisle-redis -p 6379:6379 -d redis:7-alpine

    该命令会在本机暴露 6379 端口。若你已有其他端口的 Redis，可以根据实际情况调整映射关系。

  2. 在 backend/open-isle.env 中填写连接信息

    REDIS_HOST=127.0.0.1
REDIS_PORT=6379
# 可选：若需要切换逻辑库，可新增此变量，默认使用 0 号库
REDIS_DATABASE=0

    application.properties 中的默认值为 localhost:6379、数据库 0，如果你的环境恰好一致，也可以不额外填写；显式声明可以避免 IDE/运行时读取到意外配置。

  3. 验证连接

    redis-cli -h 127.0.0.1 -p 6379 ping

    启动后端后，日志中会出现 Redis connection established ...（来自 RedisConnectionLogger），说明已成功连通。

配置 RabbitMQ

消息通知和 WebSocket 推送链路依赖 RabbitMQ。后端会自动声明交换机与队列，确保本地 RabbitMQ 可用即可。

  1. 启动 RabbitMQ 服务（推荐包含管理界面）

    docker run --name openisle-rabbitmq \
  -e RABBITMQ_DEFAULT_USER=openisle \
  -e RABBITMQ_DEFAULT_PASS=openisle \
  -p 5672:5672 -p 15672:15672 \
  -d rabbitmq:3.13-management

    管理界面位于 http://127.0.0.1:15672 ，可用于查看队列、交换机等资源。

  2. 同步填写后端与 WebSocket 服务的环境变量

    # backend/open-isle.env
RABBITMQ_HOST=127.0.0.1
RABBITMQ_PORT=5672
RABBITMQ_USERNAME=openisle
RABBITMQ_PASSWORD=openisle

# 如果需要启动 websocket_service，也需要在 websocket_service.env 中保持一致

    如果沿用 RabbitMQ 默认的 guest/guest，可以不显式设置，Spring Boot 会回退到 application.properties 中的默认值 (localhost:5672、guest/guest、虚拟主机 /)。

  3. 确认自动声明的资源

    • 交换机：openisle-exchange
    • 旧版兼容队列：notifications-queue
    • 分片队列：notifications-queue-0 ~ notifications-queue-f（共 16 个，对应路由键 notifications.shard.0 ~ notifications.shard.f）
    • 队列持久化默认开启，来自 rabbitmq.queue.durable=true，如需仅在本地短暂测试，可在 application.properties 中调整该配置。

    启动后端时可在日志中看到 === 开始主动声明 RabbitMQ 组件 === 与后续的声明结果，也可以在管理界面中查看是否创建成功。

完成 Redis 与 RabbitMQ 配置后，即可继续启动后端服务。

运行画面

Docker 环境

配置环境变量

cd docker/

主要配置两个 .env 文件

  • backend/open-isle.env：后端环境变量，配置同上，见 配置环境变量。
  • docker/.env：Docker Compose 环境变量，主要配置 MySQL 相关 
    cp .env.example .env

Tip

使用单独的 .env 文件是为了兼容线上环境或已启用 MySQL 服务的情况，如果只是想快速体验或者启动统一的环境，则推荐使用本方式。

在指定 docker/.env 后，backend/open-isle.env 中以下配置会被覆盖，这样就确保使用了同一份配置。

MYSQL_URL=
MYSQL_USER=
MYSQL_PASSWORD=

构建并启动镜像

docker compose up -d

如果想了解启动过程发生了什么可以查看日志

docker compose logs

启动前端服务

Important

⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）

cd frontend_nuxt/

配置环境变量

前端可以依赖本机部署的后端，也可以直接调用线上的后端接口。

  • 利用预发环境：（⚠️ 强烈推荐只开发前端的朋友使用该环境）

    cp .env.staging.example .env

  • 利用生产环境

    cp .env.production.example .env

  • 利用本地环境

    cp .env.dev.example .env

若依赖本机部署的后端，需要修改 .env 中的 NUXT_PUBLIC_API_BASE_URL 值与后端服务端口一致

安装依赖和运行

前端安装依赖并启动服务。

# 安装依赖
npm install --verbose

# 运行前端服务
npm run dev

如此一来，浏览器访问 http://127.0.0.1:3000 即可访问前端页面。

其他配置

配置第三方登录以GitHub为例

  • 修改 application.properties 配置

    后端配置

  • 修改 .env 配置

    前端

  • 配置第三方登录回调地址

    github配置

    github配置2

配置Resend邮箱服务

https://resend.com/emails 创建账号并登录

  • Domains -> Add Domain image-20250906150459400

  • 填写域名 image-20250906150541817

  • 等待一段时间后解析成功，创建 key API Keys -> Create API Key，输入名称，设置 Permission 为 Sending access Key 只能查看一次，务必保存下来 image-20250906150811572 image-20250906150924975 image-20250906150944130

  • 修改 .env 配置中的 RESEND_API_KEY 和 RESEND_FROM_EMAIL RESEND_FROM_EMAIL： noreply@域名 RESEND_API_KEY：刚刚复制的 Key image-20250906151218330

API文档

OpenAPI文档

https://docs.open-isle.com

部署时间线以及文档时效性

我已经将API Docs的部署融合进本站CI & CD中，目前如下

  • 每次合入main之后，都会构建预发环境 http://staging.open-isle.com/ ,现在文档是紧随其后进行部署，也就是说代码合入main之后，如果是新增后台接口，就可以立即通过OpenAPI文档页面进行查看和调试，但是如果想通过OpenAPI调试需要选择预发环境的
  • 每日凌晨三点会构建并重新部署正式环境，届时当日合入main的新后台API也可以通过OpenAPI文档页面调试

CleanShot 2025-09-10 at 12 .04.48@2x.png

👆如图是合入main之后构建预发+docs的情形，总大约耗时4分钟左右

OpenAPI文档使用

  • 预发环境/正式环境切换，可以通过如下位置切换API环境

CleanShot 2025-09-10 at 12 .08.00@2x.png

  • API分两种，一种是需要鉴权（需登录后的token），另一种是直接访问，可以直接访问的GET请求，直接点击Send即可调试，如下👇，比如本站的推荐流rss: /api/rss: https://docs.open-isle.com/openapi/feed

CleanShot 2025-09-10 at 12 .09.48@2x.png

  • 需要登陆的API，比如关注，取消关注，发帖等，则需要提供token，目前在“API与调试”可获取自身token，可点击link看看👉 https://www.open-isle.com/about?tab=api

CleanShot 2025-09-10 at 12 .11.07@2x.png

copy完token之后，粘贴到Bear之后, 即可发送调试， 如下👇，大家亦可自行尝试：https://docs.open-isle.com/openapi/me

CleanShot 2025-09-10 at 12 .13.00@2x.png

OpenAPI文档应用场景

  • 方便大部分前端调试的需求，如果有只想做前端/客户端的同学参与本项目，该平台会大大提高效率
  • 自动化：有自动化发帖/自动化操作的需求，亦可通过该平台实现或调试
  • API文档: https://docs.open-isle.com/openapi
Reference in New Issue View Git Blame Copy Permalink