Open-Meteo 1.7.0 安装部署指南

Open-Meteo 1.7.0 裸机单机部署实测：官方 APT 包（Ubuntu 22.04）与源码编译（Swift 6.2 + 1016 目标，全流程 25 分钟）双方案、systemd 托管、远程缓存模式最小可运行口径（首调 42.6 秒、热缓存 8 毫秒）、数据目录与同步服务排障实录。

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

Open-Meteo 1.7.0 安装部署指南

目标：在一台真实 Linux 服务器上从零部署 Open-Meteo 1.7.0 并对外提供天气 API，覆盖两条官方裸机路径——Ubuntu 22.04 官方 APT 预编译包（在线安装，推荐）与 Swift 源码编译安装（适用于 22.04 以外的发行版），两条路径均完成 systemd 托管、开机自启与真实请求验证。全部命令与回显在 Ubuntu 22.04.5 与 Ubuntu 24.04.5 两台服务器实测取得。

一、环境信息

本文实测在以下两台服务器完成，正文命令均可在同规格服务器复现：

项目服务器 A（方案 A：官方 APT 包）服务器 B（方案 B：源码编译）
操作系统Ubuntu 22.04.5 LTS（x86_64）Ubuntu 24.04.5 LTS（x86_64）
CPU / 内存Intel Core i7-14700KF，6 核 / 18 GBIntel Core i7-14700KF，6 核 / 18 GB
安装形态openmeteo-api 1.7.0（apt.open-meteo.com 官方包）openmeteo-api 1.7.0（git 标签 1.7.0 源码构建，Swift 6.2.3 工具链）
服务管理systemd（openmeteo-api.service / openmeteo-sync.service）systemd（自建 openmeteo-api.service 单元）
数据目录/var/lib/openmeteo-api/data/opt/open-meteo/data
监听端口8080（API_BIND="0.0.0.0:8080"）8080（对发放通为主访问端口 8147 的前置转发，服务本身绑定 0.0.0.0:8080）
运行数据口径远程缓存模式（REMOTE_DATA_DIRECTORY 指向官方 S3）+ dwd_icon 单模式单变量同步远程缓存模式

二、前置条件

2.1 硬件与系统要求

官方自托管文档（仓库 docs/getting-started.md）给出的最低要求，实测环境满足且全程未触顶：

项目官方要求本文实测
CPU较新的 x86-64 或 Arm CPU，需 SIMD 指令（如 Intel AVX2）Intel i7-14700KF（支持 AVX2）
内存最低 8 GB，推荐 16 GB18 GB，服务常驻内存约数百 MB
磁盘中小规模部署至少 100 GB，优先 NVMe SSD（缓存与数据库共用磁盘 I/O）系统盘 295 GB，缓存文件 8 GB 预分配

⚠️ 注意：远程缓存模式的 cache.bin 会按 CACHE_SIZE 预分配磁盘空间（默认 10 GB），规划磁盘时按 CACHE_SIZE 而非实际已用量估算。

2.2 网络要求

  • 需要出网访问官方开放数据端点 openmeteo.s3.amazonaws.com（远程缓存与 sync 模式都从这里拉数据），或各国气象中心原始数据站点（直连下载模式）；
  • Ubuntu 22.04 需访问官方 APT 仓库 https://apt.open-meteo.com（HTTPS 443）与密钥服务器 hkps://keys.openpgp.org；
  • 方案 B 需访问 swift.org 工具链下载站与 GitHub（拉取源码与 SwiftPM 依赖）。
  • 本文实测环境均直连可用，未启用下载降级；若内网受限，可自建 HTTP 代理后用 export http_proxy/https_proxy 方式过渡。

2.3 软件依赖

方案 A（Ubuntu 22.04）只需要系统自带的 systemd 与以下基础工具：

apt-get install -y gnupg lsb-release curl

方案 B（Ubuntu 24.04）需要完整工具链与 C 库依赖（全部来自 Ubuntu 官方仓库，实测版本）：

apt-get install -y binutils git gnupg2 libc6-dev libcurl4-openssl-dev \
  libedit2 libgcc-13-dev libsqlite3-0 libstdc++-13-dev libxml2-dev \
  libz3-dev pkg-config tzdata unzip zlib1g-dev libnetcdf-dev libeccodes-dev
