生产运行

配置缓存、限制 CPU、保护远程资产并导出可观测性数据。

共享一个缓存

解码块缓存的默认预算是 512 MiB。拥有多个 reader 的服务应把同一个 Arc<BlockCache> 注入全部 reader 和 mosaic，并为每个不同 COG 使用稳定的源 ID，避免缓存键冲突。

这个预算只覆盖缓存中常驻的解码块，不等于进程总 RSS。飞行中的压缩字节、解码和重投影缓冲区、编码响应、reader 元数据与 mosaic reducer 状态会额外占用内存；其中 Median 会保留全部参与图像直到归并完成。

库不会实施全局请求并发限制，因此不能仅根据缓存容量推导严格 RSS 上限。应在服务或网关限制并发瓦片请求，保持单瓦片资产扇出有界，并使用包含最大允许源窗口与输出瓦片尺寸的压力测试来确定容器内存。

通过 BlockCache::stats() 可观察：

hits 与 misses
decoded 与 fetched
entries
resident_bytes

可进一步计算命中率、fetch/decode 放大比，以及常驻字节占配置预算的比例。

限制 CPU 工作

解码、拼接、重投影、镶嵌归并、渲染与编码都是 CPU 密集型工作。它们通过受 CpuLimiter 限制的 spawn_blocking 运行。非 mosaic CogReader 与 Tiler 接受调用方提供的 limiter；MosaicTiler 在资产与最终渲染之间共享一个内部 limiter，但不能接入非 mosaic limiter。默认值取主机可用并行度，并把 0 修正为至少一个 permit。

Tiler::new 会复用其 reader 携带的 limiter：

use std::sync::Arc;

use async_geotiff::CpuLimiter;
use async_geotiff::io::cog::CogReader;
use async_geotiff::tiler::Tiler;

let cpu = CpuLimiter::new(8);
let reader = Arc::new(
    CogReader::builder()
        .source_id("scene-a")
        .cpu_limiter(cpu.clone())
        .open_http("https://example.com/a.tif")
        .await?,
);
let tiler = Tiler::new(reader);

示例服务的 CPU 计数方式取决于数据路径。命令行默认 COG 使用相互独立的 reader 解码与 tiler 渲染 limiter，两阶段可以重叠；延迟选择的本地数据集复用一个 AppState limiter，其大小取两项配置中的较大值；MosaicTiler 还拥有自己的共享 limiter。因此两个环境变量是组件调优项，不是通用的进程级 CPU 上限。需要单一上限时，应在库级别把同一个 CpuLimiter 注入所有支持注入的非 mosaic reader 与 tiler。

当前 MosaicTiler 拥有内部共享 limiter，但 builder 不支持注入非 mosaic 路径的 limiter。因此，目前不支持对混合 mosaic 与单 COG 流量设置严格的数值型 CPU-job 上限。库外请求并发限制只能提供粗粒度背压，并不等同于共享 permit 预算。

不要在没有测量时主动降低瓦片并发。过小的限制会给每次瓦片请求增加排队时间；应先观察 P95 延迟与 CPU 竞争。

调整访问模式

多数据集服务或大范围平移/缩放场景可增加缓存容量。
读取延迟敏感时优先使用 ZSTD 压缩 COG，而不是 DEFLATE。
示例服务默认预取一圈原生块；不希望产生额外对象存储 GET 时，设置 ASYNC_GEOTIFF_PREFETCH_RING=0。
对不可信索引保持 MosaicConfig::max_assets_per_tile 有界。

导出 trace 与指标

Tiler::tile 和 CogReader::read_window 会发出 tracing span。需要 OTLP trace 时，在应用中连接 tracing-opentelemetry layer；库本身有意不依赖 OpenTelemetry。

在 HTTP 或应用边界记录请求量、延迟、错误量以及 Ok(None) 比例；另行轮询缓存统计，观察内存与远程读取行为。

保护远程访问

当 mosaic 或 STAC 文档不可信时使用严格的 HttpAccessPolicy。凭据应配置在 object_store 实例上，而不是嵌入资产标识。应用边界也应避免记录原始预签名 URL。