项目概览

Markify 是面向可信容器内网的媒体水印服务。调用方上传临时图片后，使用版本化 JSON 描述一个或多个源资源及多个图片、文字图层，由服务端完成排版、合成、编码、实时预览和最终结果交付。

当前能力

• 上传 JPEG、PNG、WebP，并返回固定 TTL 的 resourceToken。
• 一个请求同时处理最多 8 个源资源。
• 单个任务配置最多 32 个图片或文字图层。
• 支持绝对坐标、九宫格锚点、偏移、缩放、旋转、透明度、阴影和平铺。
• 为每个源资源维护最多一个活动 streamToken，浏览器无需反复修改 <img src>。
• 最终结果以 ZIP 返回，包含渲染图片和 manifest.json。
• 调用中断、渲染失败或 ZIP 交付失败时执行取消、清理和资源状态回滚。

应用组成

应用	包名	职责	当前状态
Markify API	@markify/api	公开接口、预览流、任务编排、最终 ZIP	可用
Resource Service	@markify/resource-service	临时资源、TTL、读取租约、最终消费	可用
Image Worker	@markify/image-worker	图片和文字图层合成	可用
Video Worker	@markify/video-worker	视频探测、预览和转码	仅健康与能力接口
Docs	@markify/docs	公开项目文档	可用

设计原则

1. 协议优先：应用之间不得导入彼此源码，HTTP 契约是唯一边界。
2. 资源临时化：当前版本不把媒体保存为长期资产，进程重启允许资源失效。
3. 公开入口唯一：业务调用方只访问 Markify API；Resource Service 与 Worker 保持私有。
4. 失败不产生部分结果：批量预览原子发布，最终渲染全部成功后才开始交付 ZIP。
5. 可替换实现：Worker 可以使用其他语言重写，只要继续满足对应 OpenAPI 契约。

版本边界

当前公开请求模型使用 version: 1，Image Worker 使用 Worker v2 协议。旧的 Worker v1 multipart 图片接口仅用于兼容，不再承载新能力。

部署边界

当前系统按单个 API 和单个 Resource Service 实例设计。两者维护进程内状态，不能在没有粘性路由或共享状态设计的情况下直接横向扩容。