企业官网建设流程全解析

1. 项目概述：当业务需求撞上PPT生成的“灰色地带”

Java程序员写PPT？听起来像在Excel里用VBA画蒙娜丽莎——技术上可行，但没人这么干。可去年底我接手一个政府侧的教育信息化项目，客户明确要求：“所有学情分析报告必须自动生成PPT，且每份报告需嵌入动态图表、校徽水印、分页页脚带时间戳，导出后直接用于校长办公会汇报。”没有UI界面，不走前端渲染，纯服务端批量生成，格式必须是标准.pptx，兼容Office 2016及以上版本。那一刻我才意识到：Apache POI不是玩具库，而是生产环境里扛着钢枪的工兵——它不负责美，只负责把结构、样式、数据、元信息一砖一瓦垒成符合ECMA-376（Office Open XML）规范的ZIP包。

这个标题里的“独特”，真不是修辞。市面上95%的PPT自动化需求都靠Python+python-pptx或前端JS库（如pptxgen.js）解决，Java生态里做这事的人少，文档散，踩坑多，连Stack Overflow上相关问题的平均回答率都不到40%。而热搜词里反复出现的“apache poi <= 4.1.0 xssfexporttoxml xxe漏洞”，恰恰说明这个库在真实世界里被用得足够深、足够重——漏洞不是出现在demo里，而是出现在银行对账单PPT、医保结算报表PPT、军工项目进度汇报PPT里。我这次做的不是“Hello World”式演示，而是每天凌晨三点定时跑批，生成287所中小学的学期教学评估PPT，单次输出文件量峰值达1.2TB，其中37%的幻灯片含嵌入式SVG矢量图，19%需插入从Oracle数据库实时拉取的JFreeChart图表图片流。这不是技术选型，这是交付契约。

你可能会问：为什么不用现成的SaaS工具？因为客户的数据不出内网；为什么不用模板引擎渲染HTML再转PDF？因为校长们坚持要用PowerPoint的“演讲者备注”功能写即兴发言提纲；为什么不用Aspose.Slides？License年费比整个项目运维成本还高。所以这条路，是被业务倒逼出来的——它不优雅，但稳；不炫技，但能上线；不教科书，但经得起审计。如果你正被类似需求卡住：Java后端要吐PPT、要保格式、要抗并发、要防漏洞、还要让非技术人员能改模板，那这篇就是为你写的实战手记。它不讲API列表，只讲我怎么把POI从“能用”调到“敢用”，把.pptx文件当成可编程的XML结构来拆解、缝合、加固。

2. 技术选型与架构设计：为什么是POI，而不是其他方案？

2.1 POI vs 替代方案：一场关于控制权的硬仗

很多人看到“Java生成PPT”第一反应是：“用Aspose吧，文档全，API顺”。我试过——Aspose.Slides for Java 22.8版，在生成含复杂母版（Master Slide）和自定义主题（Theme）的PPT时，内存占用稳定在1.8GB/份，GC停顿超3秒，集群压测下JVM频繁OOM。更致命的是，它把.pptx当作黑盒处理：你调slide.getShapes().addPicture()，它内部帮你解压、写入、重压缩，但你无法干预/ppt/slides/slide1.xml里<p:pic>节点的<a:blipFill>子节点是否启用了dpi属性优化。而我们的需求里，所有插入的PNG图表必须强制设为96dpi（非默认的220dpi），否则打印出来模糊。Aspose不暴露底层XML操作入口，我们只能妥协——结果是校长反馈“投影仪上看不清柱状图”。

再看Python方案。python-pptx确实灵活，但部署在客户Linux服务器上要装Python 3.9+、pip、numpy、Pillow一堆依赖，运维团队拒绝背这个锅。而且Java服务已跑在K8s里，再起Python Sidecar，链路监控、日志聚合、熔断降级全得重做——成本远超技术本身。

最后是前端方案。用pptxgen.js在Node.js里生成，再通过HTTP API传给Java服务？延迟高、网络不可靠、二进制流传输易出错。更关键的是，客户要求PPT里嵌入的Excel表格必须支持“双击编辑”，这需要OLE对象嵌入（Object Linking and Embedding），而JS方案生成的只是静态图片快照，点不开。

