# officecli-go-project

**Repository Path**: aylerh/officecli-go-project

## Basic Information

- **Project Name**: officecli-go-project
- **Description**: 功能：PowerPoint拼接与转换;Word替换与转换;Excel替换与修改;转PDF（图片式）;PDF转图片;缺点- 图片式转换速度较慢：约2.6秒每页；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OfficeCli Go Project Document Processing System

OfficeCli Go Project 是一款专为企业级高吞吐、高清排版设计的**文档处理与拼接服务中心**。系统基于 Go + Gin 框架构建，在 Docker 容器化环境中深度集成 OfficeCLI 与 Headless 离线渲染管道，提供极其精美的前端交互面板以及全功能的 RESTful API 接口。

---
## 缺点
- 图片式转换速度较慢：约2.6秒每页；

## 页面样式

### 主页

![1](./images/1.png)

### 拼图

![2](./images/2.png)

## 💡 解决的痛点

在企业级文档自动化和 AI Agent 的集成流程中，处理 Microsoft Office 文件（Word、Excel、PowerPoint）往往面临着以下棘手痛点：

1. **排版跑偏与样式丢失（PPTX 渲染难题）**：
   - *痛点*：许多开源解析工具在将 PPTX 转为图片时，排版会严重错位，动画、艺术字、图表或渐变色会大面积丢失。
   - *解决*：本系统集成业界最成熟的 **LibreOffice Headless Core** 进行高保真 PDF 渲染，并配合基于 C++ 编写的超高速 **pdftoppm** 帧提取引擎和 **go-image-merge**，完美还原 PPTX 原始设计的每一个像素，并秒级组装为网格拼接大图。
2. **极高的系统开销与内存溢出（OOM 痛点）**：
   - *痛点*：传统的 PPT-to-PNG 解决方案常在 Docker 中跑无头浏览器（Headless Chrome），这不仅要塞入近 1GB 的 Chromium 依赖包，更在并发时消耗数个 G 的内存，极易导致服务器 OOM 崩溃。
   - *解决*：采用轻量级 `LibreOffice-nogui` 与 `pdftoppm` 管道，省去了庞大的浏览器内核启动开销，将图像提取速度缩短了近 60%，系统并发处理吞吐量大幅提高。
3. **Office 商业授权与跨平台依赖**：
   - *痛点*：修改 Word 和 Excel 里的文字，传统手段需要在 Windows 服务器上安装并授权巨型的 MS Office 套件，这在 Linux / Docker 容器化部署中是无法实现的。
   - *解决*：整合了单文件免依赖开源神器 **OfficeCLI**，以直接操控底层 OpenXML 节点树的方式对 `.docx` / `.xlsx` 文件执行**毫秒级**的原位文本替换，完美运行在任意 Linux 容器环境。
4. **批量归档压缩的冗余碎片**：
   - *痛点*：对含有大量无关文件的 ZIP 压缩包进行批量文本替换时，重新打包会混入各种非办公格式碎片（如临时隐藏文件、图片、日志等）。
   - *解决*：系统在 ZIP 管道中加入了自动化纯净过滤器，在对压缩包内所有的 Word / Excel 进行查找替换后，**仅保留修改后的 Office 办公格式文件**重新封装，提供干净整洁的最终交付包。
5. **Linux 容器中文字体缺失（“豆腐块”/乱码难题）**：
   - *痛点*：标准的 Docker 基础镜像（如 Debian Slim）不附带任何中文字体，导致 LibreOffice 渲染中文 PPTX 时，页面文字变成豆腐块 `[] [] []`，造成排版失真。
   - *解决*：在 Docker 运行时镜像中整合了 **WenQuanYi (文泉驿) 微米黑与正黑** 高质量中文字体包，使得 LibreOffice Headless 在无图形环境里也能够完美解析并渲染高清的中文矢量字体，输出精美的网格图。

---

## ⚠️ 局限性与缺点

虽然系统在**离线排版还原度**与**安全防泄露**上做到了极致，但由于其特殊的技术架构，目前存在以下缺点：

