修复OCR容器编排

.env.mac-docker.example

@@ -16,6 +16,8 @@ DATABASE_MAX_CONNECTIONS=10
 
 DATA_ROOT=/app/data
 LOG_LEVEL=info
+OCR_IMAGE=order_site-ocr-worker:latest
+OCR_PORT=8100
 
 TENCENT_REDEEM_PROOF_MODE=basic
 TENCENT_BROWSER_HEADLESS=false

.env.server.example

@@ -16,6 +16,7 @@ DATABASE_MAX_CONNECTIONS=20
 
 DATA_ROOT=/app/data
 LOG_LEVEL=info
+OCR_IMAGE=order_site-ocr-worker:latest
 
 TENCENT_REDEEM_PROOF_MODE=full
 TENCENT_BROWSER_HEADLESS=true

README.md

@@ -8,7 +8,7 @@
 
 - 前端：Vue 3、Vite、Element Plus、TypeScript
 - 后端：Node.js、Express、PostgreSQL、Playwright
-- OCR：通过 `OCR_BASE_URL` 对接外部 HTTP OCR 服务
+- OCR：外部镜像服务，后端通过 `OCR_BASE_URL` 调用
 - 网关：Caddy
 - 本地与生产运行：Docker Compose
 
@@ -30,7 +30,7 @@ docker-compose.yml          生产/服务器 Compose
 
 ## 本地开发
 
-推荐直接使用 Docker，本地不需要额外维护 Node、PostgreSQL 和 Playwright 浏览器运行环境。
+推荐直接使用 Docker，本地不需要额外维护 Node、PostgreSQL、Playwright 浏览器和 OCR 运行环境。
 
 ```bash
 cp .env.mac-docker.example .env
@@ -42,6 +42,7 @@ docker compose -f docker-compose.dev.yml up -d --build
 - 前端、后台、领取页：`http://localhost`
 - 后端健康检查：`http://localhost/health`
 - 后端 API 前缀：`http://localhost/api/v1/...`
+- OCR worker：`http://127.0.0.1:8100/health`
 - noVNC 浏览器画面：`http://127.0.0.1:6080/vnc.html`
 
 查看容器状态：
@@ -55,6 +56,7 @@ docker compose -f docker-compose.dev.yml ps
 ```bash
 docker compose -f docker-compose.dev.yml logs -f backend
 docker compose -f docker-compose.dev.yml logs -f frontend
+docker compose -f docker-compose.dev.yml logs -f ocr-worker
 ```
 
 停止环境：
@@ -120,7 +122,8 @@ cp .env.server.example .env
 - `DATABASE_URL`：PostgreSQL 连接串
 - `TENCENT_BROWSER_HEADLESS`：Playwright 是否无头运行
 - `TENCENT_BROWSER_PREWARM`：启动时是否预热浏览器
-- `OCR_BASE_URL`：外部 HTTP OCR 服务地址；不配置时 OCR 相关能力会降级
+- `OCR_IMAGE`：OCR 外部服务镜像，默认 `order_site-ocr-worker:latest`
+- `OCR_BASE_URL`：后端访问 OCR 的 HTTP 地址，Docker 内默认 `http://ocr-worker:8100`
 
 ## 运行数据
 

apps/backend/README.md

@@ -61,7 +61,7 @@ npm test
 - 服务端口
 - 日志级别 `LOG_LEVEL=debug|info|warn|error`
 - 浏览器是否无头、是否预热、是否常驻、slowMo
-- OCR 外部服务地址 `OCR_BASE_URL`
+- OCR 外部服务镜像 `OCR_IMAGE` 与访问地址 `OCR_BASE_URL`
 - 会话调试开关
 - 兑换证明模式 `full | basic | off`
 - Agiso 全局配置与后台店铺文件配置
@@ -113,6 +113,7 @@ npm test
 当前 `docker-compose.dev.yml` 已切到源码挂载模式：
 
 - `postgres` 容器提供开发库，后端通过 `DATABASE_URL` 连接