POI胜出的核心原因就一条：它把Office Open XML规范翻译成了Java对象，让你能像操作DOM一样操作PPTX的每一个XML节点。.pptx本质是个ZIP包，里面是[Content_Types].xml、_rels/.rels、ppt/presentation.xml等几十个XML文件。POI不封装这些细节，它提供XSLFSlideShow、XSLFSlide、XSLFShape等类，背后对应的就是slide1.xml里的<p:sld>、<p:cSld>、<p:sp>等元素。这意味着——

• 你能精确控制<p:txBody>里的<a:pPr>段落属性，比如把“教学目标”文本设为<a:lnSpc val="120000"/>（行距1.2倍）；
• 你能手动注入<p:extLst>扩展列表，添加客户定制的<p14:chartBuild>动画指令；
• 你能遍历/ppt/slideLayouts/目录，把slideLayout1.xml里<p:cSld><p:spTree>的<p:sp>节点复制到新幻灯片，实现母版复用。

这不是便利性选择，而是控制粒度的选择。当业务规则细到“第3页图表标题字号必须是18.5pt（非整数），且仅对该页生效”，只有POI给你手术刀。

2.2 版本陷阱：4.1.0之后的“安全”与“可用”博弈

热搜词里反复出现的apache poi <= 4.1.0 xssfexporttoxml xxe漏洞，是POI生态里绕不开的坎。这个漏洞本质是：旧版POI在导出XSSF（Excel）时，若用户可控XML内容含外部实体引用（如<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>），会触发XXE。虽然漏洞载体是XSSF，但很多项目同时用poi-ooxml（PPT）和poi-ooxml-schemas（XML Schema），共用同一套XML解析器。客户安全扫描扫出CVE-2017-5644，要求必须升级。

我们试了POI 5.2.4——官方宣称修复所有XXE，但实测发现两个致命问题：

1. XSLFTextParagraph.setBulletFontFamily("SimSun")失效，中文项目符号变成方块；
2. 插入SVG时，XSLFPictureData.addData()方法对image/svg+xmlMIME类型校验变严，客户提供的SVG文件若含<?xml version="1.0"?>声明，直接抛IllegalArgumentException。

翻源码才发现，5.x版把XML解析从DocumentBuilder换成了SAXParser，并加了setFeature("http://apache.org/xml/features/disallow-doctype-decl", true)，但没同步更新SVG解析逻辑。最终方案是：锁死POI 4.1.2（已打补丁），配合白名单XML解析器。具体做法：

• 在pom.xml中排除poi-ooxml-schemas的传递依赖；
• 手动引入org.apache.xmlbeans:xmlbeans:5.1.0（安全版）；
• 自定义XMLSlideShow构造函数，传入预配置的DocumentBuilder实例，禁用外部DTD加载：

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true); factory.setFeature("http://xml.org/sax/features/external-general-entities", false); DocumentBuilder builder = factory.newDocumentBuilder(); // 后续用builder.parse()处理所有XML操作

这招让我们既规避了XXE，又保住4.1.x的兼容性。POI官网文档从不提这个组合方案，但它在金融、政务类项目里已是事实标准。

2.3 架构分层：把PPT生成变成可测试、可灰度的服务

我们没把PPT生成塞进Controller里。整个流程拆成四层：

• 模板层：.pptx文件存OSS，带版本号（如report_v2.3.pptx），每次更新自动触发CI校验；
• 数据层：DTO对象严格按幻灯片页码索引，如ReportData.slides[0].title = "教学质量分析"；
• 渲染层：核心PptGenerator类，接收模板流和DTO，返回byte[]，内部用XSLFSlideShow逐页填充；
• 交付层：Spring Integration流，支持异步队列（RabbitMQ）、失败重试（指数退避）、限流（令牌桶）。

关键设计点是模板热加载。客户常临时改母版字体，我们不想重启服务。方案是：

• 每个模板路径配ETag，启动时加载到ConcurrentHashMap<String, XSLFSlideShow>；
• 定时任务（Quartz）每5分钟检查OSS文件MD5，变化则新建XSLFSlideShow实例，旧实例标记为@Deprecated；
• 渲染时用computeIfAbsent获取实例，保证线程安全。

这套架构让PPT生成从“偶发功能”变成“核心服务”。上线后，单机QPS从12提升到87（JMeter压测），错误率低于0.03%，而最值钱的——是客户能自己上传新模板，30秒后新格式就生效，再也不用等我们发版。

3. 核心实现细节：从XML结构到像素级控制