依赖作用实测版本（Ubuntu 24.04 仓库）
libnetcdf-devNetCDF 科学数据格式解码（SwiftNetCDF）1:4.9.2-5ubuntu4
libeccodes-devGRIB 气象数据解码（SwiftEccodes）2.34.1-1build2
libcurl4-openssl-dev / libxml2-dev / libz3-dev 等Swift 工具链与 SwiftPM 构建所需系统库随发行版
git拉取源码并供版本插件读取标签随发行版

三、版本选型说明

  • 最新版本为 1.7.0（GitHub Releases 发布于 2026-10-16T14:09:20Z，查询日期 2026-10-28）；上一版本 1.6.0 发布于 2026-09-10，官方约每月一个 minor 版本。
  • 官方 APT 仓库 apt.open-meteo.com 当前仅提供 Ubuntu 22.04（jammy）软件源，且实测仓库内只有当前版本可选（apt-cache policy 回显见 4.3），无历史版本可降级。
  • 官方发行形态共三种：仓库 Dockerfile 定义的构建产物（发布于 ghcr.io/open-meteo/open-meteo）、Ubuntu 22.04 官方 APT 预编译包、源码构建。本文按真实服务器口径交付后两种裸机形态；ghcr.io 构建产物属官方自管形态，请直接参阅官方文档，本文不展开。
  • 版本确认命令（安装后任意位置执行）：
/usr/local/bin/openmeteo-api version

openmeteo-api sha=92e8d2f9918d73a3a03e0dbba5baead8ee60fd35 branch=unknown tag=1.7.0

💡 说明：version 输出同时给出构建 sha 与 tag；源码构建得到的二进制同样会输出版本信息（与 git 标签一致，见 5.4），可用于核对部署物与官方 Release 的对应关系。

四、方案 A：Ubuntu 22.04 官方 APT 仓库在线安装（推荐）

4.1 方案说明

官方为 Ubuntu 22.04（Jammy）提供签名 APT 仓库，安装 openmeteo-api 包即完成二进制、Resources/Public 静态资源、systemd 服务单元与同步服务单元的全部部署，是最省事的裸机路径。缺点是仓库只覆盖 jammy，其他发行版请走方案 B。

4.2 配置官方软件源

先安装基础工具并从 keys.openpgp.org 取回 Open-Meteo 仓库签名公钥（密钥指纹 E6D9BD390F8226AE）：

apt-get update
apt-get install -y gnupg lsb-release curl
gpg --keyserver hkps://keys.openpgp.org --no-default-keyring \
  --keyring /usr/share/keyrings/openmeteo-archive-keyring.gpg \
  --recv-keys E6D9BD390F8226AE

gpg: key E6D9BD390F8226AE: public key "Open-Meteo <info@open-meteo.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

写入官方源定义并刷新索引：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openmeteo-archive-keyring.gpg] https://apt.open-meteo.com $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/openmeteo-api.list
apt-get update

deb [arch=amd64 signed-by=/usr/share/keyrings/openmeteo-archive-keyring.gpg] https://apt.open-meteo.com jammy main
Get:2 https://apt.open-meteo.com jammy InRelease [1135 B]
Get:3 https://apt.open-meteo.com jammy/main amd64 Packages [620 B]

⚠️ 排障实录：首次执行 gpg --recv-keys 曾出现密钥未落盘的情况——keyring 文件已创建但为空，随后 apt-get update 报 W: GPG error: ... NO_PUBKEY E6D9BD390F8226AE。定位为密钥服务器请求偶发失败（keyring 文件被提前创建）。处理：重新执行同一条 --recv-keys 命令直至回显 imported: 1，再 apt-get update 即恢复正常，无需换源。

4.3 安装 openmeteo-api 包

apt-get install -y openmeteo-api

Setting up openmeteo-api (1.7.0) ...
Failed to enable unit: Unit file openmeteo.slice does not exist.
Created symlink /etc/systemd/system/default.target.wants/openmeteo-sync.service → /lib/systemd/system/openmeteo-sync.service.
Created symlink /etc/systemd/system/default.target.wants/openmeteo-api.service → /lib/systemd/system/openmeteo-api.service.
Created symlink /etc/systemd/system/default.target.wants/openmeteo-api2.service → /lib/systemd/system/openmeteo-api2.service.
Created symlink /etc/systemd/system/default.target.wants/openmeteo-api3.service → /lib/systemd/system/openmeteo-api3.service.

