# pioner

**Repository Path**: geran/pioner

## Basic Information

- **Project Name**: pioner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pioner 多项目平台

平台仓库，用于管理多个相似的小项目（登录 + 前端 + 后端 + 数据库）。各子项目通过**二级域名**区分，请求统一经过 Nginx → Gateway → 对应后端服务。

## 子项目

| 项目 | 域名 | 说明 | 后端端口 |
|------|------|------|----------|
| **bilanee** | `www.bilanee.com` | 平台主页 | 8084 |
| **endurance** | `endurance.bilanee.com` | 训练 | 8081 |
| **ecom** | `ecom.bilanee.com` | 电商 | 8082 |

## 目录结构

```
pioner/
├── infra/                      # 共享基础设施
│   ├── gateway/                # Spring Cloud Gateway（鉴权 + 按 Host 路由）
│   ├── nginx/                  # 前置代理 + 各项目静态资源
│   │   ├── Dockerfile
│   │   └── conf.d/
│   ├── database/               # MySQL 初始化、备份/回滚
│   └── keycloak/               # Keycloak 说明
├── projects/
│   ├── bilanee/                # 平台主页
│   ├── endurance/              # 训练
│   └── ecom/                   # 电商
├── scripts/                    # 平台脚本
│   ├── deploy.ps1              # Windows (PowerShell)
│   ├── deploy.sh               # Linux / macOS / WSL (POSIX sh)
│   ├── setup.ps1               # Windows 环境检查
│   ├── setup.sh                # macOS 检查 / Ubuntu 自动安装
│   ├── check-eol.ps1           # 检查文本文件是否为 LF
│   ├── check-eol.sh
│   └── platform.sh
├── .editorconfig               # 编辑器统一 LF
├── .gitattributes              # Git 提交/检出时统一 LF
└── docker-compose.yml
```

## 架构

```
www.bilanee.com ──→ Nginx(/html/bilanee) ──→ Gateway ──→ bilanee-backend:8084 ──→ MySQL(bilanee)
endurance.bilanee.com ──→ Nginx(/html/endurance) ──→ Gateway ──→ endurance-backend:8081
ecom.bilanee.com ──→ Nginx(/html/ecom) ──→ Gateway ──→ ecom-backend:8082
```

- **Nginx**：按域名托管各项目前端，反代 `/api` 到 Gateway
- **Gateway**：JWT 校验、登录代理、按 Host 路由到对应后端、用户信息写入 Header
- **Keycloak**：统一用户管理（每项目一个 Realm）
- **项目 Backend**：纯业务 API，读 Gateway Header 识别用户

## 快速开始

**Windows（PowerShell）：**

```powershell
# 环境检查（仅检测，不自动安装）
.\scripts\setup.ps1

# 构建并部署（默认 bilanee + endurance + ecom）
.\scripts\deploy.ps1

# 大规模重构后：先删 MySQL 持久化卷，再全量部署（会重新执行 init SQL）
.\scripts\deploy.ps1 -d

# 只构建并重启指定服务（*-backend 会同步重建 nginx）
.\scripts\deploy.ps1 -p bilanee-backend
.\scripts\deploy.ps1 -p endurance-frontend
.\scripts\deploy.ps1 -p gateway
.\scripts\deploy.ps1 -p nginx

# 只起基础设施（不含业务后端）
docker compose up -d

# 单独启动某个项目后端
docker compose --profile ball up -d --build
docker compose --profile item up -d --build
```

**Linux / macOS / WSL（POSIX sh）：**

```bash
export JAVA_HOME=/path/to/jdk8

# macOS：仅检测
sh scripts/setup.sh

# Ubuntu：缺失项自动安装
sudo sh scripts/setup.sh

sh scripts/deploy.sh
sh scripts/deploy.sh -f
sh scripts/deploy.sh -r
sh scripts/deploy.sh -d
sh scripts/deploy.sh -p bilanee-backend
sh scripts/deploy.sh -p gateway
```

## 访问地址

| 入口 | 地址 |
|------|------|
| Bilanee 平台主页 | http://www.bilanee.com（或 http://localhost） |
| Endurance 训练 | http://endurance.bilanee.com |
| Ecom 电商 | http://ecom.bilanee.com |
| Keycloak 管理台 | http://localhost:8180 |

**默认业务账号：** `admin` / `admin123`  
**Keycloak 管理员：** `admin` / `Keycloak@Admin8`

**本地 hosts（推荐）：**

```
127.0.0.1  www.bilanee.com
127.0.0.1  endurance.bilanee.com
127.0.0.1  ecom.bilanee.com
```

也可使用 Nginx 已配置的 `ball.localhost` / `item.localhost`。

## 单项目开发

以 ball 为例（item 替换路径中的 `ball` 即可）：

**Windows：**

```powershell
.\projects\ball\build.ps1
cd projects\ball\frontend; pnpm dev
cd projects\ball\backend
mvn package -DskipTests -s settings.xml
.\bundle.ps1
$env:DB_NAME="ball"; $env:DB_USER="ball"; $env:DB_PASSWORD="Ball@Db8"
$env:SERVER_PORT="8081"; .\runtime\bin\start.sh
```

**Linux / macOS：**

```bash
sh projects/ball/build.sh
cd projects/ball/frontend && pnpm dev
cd projects/ball/backend
mvn package -DskipTests -s settings.xml
sh bundle.sh
export DB_NAME=ball DB_USER=ball DB_PASSWORD=Ball@Db8 SERVER_PORT=8081
sh runtime/bin/start.sh
```

## 数据库

| Schema | 用户 | 密码 |
|--------|------|------|
| bilanee | bilanee | Bilanee@Db8 |
| endurance | endurance | Endurance@Db8 |
| ecom | ecom | Ecom@Db8 |
| keycloak | keycloak | Keycloak@Db8 |

MySQL root：`Pioner@Root8`

**首次部署或切换 schema 结构时**，若旧数据卷未包含新库，需重建：

```powershell
docker compose down -v
.\scripts\deploy.ps1
```

Linux / macOS：`sh scripts/deploy.sh`

备份与恢复（全库）：

```powershell
.\scripts\db-backup.ps1
.\scripts\db-restore.ps1 -BackupFile backups\all-20260711-120000.sql.gz
```

```bash
sh scripts/db-backup.sh
sh scripts/db-restore.sh backups/all-20260711-120000.sql.gz
```

## 平台配置

所有项目信息集中在根目录 `platform.yml`，`deploy` 和数据库脚本均读取此文件：

```yaml
mysql:
  rootPassword: Pioner@Root8
  container: pioner-mysql
  backupDir: backups

projects:
  - name: bilanee
    domain: www.bilanee.com
    port: 8084
    dbSchema: bilanee
    dbUser: bilanee
    dbPassword: Bilanee@Db8
  # ...
```

## 换行符（LF）

本项目在 Windows 开发、Linux 部署，**文本文件必须统一为 LF**（`\n`），不能混用 Windows 的 CRLF（`\r\n`）。

### 常见问题

| 现象 | 原因 |
|------|------|
| `.sh` 在 Linux 报 `bad interpreter` 或 `$'\r': command not found` | 脚本是 CRLF |
| `.sql` 在 MySQL init 里执行失败 | SQL 文件含 `\r` |
| `platform.yml` 只读到第一个项目 | CRLF 空行被解析成单独的 `\r`，脚本误判段落结束 |

### 仓库约定（已配置）

三层防护，避免反复踩坑：

1. **`.gitattributes`** — 提交/检出时 Git 自动把文本文件规范为 LF（`* text=auto eol=lf`）
2. **`.editorconfig`** — Cursor / VS Code 保存时默认 LF
3. **脚本兜底** — `load-config.ps1` / `load-config.sh` 读取配置前会去掉 `\r`

### 一次性整理已有文件

刚克隆仓库，或刚合并 `.gitattributes` 变更后，对**已跟踪文件**执行一次：

```bash
git add --renormalize .
git status    # 可能显示大量 modified，多数只是换行符变化
git commit -m "Normalize line endings to LF"
```

`--renormalize` 表示按 `.gitattributes` 重新计算换行符并放入暂存区，不是普通意义的「添加新文件」。

### 提交前自检

```powershell
.\scripts\check-eol.ps1
```

```bash
sh scripts/check-eol.sh
```

发现 CRLF 会报错并列出文件路径。新文件日常由 Git + 编辑器自动保持 LF，一般无需重复执行 `renormalize`。

## 新增项目

项目不常增加，新增时**手动改配置**即可，步骤如下：

1. 复制 `projects/bilanee` 为 `projects/<name>`
2. 编写 `schema.sql`、`realm.json`，按需改 `backend/`、`frontend/`
3. 在根目录 `platform.yml` 的 `projects` 列表中加入新项目
4. 在 `docker-compose.yml` 增加 mysql/keycloak 挂载和 `<name>-backend` 服务
5. 在 `infra/database/init/00-platform.sql` 增加数据库和用户
6. 在 gateway / nginx 配置中增加 host 映射
7. 执行 `sh scripts/deploy.sh -p <name>-backend`

各项目当前配置一览：

| 项目 | 域名 | DB | 端口 | compose profile | 服务名 |
|------|------|-----|------|-----------------|--------|
| bilanee | www.bilanee.com | bilanee / Bilanee@Db8 | 8084 | bilanee | bilanee-backend |
| endurance | endurance.bilanee.com | endurance / Endurance@Db8 | 8081 | endurance | endurance-backend |
| ecom | ecom.bilanee.com | ecom / Ecom@Db8 | 8082 | ecom | ecom-backend |

**注意：** 若 MySQL 数据卷已存在（非首次部署），新增的 schema 不会自动初始化，需手动建库或执行 `docker compose down -v` 后重建。

## milky 依赖

后端基于 milky 框架，需先安装到本地 Maven 仓库：

```bash
git clone <milky 仓库>
cd milky && mvn install -DskipTests
```