3.1 解剖PPTX：ZIP包里的XML宇宙

.pptx不是二进制黑盒，它是ZIP压缩包，解压后结构如下：

├── [Content_Types].xml # 全局MIME类型注册表 ├── _rels/.rels # 关系文件（指向各部件） ├── docProps/app.xml # 应用属性（生成软件、编辑次数） ├── docProps/core.xml # 核心属性（作者、创建时间） ├── ppt/ # PPT核心目录 │ ├── _rels/presentation.xml.rels # presentation.xml的关系 │ ├── presentation.xml # 幻灯片总控（顺序、母版引用） │ ├── slideLayouts/ # 母版布局（layout1.xml, layout2.xml...） │ ├── slides/ # 实际幻灯片（slide1.xml, slide2.xml...） │ ├── theme/ # 主题（theme1.xml） │ └── media/ # 媒体文件（image1.png, image2.jpeg...） └── ppt/media/ # （同上，旧版路径）

POI的XMLSlideShow类，本质就是对这个ZIP结构的Java封装。比如slide.getShapes()，实际是在读slides/slide1.xml里<p:cSld><p:spTree>下的所有<p:sp>（形状）节点；slide.getBackground().setFillColor(Color.RED)，则是往<p:bg><p:bgRef idx="1"/>对应的theme/theme1.xml里<a:clrScheme>节点注入新颜色。

理解这点，才能突破POI API的限制。例如客户要求“所有标题文字阴影偏移量为X=2pt, Y=2pt”，POI没提供setShadowOffset()方法。但你知道<p:txBody><p:bodyPr>里有<a:sp3d>节点，于是直接操作XML：

// 获取slide1.xml的Document对象 Document doc = slide.getXmlObject().getOwnerDocument(); NodeList titleShapes = doc.getElementsByTagName("p:sp"); for (int i = 0; i < titleShapes.getLength(); i++) { Element sp = (Element) titleShapes.item(i); if ("title".equals(sp.getAttribute("use"))) { // 判断是否为标题占位符 Element bodyPr = (Element) sp.getElementsByTagName("p:bodyPr").item(0); Element sp3d = doc.createElementNS("http://schemas.openxmlformats.org/drawingml/2006/main", "a:sp3d"); sp3d.setAttribute("z", "0"); sp3d.setAttribute("extrusionH", "0"); sp3d.setAttribute("contourW", "0"); // 关键：设置阴影偏移 Element shadow = doc.createElementNS("http://schemas.openxmlformats.org/drawingml/2006/main", "a:shadow"); shadow.setAttribute("algn", "tl"); // top-left shadow.setAttribute("sx", "100000"); // X偏移（单位1/12700英寸，2pt≈200000） shadow.setAttribute("sy", "100000"); // Y偏移 sp3d.appendChild(shadow); bodyPr.appendChild(sp3d); } }

这段代码绕过POI API，直击XML，把阴影参数写死。它不优雅，但解决了问题——而这就是生产环境的真实。

3.2 动态图表：把JFreeChart塞进PPT的三种姿势

客户PPT里37%的幻灯片含图表，且必须是动态生成（数据来自实时SQL查询）。POI不支持图表渲染，只能插图。我们试了三种方案：

方案1：JFreeChart → PNG → XSLFPictureData
最常用，但有坑：JFreeChart默认DPI是72，插入PPT后放大模糊。解决方案：

JFreeChart chart = ChartFactory.createBarChart(...); chart.setRenderingHints(new RenderingHints( RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON)); BufferedImage image = new BufferedImage(800, 600, BufferedImage.TYPE_INT_ARGB); Graphics2D g2 = image.createGraphics(); g2.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON); chart.draw(g2, new Rectangle(0, 0, 800, 600)); g2.dispose(); // 关键：设置DPI为96 ByteArrayOutputStream baos = new ByteArrayOutputStream(); ImageIO.write(image, "png", baos); byte[] pngBytes = baos.toByteArray(); XSLFPictureData picData = ppt.addPicture(pngBytes, PictureData.Kind.PNG); // 插入时指定尺寸（避免PPT自动缩放） XSLFPictureShape pic = slide.createPicture(picData); pic.setAnchor(new Rectangle(100, 100, 600, 400)); // 单位：EMU（1EMU=1/914400英寸）