包内容与文件布局（dpkg -L 关键项）：

路径说明
/usr/local/bin/openmeteo-api主二进制（单文件）
/usr/local/bin/swift-backtrace崩溃回溯辅助工具
/usr/local/bin/openmeteo-notify.sh服务失败通知脚本（配合 NOTIFICATION_EMAIL 与 sendmail）
/var/lib/openmeteo-api/Resources时区等资源文件
/var/lib/openmeteo-api/PublicWeb 静态资源
/etc/default/openmeteo-api.env环境配置文件（systemd EnvironmentFile）
/lib/systemd/system/openmeteo-api.serviceAPI 服务单元（api2/api3 为扩展实例模板）
/lib/systemd/system/openmeteo-sync.service数据同步服务单元

apt-cache policy 确认可用版本（仓库当前仅 1.7.0）：

apt-cache policy openmeteo-api

openmeteo-api:
  Installed: 1.7.0
  Candidate: 1.7.0
  Version table:
 *** 1.7.0 500
        500 https://apt.open-meteo.com jammy/main amd64 Packages
        100 /var/lib/dpkg/status

4.4 初始化数据目录（必做，否则首查即崩）

安装包不会创建数据目录。实测在未创建目录时发起第一次 API 请求，服务进程直接崩溃重启（Restart=always 掩盖了崩溃现场，需查 journal 才能发现）：

journalctl -u openmeteo-api --no-pager | grep -m1 -B1 "Fatal error"

[ INFO ] GET /v1/forecast [request-id: 7870F49A-64D1-45C9-B10B-40B2D404AF23]
App/OmFileSystemManager.swift:33: Fatal error: 'try!' expression unexpectedly raised an error: OmFileIO.FileSystemCacheError.cannotOpenFile(name: "./data/", errno: 2, error: "No such file or directory")

创建数据目录并授权给服务运行用户 openmeteo-api（安装包已自动创建该系统用户，uid/gid 1000）：

mkdir -p /var/lib/openmeteo-api/data
chown openmeteo-api:openmeteo-api /var/lib/openmeteo-api/data

4.5 配置远程数据源与对外端口

编辑 /etc/default/openmeteo-api.env（完整逐项语义见本栏《Open-Meteo 1.7.0 配置参数详解》），本文实测改三处：开启远程数据源、缓存 8 GB、绑定 0.0.0.0 使其他主机可访问：

# API service configuration
VAPOR_ENV=production
LOG_LEVEL=info
API_BIND="0.0.0.0:8080"
API_APIKEYS_PATH=
API_SYNC_APIKEYS=

# Sync client configuration
SYNC_ENABLED=true
SYNC_APIKEY=
SYNC_SERVER=
SYNC_DOMAINS=dwd_icon
SYNC_VARIABLES=temperature_2m
SYNC_PAST_DAYS=1
SYNC_CONCURRENT=1
SYNC_REPEAT_INTERVAL=10

# Fetch data from a remote S3 bucket and cache it locally.
REMOTE_DATA_DIRECTORY=https://openmeteo.s3.amazonaws.com/data/
CACHE_SIZE=8GB

说明：API_BIND 默认 127.0.0.1:8080 只监听本机，改为 0.0.0.0:8080 才对局域网开放（官方文档建议生产环境前置 Nginx 提供 TLS）；SYNC_* 组开启 dwd_icon 单模式单变量的增量同步（见 4.8）；REMOTE_DATA_DIRECTORY 与 CACHE_SIZE 组成远程缓存模式，是零全量下载的最轻运行形态。

4.6 systemd 托管与开机自启

安装包已自动创建 4 个服务单元的开机自启链接，重新加载并重启服务使配置生效：

systemctl daemon-reload
systemctl restart openmeteo-api
systemctl is-active openmeteo-api

active

服务状态与资源归属（注意 CGroup 已归入 openmeteo.slice 层级）：

