离线机器上CityData、WeatherData全不能用，怎么把paclet搬过去？

一、问题定义：为什么“装好了”却查不到城市与天气

1.1 现象与最小复现

在一台可联网的机器上，CityData["Beijing"] 会返回一个 CityData 对象，WeatherData["Beijing","Temperature"] 会给出带时间戳的 TimeSeries。把同一份安装介质拷到离线机后，常见表现是：

CityData["Beijing"]
(* 离线机典型返回 *)
CityData["Beijing"]

WeatherData["Beijing", "Temperature"]
(* 返回 $Failed 或 Missing["NotAvailable"] *)

$EntityStores
(* 可能为空列表，或缺少 "City"、"WeatherStation" 等域 *)

这里需要先厘清一个概念：实体（Entity）是 Wolfram 知识库中一类可被结构化引用的对象，Entity["City", "Beijing"] 只是它的规范名称；真正承载属性值的是背后的实体存储（EntityStore）与paclet 资源。因此“查不到”通常不是语法问题，而是资源缺失。

1.2 常见误判与排除顺序

工程上最容易走弯路的地方，是把资源缺失误判为网络问题或许可证问题。建议按以下顺序排除：

笔者在实践中发现，多数离线部署事故都落在最后一行：内核与前端完整，但 $UserBaseDirectory 与 $InstallationDirectory 下的 paclet 树不完整。这一点与 Wolfram 官方文档中关于 paclet 管理的说明一致：paclet 是独立于内核的可安装单元，其资源需要显式分发。

延伸阅读：Wolfram 官方 Paclet 框架文档与 PacletInstall 参考页，可作为目录结构与安装语义的权威依据。PacletInstall · Paclets 指南

二、原理拆解：paclet 的目录布局、解析顺序与依赖模型

2.1 三个关键目录

要搬运，先要知道东西在哪。Wolfram 语言通过 $BaseDirectory、$UserBaseDirectory、$InstallationDirectory 三个根路径组织资源。paclet 通常位于各根下的 Applications 或 Paclets 子目录中。

(* 打印三个根路径，便于定位 *)
{$BaseDirectory, $UserBaseDirectory, $InstallationDirectory}

(* 列出当前可见的 paclet 及其版本与位置 *)
PacletFind[]

(* 查看某个 paclet 的详细信息 *)
PacletFind["CityData"]

三个根路径的解析优先级是有约定的：用户目录优先于系统目录，系统目录优先于安装目录。这意味着，如果用户在 $UserBaseDirectory 下装过一个旧版本 paclet，它会遮蔽安装目录中的新版本。本文评述：这一设计在单机场景下方便覆盖与实验，但在离线批量部署中恰恰是“版本漂移”的温床——多台机器上残留的用户级 paclet 会让同一份安装介质表现出不同行为，因此搬运工程必须显式处理优先级。

2.2 paclet 的内部结构与依赖声明

一个标准 paclet 目录通常包含 PacletInfo.wl（或历史格式 PacletInfo.m）、Kernel/ 下的加载代码，以及 Data/、Documentation/ 等资源目录。依赖关系写在 PacletInfo 的 PacletDependency 字段中。

(* 读取某 paclet 的元信息，观察依赖与版本 *)
info = PacletInfo /. PacletFind["CityData"];
info["Version"]
info["Dependencies"]

(* 列出所有 paclet 的名称与版本，作为清单基线 *)
Dataset[AssociationThread[
  #["Name"] -> #["Version"] & /@ PacletFind[]
]]

需要强调的是，实体数据类 paclet 的依赖往往不止一层。例如城市数据可能依赖基础地理 paclet，而地理 paclet 又依赖坐标参考系或单位系统。只拷“看起来相关”的那一个目录，是离线部署最常见的失败原因。

2.3 依赖闭包：本文的分析主线

我们把“从目标 paclet 出发，沿依赖边递归可达的全部 paclet 集合”定义为依赖闭包（dependency closure）。搬运的正确对象不是单个 paclet，而是它的依赖闭包。这个定义看似朴素，却把问题从“找文件”转化为“图遍历”，从而可以系统化、可验证地完成。

