# office_oxide-edit-project

**Repository Path**: aylerh/office_oxide-edit-project

## Basic Information

- **Project Name**: office_oxide-edit-project
- **Description**: office文件的文本批量替换：## 优点- 替代速度快：office-cli约1.x秒每页；本项目为6毫秒每页；- 保留原有版式；- 占用内存小：18M左右；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 概览

本项目是基于高性能 Rust 核心文档引擎 [office_oxide](https://github.com/yfedoseev/office_oxide) 与 Go 1.24、Gin Web 服务器及 Huma 框架构建的高并发 Office 文档文本内容批量替换微服务。系统支持现代 OOXML（DOCX、PPTX、XLSX）与传统二进制（DOC、PPT、XLS）格式的自动识别嗅探、无损文本批量替换、多文件与 ZIP 递归解压处理、精准页数与耗时度量统计，并提供单文件及 ZIP 打包一键下载功能。

## 空间占用
ayler/office-oxide-base：1.13G
ayler/office-oxide-service:36.64M;
内存占用：18M;

## 优点
- 替代速度快：office-cli约1.x秒每页；本项目为6毫秒每页；
- 保留原有版式；
- 占用内存小：18M左右；

## 页面样式

### 主页

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

---

# 构建与运行

系统采用两阶段 Docker 镜像架构（基础构建层预编译底层依赖，运行时采用极简 Distroless 二进制环境）：

### 1. 基础镜像构建（预缓存 Cgo 底层依赖与 Go Modules）

```powershell
$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; docker compose -f docker-compose-base.yml build
```

### 2. 启动应用服务（业务秒级构建并启动容器）

```powershell
$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; docker compose up --build -d
```

启动完成后：
- 🖥️ **Web 交互控制台**：http://localhost:8266/
- 📄 **OpenAPI 3.1 交互文档**：http://localhost:8266/docs
- 📡 **OpenAPI 规范定义**：http://localhost:8266/openapi.json

---

# 解决痛点与使用技术

### 1. 解决的核心痛点
- **文档版式与样式无损保护**：传统文档替换工具容易破坏 Word 排版或样式丢失，本项目结合 `office_oxide` OPC 句柄与精准 XML 节点操作，仅针对文字进行精确替换，完整保留图片、图表、字体与母版版式。
- **Huma 运行时自动生成 OpenAPI 3.1**：基于 Go 类型安全 Struct 自动产出标准化 OpenAPI 3.1 接口架构，并在 `/docs` 原生提供交互式调试界面，杜绝接口文档与代码脱节。
- **根路径防缓存智能重定向**：API 客户端访问根路径时实施 302 重定向至 `/docs`，并强制注入 `Cache-Control: no-cache, no-store, must-revalidate`、`Pragma: no-cache` 和 `Expires: 0` 标头，彻底杜绝代理网关与浏览器缓存旧版 API 导致的重定向死循环。
- **极致小巧与运行隔离**：采用 `gcr.io/distroless/cc-debian12` 作为运行层，剔除所有冗余系统工具与包管理器，容器体积从传统数百兆缩减至约 20MB，兼具极速启动与高度安全性。
- **解耦基础构建层杜绝重复下载**：通过 `Dockerfile.base` 将底层动态库 `liboffice_oxide.so` 与全局第三方 Go 依赖固化，业务代码变动时秒级构建，避免网络中断或重复下载依赖。

### 2. 项目技术栈
- **核心开发语言**：Go 1.24（Cgo 启用，与底层 Rust 动态库通信）
- **Web 引擎**：Gin Web Framework
- **API 规范**：Huma v2 (OpenAPI 3.1 / JSON Schema)
- **文档底层内核**：office_oxide (Rust Core + C-FFI)
- **容器编排**：Docker & Docker Compose V2 (无 version 声明，restart: unless-stopped)
- **运行时环境**：Google Distroless (Debian 12 cc)
- **前端技术**：原生 HTML5 + Vanilla CSS (Glassmorphism 玻璃拟态风格) + ES6 JavaScript

---

# 项目结构

```text
├── .env                              # 环境变量配置文件 (INNER_PORT=8266, OUTER_PORT=8266)
├── Dockerfile.base                   # 通用底层基础镜像 (固化 liboffice_oxide.so 与依赖缓存)
├── docker-compose-base.yml           # 基础镜像构建编排文件
├── Dockerfile                        # 多阶段应用构建文件 (Distroless 极简运行时)
├── docker-compose.yml                # 微服务容器编排文件
├── go.mod / go.sum                   # Go 模块与依赖定义
├── cmd/
│   └── server/main.go                # 程序启动入口与端口监听
├── internal/
│   ├── handler/                      # HTTP 接口处理器与 DTO
│   ├── routes/                       # 路由注册、内容协商、Huma OpenAPI 与防缓存重定向
│   └── service/                      # 批量替换、并发控制、ZIP 打包业务核心
├── pkg/
│   ├── archive/                      # ZIP 防穿越安全解压与多文件打包
│   ├── officeoxide/                  # Cgo 封装驱动与 OOXML 文本替换双保险
│   └── stats/                        # DOCX/PPTX/XLSX 页数精准统计与性能度量
├── web/                              # 前端单页应用 (HTML5 + CSS + JS)
└── docs-files/                       # 项目文档与规范
```

---

# 致谢

- [office_oxide](https://github.com/yfedoseev/office_oxide)：极速跨平台Office文档核心库。
- [Huma](https://github.com/danielgtaylor/huma)：Go现代OpenAPI 3.1框架。
- [Gin](https://github.com/gin-gonic/gin)：高性能Go HTTP Web框架。
- [Distroless](https://github.com/GoogleContainerTools/distroless)：超小体积安全容器基础运行时。