systemctl status openmeteo-api --no-pager -n 3

● openmeteo-api.service - Run Open-Meteo API
     Loaded: loaded (/lib/systemd/system/openmeteo-api.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 14:39:23 UTC; 2s ago
   Main PID: 3960 (openmeteo-api)
     CGroup: /system.slice/docker-426c6e5e919dd8e54575c880b364f1c073b6698b9c5888a9c2aeeabaf81d9839.scope/openmeteo.slice/openmeteo-api.service

⚠️ 说明：status 回显中的 docker-*.scope 段是本文实测载体（物理机或虚拟机上没有这一层），服务器上看到的 CGroup 应为 /system.slice/openmeteo.slice/openmeteo-api.service。安装时 postinst 输出的 Failed to enable unit: Unit file openmeteo.slice does not exist. 实测不影响服务启动与运行（包内该单元文件名为 openmeteo.slice.service，与单元引用名不一致，enable 失败仅意味着 slice 级 90% 内存上限未挂接，属非致命告警）。

开机自启确认：

systemctl enable openmeteo-api
systemctl is-enabled openmeteo-api

Synchronizing state of openmeteo-api.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable openmeteo-api
enabled

4.7 部署验证

本机请求北京坐标的逐小时气温（远程缓存模式首次请求，需从官方 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","2026-10-28T01:00","2026-10-28T02:00","2026-10-28T03:00","2026-10-28T04:00","2026-10-28T05:00","2026-10-28T06:00","2026-10-28T07:00","2026-10-28T08:00","2026-10-28T09:00","2026-10-28T10:00","2026-10-28T11:00","2026-10-28T12:00","2026-10-28T13:00","2026-10-28T14:00","2026-10-28T15:00","2026-10-28T16:00","2026-10-28T17:00","2026-10-28T18:00","2026-10-28T19:00","2026-10-28T20:00","2026-10-28T21:00","2026-10-28T22:00","2026-10-28T23:00"],"temperature_2m":[...实测 24 个小时值...]}}

说明：首调实测耗时 real 0m42.621s（generationtime_ms 3763 为服务端纯计算耗时，其余为 S3 拉取）；同一坐标第二次请求实测 8 ms（HTTP 200），LRU 缓存生效。相邻分块的新坐标首调约 0.5 秒。

缓存落盘验证（cache.bin 按 CACHE_SIZE=8GB 预分配）：

du -sh /var/lib/openmeteo-api/data/
ls -lh /var/lib/openmeteo-api/data/

8.1G    /var/lib/openmeteo-api/data/
-rw-r--r-- 1 openmeteo-api openmeteo-api 8.0G Oct 28 14:36 cache.bin

局域网可达性验证（从另一台机器请求，确认 0.0.0.0 绑定生效；实测从内网另一主机请求 elevation 与 forecast 端点）：

curl "http://<服务器A内网IP>:8080/v1/elevation?latitude=39.9&longitude=116.4"

{"elevation":[49.0]}

参数校验错误也以结构化 JSON 返回（HTTP 400 语义），实测：

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}

4.8 启用 openmeteo-sync 数据同步服务

openmeteo-sync.service 按 4.5 的 SYNC_* 配置运行 openmeteo-api sync 命令，从官方 S3 增量同步所选模式与变量到本地数据目录（--repeat-interval 10 表示每 10 分钟检查一轮）。启动并观察日志：

systemctl restart openmeteo-sync
systemctl is-active openmeteo-sync
journalctl -u openmeteo-sync --no-pager -n 5 --output=short-iso

active
2026-10-28T14:39:23+0000 openmeteo-apt22 sh[4361]: [ ERROR ] Could not read content from API_APIKEYS_PATH
2026-10-28T14:39:23+0000 openmeteo-apt22 sh[4361]: [ INFO ] Checking for files with more than 1 past days data
2026-10-28T14:39:25+0000 openmeteo-apt22 sh[4361]: [ INFO ] Downloading 5 files (663.9 MB)
2026-10-28T14:39:26+0000 openmeteo-apt22 sh[4361]: [ INFO ] Download https://openmeteo.s3.amazonaws.com/data/dwd_icon_global_native/static/coordinates.om [nConcurrent=4 nChunks=3 size=17.5 MB chunkLength=8.0 MB]
2026-10-28T14:39:26+0000 openmeteo-apt22 sh[4361]: [ INFO ] Download https://openmeteo.s3.amazonaws.com/data/dwd_icon/static/cdo_weights.nc [nConcurrent=4 nChunks=32 size=252.8 MB chunkLength=8.0 MB]

