# Forge Admin 构建与部署指南

> 本文档涵盖 PC 前端、H5 移动端、后端三部分的构建与部署步骤。
> 照着复制命令即可执行。

---

## 一、环境要求

| 依赖 | 版本要求 | 用途 |
|------|---------|------|
| JDK | 17+ | 后端编译运行 |
| Maven | 3.9+ | 后端构建 |
| Node.js | 20+ | 前端构建 |
| pnpm | 8+ | 前端包管理 |
| MySQL | 8.0+ | 数据库 |
| Redis | 6.0+ | 缓存 |
| Nginx | 1.25+ | 前端静态资源 + API 反向代理 |

---

## 二、PC 前端（forge-admin-ui）

### 2.1 开发模式

```powershell
cd D:\java_project\forge-admin\forge-admin-ui

# 安装依赖（首次或依赖变更后执行）
pnpm install

# 启动开发服务器（默认 http://localhost:3000）
pnpm dev
```

### 2.2 生产构建

```powershell
cd D:\java_project\forge-admin\forge-admin-ui

# 生产构建（产物输出到 dist/ 目录）
pnpm build
```

**构建产物：** `forge-admin-ui/dist/`

**生产环境配置**（`.env.production`）：

| 配置项 | 值 | 含义 |
|--------|-----|------|
| `VITE_PUBLIC_PATH` | `/forge` | 静态资源部署路径 |
| `VITE_REQUEST_PREFIX` | `/forge-api` | API 请求前缀 |

### 2.3 部署到服务器

```bash
# 1. 将 dist/ 目录上传到服务器
scp -r dist/ root@你的服务器:/usr/share/nginx/html/forge/

# 2. 确认 Nginx 配置中有以下 location（见第五节 Nginx 完整配置）
#    location /forge/ { ... }
#    location /forge-api/ { ... }

# 3. 重载 Nginx
nginx -s reload
```

**访问地址：** `http://服务器IP/forge`
**默认账号：** `admin` / `123456`

---

## 三、H5 移动端（forge-h5-ui）

### 3.1 开发模式

```powershell
cd D:\java_project\forge-admin\forge-h5-ui

# 安装依赖（首次或依赖变更后执行）
pnpm install

# 启动开发服务器（默认 http://localhost:3001）
pnpm dev:h5
```

### 3.2 生产构建

```powershell
cd D:\java_project\forge-admin\forge-h5-ui

# H5 生产构建（产物输出到 dist/build/h5/ 目录）
pnpm build:h5
```

**构建产物：** `forge-h5-ui/dist/build/h5/`

产物结构：
```
dist/build/h5/
├── index.html      # 入口文件
├── assets/         # JS/CSS 打包产物
└── static/         # 静态资源
```

**生产环境配置**（`.env.production`）：

| 配置项 | 值 | 含义 |
|--------|-----|------|
| `VITE_PUBLIC_PATH` | `/forge-h5` | 静态资源部署路径 |
| `VITE_REQUEST_PREFIX` | `/forge-h5-api` | API 请求前缀 |

### 3.3 部署到服务器

```bash
# 1. 将 dist/build/h5/ 目录内容上传到服务器
scp -r dist/build/h5/* root@你的服务器:/usr/share/nginx/forge-h5/

# 2. 确认 Nginx 配置中有以下 location（见第五节 Nginx 完整配置）
#    location /forge-h5/ { ... }
#    location /forge-h5-api/ { ... }

# 3. 重载 Nginx
nginx -s reload
```

**访问地址：** `http://服务器IP/forge-h5`

> **注意：** H5 移动端连接的是 `forge-app-server`（端口 8583），不是 admin-server（8580）。
> 确保服务器上 app-server 已启动。

---

## 四、后端打 JAR 包

### 4.1 一键打全部 JAR（推荐）

```powershell
cd D:\java_project\forge-admin\forge-server

mvn clean package -DskipTests -Pprod
```

执行完后，4 个 JAR 包分别在这里：

| 服务 | JAR 包路径 | 端口 |
|------|-----------|------|
| admin 主服务（PC 管理端 API） | `forge-admin-server/target/forge-admin-server.jar` | 8580 |
| flow 流程服务（工作流） | `forge-flow/forge-flow-server/target/forge-flow-server.jar` | 8081 |
| app 服务（H5 移动端 API） | `forge-app-server/target/forge-app-server.jar` | 8583 |
| report 报表服务（数据大屏） | `forge-report-server/target/forge-report-server.jar` | 8084 |

### 4.2 单独打某个 JAR