+- `ocr-worker` 使用外部镜像启动，后端通过 `OCR_BASE_URL=http://ocr-worker:8100` 调用
 - 后端容器启动时执行 `npm install` 和 `npm run dev`
 - 平时改 `src/` 或 `.env`，一般都不需要重建镜像
 - 生产镜像会在 build 阶段编译后端并只复制 `dist`、`config` 和运行依赖
@@ -151,7 +152,7 @@ npm test
 - `warn`：只保留告警和错误
 - `error`：只保留错误
 
-OCR 识别通过 `OCR_BASE_URL` 调用外部 HTTP 服务。不配置时，启动健康检查会标记 OCR 为 degraded，兑换中需要 OCR 的流程会在调用时返回明确错误。
+OCR 识别通过 `OCR_BASE_URL` 调用 HTTP 服务。Docker Compose 会启动 `ocr-worker` 外部镜像并注入默认地址 `http://ocr-worker:8100`；如果单独运行后端且未配置该地址，启动健康检查会标记 OCR 为 degraded，兑换中需要 OCR 的流程会在调用时返回明确错误。
 
 `TENCENT_REDEEM_PROOF_MODE` 对应的配置文件项会影响生成强度：
 

docker-compose.dev.yml

@@ -21,6 +21,20 @@ services:
     volumes:
       - postgres_dev_data:/var/lib/postgresql/data
 
+  ocr-worker:
+    image: ${OCR_IMAGE:-order_site-ocr-worker:latest}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8100/health || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 15s
+    environment:
+      TZ: ${TZ:-Asia/Shanghai}
+    ports:
+      - "${OCR_PORT:-8100}:8100"
+
   backend:
     build:
       context: .
@@ -33,6 +47,8 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
+      ocr-worker:
+        condition: service_healthy
     healthcheck:
       test:
         ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/health/ready || exit 1"]
@@ -46,6 +62,7 @@ services:
       DATABASE_URL: ${DATABASE_URL:-postgres://postgres:postgres@postgres:5432/order_site}
       DATABASE_SSL: ${DATABASE_SSL:-false}
       DATABASE_MAX_CONNECTIONS: ${DATABASE_MAX_CONNECTIONS:-10}
+      OCR_BASE_URL: ${OCR_BASE_URL:-http://ocr-worker:8100}
       CLAIM_BASE_URL: ${CLAIM_BASE_URL:-http://localhost/#/claim}
       TENCENT_REDEEM_PROOF_MODE: ${TENCENT_REDEEM_PROOF_MODE:-full}
       TENCENT_BROWSER_HEADLESS: ${TENCENT_BROWSER_HEADLESS:-true}

docker-compose.yml

@@ -15,6 +15,18 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
 
+  ocr-worker:
+    image: ${OCR_IMAGE:-order_site-ocr-worker:latest}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8100/health || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 15s
+    environment:
+      TZ: ${TZ:-Asia/Shanghai}
+
   backend:
     build:
       context: .
@@ -25,6 +37,8 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
+      ocr-worker:
+        condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/health/ready || exit 1"]
       interval: 5s
@@ -37,6 +51,7 @@ services:
       DATABASE_URL: ${DATABASE_URL:-postgres://postgres:postgres@postgres:5432/order_site}
       DATABASE_SSL: ${DATABASE_SSL:-false}
       DATABASE_MAX_CONNECTIONS: ${DATABASE_MAX_CONNECTIONS:-20}
+      OCR_BASE_URL: ${OCR_BASE_URL:-http://ocr-worker:8100}
       CLAIM_BASE_URL: ${CLAIM_BASE_URL:-http://localhost/#/claim}
       TENCENT_REDEEM_PROOF_MODE: ${TENCENT_REDEEM_PROOF_MODE:-full}
       TENCENT_BROWSER_HEADLESS: ${TENCENT_BROWSER_HEADLESS:-true}