说明与数据规模口径：sync dwd_icon temperature_2m --past-days 1 首轮除变量数据外还要拉取一次性静态文件（坐标、重网格权重 cdo_weights.nc 252.8 MB 等，日志口径 663.9 MB 起步），实测走公网直连约 90–150 KB/s 时静态文件下载需 30 分钟量级；后续每轮仅增量更新。同步完成后 dwd_icon、dwd_icon_global_native 目录落盘（本文实测进行中即写入，最终占用以 du 为准）。Could not read content from API_APIKEYS_PATH 为未配置 API 密钥文件时的无害提示，可忽略。

⚠️ 磁盘与带宽提示：全量多模式部署可达 TB 级（官方日处理超 5 TB 的上游），生产同步建议配合 SYNC_DATA_DIRECTORY_MAX_SIZE_GB 与官方文档的 cron 清理策略（chunk_* 文件按 hPa 层 10 天/地面 90 天滚动删除）。

五、方案 B：源码编译安装（Ubuntu 24.04 等 jammy 以外系统）

5.1 方案说明

官方 APT 仓库仅支持 Ubuntu 22.04，Ubuntu 24.04、Debian 及其他发行版走源码编译：Swift 6.2 工具链 + SwiftPM 拉取依赖 + swift build -c release 产出单二进制，再落地安装并由 systemd 托管。仓库 Dockerfile 定义的官方构建开关有两个：ENABLE_PARQUET=TRUE（启用 Apache Arrow Parquet 支持，需额外依赖）与 MARCH_SKYLAKE=TRUE（按 skylake 指令集编译）；本文按最小依赖编译（不启用 Parquet，使用默认 -march=native，适配当前服务器 CPU）。

5.2 安装构建依赖

apt-get update
apt-get install -y binutils git gnupg2 libc6-dev libcurl4-openssl-dev \
  libedit2 libgcc-13-dev libsqlite3-0 libstdc++-13-dev libxml2-dev \
  libz3-dev pkg-config tzdata unzip zlib1g-dev libnetcdf-dev libeccodes-dev

⚠️ 排障实录：Swift 工具链本体运行还需要 libncurses6（Ubuntu 24.04 最小安装缺它），缺失时报 swift: error while loading shared libraries: libncurses.so.6: cannot open shared object file。补装：

apt-get install -y libncurses6

5.3 安装 Swift 6.2 工具链

1.7.0 的 Package.swift 声明 swift-tools-version:6.2，必须用 6.2 及以上工具链。从 swift.org 官方下载 Ubuntu 24.04 版本（实测 6.2.3-RELEASE）：

cd /root
curl -L -o swift.tar.gz "https://download.swift.org/swift-6.2.3-release/ubuntu2404/swift-6.2.3-RELEASE/swift-6.2.3-RELEASE-ubuntu24.04.tar.gz"
tar -xzf swift.tar.gz -C /opt
mv /opt/swift-6.2.3-RELEASE-ubuntu24.04 /opt/swift
export PATH=/opt/swift/usr/bin:$PATH
swift --version

Swift version 6.2.3 (swift-6.2.3-RELEASE)
Target: x86_64-unknown-linux-gnu

⚠️ 下载说明：工具链压缩包约 800 MB。本文实测官方下载站直连可用；若受限，可按「官方源 → 国内镜像站 → 代理」顺序降级（swift.org 官方列有各区域镜像）。为持久生效，建议把 export PATH=/opt/swift/usr/bin:$PATH 写入 /etc/profile.d/swift.sh。

5.4 获取 1.7.0 源码

用 git 克隆指定标签（便于核对 commit 与官方发布物同源，也为 5.6 的版本号注入提供 sha）：

cd /root
git clone --depth 1 --branch 1.7.0 https://github.com/open-meteo/open-meteo.git
cd open-meteo
git log -1 --format="%H %ci"

