Open-Meteo 1.7.0 常用 CLI 命令与工具详解

openmeteo-api 单二进制 46 个子命令分类详解：serve/routes、sync 数据同步、version/benchmark 诊断、validate-om-files/migration 维护、convert-om/export 转换导出、download 家族与 s3-sync 分发，关键命令附真实执行回显与数据依赖排障实录，curl 实测 /v1/forecast 冷 42.6 秒、热缓存 1.1 毫秒。

Open-MeteoOpen-Meteo气象Ubuntu22.04Ubuntu24.042026/10/28

Open-Meteo 1.7.0 常用 CLI 命令与工具详解

目标：把 openmeteo-api 单二进制自带的 46 个子命令按「服务运行、数据同步、诊断基准、数据维护、数据下载、数据分发」六类讲清用法与实测行为——每个核心命令给出真实执行回显（含一次导出命令在数据未同步完整时的崩溃实录与定位过程），API 端点以 curl 实测覆盖 /v1/forecast、/v1/elevation 与错误响应。本文在 Ubuntu 22.04.5（官方 APT 包形态）与 Ubuntu 24.04.5（源码编译形态）两台服务器上实测，全部回显取自真实环境。

一、环境信息

项目服务器 A（APT 包形态）服务器 B（源码编译形态）
操作系统Ubuntu 22.04.5 LTS (jammy)Ubuntu 24.04.5 LTS (noble)
内核x86_64，6 核 / 18 GB 内存x86_64，6 核 / 18 GB 内存
软件版本openmeteo-api 1.7.0（官方 APT 包）openmeteo-api 1.7.0（源码编译）
命令路径/usr/local/bin/openmeteo-api/opt/open-meteo/bin/openmeteo-api
数据目录/var/lib/openmeteo-api/data（8.4 GB，同步中）/opt/open-meteo/data（远程缓存模式）
运行方式systemd（openmeteo-api / openmeteo-sync）systemd（openmeteo-api）
查询日期2026-10-282026-10-28

二、命令体系总览

openmeteo-api 是 Swift 编译的单二进制，所有能力以子命令组织。--help 输出完整命令清单（46 个，实测节选归类）：

openmeteo-api --help

Usage: /usr/local/bin/openmeteo-api <command>

Commands:
                    benchmark Benchmark Open-Meteo core functions like data manipulation and compression
                   convert-om Convert between om file format version or convert to NetCDF
                 download Download a specified icon model run
                 download-bom Download a specified Bom model run
                download-cams Download global and european CAMS air quality forecasts
               download-ecmwf Download a specified ecmwf model run
                download-era5 Download ERA5 from the ECMWF climate data store and convert
                 download-gfs Download GFS from NOAA NCEP
                 ...(download 家族共 33 个，按国家气象机构/数据源划分，全文见 --help)
                       export Export to dataset to NetCDF
                 merge-yearly Merge database chunks into yearly files
                    migration Perform database migration
                       routes Displays all registered routes.
                      s3-sync Synchronize a local directory to an S3-compatible server.
                        serve Begins serving the app over HTTP.
                         sync Download the open-meteo weather database from a S3 server.
            validate-om-files Recursively read the data variable of all .om files in DATA_DIRECTORY.
                      version Print the Open-Meteo build version

Use `/usr/local/bin/openmeteo-api <command> [--help,-h]` for more information on a command.

六类划分与本文对应章节：

类别命令章节
服务运行serve、routes三
诊断与基准version、benchmark四
数据同步sync五
数据完整性维护validate-om-files、migration六
数据转换与导出convert-om、export、merge-yearly七
数据下载 / 分发download-*（33 个）、s3-sync八

💡 技术拓展：这类「单二进制 + 子命令」的组织方式与 rclone（rclone serve/rclone sync）类似；区别在于 Open-Meteo 的子命令不是并列工具，而是围绕同一套 om 时序数据文件的「生产（download）→ 同步（sync/s3-sync）→ 校验（validate）→ 服务（serve）→ 再加工（export/convert-om）」流水线，命令间通过 DATA_DIRECTORY 数据目录衔接。

三、服务运行与 API 调用验证

