add docs

Dockerfile

@@ -1,8 +1,11 @@
+# syntax=docker/dockerfile:1
+
 FROM python:3.10-slim
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1
+    HF_HOME=/root/.cache/huggingface \
+    MODELSCOPE_CACHE=/root/.cache/modelscope
 
 WORKDIR /app
 
@@ -10,11 +13,20 @@ RUN apt-get update \
     && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
     && rm -rf /var/lib/apt/lists/*
 
+# Layer 1: Python deps — only rebuilds when pyproject.toml changes.
 COPY pyproject.toml README.md ./
-COPY src ./src
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --upgrade pip \
+    && pip install \
+        "fastapi>=0.115" \
+        "uvicorn[standard]>=0.30" \
+        "python-multipart>=0.0.9" \
+        "pydantic-settings>=2.4" \
+        "openocr-python==0.1.5"
 
-RUN pip install --upgrade pip \
-    && pip install .
+# Layer 2: app code — code changes only rerun this lightweight step.
+COPY src ./src
+RUN pip install --no-deps --no-cache-dir .
 
 EXPOSE 8000
 

README.md

@@ -124,12 +124,44 @@ git push
 
 ### Ubuntu 服务器
 
+**只改了 Python 代码**（最常见）：
+
 ```bash
 cd ~/OpenOCR
 git pull && docker compose up -d --build
 ```
 
-`docker compose up -d --build` 会检测代码变更并重新构建 API 容器、平滑重启服务。缓存在数据卷中的模型文件和 `data/` 目录下的解析结果不会丢失。
+优化后 Dockerfile 会分层缓存：`pyproject.toml` 不变时不会重装 `openocr-python` 等大依赖，通常 **10～30 秒** 即可完成。
+
+**只改了 `.env` 配置**（无需重新 build）：
+
+```bash
+docker compose up -d
+```
+
+**依赖变更**（改了 `pyproject.toml`）才需要完整重建：
+
+```bash
+docker compose build --no-cache
+docker compose up -d
+```
+
+模型缓存在 Docker 卷 `openocr-model-cache` 中，重建容器后**不会重复下载模型**。解析结果在 `./data/` 中，同样不会丢失。
+
+---
+
+## 启动速度优化说明
+
+每次 `docker compose up -d --build` 很慢，通常有两类原因：
+
+| 原因 | 现象 | 已做优化 |
+|------|------|----------|
+| pip 重复下载依赖 | build 阶段耗时数分钟 | Dockerfile 分层 + BuildKit pip 缓存 |
+| 模型重复下载 | 启动后日志里又在下载 | 模型目录挂载到 `openocr-model-cache` 卷 |
+
+**首次部署**仍需下载模型（5～30 分钟，一次性）。之后日常更新应明显变快。
+
+若 BuildKit 缓存未生效，可确认 Docker 版本 ≥ 20.10，compose 会自动使用 BuildKit。
 
 ---
 

docker-compose.yml

@@ -9,3 +9,8 @@ services:
       - .env
     volumes:
       - ./data:/app/data
+      # Persist downloaded models across container rebuilds.
+      - openocr-model-cache:/root/.cache
+
+volumes:
+  openocr-model-cache: