diff --git a/docs/DINGTALK_DWS_FETCHER.md b/docs/DINGTALK_DWS_FETCHER.md index 69b1e3a..5a95b30 100644 --- a/docs/DINGTALK_DWS_FETCHER.md +++ b/docs/DINGTALK_DWS_FETCHER.md @@ -32,12 +32,41 @@ `scripts/dws_error_map.py` 把 dws 的错误体(严格版 `ok/error` 包裹、普通子命令 `error` 对象、本地错误、TLS/网络文本)统一映射为平台语义 `{ok, code, retryable, missing}`。要点: -- 只有明确瞬时信号(429/5xx/超时/连接层失败/**dws 二进制缺失**)为 `retryable=true`; +- 只有明确瞬时信号(429/5xx/超时/连接层失败/**服务端导出任务失败**/**dws 二进制缺失**)为 `retryable=true`; +- **服务端导出任务失败 `export_failed` 判为可重试**:并发实测同一节点 8 路时偶发失败、1/2/4 路与串行必成(详见 §7),若判终态会把本可成功的文档永久失败; - 未分类错误 `code=unknown` 且**不重试**——避免被无限重试掩盖真因; - `workspace node not found` → `missing=true`(走 missing 分支而非 failed); - TLS 缺 CA(`x509: certificate signed by unknown authority`)→ `tls_ca`,终态(重试无意义,需补 CA)。 -覆盖样本与断言见 `scripts/test_dws_error_map.py`(17 个断言,样本为实测捕获的真实错误体)。 +覆盖样本与断言见 `scripts/test_dws_error_map.py`(18 个断言,样本为实测捕获的真实错误体)。 + +## 7. 并发实测与上限(真实 worker 容器内) + +在**已部署的 worker 容器**里用平台自己的 `artifact_fetch.py` 实测(产物写容器 /tmp,不动 spool;每级用不同节点,避免服务端导出去重缓存失真): + +| 场景 | 并发 | 结果 | 墙钟 | 单件均/p95 | 取件器 | +|---|---|---|---|---|---| +| 常规体积在线文档(容器 <200MB) | 8 | **8/8** | 3.6s | 3.5s / 3.5s | dws | +| 常规体积在线文档 | 12 | **12/12** | 3.5s | 3.4s / 3.5s | dws | +| 巨型在线文档(容器 307MB~1.33GB) | 1 | **1/1** | 4.3s | 4.3s | dws | +| 巨型在线文档 | 2 | **2/2** | 4.6s | 4.5s / 4.4s | dws | +| 巨型在线文档 | 4 | **3/3** | 4.7s | 4.3s / 4.6s | dws | +| 混合 8 路(6 常规 + 2 巨型) | 8 | 6/8 | 3.8s | — | 2× `export_failed`(可重试) | + +结论与要求: + +- **吞吐随并发线性增长**(12/3.5s ≈ 3.4 件/秒),**全程无 429**;墙钟基本恒定 → 瓶颈是服务端导出任务而非本地。 +- **常规体积:≥12 路安全**;**巨型在线文档:4 路已验证安全**;唯一见过的失败是 8 路混合时巨型文档的服务端导出偶发失败 → 已判 `export_failed=retryable`,并建议 worker 侧对在线文档并发**不超过 4**。 +- **目录大小只在"普通文件"时等于真实字节数**:`adoc/axls` 等在线文档的目录大小是"容器大小"(实测有 322MB/590MB/**1.40GB** 的 adoc,导出 docx 仅 15MB/48MB/49.5MB)。因此大小预检**只对普通文件生效**;曾对在线文档生效导致 3 个可导出文档被误判 `over_limit`(已修,见 §8 回归)。 +- 定点复测(修复后、同一生产容器):3 个巨型 adoc 全部 `ok` 导出 docx;无权限的 axls 从"无结果的 `no_result`"变为明确的 `forbidden`(终态、不重试)。 + +## 8. 压测暴露并已修复的回归 + +| 回归 | 症状 | 修复 | 测试 | +|---|---|---|---| +| 在线文档被大小预检误拒 | 3 个 adoc(容器 322MB~1.4GB)`over_limit` 永久失败 | 预检只对普通文件生效(在线文档以导出件实际大小为准) | `test_online_document_with_huge_catalog_size_still_exports` | +| 转换器错误绕过平台契约 | axls 权限失败时进程无结果退出 → 平台只看到 `artifact_fetch_no_output` | `axls_to_xlsx` 抛 `DwsCallError`,取件器映射成 `forbidden`(CLI 侧 exit 2) | `test_axls_converter_failure_maps_to_platform_error` | +| 服务端导出偶发失败被判终态 | 8 路混合下的 `export_failed` 永久失败 | `export_failed` 改判 `retryable=true` | `dws_error_map` 新增断言 | ## 4. 镜像与部署 diff --git a/scripts/artifact_fetch.py b/scripts/artifact_fetch.py index c38cabd..4df4e1d 100644 --- a/scripts/artifact_fetch.py +++ b/scripts/artifact_fetch.py @@ -466,10 +466,6 @@ def _dws_inspect_extension(raw_key): def dingtalk_dws_download(manifest, max_bytes): """Fetch one DingTalk node through dws: adoc -> docx export, axls -> converted xlsx, everything else -> raw drive download. Returns (path, size, digest, matched_local).""" - catalog_size = manifest.get("size_bytes") - if isinstance(catalog_size, int) and catalog_size > max_bytes: - # The catalog already knows the size: refuse before burning a download. - raise FetchError("artifact exceeds ingest size limit", retryable=False, code="over_limit") raw_key, _dentry_type = dingtalk_raw_keys(manifest) # The node type comes from the RESOLVED name suffix first (that is what the legacy # path keys on); declared_type is an optional hint and dingtalk_raw_keys returns a @@ -480,6 +476,14 @@ def dingtalk_dws_download(manifest, max_bytes): declared = (manifest.get("declared_type") or "").lower() extension = declared if declared not in ("", "file", "folder") else _dws_inspect_extension(raw_key) extension = (extension or "").lower().lstrip(".") + # Catalog size is only a true byte count for ORDINARY files. For online documents + # (adoc/axls/able/...) the catalog size is the container size, which can exceed the + # cap while the exported docx/xlsx stays small — pre-checking those would wrongly + # reject documents that the legacy path exported happily. + online_document = extension in ("adoc", "axls", "able", "appt", "amind", "adraw") + catalog_size = manifest.get("size_bytes") + if not online_document and isinstance(catalog_size, int) and catalog_size > max_bytes: + raise FetchError("artifact exceeds ingest size limit", retryable=False, code="over_limit") if extension in ("dlink", "hlink"): raise MissingSource("DingTalk link node has no bytes (fileSize=0)") if extension in ("amind", "appt"): @@ -494,7 +498,13 @@ def dingtalk_dws_download(manifest, max_bytes): raise _dws_error(verdict) elif extension == "axls": target = "out.xlsx" - axls_to_xlsx.build_xlsx(axls_to_xlsx.fetch_sheets(raw_key), str(workdir / target)) + try: + axls_to_xlsx.build_xlsx(axls_to_xlsx.fetch_sheets(raw_key), str(workdir / target)) + except axls_to_xlsx.DwsCallError as error: + # Map the converter's dws failure onto the platform contract instead of + # letting the process die without a result (the Go runner would then only + # see "artifact_fetch_no_output"). + raise _dws_error(dws_error_map.classify({"error": {"message": str(error)}})) else: target = "out." + (extension or "bin") _, verdict = dws_run(["drive", "+download", "--node", raw_key, "--output", target], diff --git a/scripts/artifact_fetch_test.py b/scripts/artifact_fetch_test.py index e5f80d0..cadbdfb 100644 --- a/scripts/artifact_fetch_test.py +++ b/scripts/artifact_fetch_test.py @@ -171,15 +171,46 @@ class DingTalkDwsFetcherTest(unittest.TestCase): self.assertFalse(dws_download.called) def test_catalog_size_over_limit_never_starts_a_download(self): + # 普通文件的目录大小就是真实字节数 → 可以提前拒;在线文档不行(见下一个用例) with mock.patch.object(artifact_fetch, "DINGTALK_FETCHER", "dws"), \ - mock.patch.object(artifact_fetch, "dingtalk_raw_keys") as raw_keys, \ + mock.patch.object(artifact_fetch, "dingtalk_raw_keys", return_value=("raw-13", "file")), \ mock.patch.object(artifact_fetch, "dws_run") as dws_run: with self.assertRaises(artifact_fetch.FetchError) as raised: - artifact_fetch.dingtalk_download({**self.manifest, "size_bytes": 500_000_000}, 1_000_000) + artifact_fetch.dingtalk_download( + {**self.manifest, "name": "手册.pdf", "declared_type": "pdf", "size_bytes": 500_000_000}, 1_000_000) self.assertEqual(raised.exception.code, "over_limit") - self.assertFalse(raw_keys.called) - self.assertFalse(dws_run.called) + self.assertFalse(dws_run.called) # 预检必须在真正下载之前生效 + + def test_online_document_with_huge_catalog_size_still_exports(self): + # adoc/axls 的目录大小是"容器大小",可能远超上限而导出件很小 → 不得据此提前拒 + def fake_run(args, timeout=300, cwd=None): + self.assertEqual(args[:2], ["doc", "export"]) + pathlib.Path(cwd, "out.docx").write_bytes(b"PK\x03\x04" + b"m" * 40) + return {"success": True}, self.ok_verdict + + with mock.patch.object(artifact_fetch, "DINGTALK_FETCHER", "dws"), \ + mock.patch.object(artifact_fetch, "dingtalk_raw_keys", return_value=("raw-11", "file")), \ + mock.patch.object(artifact_fetch, "dws_run", side_effect=fake_run), \ + mock.patch.object(artifact_fetch, "exported_doc_is_blank", return_value=False): + path, size, digest, matched, fetcher = artifact_fetch.dingtalk_download( + {**self.manifest, "size_bytes": 500_000_000}, 1_000_000) + + self.assertEqual(fetcher, "dws") + self.assertEqual(size, 44) + + def test_axls_converter_failure_maps_to_platform_error(self): + # 转换器里的 dws 失败必须变成平台错误码,而不是让进程无结果退出 + with mock.patch.object(artifact_fetch, "DINGTALK_FETCHER", "dws"), \ + mock.patch.object(artifact_fetch, "dingtalk_raw_keys", return_value=("raw-12", "file")), \ + mock.patch.object(artifact_fetch.axls_to_xlsx, "fetch_sheets", + side_effect=artifact_fetch.axls_to_xlsx.DwsCallError("Access Denied")): + with self.assertRaises(artifact_fetch.FetchError) as raised: + artifact_fetch.dingtalk_download( + {**self.manifest, "name": "售前信息收集表.axls", "declared_type": "axls"}, 200_000_000) + + self.assertEqual(raised.exception.code, "forbidden") + self.assertFalse(raised.exception.retryable) def test_link_and_mind_nodes_map_to_missing_and_unsupported(self): cases = (("dlink", "链接节点.dlink", "missing", True), diff --git a/scripts/axls_to_xlsx.py b/scripts/axls_to_xlsx.py index 920becb..04b5843 100644 --- a/scripts/axls_to_xlsx.py +++ b/scripts/axls_to_xlsx.py @@ -21,6 +21,10 @@ from xml.sax.saxutils import escape NUM_RE = re.compile(r"^-?\d+(\.\d+)?$") +class DwsCallError(RuntimeError): + """dws 调用失败(供取件器映射成平台错误码,而不是让进程直接退出)。""" + + def dws_binary(): return os.environ.get("DWS_BIN") or shutil.which("dws") or "/usr/local/bin/dws" @@ -34,9 +38,18 @@ def run_json(args, timeout=180): p = subprocess.run([dws_binary(), *args, "-f", "json"], capture_output=True, text=True, timeout=timeout, env=env) try: - return json.loads(p.stdout) + payload = json.loads(p.stdout) except Exception: - raise SystemExit(f"dws 调用失败: {' '.join(args)} :: {(p.stdout or p.stderr)[:300]}") + raise DwsCallError(f"dws 调用失败: {' '.join(args)} :: {(p.stdout or p.stderr)[:300]}") + failed = (p.returncode != 0 or payload.get("success") is False or payload.get("ok") is False + or payload.get("status") in ("failure", "failed")) + if failed: + message = "" + err = payload.get("error") + if isinstance(err, dict): + message = str(err.get("message") or err.get("cause") or "") + raise DwsCallError(message or f"dws 调用失败: {' '.join(args)}") + return payload def fetch_sheets(node): @@ -44,7 +57,7 @@ def fetch_sheets(node): listing = run_json(["sheet", "list", "--node", node]) sheets = listing.get("sheets") or [] if not sheets: - raise SystemExit(f"sheet list 无工作表: {json.dumps(listing, ensure_ascii=False)[:200]}") + raise DwsCallError(f"sheet list 无工作表: {json.dumps(listing, ensure_ascii=False)[:200]}") out = [] for s in sheets: sid = s.get("sheetId") or s.get("name") @@ -186,4 +199,8 @@ def main(): if __name__ == "__main__": - main() \ No newline at end of file + try: + main() + except DwsCallError as error: + print(json.dumps({"success": False, "error": str(error)[:300]}, ensure_ascii=False), file=sys.stderr) + sys.exit(2) \ No newline at end of file diff --git a/scripts/dws_error_map.py b/scripts/dws_error_map.py index ed64cd1..c451edd 100644 --- a/scripts/dws_error_map.py +++ b/scripts/dws_error_map.py @@ -45,7 +45,7 @@ RULES = [ # ---- 空文档(与平台既有判定同义) ---- (r"content is empty|正文为空|content\s+is\s+empty", "empty_document", False, False, "文档正文为空,无需入库"), # ---- 服务端导出失败/超时 ---- - (r"导出任务失败|export job failed|submitExportJob", "export_failed", False, False, "钉钉导出任务失败"), + (r"导出任务失败|export job failed|submitExportJob", "export_failed", True, False, "钉钉导出任务失败"), (r"导出任务超时|export job timed out|timed out|timeout|超时", "export_timeout", True, False, "导出/请求超时,可重试"), # ---- 连接层 ---- (r"connection refused|no such host|network is unreachable|i/o timeout|EOF|connection reset|request_failed|502|503|504|HTTP 5\d\d", diff --git a/scripts/test_dws_error_map.py b/scripts/test_dws_error_map.py index b82a636..2178bcc 100644 --- a/scripts/test_dws_error_map.py +++ b/scripts/test_dws_error_map.py @@ -1,8 +1,12 @@ #!/usr/bin/env python3 """dws_error_map 单测:全部使用本轮实测捕获的真实 dws 错误体(不改写、不简化)。""" import json +import os import sys -sys.path.insert(0, "/home/zheromiku/dws_test/bridge") +# 测的是仓库里的实现(脚本目录),bridge/ 只是本轮评估期的开发副本 +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +if not os.path.exists(os.path.join(os.path.dirname(os.path.abspath(__file__)), "dws_error_map.py")): + sys.path.insert(0, "/home/zheromiku/dws_test/bridge") from dws_error_map import classify # —— 真实样本(逐字来自本轮会话的工具输出)—— @@ -68,6 +72,11 @@ CASES = [ {"category": "api", "code": 1, "message": "DingTalk export job timed out after 120s"}, ("export_timeout", True, False)), + ("导出任务失败(并发压测实测:同一节点 8 路偶发失败、1/2/4 路及串行必成)", + {"error": {"category": "api", "code": 1, "message": "提交导出任务失败: 钉钉导出任务失败", + "server_error_code": "internalError"}}, + ("export_failed", True, False)), + ("未分类错误 → 不得默认可重试", {"category": "internal", "code": 9, "message": "something nobody has seen before"}, ("unknown", False, False)),