jubb/anydoc-service repository overview

⁠anydoc‑service

企业内网文档转换微服务，将 Word / Excel / PowerPoint / PDF / ODF / RTF / EPUB / CSV 共14种格式统一转换为 GitHub Flavored Markdown，面向Java RAG文档摄取管道设计。底层基于 Rust anydoc 引擎，转换速度快，镜像轻量，提供同步/异步API、PDF页面渲染、缓存、限流、优雅停机等生产级能力。

⁠✨ 核心能力

• 📄 多格式转Markdown：docx/xlsx/pptx/pdf/odf/rtf/epub/csv等14种格式输出GFM Markdown，支持提取图片资产base64返回，附带章节位置锚定信息
• ⚡ Rust底层引擎：单文档转换中位数约4.4ms，性能优异
• 🔁 同步 + 异步任务接口：小文档同步调用；大文档使用异步任务，轮询获取结果
• 🖼️ PDF页面位图渲染：支持指定页码、缩放倍率输出PNG/JPEG图片，用于扫描件预览、视觉模型输入
• 🧠 转换缓存 single‑flight：文档SHA‑256缓存，重复文档直接命中，并发相同文档共享一次转换
• ⚙️ 请求级动态参数：单次请求可覆盖超时、缓存开关、页码子集、最大页数限制
• 🛡️ 完整错误契约：401/413/415/422/429/503/504标准化错误码，与Java SDK异常体系对齐
• 📊 可观测性：/healthz /readyz存活就绪探针、Prometheus metrics、结构化JSON日志、X‑Request‑ID全链路透传
• 🚦 背压与限流：并发信号量、有界队列、RPM令牌限流，过载返回503+Retry‑After防止雪崩
• 🛑 优雅停机Drain：SIGTERM拒绝新请求、就绪探针置503摘流、等待在途任务完成，排队任务标记可重试失败
• 🔐 Bearer Token鉴权，恒定时间比对防时序攻击
• 🐳 容器生产加固：非root运行、安全降级、tini信号处理，适配Kubernetes / Docker Compose

⁠🚀 快速运行

docker pull jubb/anydoc-service:latest

docker run --rm -p 8080:8080 \
  -e ANYDOC_SERVICE_TOKEN="your-strong-secret-token" \
  jubb/anydoc-service:latest

健康检查

curl http://localhost:8080/healthz

⁠同步转换示例

curl -H "Authorization: Bearer your-strong-secret-token" \
  -F "[email protected]" \
  "http://localhost:8080/v1/convert?include_assets=true"

⁠异步大文档任务

# 提交任务，返回 job‑id
curl -H "Authorization: Bearer your-strong-secret-token" \
  -F "[email protected]" \
  "http://localhost:8080/v1/jobs?include_assets=true&timeout=900"

# 轮询任务状态
curl -H "Authorization: Bearer your-strong-secret-token" http://localhost:8080/v1/jobs/{job_id}

⁠PDF页面渲染

curl -H "Authorization: Bearer your-strong-secret-token" \
  -F "[email protected]" \
  "http://localhost:8080/v1/pdf/render?pages=0,2&scale=1.5&format=png"

⁠🔧 主要环境变量

⁠📡 API端点

⁠☕ Java SDK（anydoc‑sdk v2.8.0+）

<dependency>
    <groupId>io.github.zll‑g</groupId>
    <artifactId>anydoc‑sdk</artifactId>
    <version>2.8.0</version>
</dependency>

⁠SDK核心亮点

• ✅ 类型安全API：同步转换、异步任务提交轮询、PDF渲染、批量文档转换
• ✅ 内置韧性能力：指数退避重试、遵循服务端Retry‑After、熔断器、single‑flight在途合并
• ✅ 强类型异常契约：服务端HTTP状态码映射为Java异常，直接驱动RAG管道路由（死信/告警/重试）
• ✅ Spring Boot3自动装配：引入依赖自动注入AnydocClient Bean，内置Actuator健康指示器
• ✅ 全链路X‑Request‑ID透传，对接服务端日志可观测
• ✅ 零第三方HTTP框架，基于JDK内置java.net.http.HttpClient

⁠Java最小示例

AnydocClient anydoc = AnydocClient.builder()
        .baseUrl("http://localhost:8080")
        .token("your-strong-secret-token")
        .build();
ConversionResult result = anydoc.convert(Files.readAllBytes(Path.of("report.docx")), "report.docx");
String markdown = result.markdown();

⁠⚠️ 重要能力边界

• 扫描PDF（无文本层）返回 415 unsupported，需要对接外部OCR服务预处理
• 返回Markdown附带assets数组，包含图片base64与placements章节归属信息；docx浮动图片会标记floating:true
• 请求支持动态覆盖：timeout、use_cache、pages、max_pages参数
• 生产环境不要使用默认dev‑token，会输出告警日志

⁠📎 项目信息

• 底层：Firecrawl anydoc (Rust, MIT)
• 服务封装：FastAPI / Uvicorn
• Java SDK：anydoc‑sdk⁠
• 适用场景：RAG知识库文档摄取、企业内网文档解析管道