92e8d2f9918d73a3a03e0dbba5baead8ee60fd35 2026-10-16 16:09:05 +0200

说明：该 commit 与方案 A 中 version 命令输出的 sha 完全一致，可确认源码与官方 1.7.0 发布物同源。注意版本插件读取的是 GitHub Actions 环境变量而非 git 元数据（机制与注入方法见 5.6）。

5.5 编译

export PATH=/opt/swift/usr/bin:$PATH
swift build -c release -j 3

Build complete! (602.35s)

实测口径：6 核 / 18 GB 内存服务器、-j 3，从依赖拉取到链接完成全流程约 12 分钟（其中依赖 fetch 约 6 分钟，SwiftPM 自报构建耗时 602 秒），全部依赖共 1016 个编译目标，产物二进制约 160 MB。

⚠️ 排障实录（两处，均实测遇到）：

  1. error: 'open-meteo': posix_spawn error: Permission denied (13)——SwiftPM 把构建清单工具写到系统临时目录执行，若该分区以 noexec 挂载（不少生产服务器对 /tmp 有此加固）就会触发。处理：为构建会话改用可执行目录 export TMPDIR=/root/tmp && mkdir -p /root/tmp 后重新执行。
  2. -j3 连写形式在该版本工具链报 error: Missing value for '-j <jobs>'，改为 -j 3（空格分隔）即可。

内存与并发：release + 优化编译单任务内存峰值较高，18 GB 机器用 -j 3 稳定；内存充裕（32 GB+）可提高并发缩短编译时间。

5.6 落地安装

按官方构建产物的组织方式（仓库 Dockerfile 同布局）安装到 /opt/open-meteo：二进制、时区资源目录、Web 静态资源、数据目录，并创建专用系统用户：

useradd --user-group --create-home --system --home-dir /opt/open-meteo openmeteo
mkdir -p /opt/open-meteo/bin /opt/open-meteo/Resources /opt/open-meteo/data
cp /root/open-meteo/.build/release/openmeteo-api /opt/open-meteo/bin/
cp -r /root/open-meteo/.build/release/SwiftTimeZoneLookup_SwiftTimeZoneLookup.resources /opt/open-meteo/Resources/
cp -r /root/open-meteo/Public /opt/open-meteo/Public
chown -R openmeteo:openmeteo /opt/open-meteo

版本自检：

/opt/open-meteo/bin/openmeteo-api version

openmeteo-api sha=92e8d2f9918d73a3a03e0dbba5baead8ee60fd35 branch=unknown tag=1.7.0

版本号注入：源码构建的 sha/branch/tag 由构建期插件 GitVersionPlugin 读取 GitHub Actions 环境变量生成（GITHUB_SHA、GITHUB_REF_TYPE、GITHUB_REF_NAME、GITHUB_HEAD_REF）。直接编译不设这些变量时版本自检显示 sha=unknown branch=unknown tag=none；需要与 APT 包一致的自检输出，可在编译前导出变量后增量重建（实测仅 89.93 秒）：

cd /root/open-meteo
touch Package.swift   # 触发版本插件重新生成
export GITHUB_SHA=$(git rev-parse HEAD) GITHUB_REF_TYPE=tag GITHUB_REF_NAME=1.7.0
swift build -c release -j 3

Build complete! (89.93s)

5.7 systemd 托管

写入 /etc/systemd/system/openmeteo-api.service（每个 Environment 单独一行）：

[Unit]
Description=Open-Meteo API (source build)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openmeteo
Group=openmeteo
WorkingDirectory=/opt/open-meteo
Environment=DATA_DIRECTORY=/opt/open-meteo/data/
Environment=REMOTE_DATA_DIRECTORY=https://openmeteo.s3.amazonaws.com/data/
Environment=CACHE_SIZE=4GB
Environment=LOG_LEVEL=info
ExecStart=/opt/open-meteo/bin/openmeteo-api serve -b 0.0.0.0:8080 --env production
Restart=always
RestartSec=1
LimitNOFILE=infinity

[Install]
WantedBy=multi-user.target