*   **处理速度较慢**：
    *   *原因*：在执行 PowerPoint/PDF 拼接、转换为图片式 PPTX/PDF/DOCX 等操作时，系统需要启动 Headless 模式的离线 LibreOffice 将文档输出为临时 PDF，再调用 pdftoppm 渲染引擎提取为图片，并配合 Go 语言标准库对图像进行百分比裁剪、高保真缩放与拼合。
    *   *影响*：对于页数较多（例如 30 页以上）的演示文稿或复杂文档，处理耗时可能在数秒至数十秒之间。
    *   *折中方案*：尽管速度较慢，但这换取了 **100% 离线运行、无需商业 Office 授权、完美的字体和排版高保真度** 以及 **数据隐私零泄露风险**，极其适合对输出排版复原度要求苛刻且对数据合规性高度敏感的企业级私有化部署。

---

## 🛠️ 采用的技术栈

本系统采用现代微服务与云原生架构，具体技术选型如下：

*   **后端开发**：
    *   **Go (1.24)**：极高的并发运行效率与超低内存开销。
    *   **Gin 框架**：轻量级、路由性能优异的 HTTP 框架。
    *   **Swagger (swag)**：自动生成符合 OpenAPI 标准的交互式 API 接口文档，实现前后端分离的无缝开发调试。
*   **文档解析与原位操作**：
    *   **OfficeCLI**：专为 AI 设计的 OpenXML 结构操纵二进制，支持使用正则表达式和 `(?i)` 正则标记进行大小写不敏感匹配替换。
*   **排版渲染与拼接引擎**：
    *   **LibreOffice Core**：Headless 模式（Nogui），集成了 **WenQuanYi 矢量中文字体包**，保障 OpenXML 向 PDF 转换时的极限排版复原度与中文字符的完美呈现。
    *   **pdftoppm (poppler-utils)**：基于 C++ 的超快 PDF 页面提取器，代替了沉重、有安全限制的 ImageMagick PDF 转换器。
    *   **go-image-merge**：动态组装图片为行列拼接图，具备空白网格白色画布安全填充防崩溃机制。
*   **前端交互设计 (Sleek UI)**：
    *   **Vanilla CSS / HTML5**：完全摒弃冗余的打包器，使用原生高端毛玻璃（Glassmorphism）质感。
    *   **HSL 调色盘与渐变光晕**：采用深紫/青绿极光渐变，配合现代 Outfit / Inter 字体与 Lucide 图标 SVG 结构。
    *   **拖拽上传 API**：支持在 PPT / Word / Excel 标签页直接通过文件拖放执行上传、一键下载。
*   **云原生构建**：
    *   **Docker & Docker Compose**：多阶段构建，编译阶段使用国内加速代理 `goproxy.cn,direct`；运行时合并全部依赖到轻量级 Slim 镜像中。

---

## 🚀 启动与使用指南

### Windows PowerShell 一键启动

在 Windows 11/10 操作系统中，打开 PowerShell (pwsh) 终端进入项目目录，执行以下命令：

```powershell
docker pull golang:1.24-bookworm
docker pull debian:bookworm-slim

# 1. 确保已复制和配置好本地的挂载数据目录
# 2. 编译并拉起 Docker 服务隔离环境
docker compose down;docker compose up --build -d
```

启动完成后，系统将自动读取 `.env` 中的端口设置：
- **Web 交互主页**：[http://localhost:8206](http://localhost:8206) (空路径 302 自动重定向)
- **Swagger API 接口文档**：[http://localhost:8206/docs/index.html](http://localhost:8206/docs/index.html)

### 容器目录挂载与数据卷

在 `docker-compose.yml` 中默认配置了数据卷挂载：
```yaml
volumes:
  - "H:/docker-data/officecli-go-project-data/data:/app/data"
```
所有从接口处理的零星数据均在此容器数据卷或 `/app/tmp` 临时虚拟硬盘中安全隔离完成，执行完毕后系统将立刻进行物理删除，保障您的数据隐私。