KRenderEngine

高性能图片渲染服务 — 基于 Playwright 无头浏览器，模板 + JSON 实时生成 PNG 图片。
面向生产环境设计：常驻浏览器、Worker 池调度、队列熔断、WebSocket 实时监控。

快速开始 · 架构设计 · 环境变量 · 文档

---

特性

• Browser 全局常驻 — Chromium 只启动一次，所有 Worker 共享，启动毫秒级响应。
• Worker 池调度 — 可配数量的 Worker，自动 acquire/release，任务完成即取下一个。
• 队列熔断 — 队列容量 = Worker 数 × 倍数。超出自动拒绝并返回 HTTP 503。
• 图片持久化 — 生成图片保存至 public/images/，返回可访问 URL，支持定时清理过期图片。
• 依赖倒置架构 — Scheduler / Pool / Worker 只依赖 Renderer 接口，可无缝切换到 SVG/Canvas/Skia。
• WebSocket 实时监控 — 仪表盘实时显示 Worker 状态、排队数、折线图、CPU/内存。
• 管理员认证 — 独立登录页，Bearer Token 鉴权，SQLite 记录渲染和登录历史。
• 压力测试工具 — 内置 benchmark 脚本，支持可调并发、多模板混合。
• SOLID / 生产级工程 — 严格 TypeScript、模块化、职责单一、完善错误处理。

---

快速开始

环境要求

• Node.js >= 18
• pnpm >= 9

安装

pnpm install
./node_modules/.bin/playwright install chromium

配置

cp .env.example .env
# 按需修改 .env 中的配置项

启动

# 开发模式
pnpm dev

# 生产模式
pnpm build && pnpm start

详细步骤参见 docs/getting-started.md。

---

架构设计

渲染流程

HTTP 请求
  │
  ▼
Scheduler.submit(Job)
  │
  ├─ Pool 有空闲 Worker？──→ YES ──→ Worker.render(Job) ──→ 返回 URL + 元信息
  │
  ├─ Pool 无空闲 + 队列未满 ──→ Queue.enqueue(Job) ──→ Worker 完成时取下一个
  │
  └─ Pool 无空闲 + 队列已满 ──→ 拒绝（HTTP 503）

核心类关系

                  ┌─────────────┐
                  │  Scheduler  │  ← 核心编排
                  └──┬──────┬───┘
                     │      │
              ┌──────▼─┐  ┌─▼──────┐
              │  Pool   │  │ Queue  │
              └──┬──────┘  └────────┘
                 │
         ┌───────┼───────┐
         │       │       │
    ┌────▼──┐ ┌─▼───┐ ┌─▼───┐
    │Worker │ │Worker│ │ ... │  ← 每个持有 Renderer 接口
    └───┬───┘ └──┬──┘ └──┬──┘
        │        │       │
    ┌───▼────────▼───────▼──┐
    │   PlaywrightRenderer  │  ← 可替换为 Svg/Canvas/Skia
    └───────────┬────────────┘
                │
         ┌──────▼──────┐
         │BrowserManager│  ← 全局 Browser 单例
         └─────────────┘

Worker 生命周期

创建 → idle → (收到任务) busy → render() → idle → (循环)
                    │
                    ├─ 异常 → error → 自动销毁 + 重建
                    │
                    └─ 完成 1000 次 → 自动销毁 + 重建（防内存碎片）

---

环境变量

变量	默认值	说明
ADMIN_USERNAME	admin	管理员用户名
ADMIN_PASSWORD	admin123	管理员密码
HTTP_HOST	0.0.0.0	HTTP 监听地址
HTTP_PORT	3000	HTTP 监听端口
RENDER_WORKERS	10	Worker 进程数量
QUEUE_MULTIPLIER	5	队列容量 = RENDER_WORKERS × QUEUE_MULTIPLIER
DB_PATH	./data/krender.db	SQLite 数据库路径
BASE_URL	http://localhost:3000	服务绑定的域名地址（用于返回可访问的图片 URL）
IMAGE_TTL_HOURS	24	图片有效期（小时），超时自动删除；设为 0 则永不过期

---

文档

文档	内容
快速开始	环境要求、安装、配置、启动、目录结构
API 文档	接口列表、请求/响应示例、参数说明
模板指南	模板编写教程、结构说明、示例代码
Benchmark	压力测试使用方法、参数、输出解读
渲染器扩展	实现自定义渲染器（SVG/Canvas/Skia）的指南

---

技术栈

类别	技术
运行时	Node.js 18+ / TypeScript 5.6
浏览器	Playwright Chromium
HTTP 框架	Fastify 5.x
实时推送	WebSocket（@fastify/websocket）
数据库	SQLite（better-sqlite3，WAL 模式）
认证	Token-based（crypto.randomUUID）
包管理	pnpm

---

License

MIT