diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 115cbd81b..dd3275e6c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,24 +34,33 @@ cd OpenIsle 想要最快速地同时体验前端和后端，可直接使用仓库提供的 Docker Compose。该方案会一次性拉起数据库、消息队列、搜索、后端、WebSocket 以及前端 Dev Server，适合需要全链路联调的场景。 1. 准备环境变量文件： + ```shell cp .env.example .env ``` + `.env.example` 是模板，可在 `.env` 中按需覆盖如端口、密钥等配置。确保 `NUXT_PUBLIC_API_BASE_URL`、`NUXT_PUBLIC_WEBSOCKET_URL` 等仍指向 `localhost`，方便前端直接访问容器映射端口。 + 2. 启动 Dev Profile： + ```shell 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 即可查看页面。 + 3. 查看服务状态： + ```shell 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 ``` + 4. 停止所有容器： + ```shell docker compose -f docker/docker-compose.yaml --env-file .env --profile dev down ``` @@ -75,13 +84,8 @@ IDEA 打开 `backend/` 文件夹。 #### 配置环境变量 -1. 生成环境变量文件： - ```shell - cp open-isle.env.example open-isle.env - ``` - `open-isle.env` 才是实际被读取的文件。可在其中补充数据库、第三方服务等配置，`open-isle.env` 已被 Git 忽略，放心修改。 -2. 在 IDEA 中配置「Environment file」：将 `Run/Debug Configuration` 的 `Environment variables` 指向刚刚复制的 `open-isle.env`，即可让 IDE 读取该文件。 -3. 需要调整端口或功能开关时，优先修改 `open-isle.env`，例如： +1. 在 IDEA 中配置「Environment file」：将 `Run/Debug Configuration` 的 `Environment variables` 指向刚刚复制的 `.env`，即可让 IDE 读取该文件。 +2. 需要调整端口或功能开关时，优先修改 `.env`，例如： ```ini SERVER_PORT=8081 LOG_LEVEL=DEBUG @@ -89,7 +93,7 @@ IDEA 打开 `backend/` 文件夹。 也可以修改 `src/main/resources/application.properties`，但该文件会被 Git 追踪，通常不推荐。 -![配置数据库](assets/contributing/backend_img_5.png) +![backend_img_5.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/89658e5d5c0443a5939ef57ccfeab740.png) #### 配置 IDEA 参数 @@ -99,13 +103,13 @@ IDEA 打开 `backend/` 文件夹。 -Dserver.port=8081 ``` -![配置1](assets/contributing/backend_img_3.png) +![backend_img_3.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/6905f7cd4b694b1fa7214dd2b3ef9d81.png) -![配置2](assets/contributing/backend_img_2.png) +![backend_img_2.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/2bf8e139c21f4b529384ed68cef053da.png) 完成环境变量和运行参数设置后，即可启动 Spring Boot 应用。 -![运行画面](assets/contributing/backend_img_4.png) +![backend_img_4.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/474d995ddda34b6f80badffa58cec5b9.png) ## 启动前端服务 @@ -130,6 +134,7 @@ npm run dev 前端默认读取 `.env` 中的接口地址，可通过修改以下变量快速切换到预发或正式环境： 1. 复制对应模板： + ```shell # 使用预发配置 cp .env.staging.example .env @@ -137,12 +142,16 @@ npm run dev # 或者使用正式环境配置 cp .env.production.example .env ``` + 2. 按需覆盖关键变量： + ```ini NUXT_PUBLIC_API_BASE_URL=https://www.staging.open-isle.com NUXT_PUBLIC_WEBSOCKET_URL=https://www.staging.open-isle.com ``` + 将 `staging` 替换为 `www` 即可连接正式环境。其他变量（如 OAuth Client ID、站点地址等）可根据需求调整。 + 3. 已经存在 `.env` 时，可直接编辑上述变量并重启 `npm run dev` 让配置生效。 ## 其他配置 @@ -151,42 +160,41 @@ npm run dev - 修改 `application.properties` 配置 - ![后端配置](assets/contributing/backend_img.png) + ![backend_img.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/1dbb388cd1004e1d8822224cf87c9303.png) - 修改 `.env` 配置 - ![前端](assets/contributing/fontend_img.png) + ![fontend_img.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/3cc276e4795a407a90a47f2d77de2760.png) - 配置第三方登录回调地址 - ![github配置](assets/contributing/github_img.png) + ![github_img.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/14667457a15c4fbea9d91226797b7b59.png) - ![github配置2](assets/contributing/github_img_2.png) + ![github_img_2.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/7e901e1c648f4330be1d248379d699f1.png) ### 配置Resend邮箱服务 https://resend.com/emails 创建账号并登录 - `Domains` -> `Add Domain` - ![image-20250906150459400](assets/contributing/image-20250906150459400.png) - + ![image-20250906150459400.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/0168a039ca5e47239ab859f6049c4c93.png) - 填写域名 - ![image-20250906150541817](assets/contributing/image-20250906150541817.png) - + ![image-20250906150541817.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/d328cd89f21c4b8fb50c8213c9b784f0.png) - 等待一段时间后解析成功，创建 key `API Keys` -> `Create API Key`，输入名称，设置 `Permission` 为 `Sending access` **Key 只能查看一次，务必保存下来** - ![image-20250906150811572](assets/contributing/image-20250906150811572.png) - ![image-20250906150924975](assets/contributing/image-20250906150924975.png) - ![image-20250906150944130](assets/contributing/image-20250906150944130.png) + ![image-20250906150811572.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/d72959670b22451cb93e94d6e8316e05.png) + ![image-20250906150924975.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/b46f1a56f2d744a381d361ac8369a231.png) + ![image-20250906150944130.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/8eaba3fa791f4b10a5c24948812d306d.png) - 修改 `.env` 配置中的 `RESEND_API_KEY` 和 `RESEND_FROM_EMAIL` `RESEND_FROM_EMAIL`： **noreply@域名** `RESEND_API_KEY`：**刚刚复制的 Key** - ![image-20250906151218330](assets/contributing/image-20250906151218330.png) + ![image-20250906151218330.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/8319dc5037bb40b68ed35358d810552a.png) ## API文档 ### OpenAPI文档 + https://docs.open-isle.com ### 部署时间线以及文档时效性