如何自建免费 Open-Meteo 天气 API：新手三步部署完整指南

如何自建免费 Open-Meteo 天气 API：新手三步部署完整指南

【免费下载链接】open-meteoFree Weather Forecast API for non-commercial use项目地址: https://gitcode.com/GitHub_Trending/op/open-meteo

Open-Meteo 是一个免费开源的气象数据平台，用它几行命令就能自建专属天气 API 服务：拉源码、起容器、同步数据，8080 端口上就有可用的小时级预报接口。

一、Open-Meteo 到底能帮你解决什么问题

不再被第三方接口卡脖子

如果你的项目里只要"一个天气接口"，通常的路径是：找商业 API 注册、付费、看配额脸色。Open-Meteo 把这条链路整个换掉：上游数据来自各国气象机构公开发布的数值预报，处理管线和 API 服务全部开源，整套服务可以跑在你自己的机器上，端点、变量、存储都归你管。

一个容易落地的场景

假设你运营几个温室大棚，想每小时拿 2 米气温、相对湿度和降水量，来决定通风机和遮阳网的开关。调公开 API 也能做，但更新节奏、私有派生变量、内网设备访问这些需求就受制于人了。自建 Open-Meteo 之后，接口就挂在你的内网里，要什么变量自己定，数据落在自己的磁盘上。

开箱能拿到什么

• 最长 16 天的小时级预报
• 80 年历史天气（基于 ERA5 再分析）
• 多模型集成：全球 11 km 分辨率，区域模型细到 2 km（ICON D2），个别模型可达 1.5 km
• 除预报外还有海洋、空气质量、洪水、高程等 API

以上能力以 README 中的描述为准。

二、动手前：环境清单 + 源码获取

硬件最低要求与推荐配置

API 服务器用 Swift 编写，编译后是单个二进制文件，运行环境非常干净，你只需要 Docker。

两个容易忽略的点：

1. 磁盘就是缓存。每次请求只会读取压缩数据里的一小段，最近访问的数据会留在本地盘上，NVMe 和 SATA 在这里体验差距明显。
2. 内存也参与缓存。轻度自用 8 GB 足够；变量多、还要查历史数据的场景，16 GB 会从容很多。

完整硬件要求见 入门指南。

获取源码

git clone https://gitcode.com/GitHub_Trending/op/open-meteo cd open-meteo

仓库不大，核心就是 Dockerfile（把 Swift 源码编译成单个openmeteo-api二进制）和 docker-compose.yml（服务编排）。

三、三步跑起来：容器化部署实操 🚀

以下就是完整的 Open-Meteo Docker 搭建流程。

第一步：一条命令启动服务

docker compose up -d

docker-compose.yml 里定义了两个容器：

• open-meteo-api：API 服务器，监听8080端口（--hostname 0.0.0.0 --port 8080）
• open-meteo-sync：数据同步 worker，持续从数据分发源拉取dwd_icon模型的temperature_2m变量

两者共享一个命名卷open_meteo_database（挂载到容器内/app/data），所有气象数据都存在这里。首次运行需要构建镜像（Swift 编译，约几分钟），之后再启动只要几秒。

第二步：首次数据同步

同步 worker 会自动启动，你也可以手动触发一次，直观看到发生了什么：

docker exec -it open-meteo-api sync dwd_icon temperature_2m --past-days 3 --repeat-interval 5

命令格式是固定的：sync <模型，逗号分隔> <变量，逗号分隔>。想多拿几个变量，直接加：

docker exec -it open-meteo-api sync dwd_icon temperature_2m,relative_humidity_2m,precipitation --past-days 7

常用选项（完整参数见 同步命令源码）：

• --past-days：往回同步多少天，默认 7
• --repeat-interval N：常驻运行，每 N 分钟检查一次新文件
• --server：数据源，默认指向 Open-Meteo 开放数据 S3 分发源，不用配置

第三步：验证接口是否可用

curl "http://localhost:8080/v1/forecast?latitude=52.52&longitude=13.41&hourly=temperature_2m&models=icon_global"

返回包含time数组和temperature_2m数组的 JSON，就说明部署成功了。注意第一次请求偏慢：数据要从远端拉下来写入本地缓存，之后同位置或邻近坐标的请求通常都在亚秒级。接口的完整定义在 openapi/forecast.yml。

四、数据从哪来：气象模型与变量解析 📡

上游是国家气象机构的开放预报

Open-Meteo 自己不做模型，它把各国机构公开发布的数值天气预报拉下来，统一格式后存入可查询的数据库。常见来源：