方案2：JFreeChart → SVG → Apache Batik → PNG
SVG矢量图缩放不失真，但Batik渲染慢。我们做了缓存：

• 对相同SQL查询哈希值（MD5），查Redis缓存PNG字节；
• 缓存未命中时，用BatikPNGTranscoder转SVG，存入OSS；
• PPT生成时直接下载PNG，省去本地渲染。

方案3：Excel图表嵌入（OLE）
客户要求“双击编辑”，只能用OLE。POI不支持，但XSLFSlide允许插入OLE对象：

// 生成Excel文件（用POI的XSSFWorkbook） XSSFWorkbook excel = new XSSFWorkbook(); // ... 写入数据 ByteArrayOutputStream excelStream = new ByteArrayOutputStream(); excel.write(excelStream); // 创建OLE对象（需Windows系统，Linux需Wine） XSLFOLEShape ole = slide.createOLEShape(); ole.setAnchor(new Rectangle(100, 100, 600, 400)); ole.setData(excelStream.toByteArray()); ole.setProgId("Excel.Sheet.12"); // OLE程序ID

注意：OLE在Linux服务器上会失败，我们用Docker挂载Windows Server Core容器专门跑OLE生成，Java服务通过gRPC调用——这是为“双击编辑”付出的架构代价。

3.3 母版与版式：复用不是复制，是继承

客户有12种PPT模板（年度报告、月度简报、专项评估...），每种含3-5个母版。POI的XSLFSlide不直接关联母版，而是通过<p:sld><p:cSld><p:bg><p:bgRef idx="1"/>引用slideLayouts/layout1.xml。我们设计了母版继承链：

• base_master.pptx：定义基础字体、配色、页脚；
• report_master.pptx：继承base，加“教学评估”专用logo；
• executive_master.pptx：继承report，加“校长办公会”水印。

实现方式：

1. 加载base_master.pptx，提取slideLayouts/layout1.xml内容；
2. 加载report_master.pptx，将其slideLayouts/layout1.xml中<p:cSld>节点的<p:bg>、<p:txStyles>子节点，替换为base的对应节点；
3. 保存新布局到内存ZIP流，作为report_master的母版。

这样，改base字体，所有继承模板自动生效。代码里用Document.importNode()完成节点迁移，比POI的cloneSheet()更可控。

3.4 安全加固：堵住XML解析的每一处缝隙

除了前面说的XXE防护，还有三个隐形风险点：

风险1：外部字体引用
客户模板里有<a:fontScheme><a:font id="1" name="华文仿宋"/>，POI加载时会尝试从系统字体目录加载。若攻击者上传含<a:font name="C:\Windows\System32\calc.exe"/>的模板，可能触发命令执行。
→ 解决方案：重写XSLFSlideShow的字体加载逻辑，只允许白名单字体（SimSun,Microsoft YaHei,Arial），其他一律fallback为Arial。

风险2：宏病毒（VBA）
.pptx可含/ppt/vbaProject.bin，POI默认不处理。但客户上传的模板若带恶意宏，生成的新PPT会继承。
→ 解决方案：在模板校验阶段，用ZipInputStream扫描ZIP条目，若发现vbaProject.bin或/ppt/_rels/vbaProject.bin.rels，直接拒绝。

风险3：路径遍历
XSLFSlideShow构造函数接受File参数，若传入../../../etc/passwd，可能读取敏感文件。
→ 解决方案：统一用InputStream构造，且对所有输入流做IOUtils.toString(stream, "UTF-8")前，先校验ZIP条目名不含..。

这些不是POI文档里的内容，而是我们在等保三级测评中被扣分后补上的补丁。

4. 实战全流程：从零到上线的12个关键步骤

4.1 步骤1：环境准备——JDK与依赖的精准匹配

POI 4.1.2要求JDK 8u191+，但客户服务器是CentOS 7，默认OpenJDK 1.8.0_131。升级JDK会引发其他Java服务兼容性问题。我们选择JDK侧载：

• 下载jdk-8u202-linux-x64.tar.gz（Oracle JDK，含最新安全补丁）；
• 解压到/opt/jdk8u202，不替换系统JDK；
• 在PPT生成服务的start.sh里显式指定：

  export JAVA_HOME=/opt/jdk8u202 export PATH=$JAVA_HOME/bin:$PATH java -jar ppt-generator.jar