3.1 serve：启动 API 服务

openmeteo-api serve --help

Usage: /opt/open-meteo/bin/openmeteo-api serve [--hostname,-H] [--port,-p] [--bind,-b] [--unix-socket] 

Begins serving the app over HTTP.

Options:
     hostname Set the hostname the server will run on.
         port Set the port the server will run on.
         bind Convenience for setting hostname and port together.
  unix-socket Set the path for the unix domain socket file the server will bind to.
  • -b/--bind 为 hostname:port 合写（官方 systemd 单元用 serve -b $API_BIND --env $VAPOR_ENV）；-H 0.0.0.0 -p 8080 与 -b 0.0.0.0:8080 等价。
  • --unix-socket /run/openmeteo.sock 供 Nginx 前置走套接字转发。
  • 生产运行统一交给 systemd（《安装部署指南》4.6/5.7），serve 手工前台执行多用于调试。

3.2 routes：列出全部注册端点

openmeteo-api routes

+------+-----------------+
| GET  | /robots.txt     |
+------+-----------------+
| GET  | /v1/era5        |
+------+-----------------+
| POST | /v1/era5        |
+------+-----------------+
| GET  | /v1/archive     |
+------+-----------------+
| POST | /v1/archive     |
+------+-----------------+
| GET  | /v1/forecast    |
+------+-----------------+
| POST | /v1/forecast    |
+------+-----------------+
| GET  | /v1/dwd-icon    |
+------+-----------------+
| POST | /v1/dwd-icon    |
+------+-----------------+
| GET  | /v1/gfs         |
+------+-----------------+
| POST | /v1/gfs         |
+------+-----------------+
| GET  | /v1/meteofrance |
+------+-----------------+
| POST | /v1/meteofrance |
+------+-----------------+
| GET  | /v1/jma         |
+------+-----------------+
| GET  | /v1/jma         | ...(共 22 个端点，GET/POST 成对)

用途：升级版本后核对端点集合、确认某数据域是否注册（端点按域名前缀路由，如 api.open-meteo.com 对应 /v1/forecast，自托管 IP 直连同样可达）。

3.3 API 端点 curl 实测

serve 只是入口，验证服务是否真正可用靠 curl。远程缓存模式下北京坐标逐小时气温（首调需从官方 S3 拉数据分块，实测 42.6 秒）：

time curl -sS --max-time 120 "http://127.0.0.1:8080/v1/forecast?latitude=39.9&longitude=116.4&models=ecmwf_ifs025&hourly=temperature_2m&forecast_days=1"

{"latitude":39.9,"longitude":116.4,"generationtime_ms":3763.21804523468,"utc_offset_seconds":0,"timezone":"GMT","timezone_abbreviation":"GMT","elevation":49.0,"hourly_units":{"time":"iso8601","temperature_2m":"°C"},"hourly":{"time":["2026-10-28T00:00",...24 个小时值...],"temperature_2m":[...实测 24 个小时值...]}}

同坐标复测，缓存命中 1.1 毫秒；generationtime_ms 是服务端纯计算耗时（首调 3763ms → 热缓存后为个位数），可用它区分「网络拉块慢」与「计算慢」：

time curl -sS -o /dev/null -w "%{time_total}s http=%{http_code}\n" "http://127.0.0.1:8080/v1/forecast?latitude=39.9&longitude=116.4&models=ecmwf_ifs025&hourly=temperature_2m&forecast_days=1"

0.001113s http=200

高程查询（静态数据，无需时序拉块）与参数校验错误响应：

curl "http://127.0.0.1:8080/v1/elevation?latitude=39.9&longitude=116.4"

{"elevation":[49.0]}

curl -sS "http://127.0.0.1:8080/v1/forecast?latitude=999&longitude=8.4"

{"reason":"Latitude must be in range of -90 to 90°. Given: 999.0.","error":true}

💡 说明：错误响应固定为 {"reason":...,"error":true} 结构（HTTP 400 语义），可据此做监控探活。多坐标请求返回 JSON 数组、单坐标返回对象，客户端解析时注意。

四、版本与基准诊断

4.1 version：版本自检

