企业官网建设流程全解析

1. 项目背景与需求拆解

1.1 为什么会有这个需求

做过 Jeecg-Boot 项目的人都知道，它默认集成的富文本编辑器在图片上传这块走的是框架自带的通用上传接口。默认情况下，图片会被塞到本地临时目录或者某个统一的上传根路径下，路径结构往往是按日期分目录、文件名用 UUID 重命名。这套逻辑在单体部署、单机存储的场景下没什么问题，但一旦项目进入实际交付阶段，麻烦就来了。

我最近接手的一个后台管理系统就踩了这个坑。客户那边要求所有富文本里的图片必须落到对象存储的指定 bucket 下，而且路径要按业务模块区分，比如文章配图走article/目录，商品详情图走product/目录，不能全堆在一个地方。更关键的是，前端拿到的图片 URL 必须是带 CDN 域名的完整地址，而不是框架默认返回的相对路径。这就逼着我们必须把富文本编辑器的图片上传逻辑整个替换掉。

这个需求其实挺典型的。很多团队在用 Jeecg-Boot 做二次开发时，都会遇到默认上传路径不满足业务规范的问题。尤其是当项目需要对接第三方存储、需要做图片分类管理、或者需要统一走网关转发的时候，改上传路径几乎是绕不开的一步。

1.2 涉及的核心技术点

要把这件事做利索，得同时搞定几个层面的东西，缺一不可。

第一层是前端编辑器层面。Jeecg-Boot 不同版本集成的富文本编辑器不太一样，早期版本用的是 UEditor，后来陆续换成了 TinyMCE、WangEditor、Quill 等。不同编辑器的图片上传配置方式差异很大，有的靠config对象，有的靠upload回调，有的甚至要改源码里的 action 地址。你得先搞清楚自己项目里到底是哪个编辑器，才能对症下药。

第二层是上传接口层面。Jeecg-Boot 自带了一个通用的文件上传接口，通常在sys/common/upload这类路径下。这个接口内部会调用文件存储服务，把文件写到配置好的目录。我们要做的，要么是改造这个通用接口让它支持自定义路径参数，要么是另起一个专用接口专门处理富文本图片。

第三层是存储路径规则层面。路径怎么拼、按什么维度分目录、文件名怎么生成、要不要保留原始扩展名，这些都得提前定好规则。我见过有的项目路径拼得乱七八糟，后期运维找张图跟大海捞针一样。

第四层是返回格式层面。富文本编辑器对上传接口的返回格式是有要求的，通常需要返回一个包含图片 URL 的 JSON，字段名还得跟编辑器约定的一致。返回格式不对，图片就显示不出来。

1.3 适合哪些人参考

这篇内容主要面向三类人。一类是正在用 Jeecg-Boot 做项目、被富文本图片上传路径问题卡住的开发者；一类是需要对接对象存储、想把图片统一管理起来的中高级工程师；还有一类是刚接触 Jeecg-Boot、想提前了解这块坑点的新手。不管你是哪种，只要涉及到富文本图片上传的定制，这里面的思路和代码都能直接拿去改改用。

我下面会按照"先理清架构、再拆解细节、然后给完整实操、最后讲排查"的顺序来展开，尽量把每个环节的"为什么"讲透，而不是只丢一段代码让你抄。

2. 整体方案设计与选型考量

2.1 三种可选方案的对比

面对"替换富文本图片上传路径"这个需求，其实有三条路可以走，各有优劣，我先把它们摆出来对比一下。

我最终选的是方案二。原因很直接：通用上传接口在很多地方都被调用了，头像上传、附件上传、导入文件上传都走它，我要是直接改它的逻辑，万一哪个地方没考虑到，整个系统的上传功能都可能出问题。而新增一个专用接口，只服务于富文本编辑器，边界清晰，出问题也好定位。方案三虽然性能好，但涉及到临时凭证的下发和安全管理，对于一个后台管理系统来说有点杀鸡用牛刀，而且客户那边的对象存储配置也不支持前端直传，所以直接排除。

2.2 路径规则的设计思路

路径规则这块，我定的策略是"业务模块 + 日期 + 随机文件名"，拼出来大概长这样：

article/2024/06/15/a3f8c2e1b9d7408f.jpg

为什么这么设计？几个考虑。

