OpenIsle - 【开源共建】本站代码自部署方法（长期维护）

【开源共建】本站代码自部署方法（长期维护）

技术 & 开发调优

开源共建

软件开发

精品

去年 8.4 23:57

前置工作

先克隆仓库：


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 即可查看页面。

修改代码后，可以强制重新创建所有容器，执行：


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/ 文件夹。

在 IDEA 中配置「Environment file」：将 Run/Debug Configuration 的 Environment variables 指向刚刚复制的 .env，即可让 IDE 读取该文件。
需要调整端口或功能开关时，优先修改 .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文档页面调试

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