# docx-editor-front-project

**Repository Path**: athmoon/docx-editor-front-project

## Basic Information

- **Project Name**: docx-editor-front-project
- **Description**: 介绍：docx-editor的容器化部署；缺点：（1）预览效果不同于源文件；优点：（1）导出docx效果和源文件相同；
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ayler Advanced DOCX Editor - Frontend Project

本工程实现了一个 100% 本地运行、不依赖任何外部 CDN 的高级 Word (.docx) 文档编辑器，采用 React、Vite 与 `@eigenpal/docx-editor-react`，并通过 Docker Compose 与 Nginx 进行离线化容器部署。

## 页面样式

### 主页

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

## 解决痛点 (Pain Points Solved)

1. **CDN 强依赖消除 (Zero External CDN Dependency)**
   传统的前端文档编辑器在渲染数学公式、Web Worker 或特大组件时，常常会动态发起对 `unpkg.com`、`jsdelivr.net` 等外部 CDN 的请求。在政企内网或离线专网（Air-gapped Environments）中，这会导致编辑器崩溃或安全审计不通过。
   * **解决方案**：在 Docker 构建阶段将 `@eigenpal/docx-editor-react` 及其底层依赖在容器本地完成全静态编译与打包，完全通过 Nginx 进行独立托管，彻底端掉运行时任何外部 CDN 请求。

2. **重度依赖隔离缓存 (Heavy Dependency Layer Isolation)**
   由于 `@eigenpal/docx-editor-react` 及其底层 ProseMirror 引擎体积庞大且日常开发极少改动，每次修改前端业务代码都重新下载/安装依赖会极大地拖慢 CI/CD 和本地容器重构速度。
   * **解决方案**：建立专属团队基础镜像 `ayler/docx-editor-react-base:1.0`，在 `Dockerfile.base` 中锁死大体积依赖，主应用构建时直接 `FROM` 该镜像，使业务层代码构建可在几秒钟内完成。

3. **高保真 Word 原生解析 (High-Fidelity Document Rendering)**
   多数编辑器将 DOCX 转换成 HTML 进行修改后再转回，往往导致格式丢失、页边距错乱或特殊排版结构损坏。
   * **解决方案**：基于 `@eigenpal/docx-editor-core` 的 native OOXML 直解引擎，在浏览器端直接读写文档的原始 XML 结构，配合定制化的 Paged Layout 布局，还原媲美 Microsoft Word 的页面排版。

4. **单键极简部署 (Single-Command Portability)**
   复杂的编译链和本地 Nginx 配置导致在不同操作系统环境（如 Windows、Linux 生产环境）下的部署存在差异。
   * **解决方案**：使用 Docker Compose 与 `.env` 文件配合，实现环境变量（如外部端口 `OUTER_PORT=8145`）的统一管理，支持一键命令完成本地镜像构建与启动。

---

## 字体版权与防侵权合规性说明 (Font Copyright & Compliance)

在商业项目或企业级系统分发中，使用含有受版权保护的商业字体存在极高侵权与索赔风险。以下是对本项目涉及字体的合规性分析和解决方案说明：

### 1. 字体版权风险评估 (Copyright Risks)
* **微软雅黑 (Microsoft YaHei)**：由方正字库设计开发，版权归属于方正。微软仅获得了将其嵌入 Windows 操作系统用于“系统显示”与“个人非商业打印”的授权。**如果直接将其二进制字体文件打包分发到 Linux 容器中，或者在未获得授权的网页、海报或 APP 等商业发布中使用，属于严重的版权侵权行为**。
* **宋体 (SimSun)、黑体 (SimHei)、仿宋 (FangSong)、楷体 (KaiTi)**：这四款中文字体的版权归属于北京中易中标电子信息技术有限公司（中易中标）或微软等关联机构。同样，它们仅被授权在 Windows 系统环境下作为系统字体使用，**任何将字体文件进行拷贝分发、安装在 Linux 环境下或商业发布的行为都存在极大的版权纠纷风险**。

### 2. 我们的合规与防侵权措施 (Anti-Infringement Actions)
为了确保本项目在商业使用及专网环境中的完全合规，我们采取了以下防线：
1. **零字体文件分发 (Zero Proprietary File Distribution)**
   本项目在打包构建以及 Docker 镜像分发时，**绝对不包含、不复制、不分发任何字体文件**（无论是商业字体还是开源字体）。
2. **纯客户端渲染与零容器端字体依赖 (Pure Client-Side & Zero Container Font Dependency)**
   本项目采用完全的客户端（Browser-only）富文本渲染架构，文档的展示、样式切换、排版测量以及打印均由用户的浏览器执行，直接调用用户本地操作系统中已安装并获授权的字体（例如 Windows 的微软雅黑、宋体，macOS 的平方体等）。
   因此，**Docker 容器内（Nginx 服务端）无须安装任何中英文字体**。这不仅彻底排除了服务器端分发任何受版权保护字体引起的侵权风险，同时也让 Docker 镜像体积缩小了 90% 以上（从原本包含 CJK 字体的 300MB+ 骤降至仅约 25MB 的原生轻量 Nginx 镜像）。
3. **恢复默认字体列表以确保稳定性 (Restored Default Font List for Stability)**
   为了确保与富文本引擎及 OOXML 标准的 100% 兼容与稳定性，我们将编辑器的字体下拉菜单还原为了默认的内置字体列表（如 Arial, Calibri, Times New Roman 等）。默认字体列表中天然不包含任何有侵权风险的商用中文字体（如微软雅黑、宋体等），彻底消除了前端分发和展示侵权字体的合规风险。
4. **安全的 CSS 回退链设计 (Safe CSS Fallback Chains)**
   我们在 CSS 及编辑器字体回退链中使用了如 `font-family: "Noto Sans CJK SC", "Microsoft YaHei", sans-serif;` 的引用方式。此种通过字体的字符串名称指示浏览器寻找客户端系统字体的行为，**不涉及分发字体文件本身，在法律层面上是完全安全且合规的**（因为 Windows 客户端本身拥有使用自己内置字体的合法授权）。

---

## 使用技术 (Technologies Used)

* **核心框架**：React 18.3.1 + TypeScript 5 + Vite 5.3.1
* **文档引擎**：`@eigenpal/docx-editor-react` + `@eigenpal/docx-editor-core` (WYSIWYG 级 OOXML 铺设)
* **宿主服务器**：Nginx (Alpine 版，支持 Gzip 压缩及静态文件超长缓存)
* **容器化与部署**：Docker / Docker Compose

---

## 快速开始 (Quick Start)

### 1. 配置文件与数据挂载

请确认根目录下存在 `.env` 配置文件，并配置您需要的访问端口：

```env
OUTER_PORT=8145
```

为了持久化编辑数据或在容器与宿主机之间共享文件，`docker-compose.yml` 默认配置了数据卷映射：
* **宿主机路径**：`H:/docker-data/docx-editor-front-project-data/data`
* **容器内路径**：`/app/data`

*如果需要调整挂载路径，可直接编辑 `docker-compose.yml` 的 `volumes` 节点。*

### 2. 步骤一：构建专属于团队的“重依赖基础镜像”

在 Windows **PowerShell** 或 Linux 终端中运行以下命令，使用 `docker-compose-base.yml` 自动编译并生成基础依赖镜像：

```powershell
docker compose -f docker-compose-base.yml build
```

*(或者也可以使用传统命令手动构建：`docker build -t ayler/docx-editor-react-base:1.0 -f Dockerfile.base .`)*

### 3. 步骤二：启动与重构主应用容器

当基础镜像构建完毕后，拉起主应用服务进行业务层构建与启动：

```powershell
docker compose up --build -d
```

运行完成后，即可在浏览器中通过以下地址进行访问：
👉 [http://localhost:8145](http://localhost:8145)

### 4. 操作说明

* **导入文件**：点击 “UPLOAD .DOCX” 按钮，选择本地的 `.docx` 文件即可载入。
* **创建空白文档**：系统在页面打开时会自动加载一个 1 页的空白模板，您可直接开始在线编辑。
* **保存/下载**：编辑完成后，点击右上角 “SAVE .DOCX” 按钮，可将修改后的内容以二进制形式导出为原生的 `.docx` 文档并下载到您的本地。
* **打印/预览**：支持在编辑器中使用标准的 Word 打印排版功能。