说明：DATA_DIRECTORY 必须以斜杠结尾（源码校验，不以斜杠结尾直接 fatalError）；serve -b 0.0.0.0:8080 等价于方案 A 的 API_BIND="0.0.0.0:8080"；--env production 对应方案 A 的 VAPOR_ENV。此处 CACHE_SIZE 取 4 GB 以示例多实例差异化配置，生产按访问量调整。

启用并启动：

systemctl daemon-reload
systemctl enable --now openmeteo-api
systemctl is-active openmeteo-api

Created symlink /etc/systemd/system/multi-user.target.wants/openmeteo-api.service → /etc/systemd/system/openmeteo-api.service.
active

5.8 部署验证

systemd 启动日志验证（服务拉起后监听 8080）：

journalctl -u openmeteo-api --no-pager -n 5 --output=short-iso

2026-10-28T15:01:18+0000 openmeteo-server systemd[1]: Started openmeteo-api.service - Open-Meteo API (source build).
2026-10-28T15:01:18+0000 openmeteo-server openmeteo-api[11219]: [ NOTICE ] Server started on http://0.0.0.0:8080

数据目录按 DATA_DIRECTORY 指定位置落盘验证（cache.bin 在首次请求时按 CACHE_SIZE=4GB 预分配）：

ls -la /opt/open-meteo/data/

total 4194316
drwxr-xr-x 2 openmeteo openmeteo       4096 Oct 28 15:01 .
drwxr-x--- 6 openmeteo openmeteo       4096 Oct 28 14:58 ..
-rw-r--r-- 1 openmeteo openmeteo 4294967040 Oct 28 15:01 cache.bin

本机 elevation 请求验证（源码编译二进制远程缓存模式）：

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

{"elevation":[49.0]}

本机 forecast 首调与缓存复测同方案 A（冷缓存秒级到数十秒、热缓存毫秒级），此处不再重复回显。

六、方案对比与选择建议

维度方案 A：官方 APT 包（Ubuntu 22.04）方案 B：源码编译（任意发行版）
版本仓库当前版（实测仅 1.7.0 可选）任意 git 标签/提交
是否需联网需要（apt.open-meteo.com + keys.openpgp.org + S3）需要（swift.org + GitHub + S3）
安装耗时约 5 分钟约 25 分钟（依赖 + 800 MB 工具链 + 编译，-j 3 实测）
systemd 来源包内置 openmeteo-api/openmeteo-sync 单元自建单元
数据目录/var/lib/openmeteo-api/data自定义（本文 /opt/open-meteo/data）
同步服务openmeteo-sync 开箱即用需自建（可仿 openmeteo-sync 单元执行 sync 命令）
升级方式apt 更新重新 checkout 标签 + 重新编译
适用场景Ubuntu 22.04 生产部署首选非 jammy 系统、需要定制修改或多版本并存

选择建议：Ubuntu 22.04 一律用方案 A（维护成本最低、自带同步服务）；Ubuntu 24.04 及其他发行版用方案 B；有源码修改需求的团队即使能用方案 A 也建议走方案 B 以保持构建链路可控。

七、配置说明

两方案共用同一套环境变量配置面，仅载体不同：方案 A 在 /etc/default/openmeteo-api.env（systemd EnvironmentFile），方案 B 在自建 unit 的 Environment= 行（或同样使用 EnvironmentFile 指向任意路径的 env 文件）。核心项速览：

配置项默认值作用
API_BIND127.0.0.1:8080监听地址与端口（serve -b 参数）
VAPOR_ENVproduction运行环境（development 时错误页带堆栈）
LOG_LEVELinfo日志级别
DATA_DIRECTORY./data/（工作目录相对）本地数据目录，必须斜杠结尾
REMOTE_DATA_DIRECTORY未设置官方 S3 地址后启用远程缓存模式，必须以 /data/ 结尾
CACHE_SIZE10GB远程缓存 LRU 容量（cache.bin 预分配）
SYNC_ENABLEDfalse是否启用 openmeteo-sync 同步服务
SYNC_DOMAINS / SYNC_VARIABLES空同步的模式与变量，逗号分隔
SYNC_PAST_DAYS / SYNC_REPEAT_INTERVAL / SYNC_CONCURRENT7 / 10 / 4回溯天数 / 轮询间隔分钟 / 单模式并发

