系统架构

仓库边界

markify/
├── services/
│   ├── api/          公开 API 与任务编排
│   ├── resource/     临时资源服务
│   └── docs/         VitePress / Nginx 文档站
├── workers/
│   ├── image/        图片渲染 Worker
│   └── video/        视频 Worker 边界
├── contracts/        版本化 OpenAPI 协议
└── docs/             仓库内部设计、ADR 与实施记录

每个应用拥有自己的包清单、启动入口、配置和容器镜像。根目录只负责编排 workspace、锁文件、Compose、协议和工程文档。

部署拓扑

外部网关 / 调用方
        │
        ├──────────────▶ markify-docs (Nginx 静态站)
        │
        └──────────────▶ markify-api
                              │
                     markify-internal
                  ┌───────────┼───────────┐
                  ▼           ▼           ▼
          resource-service image-worker video-worker

• markify-api 和 markify-docs 加入外部 wangquan-network。
• Resource Service 与 Worker 只加入私有 markify-internal。
• 媒体下游服务不发布宿主机端口。
• 四个后端容器拥有独立网络命名空间，因此都可以监听端口 80。

调用约束

调用方	被调用方	协议
业务客户端	Markify API	公开 HTTP API
Markify API	Resource Service	Resource v1 HTTP
Markify API	Image Worker	Worker v2 HTTP
Image Worker	Resource Service	Resource v1 内部 HTTP
浏览器/读者	Docs	静态 HTTP

任何应用都不得通过文件系统路径或 TypeScript 源码引用另一个应用。图片图层只接受 resourceToken，Worker 不接受调用方提供的任意 URL。

状态所有权

状态	所有者	存储
临时媒体文件与元数据	Resource Service	tmpfs + 进程内 Map
resourceToken → streamToken	Markify API	进程内 Map
最新预览帧	Markify API	受容量限制的内存
请求级渲染中间结果	API / Worker	tmpfs 或内存
静态文档	Docs	Nginx 镜像只读内容

Image Worker 是无跨请求状态的；API 与 Resource Service 当前不是。因此现阶段部署约束是一台服务器一套服务、API 和 Resource Service 各一个实例。