openmeteo-api version

openmeteo-api sha=92e8d2f9918d73a3a03e0dbba5baead8ee60fd35 branch=unknown tag=1.7.0
  • sha 与 1.7.0 源码标签 commit 一致，可核对安装物与官方发布物同源。
  • 源码编译若构建时未注入 GitHub Actions 版本变量，会显示 sha=unknown branch=unknown tag=none，注入方法见《安装部署指南》5.6。

4.2 benchmark：核心函数基准

量化当前机器的太阳位置计算、辐射插值等核心算力（与 Apple M1 基线对比，正值为更慢）。实测 -t 2（每项跑 2 秒）：

openmeteo-api benchmark -t 2

Open-Meteo Benchmark
Apple M1 is used as baseline. Positive values = slower than M1.
Time per test 2 seconds (See --help)
| Test                                                                             | Mean     | Min      | Max      | Runs     | Diff to Apple M1     |
|----------------------------------------------------------------------------------|----------|----------|----------|----------|----------------------|
| Solar Position Calculation for 50 years, hourly                                  | 0.83s    | 0.83s    | 0.83s    | 3        | +207ms (x1.33)       |
| Calculate extra terrestrial radiation (100 years, hourly)                        | 52ms     | 51ms     | 55ms     | 39       | +4.5ms (x1.1)        |
| Interpolate radiation to 15 minutes                                              | 291ms    | 284ms    | 297ms    | 7        | +45ms (x1.18)        |

用途：新机器上线前跑一轮，与既有节点横向对比，评估承载数据处理流水线的算力余量。注意 benchmark 占满 CPU，勿在生产高峰执行。

五、数据同步命令（sync）

sync 从 S3 协议对端拉取已成品化的 open-meteo 数据库（om 文件），是官方推荐的节点间数据获取方式（区别于 download-* 拉原始气象数据再自行转换）：

openmeteo-api sync --help

Usage: /usr/local/bin/openmeteo-api sync <models> <variables> [--apikey] [--server] [--rate] [--past-days] [--repeat-interval] [--concurrent,-c] [--concurrent-models,-c] [--year] [--execute] 

Download the open-meteo weather database from a S3 server.

Arguments:
             models Weather model domains separated by comma. E.g. 'cmc_gem_gdps,dwd_icon'
          variables Weather variables separated by comma. E.g. 'temperature_2m,relative_humidity_2m'

Options:
             apikey Sync API key for accessing Open-Meteo servers directly. Not required for AWS open-data.
             server Server base URL. Default 'https://openmeteo.s3.amazonaws.com/'
               rate Transfer rate in megabytes per second. Not applicable for AWS open-data.
          past-days Maximum age of synchronised files. Default 7 days.
    repeat-interval If set, check for new files every specified amount of minutes.
         concurrent Number of concurrent files per model download. Default 2
  concurrent-models Number of concurrent models to download. Default 2
               year Download one year or a range of years (e.g. 2000-2005)

Flags:
            execute Actually perfom file delete on cleanup

生产上不手工执行 sync，而是由 openmeteo-sync.service 按 env 文件的 SYNC_* 变量拼装命令常驻运行（拼装逻辑见《配置参数详解》3.2）。本机实测同步 dwd_icon temperature_2m --past-days 1 的真实日志（S3 直连实测 43-590 KB/s，单个全球 chunk 约 380 MB）：

journalctl -u openmeteo-sync --no-pager -n 6 --output=short-iso

