如何快速部署“轻便式BESP.Han（汉）框架“

admin · 2025 年7 月 17 日 01:29

BESP.Han 部署文档

本文档详细介绍了如何将 BESP.Han 项目打包并部署到生产环境。

环境要求

服务器环境

操作系统: Linux (推荐 CentOS 7+/Ubuntu 18+) 或 Windows Server
JDK: 11 或更高版本
内存: 最低 512MB，推荐 2GB+
磁盘: 最低 1GB 可用空间

项目打包

1. 指定打包类型为 jar

确保 app/pom.xml 文件中的 packaging 标签值为 jar：

<packaging>jar</packaging>

强烈建议: 从项目中获取 pom.xml、package.xml、han.sh 等配置文件，这些文件已经过优化配置。

2. Maven 插件配置

项目已配置以下关键插件：

maven-jar-plugin 插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.4.1</version>
    <configuration>
        <archive>
            <manifest>
                <mainClass>com.besp.Main</mainClass>
                <addClasspath>true</addClasspath>
                <classpathPrefix></classpathPrefix>
            </manifest>
        </archive>
        <excludes>
            <exclude>*.txt</exclude>
            <exclude>*.xml</exclude>
            <exclude>*.properties</exclude>
        </excludes>
    </configuration>
</plugin>

注意: jar 包中的配置文件优先级高于 config 目录下的同名文件，因此打包时需要排除配置文件，确保部署时 config 目录中的配置文件生效。

maven-assembly-plugin 插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.7.1</version>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
            <configuration>
                <recompressZippedFiles>false</recompressZippedFiles>
                <appendAssemblyId>true</appendAssemblyId>
                <descriptors>
                    <descriptor>package.xml</descriptor>
                </descriptors>
                <outputDirectory>${project.build.directory}/</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

3. 打包命令

开发环境打包

mvn clean package

指定环境打包

# 本地环境
mvn clean package -P local

# 开发环境
mvn clean package -P dev

# 生产环境
mvn clean package -P prod

4. package.xml 配置文件

项目根目录下的 package.xml 是打包描述文件，配置了以下打包规则：

<!-- 设置打包格式 -->
<formats>
    <format>dir</format>    <!-- 便于本地测试 -->
    <format>zip</format>    <!-- 便于 Windows 解压运行 -->
    <!-- <format>tar.gz</format> --> <!-- 便于 Linux 解压运行 -->
</formats>

文件分布规则:

src/main/resources → config/ 目录
src/main/webapp → webapp/ 目录
*.sh 脚本文件 → 根目录 (Linux 权限 755)
*.bat 脚本文件 → 根目录 (Windows)
依赖 jar 包 → lib/ 目录

部署结构

打包完成后，生成的部署包结构如下：

app-custom-release/
├── config/                 # 配置文件目录
│   ├── app.properties      # 应用配置
│   ├── besp-dev.properties # 环境配置
│   ├── log4j2-dev.xml      # 日志配置
│   └── ...
├── lib/                    # 依赖库目录
│   ├── app-custom.jar      # 主程序 jar
│   ├── jfinal-5.2.6.jar    # JFinal 框架
│   ├── hutool-*.jar        # 工具库
│   └── ...
├── webapp/                 # Web 资源目录 (可选)
│   ├── static/
│   └── ...
├── han.sh                  # Linux 启动脚本
├── han.bat                 # Windows 启动脚本 (如果有)
└── logs/                   # 日志目录 (运行时创建)

配置文件

应用配置 (config/app.properties)

# 服务器配置
undertow.port=8080
undertow.host=0.0.0.0

# 开发模式
jfinal.devMode=false

环境配置 (config/besp-prod.properties)

# 数据库配置
jdbc.url=jdbc:mysql://localhost:3306/besp_han?useSSL=false&serverTimezone=UTC
jdbc.user=your_username
jdbc.password=your_password

# Redis 配置
redis_host=localhost
redis_port=6379
redis_password=your_redis_password

# 其他环境相关配置

日志配置 (config/log4j2-prod.xml)

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
        <RollingFile name="RollingFile" fileName="logs/app.log"
                     filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <SizeBasedTriggeringPolicy size="100MB"/>
            </Policies>
            <DefaultRolloverStrategy max="30"/>
        </RollingFile>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="RollingFile"/>
        </Root>
    </Loggers>
</Configuration>

启动与停止

Linux 环境

启动应用

# 进入部署目录
cd /path/to/app-custom-release

# 启动应用
./han.sh start

停止应用

./han.sh stop

重启应用

./han.sh restart

查看启动状态

# 查看进程
ps aux | grep java

# 查看日志
tail -f logs/app.log

Windows 环境

启动应用

# 进入部署目录
cd C:\path\to\app-custom-release

# 启动应用
han.bat start

手动启动 (调试用)

# Linux/Mac
java -Xverify:none -cp config:lib/* com.besp.Main

# Windows
java -Xverify:none -cp config;lib/* com.besp.Main

多环境部署

环境配置

项目支持多环境配置，通过 Maven Profile 切换：

local: 本地开发环境
dev: 开发测试环境
prod: 生产环境

环境切换

# 打包开发环境
mvn clean package -P dev

# 打包生产环境  
mvn clean package -P prod

JVM 参数调优

编辑 han.sh 脚本，根据服务器配置调整 JVM 参数：

# 生产环境推荐配置
JAVA_OPTS="-Xms1024m -Xmx2048m -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# 开发环境配置
JAVA_OPTS="-Xms256m -Xmx1024m"

# 指定端口和主机
JAVA_OPTS="$JAVA_OPTS -Dundertow.port=8080 -Dundertow.host=0.0.0.0"

常见问题

1. 端口被占用

# 查看端口占用
netstat -tlnp | grep 8080

# 杀死占用进程
kill -9 <pid>

2. 权限问题

# 给脚本执行权限
chmod +x han.sh

# 检查 Java 权限
ls -la /usr/bin/java

3. 内存不足

# 查看内存使用
free -h

# 调整 JVM 内存参数
JAVA_OPTS="-Xms512m -Xmx1024m"

4. 配置文件不生效

确保配置文件在 config 目录下，且文件名正确：

检查环境后缀是否匹配 (如 -prod, -dev)
确认文件编码为 UTF-8
验证配置文件语法正确

5. 数据库连接失败

检查数据库配置：

# 确认数据库地址、端口、用户名、密码
jdbc.url=jdbc:mysql://localhost:3306/database_name
jdbc.user=username
jdbc.password=password

6. 查看详细日志

# 实时查看日志
tail -f logs/app.log

# 查看错误日志
grep -i error logs/app.log

# 查看启动日志
grep -i "服务启动" logs/app.log

技术支持

如遇到部署问题，请：

检查日志文件 logs/app.log
确认环境配置正确
验证依赖服务 (数据库、Redis) 可用
论坛发帖反馈

BESP.Han - 让 Java Web 开发更简单、更高效！