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 开发模式

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

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

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

2.2 生产构建

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 部署到服务器

# 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 开发模式

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

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

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

3.2 生产构建

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 部署到服务器

# 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（推荐）

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

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 包启动服务

# 启动顺序：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 部署到服务器

# 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）：

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 一键部署：

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：

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: 前端构建报内存不足

# 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 已创建

构建与部署指南.md 12 KB Historia Raaka