v0.3.0

v0.3.0 —— 地形切片层级改成按源数据分辨率自动决定；瓦片挪到独立端口，看地图时页面不再跟着卡住

先说结论：这一版有两处升级即生效、不需要你动手的变化 —— 地形切片的「最大层级」不再固定在 14，改成按源数据的分辨率现算；底图、地形、等高线和历史预览的瓦片挪到一个独立端口 5001，出图期间页面上其他操作不再排队等它。已有瓦片不失效，已下载的数据、已切好的地形都不必重做。 要留意的只有两件事：程序从此多监听一个端口（首次运行防火墙可能多问一次，但不放行也照常能用，只是慢回去），以及那个端口对任意网页开放跨源读取 —— 这条写在第二节末尾，请读一下再决定要不要放行。

地形切片层级改成按源数据分辨率自动决定（升级即生效，出厂默认）

• 结论：切片的「最大层级」不再固定在 14。新装的程序、以及配置里这一项还是出厂 14 的老用户，升级后每次切片都按源数据的像素尺寸现算基准层级。自己把它设成过别的数（12、16 之类）的人完全不受影响，那条配置原样保留。
• 对本工具默认下载的 30 m 源（Copernicus GLO-30 / ASTER）产物零变化。 按分辨率算出来的基准层级对它正好就是 14：同一份 DEM、同一个档位，切出来的层级、张数、体积与上一版逐位相同。这也正是敢动出厂值的理由。
• 变化只发生在非 30 m 源上，此前两个方向都在做无用功：
  • 粗源不再超建。 3″（约 93 m）的 DEM 此前照样建到 z14 = 77.4 MB / 12071 张；按它自己的分辨率只需建到 z12 = 6.9 MB / 1445 张。多出来的 11 倍体积不含任何新地形，只是同一批 93 m 数据被插得更平滑。
  • 细源不再被截断。 5 m 的 DEM 应当建到 z16，此前一律卡在固定的 14，你手里的细节根本没进瓦片 —— 而且从界面上看不出来。
• 想要固定层级的照旧可以：在「数据处理」表单里把层级旁边的「自动」取消勾选，数字框就恢复可填，行为与上一版完全一样。
• 起切之前先告诉你规模：选好源文件后，信息卡里多一行「预计切片」，写明基准层级、当前档位实际会切到的层级、瓦片张数与体积估算（勾了顶点法线再乘 1.4）。只预告、不拦你。跨 180° 经线的 DEM 上这一行会隐藏 —— 那种数据的张数会少算约六成，与其给个错数不如不给。
• 顺带把三个档位的含义坐实了：精细 / 均衡 / 快速此前是「比你填的那个数多切一级 / 不变 / 少切一级」，你填错了它们就跟着错；现在锚在源分辨率上，三档实打实等于顶点间距约 0.3 / 0.6 / 1.2 倍源像素。
• 升级后首次启动会自动改一次配置：配置里的切片层级如果还是出厂的 14，会被改写成 auto；你自己填过别的数就一个字不动。这是一次性的，不需要你做任何事。任务详情里那一格也跟着改口 —— 自动挡下显示「自动（按源数据分辨率）」，切完之后显示实际切到的层级，不再拿一个填过的数冒充结果。

瓦片挪到一个独立端口出图，看地图的时候页面不再被拖住（升级即生效）