2026-10-28T15:24:13+0000 openmeteo-apt22 sh[4361]: [ ERROR ] Could not read content from API_APIKEYS_PATH
2026-10-28T15:24:22+0000 openmeteo-apt22 sh[4361]: [ INFO ] Download https://openmeteo.s3.amazonaws.com/data/dwd_icon_global_native/temperature_2m/chunk_1968.om 105% 392.8 MB / 374.3 MB in 37m, 222.8 KB/s remaining -84794.12ms
2026-10-28T15:24:23+0000 openmeteo-apt22 sh[4361]: [ ERROR ] Could not read content from API_APIKEYS_PATH
2026-10-28T15:24:30+0000 openmeteo-apt22 sh[4361]: [ INFO ] Download https://openmeteo.s3.amazonaws.com/data/dwd_icon/temperature_2m/chunk_1968.om 52% 198.0 MB / 379.4 MB in 13m, 43.4 KB/s remaining 71m
2026-10-28T15:24:33+0000 openmeteo-apt22 sh[4361]: [ ERROR ] Could not read content from API_APIKEYS_PATH
2026-10-28T15:24:42+0000 openmeteo-apt22 sh[4361]: [ INFO ] Download https://openmeteo.s3.amazonaws.com/data/dwd_icon_global_native/temperature_2m/chunk_1968.om 106% 395.3 MB / 374.3 MB in 38m, 128.7 KB/s remaining -166881.91ms

⚠️ 注意（实测沉淀）：日志中周期性出现的 [ ERROR ] Could not read content from API_APIKEYS_PATH 是无害噪音——env 模板把 API_APIKEYS_PATH 置空，进程初始化 API key 管理器时读空路径报错后继续正常工作。实测数据下载不受影响；介意刷屏可在 env 中注释掉该行。remaining -84794.12ms 这类负数 remaining 是进度估算在下载尾段的正常抖动，出现「105%/106%」系分块文件在同步期间被上游更新，下一轮会自动对齐。

--repeat-interval 拉起常驻循环（每 N 分钟一轮）；--year 2000-2005 用于按年补历史数据（需对端提供对应年份归档）。

六、数据完整性维护

6.1 validate-om-files：校验 om 文件可读性

递归读取数据目录内所有 .om 文件的数据变量（默认只读每文件中心像素，快扫；-f 全量读）。实测对同步中的数据目录执行：

openmeteo-api validate-om-files -d /var/lib/openmeteo-api/data

[ INFO ] Scanning /var/lib/openmeteo-api/data for .om files...
[ INFO ] Reading file /var/lib/openmeteo-api/data/dwd_icon/static/HSURF.om [time: 2026-10-28T15:24]
[ WARNING ] 2D file in /var/lib/openmeteo-api/data/dwd_icon/static/HSURF.om
[ INFO ] Reading file /var/lib/openmeteo-api/data/dwd_icon_global_native/static/HSURF.om [time: 2026-10-28T15:24]
[ WARNING ] 2D file in /var/lib/openmeteo-api/data/dwd_icon_global_native/static/HSURF.om
[ INFO ] Reading file /var/lib/openmeteo-api/data/dwd_icon_global_native/static/coordinates.om [time: 2026-10-28T15:24]
[ WARNING ] Failed to read /var/lib/openmeteo-api/data/dwd_icon_global_native/static/coordinates.om: invalidDataType

退出码 0 表示扫描完成；两类 WARNING 均为正常现象：2D file 指静态场（地表高程）只有单层；coordinates.om: invalidDataType 指该文件是网格坐标元数据而非数据变量。时序 chunk 损坏（如断电写一半）会以读取失败形式暴露，是排查「某坐标请求 500」的第一手工具。

⚠️ 注意：不带 -d 时扫描 ./data/（相对当前目录）——手工执行时要么 cd /var/lib/openmeteo-api 再跑，要么显式 -d，否则静默扫到空目录退出 0（实测踩过）。

6.2 migration：数据库布局迁移

openmeteo-api migration --help

Usage: /usr/local/bin/openmeteo-api migration [--execute] 

Perform database migration

Flags:
  execute Perform file moves

不带 --execute 为干跑（打印将发生的文件移动，无变动时无输出）；--execute 才真正移动文件。用于 om 数据库目录布局跨版本升级，常规小版本升级不需要。干跑无输出即「无待迁移项」，生产先干跑确认清单再执行。

七、数据转换与导出

7.1 convert-om：om 文件 ↔ NetCDF

把单个 om 文件转成 NetCDF（或在 om 格式版本间转换）。实测把 dwd_icon 静态高程场转出：

openmeteo-api convert-om /var/lib/openmeteo-api/data/dwd_icon/static/HSURF.om --format netcdf -o /tmp/hsurf.nc

