f4e1ecc5f1
- artifact_fetch.py: 新增 dingtalk dws 取件器(adoc→doc export、axls→sheet 转换、其余→drive 直下),
ARTIFACT_DINGTALK_FETCHER=dws|auto|legacy 三级开关,auto 仅对可重试错误回落老路径;
平台侧判定(pick_suffix/SLIDES/magic/大小上限/sha256/spool/空壳检查)全部保留;
结果 JSON 字段不变(Go runner 用 DisallowUnknownFields 解析 stdout),取件器来源只写 stderr。
- axls_to_xlsx.py: 纯标准库 axls→xlsx(文本写入 sharedStrings 以通过空壳判定)。
- dws_error_map.py: dws 错误→平台 {ok,code,retryable,missing};未分类错误默认不重试。
- Dockerfile: alpine 增加 gcompat/libc6-compat;dws v1.0.63 固定版本+sha256 校验;构建期 dws version 自检。
- compose.yaml: worker 增加 dws 环境与凭据挂载(DWS_HOME 方案,XDG_DATA_HOME 不被 dws 识别)。
- 测试: artifact_fetch_test 新增 11 项(路由/回落语义/契约字段锁定);dws_error_map 17 断言。
- 实测: 真容器(--read-only --tmpfs --user 1000:1000) 端到端 adoc/axls/pdf 3/3 成功,docx sha 与平台基准一致。
78 lines
5.0 KiB
Markdown
78 lines
5.0 KiB
Markdown
# DingTalk 取件走 dws(DingTalk Workspace CLI)
|
||
|
||
默认**优先使用 dws** 取钉钉知识库字节,老路径(本地镜像树 + 浏览器 a-token 实况导出)作为回退保留。
|
||
|
||
## 1. 开关
|
||
|
||
| 环境变量 | 取值 | 含义 |
|
||
|---|---|---|
|
||
| `ARTIFACT_DINGTALK_FETCHER` | `auto`(默认) | 先 dws;**仅当** dws 返回可重试错误(429/5xx/超时/连接层/dws 二进制缺失)时回落到老路径 |
|
||
| | `dws` | 只用 dws,失败即失败(灰度验证/压测用) |
|
||
| | `legacy` | 完全绕过 dws,走原逻辑(回退开关) |
|
||
| `DWS_BIN` | 默认 `/usr/local/bin/dws` | dws 可执行文件 |
|
||
| `DWS_CONFIG_DIR` | 容器内 `/data/dws` | dws 配置目录(profiles/identity) |
|
||
| `DWS_HOME` | 容器内 `/data/home` | **dws 子进程专用 HOME**:文件型 keychain 必须位于 `$HOME/.local/share/dws-cli`(`XDG_DATA_HOME` 不被识别),只给 dws 子进程换 HOME,不动 worker 全局 HOME |
|
||
| `DWS_DISABLE_KEYCHAIN` | `1` | 无系统 keychain 的环境用 file-DEK 模式 |
|
||
|
||
## 2. 路由
|
||
|
||
按**已解析文件名后缀**路由(与老路径判定一致;manifest 无 `declared_type`,缺失时依次退回 `declared_type` → `dws drive +inspect`):
|
||
|
||
| 后缀 | 取件方式 | 产物 |
|
||
|---|---|---|
|
||
| `adoc` | `dws doc export --export-format docx` | docx |
|
||
| `axls` | `dws sheet list` + `sheet range read` → `scripts/axls_to_xlsx.py` 落盘 | xlsx |
|
||
| 其余可入库类型 | `dws drive +download` | 原后缀 |
|
||
| `dlink` / `hlink` | 直接 `missing`(链接节点 fileSize=0) | — |
|
||
| `amind` / `appt` | `unsupported_format`(CLI 无内容导出入口,与老路径等价) | — |
|
||
|
||
**平台侧判定一律保留**:`pick_suffix`、`SLIDES`(PPT 必须 PDF 双胞胎)、magic 校验、大小上限、`sha256`、spool 原子写、`exported_doc_is_blank()` 空壳检查。dws 只负责“取字节”。
|
||
|
||
## 3. 错误映射
|
||
|
||
`scripts/dws_error_map.py` 把 dws 的错误体(严格版 `ok/error` 包裹、普通子命令 `error` 对象、本地错误、TLS/网络文本)统一映射为平台语义 `{ok, code, retryable, missing}`。要点:
|
||
|
||
- 只有明确瞬时信号(429/5xx/超时/连接层失败/**dws 二进制缺失**)为 `retryable=true`;
|
||
- 未分类错误 `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 个断言,样本为实测捕获的真实错误体)。
|
||
|
||
## 4. 镜像与部署
|
||
|
||
- 镜像:`alpine:3.22` + `gcompat libc6-compat ca-certificates`(官方 dws 是动态链接 glibc 的二进制,靠 gcompat 在 musl 上运行;已验证端到端字节一致);dws **版本与 sha256 固定在 Dockerfile 的 `DWS_VERSION`/`DWS_SHA256`**,**禁用 `dws upgrade`**。
|
||
- 凭据:**与宿主共享同一份 state**(refresh token 是轮换制,两个副本会互相顶掉):
|
||
- `~/.dws` → `/data/dws`(`DWS_CONFIG_DIR`)
|
||
- `~/.local/share/dws-cli` → `/data/home/.local/share/dws-cli`(`DWS_HOME`)
|
||
- 容器必须 `--user <宿主 uid>:<gid>`(worker 已是 `1000:1000`),否则 state 被写成 root 所有。
|
||
|
||
## 5. 续期 Runbook(refresh token 30 天)
|
||
|
||
```bash
|
||
# 到期前 7 天(阈值告警)在目标机执行,本人完成浏览器授权
|
||
dws auth login --device
|
||
# 验证必须真实调用,而不是只看 authenticated 字段
|
||
dws wiki +space-list --limit 1 -f json # 期望 ok:true
|
||
docker exec <worker> dws auth status --readonly -f json
|
||
```
|
||
|
||
出现 `code=credentials` 时**立即停批**(不要重试风暴),重新授权后 `--retry-failed` 续跑。健康面板建议展示 `refresh_expires_at`:<7 天黄、<3 天红。
|
||
|
||
## 6. 回退演练(上线前必做)
|
||
|
||
```bash
|
||
docker compose exec worker env ARTIFACT_DINGTALK_FETCHER=legacy ... # 或改 compose 环境变量后重建 worker
|
||
# 取同一批节点 → 断言 spool_ref/sha256 契约不变、无新增 code=* → 再切回 auto
|
||
```
|
||
|
||
保留 `dingtalk-login` sidecar 与 63GB 镜像树至少 2 周(镜像树可降级为只读热备)。
|
||
|
||
## 7. 验证证据(2026-10-09)
|
||
|
||
| 项 | 结果 |
|
||
|---|---|
|
||
| 影子比对(真实 worker 容器 vs 宿主 dws) | adoc 24/24 等价(正文相似度 1.0、media 逐项相等、11/24 字节完全相同);普通文件 5/5 `sha256` 一致;axls 归一化后值覆盖 100%/100% |
|
||
| 容器端到端(本改动 + 真容器约束 `--read-only --tmpfs /tmp --user 1000:1000`) | adoc/docx 305,078B(sha `77b393c3…`,与平台基准一致)、axls/xlsx 3,330B、pdf 27,140B → **3/3 成功**;结果 JSON 字段与改动前完全一致 |
|
||
| 单元测试 | `scripts/artifact_fetch_test.py` 14 项、`scripts/artifact_fetch_blank_doc_test.py` 5 项、`scripts/test_dws_error_map.py` 17 断言 —— 全绿 |
|
||
| 大表能力 | 平台老路径失败的 220MB/15 表/3,658 行 axls,dws + 转换器 18s 产出 128KB 有效 xlsx | |