形式化地，设 paclet 集合为 P，依赖关系为有向边 E，目标集合为 T，则需搬运的集合为 C = { p ∈ P | 存在 t ∈ T，t 可经 E 到达 p }。工程上还要叠加两个约束：版本约束（依赖声明的版本区间）与平台约束（部分 paclet 按操作系统分发二进制资源）。

笔者认为，依赖闭包之所以值得作为主线，是因为它同时解决了三个痛点：漏拷（闭包保证完备）、多拷（闭包保证最小）、错版本（闭包可携带版本约束）。后续所有步骤都围绕它展开。

三、主线方法：以依赖闭包为核心的搬运工程

3.1 依赖图构建

第一步是在在线参考机上构建依赖图。参考机应与离线机保持相同的内核版本与操作系统，否则闭包中的平台相关资源可能不匹配。构建方式有两种：一是解析各 paclet 的 PacletInfo，二是利用 PacletFind 的依赖查询接口。

(* 构建 paclet 依赖图（示意，按实际 API 调整） *)
all = PacletFind[];
edges = Flatten@Table[
   With[{name = p["Name"], deps = p["Dependencies"]},
     If[deps === Missing["NotAvailable"] || deps === {},
       {},
       name -> #["Name"] & /@ deps
     ]
   ],
   {p, all}
];

g = Graph[DeleteDuplicates@Flatten[edges],
   VertexLabels -> "Name",
   GraphLayout -> "LayeredDigraphEmbedding"];

(* 求目标 paclet 的依赖闭包 *)
closure = VertexInComponent[g, "CityData", 1]

本文评述：直接依赖 PacletFind 的返回结构在不同版本间存在差异，工程脚本必须做防御性判断（如上面的 Missing 分支）。把“依赖字段可能缺失”当作常态而非异常，是脚本可跨版本复用的关键。

3.2 版本钉扎与清单固化

闭包确定后，需要把每个 paclet 的名称、版本、来源路径、校验值固化为清单文件。这一步借鉴了软件供应链中“锁文件”的思路：离线部署的可复现性，取决于清单是否完整记录了当时的确切状态。

清单建议以 JSON 或 WL 关联形式保存，并与安装介质一同归档。笔者建议把清单纳入版本控制，这样每次离线镜像更新都有可追溯的差异记录。

3.3 离线镜像的目录组织

把闭包内 paclet 打包成离线镜像时，建议保持与目标机解析路径一致的目录层级，避免落地时再做路径映射。一个可用的镜像结构如下：

offline-mirror/
├── manifest.json          # 清单：名称/版本/哈希/平台
├── paclets/
│   ├── CityData-1.x.y/    # 目录名含版本，避免覆盖
│   ├── WeatherData-1.x.y/
│   └── GeoBase-1.x.y/
└── checksums.sha256       # 汇总校验文件

本文评述：目录名带版本号是一种低成本的“防覆盖”手段。离线机多次升级时，旧版本目录仍可保留，配合优先级规则即可实现快速回滚，而不必重新从参考机拷贝。

四、实操步骤：从在线机采集到离线机落地的完整流程

4.1 在线参考机：采集与打包

在参考机上执行采集脚本，输出清单与压缩包。注意两点：一是采集前先清理用户级 paclet，确保采集到的是安装目录中的“干净”版本；二是打包时保留文件权限与符号链接（部分 paclet 含可执行资源）。

