OpenIsle/CONTRIBUTING.md at 6aecb4f583f7d911b8aae3962718d67790f9a5c2

mirror of https://github.com/nagisa77/OpenIsle.git synced 2026-02-06 23:21:16 +08:00

Files

Tim 39d954d98a fix: 继续做UI工作

2025-10-16 18:11:27 +08:00

前置工作

先克隆仓库：

git clone https://github.com/nagisa77/OpenIsle.git
cd OpenIsle

想要最快速地同时体验前端和后端，可直接使用仓库提供的 Docker Compose。该方案会一次性拉起数据库、消息队列、搜索、后端、WebSocket 以及前端 Dev Server，适合需要全链路联调的场景。

准备环境变量文件：
```
cp .env.example .env
```
.env.example 是模板，可在 .env 中按需覆盖如端口、密钥等配置。确保 NUXT_PUBLIC_API_BASE_URL、NUXT_PUBLIC_WEBSOCKET_URL 等仍指向 localhost，方便前端直接访问容器映射端口。

启动 Dev Profile：

docker compose \
  -f docker/docker-compose.yaml \
  --env-file .env \
  --profile dev build

docker compose \
  -f docker/docker-compose.yaml \
  --env-file .env \
  --profile dev up -d

该命令会创建名为 frontend_dev 的容器并运行 npm run dev，浏览器访问 http://127.0.0.1:3000 即可查看页面。修改前端代码，页面会热更新。如果修改后端代码，可以重启后端容器, 或是环境变量中指向IDEA，采用IDEA编译运行也可以哦。

docker compose \
  -f docker/docker-compose.yaml \
  --env-file .env \
  --profile dev up -d --force-recreate

查看服务状态：

docker compose -f docker/docker-compose.yaml --env-file .env ps
docker compose -f docker/docker-compose.yaml --env-file .env logs -f frontend_dev

停止所有容器：

docker compose -f docker/docker-compose.yaml --env-file .env --profile dev down

如需自定义 Node 依赖缓存、数据库持久化等，可参考 docker/docker-compose.yaml 中各卷的定义进行调整。

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

Important

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

cd backend/

IDEA 打开 backend/ 文件夹。

生成环境变量文件：
```
cp open-isle.env.example open-isle.env
```
open-isle.env 才是实际被读取的文件。可在其中补充数据库、第三方服务等配置，open-isle.env 已被 Git 忽略，放心修改。
在 IDEA 中配置「Environment file」：将 Run/Debug Configuration 的 Environment variables 指向刚刚复制的 open-isle.env，即可让 IDE 读取该文件。
需要调整端口或功能开关时，优先修改 open-isle.env，例如：
```
SERVER_PORT=8081
LOG_LEVEL=DEBUG
```

也可以修改 src/main/resources/application.properties，但该文件会被 Git 追踪，通常不推荐。

设置 JDK 版本为 Java 17。
设置 VM Option，最好运行在其他端口（例如 8081）。若已经在 open-isle.env 中调整端口，可省略此步骤。
```
-Dserver.port=8081
```

完成环境变量和运行参数设置后，即可启动 Spring Boot 应用。

前端默认读取 .env 中的接口地址，可通过修改以下变量快速切换到预发或正式环境：

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 Docs的部署融合进本站CI & CD中，目前如下

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