```powershell
cd D:\java_project\forge-admin\forge-server

# 只打 admin 主服务（自动编译依赖的 framework、plugin 模块）
mvn clean package -pl forge-admin-server -am -DskipTests -Pprod

# 只打 flow 流程服务
mvn clean package -pl forge-flow/forge-flow-server -am -DskipTests -Pprod

# 只打 app 服务（H5 需要）
mvn clean package -pl forge-app-server -am -DskipTests -Pprod

# 只打 report 报表服务
mvn clean package -pl forge-report-server -am -DskipTests -Pprod
```

> **参数说明：**
> - `-pl` 指定要打包的模块
> - `-am` 自动编译该模块依赖的其他模块（framework、plugin 等）
> - `-DskipTests` 跳过单元测试，加快速度
> - `-Pprod` 使用生产环境配置（日志级别 warn 等）

### 4.3 用 JAR 包启动服务

```powershell
# 启动顺序：flow → admin → app（app 依赖 admin 的认证模块）

# 1. flow 流程服务
cd D:\java_project\forge-admin\forge-server
java -jar forge-flow/forge-flow-server/target/forge-flow-server.jar --spring.profiles.active=dev

# 2. admin 主服务
java -jar forge-admin-server/target/forge-admin-server.jar --spring.profiles.active=dev

# 3. app 服务（H5 移动端需要）
java -jar forge-app-server/target/forge-app-server.jar --spring.profiles.active=dev

# 4. report 报表服务（可选）
java -jar forge-report-server/target/forge-report-server.jar --spring.profiles.active=dev
```

> 本地开发用 `--spring.profiles.active=dev`，服务器部署用 `--spring.profiles.active=prod`

### 4.4 部署到服务器

```bash
# 1. 把 JAR 包上传到服务器
scp forge-admin-server/target/forge-admin-server.jar root@服务器:/opt/forge/
scp forge-flow/forge-flow-server/target/forge-flow-server.jar root@服务器:/opt/forge/
scp forge-app-server/target/forge-app-server.jar root@服务器:/opt/forge/

# 2. 在服务器上按顺序启动
# 先启动 flow
nohup java -Xms256m -Xmx512m \
  -Dspring.profiles.active=prod \
  -jar /opt/forge/forge-flow-server.jar \
  > /opt/forge/logs/flow.log 2>&1 &

# 再启动 admin
nohup java -Xms256m -Xmx512m \
  -Dspring.profiles.active=prod \
  -jar /opt/forge/forge-admin-server.jar \
  > /opt/forge/logs/admin.log 2>&1 &

# 最后启动 app（H5 需要）
nohup java -Xms256m -Xmx512m \
  -Dspring.profiles.active=prod \
  -jar /opt/forge/forge-app-server.jar \
  > /opt/forge/logs/app.log 2>&1 &
```

**服务器配置文件：** 在 jar 同目录放 `application-prod.yml`，配置数据库和 Redis 连接信息。

---

## 五、Nginx 完整配置

将以下内容写入 `/etc/nginx/conf.d/forge.conf`（或合并到 `nginx.conf`）：

```nginx
server {
    listen 80;
    server_name localhost;

    # ==================== PC 前端 ====================
    location /forge/ {
        alias   /usr/share/nginx/html/forge/;
        index   index.html index.htm;
        try_files $uri $uri/ /forge/index.html;
    }

    # ==================== H5 移动端前端 ====================
    location /forge-h5/ {
        alias   /usr/share/nginx/forge-h5/;
        index   index.html;
        try_files $uri $uri/ /forge-h5/index.html;
    }

    # ==================== H5 API 代理 → app-server:8583 ====================
    location /forge-h5-api/ {
        proxy_pass http://127.0.0.1:8583/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # ==================== 流程服务 API（路径更长，优先匹配） ====================
    location /forge-api/api/flow/ {
        proxy_send_timeout 3000;
        proxy_read_timeout 3000;
        proxy_connect_timeout 3000;
        proxy_pass http://127.0.0.1:8081/api/flow/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # ==================== PC API 代理 → admin-server:8580 ====================
    location /forge-api/ {
        proxy_send_timeout 3000;
        proxy_read_timeout 3000;
        proxy_connect_timeout 3000;
        proxy_pass http://127.0.0.1:8580/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # ==================== 通用配置 ====================
    client_max_body_size 20m;

    gzip on;
    gzip_types text/plain application/json application/javascript text/css;
    gzip_min_length 1000;
}
```

### 请求链路图

