Merge pull request #875 from palmcivet/docs/docker-contributing

docs: 完善开发环境的 Docker Compose 配置
2026-02-06 23:21:16 +08:00 · 2025-09-04 09:54:08 +08:00
parent 49a55bcc36 931aee4c3f
commit 6f30cf0bc2
6 changed files with 158 additions and 32 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,30 @@
+# IDE
 .idea
 target
-openisle.iml
+
+# log
+logs
+
+# deps
 node_modules
+
+# test & build
+coverage
+out/
+build
 dist
-open-isle.env
-logs
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env
+*.env
+.env*.local
+
+# others
+openisle.iml
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,14 +1,14 @@
 - [前置工作](#前置工作)
 - [启动后端服务](#启动后端服务)
    - [本地 IDEA](#本地-idea)
-        - [环境变量配置](#环境变量配置)
-        - [配置参数](#配置参数)
+        - [配置环境变量](#配置环境变量)
+        - [配置 IDEA 参数](#配置-idea-参数)
        - [配置 MySQL](#配置-mysql)
    - [Docker 环境](#docker-环境)
-        - [环境变量配置](#环境变量配置-1)
+        - [配置环境变量](#配置环境变量-1)
        - [构建并启动镜像](#构建并启动镜像)
 - [启动前端服务](#启动前端服务)
-    - [环境变量配置](#环境变量配置-2)
+    - [配置环境变量](#配置环境变量-2)
    - [安装依赖和运行](#安装依赖和运行)
 - [其他配置](#其他配置)

@@ -21,6 +21,11 @@ git clone https://github.com/nagisa77/OpenIsle.git
 cd OpenIsle
 ```

+- 后端开发环境
+    - JDK 17+
+- 前端开发环境
+    - Node.JS 20+
+
 ## 启动后端服务

 启动后端服务有多种方式，选择一种即可。
@@ -30,9 +35,13 @@ cd OpenIsle

 ### 本地 IDEA

+```shell
+cd backend/
+```
+
 IDEA 打开 `backend/` 文件夹。

-#### 环境变量配置
+#### 配置环境变量

 1. 生成环境变量文件

@@ -58,7 +67,7 @@ SERVER_PORT=8082

 ![配置数据库](assets/contributing/backend_img_5.png)

-#### 配置参数
+#### 配置 IDEA 参数

 - 设置 JDK 版本为 java 17
 - 设置 VM Option，最好运行在其他端口，非 `8080`，这里设置 `8081`
@@ -73,14 +82,14 @@ SERVER_PORT=8082

 #### 配置 MySQL

+> [!TIP]
+> 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节
+
 1. 本机配置 MySQL 服务（网上很多教程，忽略）

    + 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence
    + [下载地址](https://github.com/leokhoa/laragon/releases)

-    > [!TIP]
-    > 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节
-
 2. 填写环境变量

    ![环境变量](assets/contributing/backend_img_6.png)
@@ -91,7 +100,7 @@ SERVER_PORT=8082
    MYSQL_PASSWORD=<数据库密码>
    ```

-3. 执行 db/init.sql 脚本，导入基本的数据
+3. 执行 [`db/init/init_script.sql`](backend/src/main/resources/db/init/init_script.sql) 脚本，导入基本的数据

    ![初始化脚本](assets/contributing/resources_img.png)

@@ -100,30 +109,57 @@ SERVER_PORT=8082
    ![运行画面](assets/contributing/backend_img_4.png)

 ### 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
-cd docker
 docker compose up -d
 ```

+如果想了解启动过程发生了什么可以查看日志
+
+```shell
+docker compose logs
+```
+
 ## 启动前端服务

-**⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）**
+> [!IMPORTANT]
+> **⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）**

 ```shell
 cd frontend_nuxt/
 ```

-### 环境变量配置
+### 配置环境变量

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

- 利用预发环境：**(⚠️强烈推荐只部署前端的朋友使用该环境)**
+- 利用预发环境：**（⚠️ 强烈推荐只开发前端的朋友使用该环境）**

    ```shell
    cp .env.staging.example .env
@@ -143,7 +179,7 @@ cd frontend_nuxt/

 ### 安装依赖和运行

-前端安装编译并启动服务
+前端安装依赖并启动服务。

 ```shell
 # 安装依赖
@@ -153,11 +189,11 @@ npm install --verbose
 npm run dev
 ```

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

 ## 其他配置

-配置第三方登录，这里以 GitHub 为例
+配置第三方登录，这里以 GitHub 为例：

 - 修改 `application.properties` 配置

@@ -169,6 +205,6 @@ npm run dev

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

-  ![github配置](assets/contributing/github_img.png)
+    ![github配置](assets/contributing/github_img.png)

-  ![github配置2](assets/contributing/github_img_2.png)
+    ![github配置2](assets/contributing/github_img_2.png)
--- a/backend/open-isle.env.example
+++ b/backend/open-isle.env.example
@@ -2,10 +2,9 @@
 SERVER_PORT=8080

 # === Database ===
-MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
+MYSQL_URL=jdbc:mysql://<数据库地址>:<数据库端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
 MYSQL_USER=<数据库用户名>
 MYSQL_PASSWORD=<数据库密码>
-MYSQL_ROOT_PASSWORD=<数据库 root 用户密码>

 # === JWT ===
 JWT_SECRET=<jwt secret>
--- a/backend/src/main/resources/db/init/init_script.sql
+++ b/backend/src/main/resources/db/init/init_script.sql
@@ -2,6 +2,34 @@
 -- 本地化开发，初始化脚本
 -- 抽奖的时候奖品图片是必须的，把相关代码注释掉即可跳过check

+-- 设置字符集和排序规则
+SET NAMES utf8;
+SET CHARACTER SET utf8;
+SET collation_connection = utf8_general_ci;
+
+-- 创建 users 表（如果不存在）
+CREATE TABLE IF NOT EXISTS `users` (
+	`id` bigint NOT NULL AUTO_INCREMENT,
+	`approved` bit(1) DEFAULT NULL,
+	`avatar` varchar(255) DEFAULT NULL,
+	`created_at` datetime(6) DEFAULT NULL,
+	`display_medal` varchar(255) DEFAULT NULL,
+	`email` varchar(255) NOT NULL,
+	`experience` int DEFAULT NULL,
+	`introduction` text,
+	`password` varchar(255) NOT NULL,
+	`password_reset_code` varchar(255) DEFAULT NULL,
+	`point` int DEFAULT NULL,
+	`register_reason` text,
+	`role` varchar(20) DEFAULT 'USER',
+	`username` varchar(50) NOT NULL,
+	`verification_code` varchar(255) DEFAULT NULL,
+	`verified` bit(1) DEFAULT NULL,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `UK_users_email` (`email`),
+	UNIQUE KEY `UK_users_username` (`username`)
+);
+
 -- 清空users表
 DELETE FROM `users`;
 -- 插入用户，两个普通用户，一个管理员
@@ -10,6 +38,21 @@ INSERT INTO `users` (`id`, `approved`, `avatar`, `created_at`, `display_medal`,
 	(2, b'1', '', '2025-09-03 16:08:17.426430', 'PIONEER', 'usermail2@openisle.com', 70, NULL, '$2a$10$m.lLbT3wFtnzFMi7JqN17ecv/dzH704WzU1f/xvQ0nVz4XxTXPT0K', NULL, 110, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', '普通用户2', NULL, b'1'),
 	(3, b'1', '', '2025-09-02 17:21:21.617666', 'PIONEER', 'usermail1@openisle.com', 40, NULL, '$2a$10$m.lLbT3wFtnzFMi7JqN17ecv/dzH704WzU1f/xvQ0nVz4XxTXPT0K', NULL, 40, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', '普通用户1', NULL, b'1');

+-- 创建 tags 表（如果不存在）
+CREATE TABLE IF NOT EXISTS `tags` (
+  `id` bigint NOT NULL AUTO_INCREMENT,
+  `approved` bit(1) DEFAULT NULL,
+  `created_at` datetime(6) DEFAULT NULL,
+  `description` text,
+  `icon` varchar(255) DEFAULT NULL,
+  `name` varchar(50) NOT NULL,
+  `small_icon` varchar(255) DEFAULT NULL,
+  `creator_id` bigint DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `UK_tags_name` (`name`),
+  KEY `FK_tags_creator` (`creator_id`),
+  CONSTRAINT `FK_tags_creator` FOREIGN KEY (`creator_id`) REFERENCES `users` (`id`)
+);
 -- 清空tags表
 DELETE FROM `tags`;
 -- 插入标签，三个测试用标签
@@ -18,6 +61,16 @@ INSERT INTO `tags` (`id`, `approved`, `created_at`, `description`, `icon`, `name
 	(2, b'1', '2025-09-02 10:51:56.000000', '测试用标签2', NULL, '测试用标签2', NULL, NULL),
 	(3, b'1', '2025-09-02 10:51:56.000000', '测试用标签3', NULL, '测试用标签3', NULL, NULL);

+-- 创建 categories 表（如果不存在）
+CREATE TABLE IF NOT EXISTS `categories` (
+  `id` bigint NOT NULL AUTO_INCREMENT,
+  `description` text,
+  `icon` varchar(255) DEFAULT NULL,
+  `name` varchar(50) NOT NULL,
+  `small_icon` varchar(255) DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `UK_categories_name` (`name`)
+);
 -- 清空categories表
 DELETE FROM `categories`;
 -- 插入分类，三个测试用分类
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -0,0 +1,11 @@
+# 前端访问端口
+SERVER_PORT=8080
+
+# MySQL 配置
+MYSQL_ROOT_PASSWORD=toor
+
+# 会覆盖 `open-isle.env`
+MYSQL_PORT=3306
+MYSQL_DATABASE=openisle
+MYSQL_USER=<数据库用户名>
+MYSQL_PASSWORD=<数据库密码>
--- a/docker/docker-compose.yaml
+++ b/docker/docker-compose.yaml
@@ -6,11 +6,12 @@ services:
    restart: always
    env_file:
      - ../backend/open-isle.env
+      - ./.env
    ports:
-      - '3306:3306'
+      - "${MYSQL_PORT}:3306"
    volumes:
      - mysql-data:/var/lib/mysql
-      - ../backend/src/main/resources/db/init/init_script.sql:/docker-entrypoint-initdb.d/init.sql
+      - ../backend/src/main/resources/db/init:/docker-entrypoint-initdb.d
    networks:
      - openisle-network

@@ -19,13 +20,16 @@ services:
    image: maven:3.9-eclipse-temurin-17
    container_name: openisle-springboot
    working_dir: /app
+    env_file:
+      - ../backend/open-isle.env
+      - ./.env
+    environment:
+      - MYSQL_URL=jdbc:mysql://mysql:${MYSQL_PORT}/${MYSQL_DATABASE}?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
+    ports:
+      - "${SERVER_PORT}:8080"
    volumes:
      - ../backend:/app
      - maven-repo:/root/.m2
-    ports:
-      - '8080:8080'
-    env_file:
-      - ../backend/open-isle.env
    depends_on:
      - mysql
    command: mvn clean spring-boot:run -Dmaven.test.skip=true