jubb/docgen repository overview

⁠DocGen - 文档模板自动化生成系统

⁠✨ 核心特性

• 上传 .docx/.xlsx/.pptx/.html/.md 等模板，自动识别 ${placeholder} 占位符
• 多数据源支持：手动JSON、REST API、SQL查询、CSV、Excel、XML
• 拖拽可视化映射：将数据源字段拖拽绑定到模板占位符，无需手写配置
• 强大模板语法：默认值、数字格式化、日期格式化、trim、大小写转换过滤器
• 表格循环渲染 {{#each}}、条件渲染 {{#if}}，轻松输出合同明细、报表清单
• 图片占位符：支持URL、Base64、后端本地路径图片插入文档
• 多数据源合并：一个模板同时读取多个数据源数据
• 槽位支持固定值，无需数据源即可填充静态内容
• 定时Cron任务：定时自动生成文档，支持Spring 6位Cron表达式
• Webhook回调通知：任务成功/失败回调，返回带签名的下载&预览链接
• 内置文件预览组件，页面直接预览生成后的文档，无需下载
• JWT无状态鉴权，用户权限管理、登录防爆破、审计日志、敏感字段加密
• H2内置数据库，开箱即用；
• 分布式锁，支持多实例部署，防止定时任务重复执行
• SSRF防护、并发限流、熔断降级、优雅停机，面向企业生产环境

⁠🚀 快速启动

⁠拉取镜像

docker pull jubb/docgen:latest

⁠运行容器（基础示例）

docker run -d \
  -p 8080:8080 \
  -v ./docgen-data:/app/data \
  -e DOCGEN_JWT_SECRET="your-random-jwt-secret-at-least-32-chars" \
  -e DOCGEN_MASTER_KEY="your-random-master-key" \
  -e DOCGEN_ADMIN_PASSWORD="change-me-strong-password" \
  --name docgen \
  jubb/docgen:latest

访问地址：http://localhost:8080

• 默认管理员账号：docgen，密码由环境变量 DOCGEN_ADMIN_PASSWORD 指定
• Swagger API文档：http://localhost:8080/swagger-ui.html

⁠主要环境变量

⁠📝 模板语法示例

普通占位符 & 过滤器

${customerName}
${customerName|default:未知客户}
${amount|number:#,##0.00}
${reportDate|date:yyyy年MM月dd日}

表格循环

{{#each rows}}
${no} ${name} ${amount|number:#,##0.00}
{{/each}}

条件渲染

{{#if paid}}✅已付款{{/if}}

图片插入

${logo|image:120x80}

⁠📊 数据源类型

• MANUAL_JSON：手动输入JSON数据
• REST_API：调用HTTP接口获取JSON（支持GET/POST，自定义Header/Body）
• SQL：JDBC查询数据库获取数据
• CSV：文本或上传CSV文件
• EXCEL：读取xlsx工作表作为数据源
• XML：XML文本或XML文件

⁠⏱️ 定时任务 & Webhook

• 基于Spring Cron表达式执行文档生成任务
• 任务基于拖拽设计方案，复用模板、映射、多数据源配置
• Webhook推送执行结果，返回带HMAC签名的限时下载、预览链接
• Webhook请求携带防重放时间戳与签名头，提供Java/Python验签示例

⁠🔐 安全特性

• JWT无状态鉴权，全部 /api/** 需要登录
• 登录防爆破，IP+账号失败锁定
• 审计日志记录登录、模板、数据源、任务、下载等敏感操作
• 数据源/Webhook默认禁止访问内网地址（SSRF防护）
• 数据源密码、Webhook Secret等敏感字段AES‑GCM加密存储
• 定时任务分布式锁，多实例部署任务不会重复运行
• 文档生成并发限流，防止OOM

⁠📁 支持模板/输出格式

⁠📖 使用流程

1. 访问Web页面登录系统
2. 模板管理：上传模板文件，模板内编写占位符语法
3. 数据源：创建JSON / REST / SQL / CSV等数据源
4. 拖拽设计器：选择模板与数据源，拖拽字段绑定占位符，支持多数据源、固定值
5. 保存映射方案，手动生成文档下载预览
6. 创建定时任务，绑定已保存映射方案，配置Cron表达式、Webhook通知