模型域注册表 里列出了全部可用的域标识符，sync命令里的dwd_icon指的就是 DWD ICON。

变量名怎么读

变量命名基本自解释，几个高频的：

• temperature_2m：距地面 2 米气温，后缀_2m表示高度
• dew_point_2m、relative_humidity_2m：露点温度、相对湿度
• precipitation：每小时降水量
• wind_speed_10m、wind_direction_10m：10 米高度风速、风向
• weather_code：整数天气码（WMO 标准），对应"小雨""多云"这类文字描述

想看某个模型支持哪些变量，直接读源码最快，例如 ICON 的完整变量清单在 IconVariable.swift。

单点取数为什么快

这是 Open-Meteo 最有工程味的一环。原始模型文件（GRIB 之类）体积很大，每次查询都要在网格里定位经纬度再插值，开销不小。Open-Meteo 把数据预先转成自研二进制格式：按"位置 × 变量 × 时间段"拆成独立小文件，查询时直接打开对应文件就行——类似图书馆按编号取书，而不是每次翻遍整个书库。这也是它能在普通硬件上把平均响应时间压到毫秒级的原因。

五、调优与生产化：性能、成本、安全 🔧

只同步需要的变量

这是省空间最直接的手段。ICON 全量变量体积可观，只需要温度和湿度就只同步这两个：

docker exec -it open-meteo-api sync dwd_icon temperature_2m,relative_humidity_2m --past-days 7 --repeat-interval 5

如果用 Ubuntu 包版本，也可以写进配置文件：SYNC_ENABLED=true、SYNC_DOMAINS=dwd_icon、SYNC_VARIABLES=temperature_2m,dew_point_2m、SYNC_REPEAT_INTERVAL=5，然后重启同步服务。全部参数见 数据下载文档。

8GB 内存够不够

轻度使用够。记住前面的结论：内存和磁盘都参与缓存。跑高频业务或大量查询历史数据时（ERA5 一年大约 60 GB），把CACHE_SIZE环境变量调大（如 8GB），内存给到 16 GB + NVMe，体验会明显更好。

用 cron 自动清理过期数据

预报数据时效性强，老数据没多少价值。官方给出的清理模板是：气压层数据 10 天后删除，地表数据 90 天后删除，照抄即可，模板见 cronjobs.md。

前置 nginx：TLS 与限流

compose 版默认监听 0.0.0.0:8080，直接暴露公网不建议。生产环境挂一层反向代理做 TLS 最稳妥，多节点同步文档 里有一份现成的 nginx 配置可以参考。服务端自带限流和 API key 管理实现（RateLimiter.swift、ApiKeyManager.swift），需要管控访问时可以用上。另外数据是 CC-BY-4.0：展示数据时要保留来源署名。

六、常见问题 FAQ 🛟

首次请求为什么很慢

冷缓存。第一次请求某个变量需要从远端分发源取数，单次可能涉及几 MB 数据；之后同位置或邻近坐标的请求命中本地缓存，通常亚秒返回。

能不能不下载全量数据直接用

能。API 可以直接读取远端开放数据源并本地缓存，不需要先下完整个数据集。只有当你想完全离线、或者查询量很大时，才需要用sync把数据完整拉到本地。

想加一个新变量怎么办

把变量追加到sync命令的变量列表即可。如果要走原始数据路线，也可以让下载器按变量过滤，例如download icon --run 00 --only-variables temperature_2m,weather_code。注意不是所有变量在所有模型上都提供。

想绑域名对外提供怎么配

nginx 反代到127.0.0.1:8080，配上证书即可。Ubuntu 包版本默认只绑定 127.0.0.1（外部不可访问），天然安全，直接加代理层就行。

能商用吗

自部署支持非商业与商业两种用途，但注意两份协议：源码是 AGPL-3.0（修改后以服务形式对外提供，需要开放你的修改版源码），数据是 CC-BY-4.0（必须署名）。完整条款见 README。

写在最后

把主线再串一遍：git clone→docker compose up -d→sync→curl验证，这套 Open-Meteo 部署下来也就半小时的事。自建的最大价值不是省下几块钱接口费，而是端点、变量、存储都在你手里，可以按业务节奏改。如果你的项目涉及天气，值得在服务器上给它留个位置。

再往后延伸的空间也不小：海洋 API、空气质量 API、80 年历史天气 API，以及多节点分布式部署（一台机器负责下载、多台机器共享查询）——每个方向都值得单独展开。

【免费下载链接】open-meteoFree Weather Forecast API for non-commercial use项目地址: https://gitcode.com/GitHub_Trending/op/open-meteo