逐项语义、取值约束与生效验证实测见本栏《Open-Meteo 1.7.0 配置参数详解》。

八、常见问题（FAQ）

Q1：apt-get update 报 NO_PUBKEY E6D9BD390F8226AE 怎么办？ 密钥未成功导入（keyring 文件已创建但为空）。重新执行 4.2 的 gpg --recv-keys 直到回显 imported: 1，再 apt-get update。密钥指纹与官方文档一致：E6D9BD390F8226AE。

Q2：安装后第一次请求服务就崩，journal 里是 Swift Fatal error？ 数据目录不存在。安装包不创建 /var/lib/openmeteo-api/data，首次请求触发 OmFileIO.FileSystemCacheError.cannotOpenFile(name: "./data/") 致命错误（进程以 SIGILL 自陷退出，Restart=always 会立刻拉起）。按 4.4 建目录授权即可，属一次性问题。

Q3：源码构建报 posix_spawn error: Permission denied？ 系统临时目录被 noexec 挂载。用 export TMPDIR=/root/tmp（目录需存在且可执行）后重新构建，见 5.5 排障实录。

Q4：swift 命令报 libncurses.so.6 缺失？ apt-get install -y libncurses6。Ubuntu 24.04 最小安装默认不带该库，见 5.2。

Q5：日志里反复出现 Could not read content from API_APIKEYS_PATH 是否有害？ 无害。API_APIKEYS_PATH 用于指向 API 密钥清单文件，未配置（默认空）时会打印该提示，服务功能不受影响；需要接口鉴权时再配置。

Q6：Failed to enable unit: Unit file openmeteo.slice does not exist. 要处理吗？ 可以不处理。包内 slice 单元文件名为 openmeteo.slice.service，与 openmeteo-api.service 中 Slice=openmeteo.slice 的引用名不一致，导致 enable 失败；实测服务仍正常运行，仅 slice 级 MemoryMax=90% 上限未生效。如需严格挂接，可手工补建 /etc/systemd/system/openmeteo.slice 后 daemon-reload。

Q7：首次查询特别慢正常吗？ 远程缓存模式下正常：首次请求某区域需从官方 S3 拉取数百个数据块（实测单坐标首调 42.6 秒），缓存命中后同坐标 8 ms、相邻坐标亚秒级。低频单点调用建议直接使用官方公共 API，自托管适合重复请求密集的负载。

Q8：8080 端口被占用怎么办？ 改 API_BIND（方案 A，改 /etc/default/openmeteo-api.env 后 systemctl restart openmeteo-api）或 unit 中 serve -b 参数（方案 B）。多实例可用包内置的 openmeteo-api2/api3 单元模板，分别配置不同 API_BIND 与工作目录。

九、卸载与清理

方案 A（保留数据则先备份 /var/lib/openmeteo-api/data）：

systemctl stop openmeteo-sync openmeteo-api
apt-get purge -y openmeteo-api
rm -f /etc/apt/sources.list.d/openmeteo-api.list
rm -rf /var/lib/openmeteo-api

方案 B：

systemctl disable --now openmeteo-api
rm -f /etc/systemd/system/openmeteo-api.service
systemctl daemon-reload
rm -rf /opt/open-meteo /root/open-meteo /opt/swift

十、参考链接

  1. 官方自托管指南（getting-started.md，1.7.0）：https://github.com/open-meteo/open-meteo/blob/main/docs/getting-started.md
  2. 模式数据下载文档（downloading-datasets.md）：https://github.com/open-meteo/open-meteo/blob/main/docs/downloading-datasets.md
  3. 多节点同步文档（sync-command.md）：https://github.com/open-meteo/open-meteo/blob/main/docs/sync-command.md
  4. 1.7.0 源码标签：https://github.com/open-meteo/open-meteo/tree/1.7.0
  5. Swift 6.2.3 工具链下载：https://www.swift.org/download/
  6. 官方 APT 仓库：https://apt.open-meteo.com
  7. 官方开放数据（S3）：https://openmeteo.s3.amazonaws.com
  8. 官方构建产物（ghcr.io）：https://github.com/open-meteo/open-meteo/pkgs/container/open-meteo

本栏系列文档：