(* 采集脚本骨架：导出闭包清单 *)
targets = {"CityData", "WeatherData"};
all = PacletFind[];
g = Graph[DeleteDuplicates@Flatten[
   Table[With[{n = p["Name"], d = p["Dependencies"]},
      If[ListQ[d] && d =!= {}, n -> #["Name"] & /@ d, {}]],
     {p, all}]]];
closureNames = DeleteDuplicates@Flatten[
   VertexInComponent[g, #, 1] & /@ targets];

manifest = <|
   "Generated" -> DateString[],
   "Kernel" -> $Version,
   "Platform" -> $SystemID,
   "Paclets" -> KeyValueMap[
     <|"Name" -> #1, "Version" -> #2["Version"],
       "Location" -> #2["Location"]|> &,
     AssociationThread[closureNames,
       PacletFind[#] & /@ closureNames]]
|>;
Export["manifest.json", manifest, "JSON"];

打包命令在系统 shell 中执行，便于保留权限：

# 以 Linux 为例，打包闭包目录并生成校验
tar --numeric-owner -czf paclets.tar.gz paclets/
sha256sum paclets.tar.gz > paclets.tar.gz.sha256

4.2 介质传递与完整性校验

跨网传递后，第一步永远是校验而非解压。校验失败通常意味着传输截断或介质损坏，此时解压只会得到半成品目录，反而增加排查成本。

# 校验通过再解压
sha256sum -c paclets.tar.gz.sha256
tar -xzf paclets.tar.gz -C /opt/wolfram-offline/

4.3 离线机：落地与注册

落地有两种方式：一是把 paclet 目录直接放入 $UserBaseDirectory/Applications，二是使用 PacletInstall 从本地文件安装。前者简单直接，后者会登记元信息、便于 PacletFind 统一管理。推荐后者。

(* 从本地目录安装（路径按实际调整） *)
PacletInstall["/opt/wolfram-offline/paclets/CityData-1.x.y"]

(* 验证：应能看到目标 paclet 及其版本 *)
PacletFind["CityData"]

(* 验证实体存储是否可用 *)
$EntityStores
CityData["Beijing"]

若 PacletFind 能看到但 CityData 仍不可用，多半是依赖闭包不完整——某个二级依赖未安装，导致实体存储初始化失败。此时应回到依赖图，检查该 paclet 的依赖是否全部落地。

拓展资源：Wolfram 社区关于离线安装与 paclet 分发的讨论帖，常有一线工程师分享的踩坑记录。Wolfram Community · Wolfram Paclet Repository

五、校验、回滚与版本钉扎

5.1 三层校验

离线部署的可靠性来自“可验证”。建议设置三层校验：文件层（哈希一致）、注册层（PacletFind 可见且版本正确）、功能层（关键实体查询返回非空）。三层缺一不可，因为文件完整不代表注册成功，注册成功也不代表数据可读。

(* 功能层校验：对关键实体做冒烟测试 *)
smoke = <|
  "City" -> Head[CityData["Beijing"]] =!= $Failed,
  "Weather" -> Head[WeatherData["Beijing", "Temperature"]] =!= $Failed
|>;
smoke

5.2 回滚策略

回滚的前提是旧版本仍在磁盘上。由于镜像目录带版本号，回滚只需调整解析优先级：删除或重命名新版本目录，使旧版本重新可见；或使用 PacletUninstall 卸载新版本后再安装旧版本。本文评述：回滚方案必须在升级前就设计好，事后补做往往因旧目录被覆盖而无从下手。

5.3 版本钉扎的边界

钉扎并非越死越好。实体数据类 paclet 会随地理边界、气象站变更而更新，长期钉扎旧版本会导致数据陈旧。合理做法是：内核与基础依赖钉扎，实体数据类 paclet 按季度评估更新，并在更新前用同一套三层校验做回归。这样既保证稳定性，又不至于让数据脱节。

六、对比与局限：几种搬运路线的边界条件

6.1 路线对比

6.2 局限与未解问题

依赖闭包方法并非万能。其一，部分实体数据在首次查询时仍需联网获取增量，离线环境下只能返回缓存或历史值，这是数据源本身的限制，而非搬运问题。其二，许可证条款可能限制 paclet 资源的再分发，批量拷贝前应确认授权范围。其三，跨大版本内核时，paclet 的二进制资源可能不兼容，闭包方法无法绕过 ABI 约束。笔者认为，承认这些边界，比宣称“一套脚本解决所有离线问题”更负责任。

七、结论与展望

离线机器上 CityData、WeatherData 不可用，根因是 paclet 资源未随内核迁移。本文以依赖闭包为主线，给出了从目录定位、依赖图构建、清单固化、镜像打包到落地校验与回滚的完整路径。其核心结论可以概括为三句话：搬闭包而非搬单件；钉版本而非钉路径；做校验而非凭感觉。

展望后续，随着 paclet 生态的规范化，离线镜像有望像容器镜像一样具备内容寻址与签名验证能力，届时依赖闭包的构建可以进一步自动化。对工程团队而言，尽早把清单与校验纳入版本控制，是应对未来数据更新与内核升级的最低成本准备。