[ INFO ] Processing file: /var/lib/openmeteo-api/data/dwd_icon/static/HSURF.om
[ INFO ] File dimensions: [1441, 2879], chunks: [20, 20]
[ INFO ] Converting to NetCDF: /tmp/hsurf.nc
[ WARNING ] No domain provided, converting to LAT and LON dimensions, which might not be what you want for weather domains!
[ WARNING ] If you want to convert to a proper 3-dimensional NetCDF file, please provide a domain (for grid dimensions).

ls -la /tmp/hsurf.nc

-rw-r--r-- 1 root root 16600700 Oct 28 15:23 /tmp/hsurf.nc

产物可直接被 xarray/panoply 打开。两条 WARNING 提示：不带 --domain 时输出按经纬度维度组织，做正规三维气象场转换应传模式域名（如 --domain dwd_icon）以使用原生网格定义。

7.2 export：批量导出数据集为 NetCDF

openmeteo-api export --help

Usage: /usr/local/bin/openmeteo-api export <domains> <variable> [--regridding] [--start_date] [--end_date] [--calculate_daily_normals_over_n_years] [--normals_years] [--normals_width] [--format] [--rain-day-distribution] [--latitude-bounds] [--longitude-bounds] [--output,-o] [--compression,-c] [--ignore_sea_search_radius] [--concurrent] [--concurrent-chunk-length] [--only-full-bounding-box] [--output_coordinates] [--output_elevation] [--ignore_sea] [--debug] 

Export to dataset to NetCDF

Arguments:
                               domains Model domain
                              variable Weather variable

Options:
                            regridding Regrid data to a specified grid, perform bias and elevation correction
                            start_date n/a
                              end_date n/a
                 ...
                       latitude-bounds n/a
                      longitude-bounds n/a
                            output Output file name. Default: ./output.nc
                        compression Enable NetCDF compression and set the compression level from 0-9
                 ...(全文见 --help)

⚠️ 排障实录：export 依赖本地已同步完整的时序 chunk。实测在同步只完成 1 个 chunk（global_native/temperature_2m）时对 dwd_icon_global_native temperature_2m --latitude-bounds 47:48 --longitude-bounds 7:9 --start_date 2026-10-28 --end_date 2026-10-28 执行导出，进程直接崩溃退出（timeout: the monitored command dumped core，无产物文件）。定位：请求范围与已同步 chunk 不匹配/时次不全时，Swift try! 直接 fatal（与《配置参数详解》FAQ Q2 同机理）。结论：先 sync 完成、validate-om-files 通过，再跑 export；用 --start_date/--end_date 限定已有数据时段。

7.3 merge-yearly：分块合并为年度文件

openmeteo-api merge-yearly --help

Usage: /usr/local/bin/openmeteo-api merge-yearly <domain> <years> [--variables] [--force] [--delete] [--allow-missing] 

Merge database chunks into yearly files

Arguments:
         domain Domain e.g. 
          years A singe year or a range of years. E.g. 2017-2020

Options:
      variables Only process a list of coma separated variables

Flags:
          force Generate yearly file, even if it already exists
         delete Delete the underlaying chunks
  allow-missing Allow partial years (missing chunks)

用途：把按 chunk 组织的时序库压缩成年度大文件，常用于历史归档/对外分发（ERA5 等再分析数据按年组织）。--delete 会删除被合并的 chunk（腾空间），务必先确认年度文件校验通过。本机实测数据仅同步了当天时序，不足一年，未执行合并（避免产出半截年度文件）；最小可运行口径下用不到此命令。

八、数据下载命令家族（download-*）与数据分发

8.1 download-*：从各国气象机构拉原始数据

33 个 download-<机构/数据源> 命令负责从 DWD（icon）、ECMWF、NOAA（gfs）、Météo-France、JMA、CMA 等上游拉取原始 GRIB 数据并转换为 om 数据库——这是「数据生产节点」的角色，单机自托管 API 用 sync 拉成品即可，无需碰这组命令。以 download-ecmwf 为例（帮助文本节选）：

openmeteo-api download-ecmwf --help

Usage: /usr/local/bin/openmeteo-api download-ecmwf [--run] [--domain] [--server] [--source] [--concurrent,-c] [--max-forecast-hour] [--timeinterval,-t] [--only-variables] [--upload-s3-bucket] [--create-netcdf] [--upload-s3-only-probabilities] [--download-full-grib-file] [--skip-timeseries] 

Download a specified ecmwf model run

Options:
                           run n/a
                        domain n/a
                        server Root server path. Default: 'https://data.ecmwf.int/forecasts/'
                        source Open data source: ecmwf (default), aws, azure, google. Mutually exclusive with --server
                    concurrent Numer of concurrent download/conversion jobs
             max-forecast-hour Only download data until this forecast hour
              upload-s3-bucket Upload open-meteo database to an S3 bucket after processing
                 ...(全文见 --help)
  • --run 2026102812 指定起报时次；--max-forecast-hour 120 限制预报时效；--timeinterval 20220101-20220131 批量补历史。
  • --upload-s3-bucket 处理完成后直传 S3，配合 s3-sync 形成生产流水线。
  • 上游机构凭证（KNMI/Météo-France 需 API key）通过环境变量注入，见《配置参数详解》5.6。

8.2 s3-sync：本地目录推送 S3 兼容服务端

openmeteo-api s3-sync --help

Usage: /usr/local/bin/openmeteo-api s3-sync <local-dir> <remote-server> <base-path> [--dry-run] 

Synchronize a local directory to an S3-compatible server.

Arguments:
      local-dir Local directory to upload recursively.
  remote-server S3-compatible server or bucket URL.
      base-path Remote object prefix for the local directory.

Flags:
        dry-run Scan and report files without uploading them.

多节点架构中「生产节点把本地数据库发布给 API 节点」的推送侧命令（API 节点拉取侧是 sync + API_SYNC_APIKEYS 门控，服务端配置见《配置参数详解》5.5）。先 --dry-run 看上传清单再实推。

九、常见问题（FAQ）

Q1：手工跑 validate-om-files / export，提示目录不存在或扫不到文件？

Open-Meteo 的数据目录默认是 ./data/（相对进程工作目录）。systemd 单元靠 WorkingDirectory=/var/lib/openmeteo-api/ 定位；手工执行没有这个上下文，必须显式指定：validate 用 -d <数据目录>，export/convert 等通过环境变量 DATA_DIRECTORY=<目录>/（注意尾斜杠）注入。实测不带 -d 的 validate 对空目录静默退出 0，容易造成「已校验」假象。

Q2：sync 日志反复报 [ ERROR ] Could not read content from API_APIKEYS_PATH？

无害噪音。env 模板中 API_APIKEYS_PATH 为空值，进程初始化 API key 管理器时读空路径报错后继续；实测数据同步正常推进（回显见五）。可在 env 中注释该变量消除刷屏。

Q3：export 执行到一半 core dump，没有任何产物？

export 要求请求范围内时序数据完整。数据仍在 sync 中或请求了未同步的时段/区域时，Swift 内部 try! 直接崩溃（实测回显见 7.2）。先 sync 完整 + validate-om-files 校验，再用 --start_date/--end_date 收窄到已有数据时段重试。

Q4：怎么确认升级后端点/命令没有变化？

openmeteo-api routes 核对端点集合（升级前后各跑一次比对），openmeteo-api --help 核对子命令清单，openmeteo-api version 确认 sha/tag 与 Release 对应。三件套均只读、无副作用。

十、参考链接

  1. sync 命令官方文档（sync-command.md）：https://github.com/open-meteo/open-meteo/blob/main/docs/sync-command.md
  2. 数据下载文档（downloading-datasets.md）：https://github.com/open-meteo/open-meteo/blob/main/docs/downloading-datasets.md
  3. 1.7.0 源码标签（Commands 目录）：https://github.com/open-meteo/open-meteo/tree/1.7.0/Sources/App/Commands
  4. 官方开放数据（AWS Open-Data，sync 默认对端）：https://openmeteo.s3.amazonaws.com
  5. om-file-format 仓库（om 文件格式）：https://github.com/open-meteo/om-file-format

本栏系列文档：