一、项目概述

构建了一个基于 Spring Boot 的个人博客系统，采用模块化部署架构。核心特点是将配置文件、模板文件、静态资源等关键组件从 JAR 包中分离出来，实现灵活的运维管理和热更新能力。

二、技术架构设计

核心框架

后端：Spring Boot 3.x 作为主要开发框架

模板引擎：Thymeleaf 实现动态页面渲染

数据库：H2 嵌入式数据库（文件模式存储）

构建工具：Maven 进行项目构建和依赖管理

部署架构

容器化：Docker 容器化部署

反向代理：Nginx 处理域名访问和负载均衡

操作系统：CentOS 7 作为生产环境

文件存储：外部目录管理静态资源和数据文件

三、核心设计理念

资源外置策略

配置文件独立存放于 config/ 目录

模板文件放置在 templates/ 目录

静态资源（CSS/JS/图片）置于 static/ 目录

数据库文件存储在 data/ 目录

用户上传文件管理在 uploads/ 目录

分离式部署结构

主程序 JAR 不包含任何资源文件

依赖库统一打包至 lib/ 目录

支持一键升级（仅替换 JAR 包）

便于运维人员修改配置和页面内容

四、遇到的主要问题及解决方案

1. XML 配置验证错误

问题表现：IDE 中 assembly.xml 文件报错，提示无法找到元素声明

根本原因：IDE 安全策略禁止下载外部 XSD 文件进行验证

解决方案：

采用无命名空间的简化 XML 结构

避免复杂的命名空间声明

依赖 Maven 插件的内部解析逻辑而非外部验证

2. 跨平台脚本兼容性

问题表现：启动脚本在 Linux 环境下提示解释器错误

根本原因：Windows 系统使用 CRLF 换行符，Linux 系统使用 LF 换行符

解决方案：

使用 dos2unix 工具转换文件格式

在 Linux 环境下重新创建启动脚本

建立开发规范，统一使用 Unix 风格换行符

3. 静态资源访问权限问题

问题表现：Windows 环境正常，Linux 环境下静态资源 404

根本原因：

工作目录与应用目录不一致
Linux 文件系统权限限制
路径大小写敏感性差异

解决方案：

标准化启动脚本，确保在正确目录下运行
设置适当的文件系统读取权限
统一使用小写路径避免大小写问题

4. Nginx 代理配置冲突

问题表现：直接访问正常，通过域名代理后静态资源无法加载

根本原因：Nginx 静态资源匹配规则未正确配置代理

解决方案：

简化 Nginx 配置，统一代理所有请求
避免静态资源路由分裂
依赖后端应用处理所有资源请求

五、技术选型考量

选择外置资源的优势

运维友好：无需重新打包即可修改页面和配置

热更新能力：支持在线修改模板和静态文件

数据安全：数据库和上传文件独立存储

版本管理：配置与代码分离，便于不同环境管理

部署架构权衡

性能考虑：Nginx 直接代理所有请求，避免静态资源路由复杂性

维护成本：简化配置，降低运维复杂度

扩展性：为后续 CDN 集成预留接口

六、最佳实践总结

开发阶段

统一开发环境和编码规范
建立跨平台兼容性测试流程
配置文件版本化管理

部署阶段

标准化部署目录结构
自动化权限设置脚本
完整的部署验证流程
运维阶段
监控日志记录和分析
定期备份策略
健康检查和故障恢复机制

七、经验教训

环境一致性是关键：开发、测试、生产环境应尽可能保持一致
配置外置需谨慎：必须考虑权限、路径、兼容性等多方面因素
简化优于复杂：避免过度设计，选择最直接有效的解决方案
日志是排障利器：完善的日志记录能快速定位问题根源

八、未来优化方向

集成 HTTPS 证书自动更新
考虑静态资源 CDN 化部署
完善监控和告警机制
探索容器编排技术应用