add docs

README.md

@@ -2,82 +2,177 @@
 
 一个精简版图片/PDF 转 Markdown 服务，核心依赖 `openocr-python==0.1.5`，保留文档解析能力，去掉训练、评测和实验脚本。
 
+**工作流**：Windows 本地编写代码 → Git 推送 → Ubuntu 服务器 Docker 运行。
+
 ## 功能
 
-- `POST /api/recognize`：上传图片或 PDF，生成 Markdown 和 JSON。
+- `POST /api/recognize`：上传图片或 PDF，生成 Markdown 和 JSON
-- `GET /api/history`：查看已解析文件列表。
+- `GET /api/history`：查看已解析文件列表
-- `GET /output/...`：访问生成的 Markdown、JSON 和原始文件。
+- `GET /output/...`：访问生成的 Markdown、JSON 和原始文件
-- `openocr-md`：命令行直接解析单个图片/PDF。
+- `GET /health`：健康检查
+- `GET /docs`：Swagger API 文档
 
-## 本地运行
+---
+
+## 服务器首次初始化（Ubuntu）
+
+### 1. 克隆代码与创建目录
 
 ```bash
-python -m venv .venv
+cd ~
-source .venv/bin/activate
+git clone <你的仓库地址> OpenOCR
-pip install -e .
+cd OpenOCR
-cp .env.example .env
+mkdir -p data/output data/uploads
-uvicorn openocr_markdown.api:app --host 0.0.0.0 --port 8000
 ```
 
-Windows PowerShell:
+### 2. 生成并配置环境变量
-
-```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-pip install -e .
-Copy-Item .env.example .env
-uvicorn openocr_markdown.api:app --host 0.0.0.0 --port 8000
-```
-
-首次运行会自动下载 OpenOCR 所需模型，耗时取决于网络和机器性能。
-
-## API 示例
-
-```bash
-curl -F "file=@examples/page.png" http://127.0.0.1:8000/api/recognize
-curl http://127.0.0.1:8000/api/history
-```
-
-重复上传同名文件默认复用已有结果；需要重新识别时增加 `force=true`：
-
-```bash
-curl -F "file=@examples/page.png" -F "force=true" http://127.0.0.1:8000/api/recognize
-```
-
-## 命令行
-
-```bash
-openocr-md path/to/document.pdf --output-dir data/output
-```
-
-## Docker 部署
 
 ```bash
 cp .env.example .env
-docker compose up -d --build
 ```
 
-服务启动后访问：
+纯 Docker 部署时，重点确认以下配置：
-
-- API 文档：`http://服务器IP:8000/docs`
-- 健康检查：`http://服务器IP:8000/health`
-- 输出文件：`http://服务器IP:8000/output/...`
-
-## 关键配置
-
-通过 `.env` 或服务器环境变量配置：
 
 ```env
-OPENOCR_OUTPUT_DIR=data/output
+OPENOCR_AUTO_DOWNLOAD=true     # 首次运行让容器自动下载模型
-OPENOCR_UPLOAD_DIR=data/uploads
+OPENOCR_USE_GPU=false          # 未配置 NVIDIA Docker 插件前保持 false
-OPENOCR_USE_GPU=false
-OPENOCR_AUTO_DOWNLOAD=true
-OPENOCR_LAYOUT_THRESHOLD=0.4
-OPENOCR_MAX_LENGTH=2048
 OPENOCR_CORS_ORIGINS=*
 ```
 
