Draftable API Self-hosted 技术文档

1. 镜像概述

Draftable API Self-hosted是一款自托管的文档比较API服务，旨在为企业与开发者提供本地化部署的文档差异分析能力。该服务支持PDF、Word、Excel等多种主流文档格式的比对，可生成结构化差异数据与可视化报告，并通过RESTful API接口实现灵活集成，确保数据处理全程在用户自有基础设施内完成，满足隐私与合规需求。

2. 核心功能与特性

2.1 多格式文档支持

• 兼容PDF、Microsoft Word (DOCX)、Excel (XLSX)、PowerPoint (PPTX)、纯文本(TXT)等格式文档的比对
• 支持跨格式比较（如PDF与Word文档比对）

2.2 差异分析与可视化

• 精确识别文本内容、格式样式（字体、颜色、排版）、表格、图片等元素的差异
• 提供JSON结构化差异数据与HTML可视化报告两种输出形式
• 支持内联对比（修改内容标红/绿）与侧边对比（源文档与目标文档并列展示）模式

2.3 自托管与安全性

• 本地化部署，文档数据存储与处理均在用户服务器内完成，避免数据外泄风险
• 支持API密钥认证，限制非法访问
• 可配置文档自动清理策略，避免存储占用过大

2.4 灵活集成能力

• 提供RESTful API接口，支持文档上传、比较任务创建、结果查询等全流程操作
• 兼容主流编程语言（Python、Java、JavaScript等），提供SDK简化集成
• 支持同步与异步两种调用模式，适配不同业务场景

3. 使用场景

3.1 企业文档管理

• 内部报告、技术文档的版本差异审核
• 合同、协议等***文件的修改追踪
• 多部门协作文档的变更管理

3.2 开发者集成

• 文档管理系统的版本对比功能
• 内容协作平台的修改追踪模块
• 教育类应用的论文/作业批改工具

3.3 合规与审计

• ***、***等行业的合规文档变更记录
• ***、事业单位的公文流转修改存档
• 审计报告的版本差异追溯

4. 部署与使用指南

4.1 部署前提

• 系统要求：64位Linux系统（推荐Ubuntu 20.04+/CentOS 8+），4核CPU，8GB RAM，20GB+可用磁盘空间
• 依赖环境：Docker Engine 20.10+，Docker Compose 2.0+（可选），网络端口开放（默认8080）

4.2 Docker快速部署

4.2.1 单容器部署

通过docker run命令直接启动服务：

bash
docker run -d \
  --name draftable-api \
  -p 8080:8080 \
  -e DRAFTABLE_API_KEY="your-strong-api-key" \  # 自定义API密钥，用于认证
  -e DRAFTABLE_STORAGE_PATH="/data" \           # 文档存储路径
  -v /host/path/to/data:/data \                 # 挂载本地目录持久化存储
  --restart always \
  draftable/api:self-hosted-latest

4.2.2 Docker Compose部署

创建docker-compose.yml配置文件：

yaml
version: '3.8'
services:
  draftable-api:
    image: draftable/api:self-hosted-latest
    container_name: draftable-api
    restart: always
    ports:
      - "8080:8080"  # 宿主机端口:容器端口
    environment:
      - DRAFTABLE_API_KEY="your-strong-api-key"  # 必填，API访问密钥
      - DRAFTABLE_PORT=8080                     # 服务监听端口，默认8080
      - DRAFTABLE_STORAGE_PATH="/data"          # 容器内文档存储路径
      - DRAFTABLE_LOG_LEVEL="info"              # 日志级别：debug/info/warn/error，默认info
      - DRAFTABLE_MAX_FILE_SIZE="100M"          # 单文件最大上传限制，默认50M
      - DRAFTABLE_RETENTION_DAYS=7              # 文档自动清理周期（天），默认30天
    volumes:
      - ./draftable-data:/data  # 本地目录挂载，持久化存储文档
    networks:
      - draftable-net

networks:
  draftable-net:
    driver: bridge

启动服务：

bash
docker-compose up -d

4.3 环境变量配置说明

4.4 API使用示例

4.4.1 创建文档比较任务

通过POST请求提交两个文档进行比较：

bash
curl -X POST http://localhost:8080/api/v1/comparisons \
  -H "Authorization: Bearer your-strong-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "source_file=@/local/path/source.docx" \  # 源文档
  -F "target_file=@/local/path/target.docx" \  # 目标文档
  -F "output_formats=json,html" \              # 输出格式：json（结构化数据）、html（可视化报告）
  -F "mode=side_by_side"                       # 对比模式：side_by_side（侧边）/inline（内联）

4.4.2 查询比较结果

任务创建后返回comparison_id，使用该ID查询结果：

bash
curl -X GET "http://localhost:8080/api/v1/comparisons/{comparison_id}" \
  -H "Authorization: Bearer your-strong-api-key"

响应示例（JSON）：

json
{
  "comparison_id": "cmp-123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "created_at": "2024-05-20T14:30:00Z",
  "completed_at": "2024-05-20T14:30:05Z",
  "differences_count": 8,
  "results": {
    "json_url": "http://localhost:8080/api/v1/comparisons/{comparison_id}/result.json",
    "html_url": "http://localhost:8080/api/v1/comparisons/{comparison_id}/result.html"
  }
}

5. 注意事项

• 服务启动后，建议通过反向代理（如Nginx）配置HTTPS，增强传输安全性
• 高并发场景下，建议增加CPU核心数与内存，避免比较任务积压
• 定期备份挂载的文档存储目录，防止数据丢失
• 企业级应用需联系Draftable***获取商业授权，避免合规风险

详细API文档与SDK下载可访问容器内服务首页（http://localhost:8080）查看。