按业务模块分目录，是为了后期做图片清理和迁移方便。比如某个模块下线了，直接把这个目录打包删掉就行，不会误伤其他模块的图。日期分目录是老传统了，好处是单个目录下的文件数量不会爆炸式增长，文件系统查找效率有保障。我见过有的项目所有图片堆一个目录，跑到几万张之后，列目录都卡。

文件名用随机字符串而不是原始文件名，主要是为了避免重名覆盖和特殊字符问题。用户上传的图片文件名五花八门，有中文的、有空格的、有超长名字的，直接拿来当存储名很容易出幺蛾子。用 UUID 或者时间戳加随机数生成一个干净的文件名，省心得多。扩展名还是要保留的，不然浏览器识别不了图片类型。

2.3 返回格式的约定

富文本编辑器对上传接口的返回格式有硬性要求。以 TinyMCE 为例，它期望返回的 JSON 里有一个location字段，值是图片的完整访问地址。WangEditor 则期望返回errno和data结构。所以我在设计接口返回时，会同时兼容几种常见格式，把该给的字段都给上，前端用哪个编辑器都能接。

这里有个细节要注意：返回的 URL 必须是完整可访问地址，不能是相对路径。因为富文本内容最终是要存到数据库、在别的页面渲染的，如果存的是相对路径，换个页面上下文就找不到图了。所以我在接口里会把配置好的域名前缀拼上去，确保返回的是https://cdn.example.com/article/2024/06/15/xxx.jpg这种形式。

提示：域名前缀建议做成配置项，不要硬编码在代码里。不同环境（开发、测试、生产）的域名不一样，硬编码后期改起来很痛苦。

3. 核心细节解析与实操要点

3.1 定位项目里用的是哪个编辑器

动手之前，第一件事是确认项目里富文本编辑器到底是哪个。Jeecg-Boot 版本迭代比较多，不同版本默认集成的编辑器不一样。判断方法很简单，去前端代码里搜关键词。

如果你在package.json里看到tinymce或者@tinymce，那就是 TinyMCE。看到wangeditor就是 WangEditor。看到quill就是 Quill。看到vue-ueditor-wrap或者ueditor就是 UEditor。还有一种情况是项目里自己封装了一个富文本组件，那就要去看那个组件的实现。

我这次的项目用的是 TinyMCE，所以后面的配置都以它为例。但思路是通用的，换成别的编辑器，无非是改配置的地方不一样，核心逻辑一致。

3.2 后端接口的路径参数怎么传

新增的专用接口，我设计成接收一个bizType参数，用来标识业务模块。前端在上传时把这个参数带过来，后端根据它决定存到哪个目录。

接口签名大概是这样：