-如果远程服务器有 GPU，可以先安装带 GPU 的运行环境，再把 `OPENOCR_USE_GPU=true`。当前 Dockerfile 默认是 CPU 版，适合先验证完整链路。
+完整配置项见 `.env.example`。
+
+### 3. 一键编译并启动容器
+
+```bash
+docker compose up -d --build
+```
+
+### 4. 跟踪模型下载进度
+
+模型体积较大，容器启动后会在后台自动下载。**此时不要急着调用接口**，先查看日志：
+
+```bash
+docker compose logs -f
+```
+
+首次下载可能需要 **5～30 分钟**（取决于网络）。当日志出现 `Application startup complete.` 且无报错时，说明模型加载完成，按 `Ctrl + C` 退出日志跟踪。
+
+---
+
+## 健康检查与验证
+
+### 服务器本地
+
+```bash
+curl http://127.0.0.1:8000/health
+# 期望返回: {"status":"ok"}
+```
+
+### Windows 本地浏览器
+
+将 `服务器IP` 替换为实际地址：
+
+- API 文档：`http://服务器IP:8000/docs`
+- 健康检查：`http://服务器IP:8000/health`
+
+若无法访问，请在云服务器安全组中放行 **8000** 端口。
+
+### API 调用示例
+
+```bash
+# 上传图片/PDF 进行解析
+curl -F "file=@/path/to/page.png" http://127.0.0.1:8000/api/recognize
+
+# 查看历史记录
+curl http://127.0.0.1:8000/api/history
+
+# 强制重新识别（同名文件默认复用已有结果）
+curl -F "file=@/path/to/page.png" -F "force=true" http://127.0.0.1:8000/api/recognize
+```
+
+成功响应示例：
+
+```json
+{
+  "id": "page",
+  "status": "success",
+  "message": "Parsed successfully in 12.34s.",
+  "markdown_url": "/output/page/page.md",
+  "json_url": "/output/page/page.json"
+}
+```
+
+Markdown 访问地址：`http://服务器IP:8000/output/<文档名>/<文档名>.md`
+
+---
+
+## 日常开发与更新
+
+### Windows 本地
+
+改完代码后推送到远程仓库：
+
+```powershell
+# 若已配置 git 快捷别名
+gpush "feat: 优化 OCR 的 Markdown 布局解析器"
+
+# 或标准命令
+git add .
+git commit -m "feat: 优化 OCR 的 Markdown 布局解析器"
+git push
+```
+
+### Ubuntu 服务器
+
+```bash
+cd ~/OpenOCR
+git pull && docker compose up -d --build
+```
+
+`docker compose up -d --build` 会检测代码变更并重新构建 API 容器、平滑重启服务。缓存在数据卷中的模型文件和 `data/` 目录下的解析结果不会丢失。
+
+---
+
+## 日常排错与手动测试
+
+### 查看日志
+
+```bash
+docker compose logs -f openocr-markdown
+```
+
+### 命令行手动解析（不经过 API）
+
+```bash
+docker compose exec openocr-markdown openocr-md /app/data/uploads/test.pdf --output-dir /app/data/output
+```
+
+### 常用运维命令
+
+```bash
+docker compose ps              # 查看容器状态
+docker compose down            # 停止服务
+docker compose up -d --build   # 重新构建并启动
+```
+
+---
+
+## 关键配置
+
+通过 `.env` 或环境变量配置：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OPENOCR_OUTPUT_DIR` | `data/output` | 解析结果输出目录 |
+| `OPENOCR_UPLOAD_DIR` | `data/uploads` | 上传文件临时目录 |
+| `OPENOCR_USE_GPU` | `false` | 是否使用 GPU |
+| `OPENOCR_AUTO_DOWNLOAD` | `true` | 首次运行自动下载模型 |
+| `OPENOCR_LAYOUT_THRESHOLD` | `0.4` | 版面分析阈值 |
+| `OPENOCR_MAX_LENGTH` | `2048` | 识别最大长度 |
+| `OPENOCR_CORS_ORIGINS` | `*` | 跨域来源，多个用逗号分隔 |
+| `OPENOCR_LOG_LEVEL` | `info` | 日志级别 |
+
+---
 
 ## 项目结构
 
@@ -95,3 +190,9 @@ OPENOCR_CORS_ORIGINS=*
 ├── pyproject.toml
 └── .env.example
 ```
+
+## 注意事项
+
+- `.env`、`data/`、模型缓存目录已在 `.gitignore` 中排除，不会进入 Git
+- 首次启动耗时较长属于正常现象，等待模型下载完成后再调用接口
+- 生产环境建议在 Docker 前加 Nginx 反向代理并配置 HTTPS