```
PC 浏览器
  http://服务器/forge/          → Nginx → /usr/share/nginx/html/forge/（静态文件）
  http://服务器/forge-api/xxx   → Nginx → admin-server:8580/xxx

H5 手机浏览器
  http://服务器/forge-h5/        → Nginx → /usr/share/nginx/forge-h5/（静态文件）
  http://服务器/forge-h5-api/xxx → Nginx → app-server:8583/xxx

流程服务（PC 和 H5 共用）
  http://服务器/forge-api/api/flow/xxx → Nginx → flow-server:8081/api/flow/xxx
```

---

## 六、Docker 一键部署（可选）

如果服务器上有 Docker，可以用 docker-compose 一键部署：

```bash
cd /mnt/project/forge_admin/docker

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 修改数据库密码等配置
vim .env

# 一键构建并启动（首次约 15-20 分钟）
docker compose up -d --build

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f
```

> **注意：** 当前 Docker 配置只包含 PC 前端和 admin/flow 服务，H5 前端和 app-server 需要手动添加（见下方扩展说明）。

### Docker 扩展：加入 H5 前端

修改 `docker/Dockerfile.ui`：

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app

# PC 前端
COPY forge-admin-ui/package.json forge-admin-ui/pnpm-lock.yaml ./pc/
RUN npm install -g pnpm@8 && cd pc && pnpm install
COPY forge-admin-ui/ ./pc/
RUN cd pc && pnpm build

# H5 移动端
COPY forge-h5-ui/package.json forge-h5-ui/pnpm-lock.yaml ./h5/
RUN cd h5 && pnpm install
COPY forge-h5-ui/ ./h5/
RUN cd h5 && pnpm build:h5

FROM nginx:1.25-alpine
COPY --from=builder /app/pc/dist /usr/share/nginx/html/forge
COPY --from=builder /app/h5/dist/build/h5 /usr/share/nginx/html/forge-h5
COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

---

## 七、快速命令速查表

| 操作 | 命令 |
|------|------|
| **PC 前端开发** | `cd forge-admin-ui && pnpm dev` |
| **PC 前端构建** | `cd forge-admin-ui && pnpm build` |
| **H5 前端开发** | `cd forge-h5-ui && pnpm dev:h5` |
| **H5 前端构建** | `cd forge-h5-ui && pnpm build:h5` |
| **后端全量构建** | `cd forge-server && mvn clean install -DskipTests` |
| **后端单独构建 admin** | `cd forge-server && mvn clean package -pl forge-admin-server -am -DskipTests -Pprod` |
| **后端单独构建 flow** | `cd forge-server && mvn clean package -pl forge-flow/forge-flow-server -am -DskipTests -Pprod` |
| **后端单独构建 app** | `cd forge-server && mvn clean package -pl forge-app-server -am -DskipTests -Pprod` |
| **启动 admin 服务** | `cd forge-server/forge-admin-server && mvn spring-boot:run` |
| **启动 flow 服务** | `cd forge-server/forge-flow && mvn spring-boot:run` |
| **启动 app 服务** | `cd forge-server/forge-app-server && mvn spring-boot:run` |
| **Docker 一键部署** | `cd docker && docker compose up -d --build` |
| **Nginx 重载配置** | `nginx -s reload` |
| **检查 Nginx 配置** | `nginx -t` |

---

## 八、常见问题

### Q1: 前端构建报内存不足
```powershell
# PC 前端构建时增大 Node 内存
$env:NODE_OPTIONS="--max-old-space-size=4096"
pnpm build
```

### Q2: H5 构建后页面白屏
- 检查 Nginx 的 `alias` 路径是否指向 `dist/build/h5/` 目录
- 检查浏览器控制台是否有 404 错误（静态资源路径不对）
- 确认 `.env.production` 中 `VITE_PUBLIC_PATH=/forge-h5` 与 Nginx location 一致

### Q3: API 请求 404/502
- 确认后端服务已启动（`curl http://127.0.0.1:8580/` 测试）
- 确认 Nginx `proxy_pass` 地址和端口正确
- 检查防火墙是否放行了后端端口

### Q4: H5 页面能打开但接口不通
- H5 连接的是 app-server（8583），不是 admin-server（8580）
- 确认 app-server 已启动
- 确认 Nginx `/forge-h5-api/` 代理到 `127.0.0.1:8583`

### Q5: 后端启动报数据库连接失败
- 检查 `application-dev.yml` 或 `application-prod.yml` 中的数据库配置
- 确认 MySQL 已启动且可访问
- 确认数据库 `forge_admin` 已创建