ow

idcard-api/README.md

@@ -130,10 +130,38 @@ docker stats idcard-api                                   # 看内存峰值是
 ### 第 5 步：接入调用方
 
 - **同 NAS 上的其他 Docker 容器**：把调用方容器加入 `idcard-api_idcard-api` 网络（或在调用方 compose 里加 `external_links` / 同一自定义网络），地址写 `http://idcard-api:8000`；图省事直接用 `http://飞牛IP:8000`。
-- **局域网其他设备**：`http://飞牛IP:8000`，带 `X-API-Key` 头。
+- **局域网其他设备**：`http://飞牛IP:8000`，带 `Authorization: Bearer <token>` 头。
 - **要域名 + HTTPS**：用 fnOS 自带的反向代理/远程访问把域名指到 `127.0.0.1:8000`，不要在路由器上映射公网端口直连。
 - **ARM 机型（aarch64）**：python:3.11-slim 和 opencv-headless 有 ARM 版，但 onnxruntime 需 ≥1.19 才有完善的 ARM wheel，先在 NAS上 `docker compose build` 试；若 onnxruntime 装不上，只能换 x86 机型或用云侧部署。
 
+### 第 6 步：以后更新代码怎么发（重要）
+
+**fnOS 的「重新部署 / 重建容器」只会 recreate 容器，不会 rebuild 镜像**——environment 变了会把新变量注进新容器，但代码改动完全不会进去。所以改完代码必须显式 build。
+
+```bash
+cd /vol1/1000/Docker/idcard-api        # 换成你的实际目录
+sudo docker compose -p icd up -d --build
+```
+
+> `-p icd` 不能省：镜像名 `icd-idcard-api` 说明 compose 项目名是 `icd`，不带这个参数会建成另一个项目，跟现有容器对不上。宿主机用户如果不在 docker 组，命令前都要 `sudo`（或执行一次 `sudo usermod -aG docker $USER && newgrp docker`）。
+
+| 你改了什么 | 命令 | 耗时 |
+|---|---|---|
+| `app/*.py` | `up -d --build` | 10–30 秒 |
+| `requirements.txt` | `up -d --build`（pip 层失效重跑） | 1–3 分钟 |
+| `.env` / `docker-compose.yml` | `up -d`（自动 recreate，无需 build） | 秒级 |
+| 怀疑缓存脏 / 要刷基础镜像 | `build --no-cache` + `up -d --force-recreate` | 3–5 分钟 |
+
+**`--no-cache` 不是日常操作**：Docker 的层缓存按内容哈希失效，`COPY app ./app` 依赖代码内容，代码一变这一层和后续层必然重跑，前面的 apt/pip 层照常命中缓存。
+
+也可以直接用 `deploy.sh`（已随项目提供），它会增量构建、等就绪、校验镜像内代码真的更新了，失败自动降级全量重建：
+
+```bash
+bash /vol1/1000/Docker/idcard-api/deploy.sh
+```
+
+> 如果脚本报 `\r: command not found`，是 Windows 换行符问题，执行 `sed -i 's/\r$//' deploy.sh` 修一下。
+
 ## 调用
 
 ```bash
@@ -175,6 +203,37 @@ curl -X POST http://127.0.0.1:8000/api/v1/idcard/recognize/base64 \
 
 Python 示例见 `client_example.py`。
 
+### C# / .NET 调用示例（server-to-server）
+
+要点三个：**必须带鉴权头**、**必须检查 HTTP 状态码**（否则 401 会被当成"未识别到"静默吞掉）、**超时要给足**（低端 NAS 首张要加载模型 10–20 秒）。
+
+```csharp
+// 配置里加一项 IdCardOcrToken，与服务端 .env 的 API_TOKENS 对应
+string token = ServiceSettingsPolicy.GetIdCardOcrToken(service);
+
+using var request = new HttpRequestMessage(HttpMethod.Post, apiUrl);
+if (!string.IsNullOrWhiteSpace(token))
+{
+    // 新版服务（推荐）：标准 Bearer 头
+    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+    // 或旧版服务（仅设置了 API_KEY）：改用下面这行
+    // request.Headers.TryAddWithoutValidation("X-API-Key", token);
+}
+request.Content = form;
+
+using var response = client.SendAsync(request).GetAwaiter().GetResult();
+
+// 关键：先判状态码，别让 401/413/422 掉进 JSON 解析分支变成"静默失败"
+if (!response.IsSuccessStatusCode)
+{
+    string body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+    Console.WriteLine($"[UploadIdCardFile] OCR HTTP {(int)response.StatusCode}: {body}");
+    return data;   // 前端提示"未识别到信息"，后端日志里有真实原因
+}
+```
+
+`HttpClient` 建议用 `IHttpClientFactory` 或静态单例，不要每次 `new`——高频调用会耗尽 socket。
+
 ## 鉴权（Token 验证）
 
 支持三种方式，全部用**标准库实现**（HMAC-SHA256），不引入 PyJWT 等依赖，对 1C/2G 无额外开销。