@PostMapping("/upload/richText") public Result<?> uploadRichTextImage( @RequestParam("file") MultipartFile file, @RequestParam(value = "bizType", defaultValue = "common") String bizType) { // 处理逻辑 }

为什么用bizType而不是让前端直接传完整路径？这是出于安全考虑。如果让前端传路径，恶意用户可能传个../../之类的做目录穿越，把文件写到不该写的地方。用bizType做白名单校验，只允许预定义的几个值，安全得多。

白名单校验的代码大概这样：

private static final Set<String> ALLOWED_BIZ_TYPES = Set.of("article", "product", "common", "notice"); if (!ALLOWED_BIZ_TYPES.contains(bizType)) { return Result.error("非法的业务类型"); }

3.3 文件名的生成策略

文件名生成这块，我用的是"时间戳 + 随机数 + 原扩展名"的组合。具体代码：

String originalFilename = file.getOriginalFilename(); String extension = ""; if (originalFilename != null && originalFilename.contains(".")) { extension = originalFilename.substring(originalFilename.lastIndexOf(".")); } String fileName = System.currentTimeMillis() + "_" + UUID.randomUUID().toString().replace("-", "").substring(0, 8) + extension;

为什么不用纯 UUID？因为纯 UUID 看起来太乱，加上时间戳前缀之后，文件在目录里按名称排序天然就是按时间顺序，运维排查问题时一眼就能看出大概是什么时候传的。这个细节很小，但实际用起来很舒服。

扩展名这块要特别注意，不能直接信任前端传来的文件名。有些攻击者会把.jsp、.php之类的可执行文件伪装成图片上传。所以我在保存前会做一次扩展名白名单校验，只允许jpg、jpeg、png、gif、webp这几种。

3.4 目录的创建与写入

目录创建这块，Java 的File.mkdirs()能自动创建多级目录，用起来很方便。但有个坑要注意：如果多个请求同时上传，可能会并发创建同一个目录，虽然mkdirs()本身对已存在目录返回 false 不会报错，但为了保险，我会在创建前先判断一下。

写入文件我推荐用Files.copy()或者transferTo()，比传统的流拷贝简洁。不过要注意transferTo()在某些容器下对临时文件有依赖，如果临时目录被清理了会失败。稳妥起见，我用的是Files.copy(inputStream, targetPath, StandardCopyOption.REPLACE_EXISTING)。

Path targetDir = Paths.get(basePath, bizType, year, month, day); Files.createDirectories(targetDir); Path targetFile = targetDir.resolve(fileName); Files.copy(file.getInputStream(), targetFile, StandardCopyOption.REPLACE_EXISTING);

3.5 前端编辑器的配置改造

后端接口写好了，前端得告诉编辑器往哪传。TinyMCE 的图片上传配置在init对象里，关键是images_upload_handler这个回调。

images_upload_handler: (blobInfo, success, failure) => { const formData = new FormData(); formData.append('file', blobInfo.blob(), blobInfo.filename()); formData.append('bizType', 'article'); axios.post('/api/upload/richText', formData, { headers: { 'Content-Type': 'multipart/form-data' } }).then(res => { if (res.data.success) { success(res.data.result.url); } else { failure('上传失败：' + res.data.message); } }).catch(() => { failure('上传异常'); }); }

这里有个关键点：success回调里传的必须是图片的完整 URL，编辑器会把这个 URL 直接插到内容里。如果你传的是相对路径，编辑器也能显示，但存到数据库后在别的页面就挂了。

注意：bizType的值建议根据当前页面动态传入，而不是写死。比如文章编辑页传article，商品编辑页传product。可以在组件初始化时通过 props 或者路由参数拿到。

4. 完整实操流程与关键环节

4.1 后端接口的完整实现

我把后端接口的完整代码贴出来，你可以直接参考。先看 Controller 层：

@RestController @RequestMapping("/sys/upload") public class RichTextUploadController { @Autowired private RichTextUploadService richTextUploadService; @PostMapping("/richText") public Result<Map<String, String>> uploadRichTextImage( @RequestParam("file") MultipartFile file, @RequestParam(value = "bizType", defaultValue = "common") String bizType) { if (file.isEmpty()) { return Result.error("上传文件为空"); } try { String url = richTextUploadService.saveImage(file, bizType); Map<String, String> data = new HashMap<>(); data.put("url", url); data.put("location", url); return Result.ok(data); } catch (IllegalArgumentException e) { return Result.error(e.getMessage()); } catch (Exception e) { log.error("富文本图片上传失败", e); return Result.error("上传失败，请稍后重试"); } } }

注意返回结构里我同时放了url和location两个字段。url是给 WangEditor 这类编辑器用的，location是给 TinyMCE 用的。多给一个字段不费事，但能省掉前端适配的麻烦。

再看 Service 层的核心逻辑：

@Service public class RichTextUploadService { private static final Set<String> ALLOWED_BIZ_TYPES = Set.of("article", "product", "common", "notice"); private static final Set<String> ALLOWED_EXTENSIONS = Set.of("jpg", "jpeg", "png", "gif", "webp"); @Value("${file.upload.base-path:/data/upload}") private String basePath; @Value("${file.upload.domain:}") private String domain; public String saveImage(MultipartFile file, String bizType) throws IOException { // 1. 校验业务类型 if (!ALLOWED_BIZ_TYPES.contains(bizType)) { throw new IllegalArgumentException("非法的业务类型：" + bizType); } // 2. 校验扩展名 String originalFilename = file.getOriginalFilename(); String extension = getExtension(originalFilename); if (!ALLOWED_EXTENSIONS.contains(extension.toLowerCase())) { throw new IllegalArgumentException("不支持的文件类型：" + extension); } // 3. 生成文件名 String fileName = System.currentTimeMillis() + "_" + UUID.randomUUID().toString().replace("-", "").substring(0, 8) + "." + extension; // 4. 构建日期目录 LocalDate now = LocalDate.now(); String datePath = String.format("%d/%02d/%02d", now.getYear(), now.getMonthValue(), now.getDayOfMonth()); // 5. 创建目录并写入 Path targetDir = Paths.get(basePath, bizType, datePath); Files.createDirectories(targetDir); Path targetFile = targetDir.resolve(fileName); Files.copy(file.getInputStream(), targetFile, StandardCopyOption.REPLACE_EXISTING); // 6. 拼接访问 URL String relativePath = bizType + "/" + datePath + "/" + fileName; return domain + "/" + relativePath; } private String getExtension(String filename) { if (filename == null || !filename.contains(".")) { return ""; } return filename.substring(filename.lastIndexOf(".") + 1); } }

这段代码里有几个我特意处理的点，值得说一下。

第一，ALLOWED_BIZ_TYPES用Set.of()定义成常量，校验时contains一下就行，比写一堆if-else清爽。第二，扩展名校验放在文件名生成之前，避免生成了文件名才发现类型不对，浪费一次计算。第三，日期路径用String.format补零，保证6月显示成06，目录排序才正确。第四，URL 拼接时domain从配置读，末尾不带斜杠，中间手动加，避免出现双斜杠。

4.2 配置文件怎么写

application.yml里加上这两项：

file: upload: base-path: /data/upload domain: https://cdn.example.com

base-path是文件实际存储的根目录，domain是对外访问的域名前缀。开发环境可以配成本地路径和http://localhost:8080，生产环境换成对象存储挂载路径和 CDN 域名。

提示：如果用的是对象存储，base-path可以指向挂载点，或者干脆在 Service 里换成对象存储 SDK 的上传调用。路径规则和返回格式的逻辑不用变，只替换写入那一步。

4.3 前端组件的完整改造

前端这块，我以 Vue 项目里封装一个富文本组件为例。核心是初始化 TinyMCE 时把上传处理器替换掉。

<template> <div> <editor v-model="content" :init="editorInit" /> </div> </template> <script> import Editor from '@tinymce/tinymce-vue' export default { name: 'RichTextEditor', components: { Editor }, props: { value: String, bizType: { type: String, default: 'common' } }, data() { return { content: this.value, editorInit: { height: 500, menubar: false, plugins: 'image link lists code', toolbar: 'image link | bold italic | bullist numlist | code', images_upload_handler: this.handleUpload } } }, methods: { handleUpload(blobInfo, success, failure) { const formData = new FormData() formData.append('file', blobInfo.blob(), blobInfo.filename()) formData.append('bizType', this.bizType) this.$http.post('/sys/upload/richText', formData, { headers: { 'Content-Type': 'multipart/form-data' } }).then(res => { if (res.data.success) { success(res.data.result.location) } else { failure(res.data.message || '上传失败') } }).catch(err => { failure('网络异常，上传失败') }) } }, watch: { value(val) { this.content = val }, content(val) { this.$emit('input', val) } } } </script>

这个组件用起来就很简单了，在文章编辑页里：

<rich-text-editor v-model="article.content" biz-type="article" />

在商品编辑页里：

<rich-text-editor v-model="product.detail" biz-type="product" />

bizType一改，图片就自动存到对应目录，前端完全不用关心路径细节。

4.4 参数计算与路径示例

为了让你更直观地理解路径是怎么拼出来的，我列几个实际例子。

假设base-path是/data/upload，domain是https://cdn.example.com，今天是 2024 年 6 月 15 日。

上传一张文章配图，bizType为article，原始文件名封面图.jpg：

• 扩展名：jpg
• 生成文件名：1718438400000_a3f8c2e1.jpg
• 日期路径：2024/06/15
• 实际存储路径：/data/upload/article/2024/06/15/1718438400000_a3f8c2e1.jpg
• 返回 URL：https://cdn.example.com/article/2024/06/15/1718438400000_a3f8c2e1.jpg

上传一张商品详情图，bizType为product，原始文件名detail.png：

• 扩展名：png
• 生成文件名：1718438500000_b7d9e3f2.png
• 实际存储路径：/data/upload/product/2024/06/15/1718438500000_b7d9e3f2.png
• 返回 URL：https://cdn.example.com/product/2024/06/15/1718438500000_b7d9e3f2.png

这样每个业务模块的图片各归各的目录，日期分层，文件名唯一，后期维护起来一目了然。

5. 常见问题与排查技巧实录

5.1 图片上传成功但编辑器不显示

这是最常见的问题，八成是返回格式不对。TinyMCE 只认location字段，你返回url它就不认。解决办法是在返回结构里把location也带上，或者在前端success回调里手动取res.data.result.url传进去。

还有一种可能是返回的 URL 是相对路径，编辑器在当前页面能显示，但存到数据库后在别的页面就 404 了。排查方法是打开浏览器控制台看图片请求的实际地址，如果是/article/2024/...这种没有域名的，就是这个问题。

5.2 上传报 413 请求体过大

这是 Nginx 或者网关的限制，不是代码问题。默认情况下 Nginx 的client_max_body_size是 1M，稍微大点的图就传不上去。解决办法是在 Nginx 配置里加上：

client_max_body_size 20m;

如果前面还有网关，网关那边也要相应调整。Spring Boot 本身也有spring.servlet.multipart.max-file-size和max-request-size两个配置，默认是 1MB 和 10MB，大图场景下也要调大。

5.3 中文文件名乱码

虽然我生成的存储文件名是纯英文数字，但原始文件名如果是中文，在某些容器下getOriginalFilename()拿到的可能是乱码。不过因为我不依赖原始文件名做存储，所以这个问题对我影响不大。如果你确实需要保留原始文件名，那就要在接收时做编码转换，或者干脆在前端上传前就把文件名处理掉。

5.4 并发上传时文件名冲突

理论上时间戳加随机数已经能避免冲突了，但如果同一毫秒内有大量上传，随机数只有 8 位，还是有极小概率撞车。更稳妥的做法是用完整的 UUID，或者用Files.createFile()配合重试机制。不过对于后台管理系统这种上传量，8 位随机数足够了，我实际跑下来没遇到过冲突。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑是目录权限。有次部署到新服务器，接口一直报 500，日志里是AccessDeniedException。查了半天发现是/data/upload目录属主是 root，而应用是用另一个用户跑的，没写权限。解决办法是chown一下，或者把上传目录配到应用有权限的地方。

第二个坑是对象存储挂载延迟。如果base-path指向的是对象存储的挂载点，写入后立刻读取可能会有一点点延迟，导致刚上传的图片偶尔显示不出来。这种情况要么等挂载同步，要么直接用对象存储 SDK 上传而不是走文件系统。

第三个坑是编辑器缓存。改了上传配置后，前端页面没生效，折腾半天发现是浏览器缓存了旧的 JS。清缓存或者加版本号就好了。这种问题最气人，因为代码明明是对的。

第四个坑是路径分隔符。Windows 开发环境下路径用反斜杠，Linux 用正斜杠。我一开始用字符串拼接路径，在 Windows 上跑没问题，部署到 Linux 就出问题。后来统一用Paths.get()和resolve()，让 JDK 自己处理分隔符，就再没出过事。

6. 扩展思路与优化方向

6.1 支持图片压缩

如果上传的图片普遍比较大，可以在保存前做一次压缩。Java 里可以用Thumbnails库，几行代码就能把图片压到指定尺寸。压缩后再存，既省存储空间，又加快页面加载。不过要注意压缩会损失画质，得根据业务场景权衡。

6.2 支持多存储后端

现在代码是写死走本地文件系统的。如果想同时支持本地存储和对象存储，可以抽象一个StorageService接口，本地实现和对象存储实现各写一个，通过配置切换。这样以后换存储方案就不用改业务代码了。

6.3 图片访问鉴权

如果图片涉及敏感内容，不能公开访问，那就要在返回 URL 里带上签名或者 token。这个复杂度会高一些，需要配合后端的鉴权逻辑。一般后台管理系统的图片都是公开的，用不上这层，但如果有需求，思路是在 URL 里加一个有过期时间的签名参数。

6.4 上传进度反馈

大图上传时用户看不到进度，体验不好。可以在前端用axios的onUploadProgress回调拿到进度，配合进度条组件展示。这个改动只在前端，后端不用动。

我在实际项目里把这套方案跑通之后，图片管理确实清爽了很多。以前所有图堆在一起，想找某篇文章的配图得翻半天，现在按模块和日期分好，直接定位目录就行。而且因为返回的是完整 URL，富文本内容复制到别的系统也能正常显示，省了不少沟通成本。如果你也在被这个问题困扰，建议直接按这个思路改，改动量不大，但收益很实在。