• 结论：程序现在多监听一个端口 5001，底图、地形、等高线和历史任务预览的瓦片全部走它；页面、配置、任务接口和实时进度仍然走 5000。已有瓦片、已下载的数据、已切好的地形全部不失效，不必重做，也没有数据库迁移。
• 修的是什么现场：浏览器对同一个「地址 + 端口」在 HTTP/1.1 下只开约 6 条连接。此前所有瓦片都由程序在 5000 上转发出去，首屏几十张瓦片、每张回源要秒级，这 6 条被占满期间页面上其他动作全在浏览器自己的队列里等着 —— 配置保存点了没反应、任务列表刷不出来、历史页转圈，连实时进度的连接握手都排在同一条队里。换句话说，堵在浏览器到程序这一段，不是程序只能同时处理 6 个请求，调大配置里的「并发下载数」对它一点用都没有。磁盘缓存也挡不住：它只挡重复访问，第一次看、或者平移到没看过的区域时照旧。
• 分成两个端口之后，浏览器按「地址 + 端口」各给一套连接池，瓦片风暴再也挤不到接口那一侧。
• 顺带修好一条串行：历史页的表格和统计不再等地图。以前小地图不初始化完，表格根本不开始加载；现在两边并行，地图起不来也不连累表格。
• 不必为 5001 专门开防火墙。 本机用 localhost 访问走的是回环地址，不经过入站规则；只放行 5000 的环境照样能用 —— 瓦片会自动退回原来的同源路径，功能一模一样，只是慢回去。降级有三种触发方式：端口被别的程序占住（服务端启动时就知道，当场退回，不重试也不换端口）、端口起来了但客户端够不着（防火墙拦入站、反代只转了 5000、从另一台设备访问 —— 由浏览器每次开页面探一次，1 秒内没回应就整页退回）、以及通过 HTTPS 访问时根本不启用（页面不会去探一个明文端口，那本来就会被浏览器按混合内容拦掉）。
• 探测结果只存在当前页面里，改完防火墙或转发规则要刷新一次页面才重新判定。
• 5001 不是第二个 API 入口。 它只放行 /basemap/、/tiles/、/terrain/、/contour/ 四类瓦片路径和一个健康检查 /tile-health，其余请求（页面、静态资源、所有 /api/）一律 404。
• ⚠️ 一条 5001 带来的新暴露面，放行之前请读：它对自己的每一个响应（包括 404）都发 Access-Control-Allow-Origin: * —— 换个端口对浏览器就是跨源，不发这个头 Cesium 取瓦片和 layer.json 会直接失败，而且失败会被浏览器盖成一句 CORS 错误、真实状态码看不见。代价是你在浏览器里打开的任意一个网页，都可以跨源读取 5001 上的内容：底图瓦片、已下载任务的瓦片、地形与等高线瓦片。边界是清楚的 —— /api/ 全部 404，任务列表、配置、磁盘路径读不到；只有读、没有写（这些路径只登记了 GET）；泄露的是「这台机器上存在哪些瓦片」，比如挨个探任务 ID 的瓦片是否 200，从而知道你下过哪片区域。这一条与防火墙无关：跨源读取来自你本机浏览器里打开的页面，走回环地址，入站规则拦不到。不想要它，让 5001 起不来即可（比如让别的程序先占住这个端口），程序会自动退回同源出图，功能不变、只是慢一点。
• 地形任务的父层地址不再写死 localhost:5000。 那个值原本固定指向本机主端口，于是从另一台机器打开时，localhost 指的是你自己那台机器，父层根本取不到 —— 而 Cesium 对这种取不到并不报错：它塞一个假图层，还会连累你自己那份地形按错的格式解析，瓦片全 200、控制台干净、高程全错。现在默认写成相对路径，由浏览器按「谁提供了这份 layer.json」自己解析，换端口、走反代、从别的机器访问都对。已经切好的任务不用重切：磁盘上的文件一个字不动，只在程序对外提供它的时候归一。改写口径故意很窄 —— 只认「http + localhost/127.0.0.1 + 5000 端口 + /terrain/ 前缀」这一种旧写法；自己把它配成局域网 IP 或者外部地形服务地址的原样保留（那多半是部署者有意为之，猜错方向就是把一个能用的地形改成 404）。另外，把任务目录直接拷去 nginx 之类的静态服务器对外提供的，磁盘上仍是旧值，症状照旧 —— 别把这条归一当保险。

给排障和构建的人

• CI 的冒烟测试现在两个端口都探：http://127.0.0.1:5000/ 要 200，http://127.0.0.1:5001/tile-health 要 204，缺一条就判失败。原因是瓦片端口起不来属于静默降级（主服务照常 200），只探 5000 的话这类回归永远报绿，用户拿到的是一个瓦片全走同源、首屏照样被浏览器连接池堵死的包。
• /tile-health 只有一个用途：让客户端确认这个端口真的够得着。服务端知道自己绑上了没有，但不知道浏览器能不能连上（防火墙、NAT、反代、从另一台设备访问都可能让它连不上）。它返回 204、没有正文、不许缓存，且是精确匹配 —— /tile-health/、/tile-healthx 都是 404。
• 瓦片端口不可配置（固定主端口 + 1），被占用时不会自动换到 5002，只会降级；服务端日志里有一条 warning，界面上没有提示 —— 因为它只影响速度，不影响功能。

验证

• 本版全量测试 2214 项通过 / 3 项跳过（开发机 Linux；跳过的只在特定平台上有意义）。上一版发布时是 2035 项。
• 两部分都是逐个任务做的：写用例 → 在未改的实现上跑一遍确认它确实会红 → 再改、再跑绿，每个任务单独过一轮评审，最后再对整包做一次整体评审。自动层级那部分另有两轮专门的清理：先纠了 7 条「说法与事实不符」的注释与文档，再收紧 11 条「断言其实咬不住」的用例，每一条都用变异体自证过（把实现改坏，盯着断言真的变红）。
• 瓦片端口那部分的前端探测逻辑不是靠读代码断言的：用 Node 真的执行 static/js/ui.js，验证探测成功、只探一次、超时会取消请求、任何情况下都不抛错、HTTPS 页面直接跳过、外部地址不被改写。前后端那份瓦片路径白名单由一条相等性断言钉死，改一边不改另一边当场红。
• 这一节没有「快了多少」的现场数字：连接池上限是浏览器行为，本轮没有做改前改后的计时对比，只做了功能与契约验证。宁可不写，也不给一个编出来的倍数。
• 一处需要说明的口径：预告的瓦片张数是「预计生成的张数」，不是「Cesium 认得的可用张数」—— 后者还要过一道覆盖率闸门（v0.2.14 加的那条），比预告的少。

---

通用说明

• 下载安装：从下方 Assets 下载对应平台压缩包（terraforge-windows.zip / terraforge-linux.tar.gz / terraforge-macos.tar.gz），解压即用，无需安装 Python 环境。
• 下载体积：每个平台仍包含 167 MB 的全球底图分卷（自 v0.2.8 起）。
• 首次运行：启动可执行文件后，浏览器访问 http://localhost:5000 ；代理、并发、缓存管理等在「配置」页修改。程序另会监听 5001 出瓦片，不放行也能用（见上）。
• 历史版本：完整更新历史见仓库 CHANGELOG.md。
• 使用文档：见仓库 README.md 与 docs/guides/QUICKSTART.md。