Maven依赖精简到最小集：

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>4.1.2</version> <!-- 排除危险的xmlbeans --> <exclusions> <exclusion> <groupId>org.apache.xmlbeans</groupId> <artifactId>xmlbeans</artifactId> </exclusion> </exclusions> </dependency> <!-- 手动引入安全版xmlbeans --> <dependency> <groupId>org.apache.xmlbeans</groupId> <artifactId>xmlbeans</artifactId> <version>5.1.0</version> </dependency>

理由：POI 4.1.2自带的xmlbeans 3.0.2有反序列化漏洞（CVE-2019-12418），必须替换。

4.2 步骤2：模板制作——设计师与开发者的交接清单

客户设计师用PowerPoint 2019做模板，我们给她一份《PPTX开发友好指南》：

• ✅ 允许：使用内置母版、占位符（Title, Content, Picture）、主题颜色；
• ❌ 禁止：嵌入字体（导致文件过大）、3D模型、墨迹笔迹、动画触发器；
• ⚠️ 注意：所有图片占位符必须设为“锁定纵横比”，否则POI插入时变形；
• 📏 尺寸：幻灯片尺寸固定为13.33×7.5英寸（16:9），所有坐标单位按EMU计算（1英寸=914400EMU）。

我们提供了一个校验工具：上传PPTX，自动检测违规项并生成报告。一次审核，设计师改了37处，从此模板一次过。

4.3 步骤3：DTO建模——让数据结构匹配幻灯片逻辑

不是把JSON塞进PPT，而是按幻灯片页码建模。DTO示例：

public class ReportData { public String reportTitle; // 第1页标题 public List<SlideData> slides; // 每页数据 } public class SlideData { public int pageIndex; // 页码（1-based） public String title; // 标题文本 public List<ChartData> charts; // 图表列表 public List<String> bulletPoints; // 项目符号列表 public byte[] watermarkImage; // 水印图片（byte[]） }

关键设计：pageIndex字段。POI的slide.getSlideNumber()返回的是物理页码（1,2,3...），但客户要求“第3页”永远显示“教学质量分析”，不管前面是否插入了封面页。所以我们用XSLFSlide的getSlideIndex()（0-based索引）映射到DTO的pageIndex，确保逻辑页码与物理页码解耦。

4.4 步骤4：字体嵌入——解决中文乱码的终极方案

POI默认用java.awt.Font渲染，但Linux服务器无中文字体。常见方案是Font.createFont()加载TTF，但客户禁止上传字体文件（版权风险）。最终方案：用Apache PDFBox的字体子集技术。

• 从客户提供的simhei.ttf（黑体）中，提取PPT里实际用到的汉字（如“教学质量分析”共8个字）；
• 生成精简TTF（<10KB），存OSS；
• POI插入时，用XSLFTextRun.setFontFamily("SimHeiSubset")，并确保模板里该字体已注册。

代码片段：

// 用PDFBox提取子集 PDType0Font font = PDType0Font.load(doc, new File("simhei.ttf")); String text = "教学质量分析"; PDType0Font subsetFont = font.getSubset(text); // 返回子集字体 // 将subsetFont的字节流存为simhei_subset.ttf

这样既合规，又解决乱码，文件体积还小。

4.5 步骤5：图片处理——压缩与尺寸的平衡术

客户原始图表PNG平均2.1MB，插入PPT后单文件超50MB。我们做了三重压缩：

1. 尺寸裁剪：用Thumbnailator将800×600图缩至600×450（PPT显示区大小），质量85%；
2. PNG优化：用pngquant命令行工具（Java调Runtime.exec()），减少颜色数；
3. PPT内嵌优化：POI插入时，设置XSLFPictureData的setCompressionLevel(8)（最高）。

实测：单图从2.1MB→186KB，PPT总大小从62MB→14MB，打开速度提升4倍。

4.6 步骤6：水印注入——动态生成而非静态贴图

客户要求水印带当前时间（“2024年05月23日 14:22:37”），且半透明。POI不支持水印API，但我们发现<p:bg>节点可加<p:bgPr>的<a:fill>，用<a:blipFill>引用一张PNG水印图。方案：

• 启动时生成一张透明PNG水印（含时间占位符{timestamp}）；
• 渲染时，用ImageIO动态写入当前时间，生成新PNG流；
• 插入PPT时，用addPicture()添加此流。

为避免每次生成PNG的IO开销，我们用BufferedImage内存缓存：

private static final Map<String, byte[]> WATERMARK_CACHE = new ConcurrentHashMap<>(); public byte[] getWatermark(String timestamp) { String key = "watermark_" + timestamp; return WATERMARK_CACHE.computeIfAbsent(key, k -> { BufferedImage img = new BufferedImage(1000, 600, BufferedImage.TYPE_INT_ARGB); Graphics2D g = img.createGraphics(); g.setColor(new Color(0, 0, 0, 30)); // 半透明黑 g.setFont(new Font("SimSun", Font.BOLD, 48)); g.drawString(timestamp, 200, 300); g.dispose(); // 转PNG字节 ByteArrayOutputStream baos = new ByteArrayOutputStream(); ImageIO.write(img, "png", baos); return baos.toByteArray(); }); }

4.7 步骤7：页脚时间戳——XML级精准控制

客户要求页脚显示“生成时间：2024-05-23 14:22:37”，且字体为10号。POI的slide.getFooter()只能设文本，不能设字体。我们直接改slide1.xml：

// 获取页脚占位符的<p:sp>节点 NodeList footerSp = doc.getElementsByTagName("p:footer"); if (footerSp.getLength() > 0) { Element sp = (Element) footerSp.item(0); Element txBody = (Element) sp.getElementsByTagName("p:txBody").item(0); Element p = (Element) txBody.getElementsByTagName("a:p").item(0); Element r = (Element) p.getElementsByTagName("a:r").item(0); Element t = (Element) r.getElementsByTagName("a:t").item(0); t.setTextContent("生成时间：" + LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))); // 设置字体 Element rPr = (Element) r.getElementsByTagName("a:rPr").item(0); rPr.setAttribute("sz", "2000"); // 10号=2000半磅 rPr.setAttribute("latin", "Arial"); rPr.setAttribute("ea", "SimSun"); }

4.8 步骤8：异常处理——让失败变得可诊断

POI报错常是NullPointerException或XmlValueOutOfRangeException，不指明哪一页哪个形状。我们加了上下文包装：

try { generateSlide(slide, data.slides.get(i)); } catch (Exception e) { throw new PptGenerationException( String.format("生成第%d页失败（模板：%s，数据ID：%s）", i+1, templateName, data.getId()), e); }

日志里自动带页码、模板名、数据ID，运维定位问题从2小时缩短到2分钟。

4.9 步骤9：性能调优——从12QPS到87QPS的实操

瓶颈在XSLFSlideShow构造和write()。优化点：

• 构造优化：模板XSLFSlideShow实例复用，避免重复解压ZIP；
• 写入优化：用ByteArrayOutputStream替代FileOutputStream，减少磁盘IO；
• GC优化：JVM参数加-XX:+UseG1GC -XX:MaxGCPauseMillis=200；
• 线程池：PptGenerator用ForkJoinPool.commonPool()，非Executors.newCachedThreadPool()（避免线程爆炸）。

压测对比：

4.10 步骤10：灰度发布——让新模板零风险上线

新模板上线不直接切流，而是：

• 配置中心设ppt.template.version=report_v2.3；
• 新增ppt.template.canary=0.05（5%流量走新模板）；
• 监控指标：生成成功率、文件大小、打开耗时；
• 若成功率<99.5%，自动回滚版本。

4.11 步骤11：审计日志——满足等保三级要求

每份PPT生成记录：

• 模板SHA256；
• 数据DTO的MD5（脱敏后）；
• 生成时间、IP、操作人；
• 文件大小、页数、图表数；
• 签名（用RSA私钥对上述字段签名）。

存ES，保留180天，供审计抽查。

4.12 步骤12：交付物打包——不只是jar包

给客户的交付物包括：

• ppt-generator.jar（Spring Boot可执行包）；
• config/application.yml（含OSS、DB、模板URL配置）；
• docs/运维手册.md（含重启、日志查看、模板更新流程）；
• test/ppt-template-validator.jar（模板校验工具）；
• security/漏洞修复说明.pdf（解释POI版本选择与加固措施）。

这才是企业级交付——不是扔个jar包了事。

5. 常见问题与避坑指南：血泪总结的21个实战技巧

5.1 POI特有坑：API与XML的鸿沟

5.2 Office Open XML规范坑：你以为的常识其实是陷阱

5.3 生产环境坑：服务器、网络、权限的现实约束

| 问题