企业官网建设流程全解析

OneUptime Terraform Provider 自托管部署指南：URL 指向、版本约束、离线镜像与 TLS 配置

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

这篇技术指南完整讲解如何让 OneUptime 官方 Terraform Provider 对接你自己部署（self-hosted）的 OneUptime 实例：从oneuptime_url的正确书写、项目 API Key 的获取，到与平台版本严格对应的 provider 版本约束策略、离线（air-gapped）网络下的 provider 镜像，以及私有 CA 场景的 TLS 信任配置。读完本文，你将能够在自托管 OneUptime 上稳定运行terraform init / plan / apply，并快速定位ProjectId required、x509: certificate signed by unknown authority、no matching version found等高频报错。

自托管与云端的唯一差异：URL 与版本规则

OneUptime 的 Terraform Provider 本身对云端与自托管完全一致——相同的资源类型（oneuptime_project、oneuptime_monitor等）、相同的属性、相同的认证方式。自托管场景下真正不同的只有两点：

1. 把 provider 指向你实例的地址（oneuptime_url/ONEUPTIME_URL）；
2. provider 版本必须受你的平台版本约束。

这一设计在仓库中也有印证：provider 是由 OneUptime 的 OpenAPI 规范自动生成的（生成器位于 Scripts/TerraformProvider/Core/ProviderGenerator.ts，生成流程见 Scripts/TerraformProvider/README.md），生成出的 Go 客户端只关心"URL + API Key"两个配置，并不会区分目标实例是云服务还是自托管。

将 Provider 指向你的实例

1. 在 provider 块中设置oneuptime_url

oneuptime_url必须是实例的origin——只包含 scheme 和主机名，不要带/api后缀，也不要带任何路径：

terraform { required_providers { oneuptime = { source = "oneuptime/oneuptime" version = "~> 11.0" } } } provider "oneuptime" { oneuptime_url = "https://oneuptime.example.com" # api_key 从 ONEUPTIME_API_KEY 环境变量读取，也可显式指定： # api_key = var.oneuptime_api_key }

为什么不能写/api？因为 provider 的 HTTP 客户端会自动拼接：从源码看，生成器产出的NewClient会先确保 URL 带 scheme，再把末尾的/去掉、追加/api，最后做一次url.Parse校验，非法地址会直接返回invalid oneuptime_url错误（见 ProviderGenerator.ts）。所以https://oneuptime.example.com会被规范化为实际请求基址https://oneuptime.example.com/api，而如果你多写了一个/api，就会变成https://oneuptime.example.com/api/api。

2. 用环境变量保持配置可移植

URL 与 API Key 都支持环境变量，这让同一份.tf配置可以在云端与自托管之间切换而不改代码：

export ONEUPTIME_URL="https://oneuptime.example.com" export ONEUPTIME_API_KEY="your-project-api-key"

这两个环境变量名与生成器代码一一对应：provider schema 中oneuptime_url、api_key两个属性在未显式设置时会回退到ONEUPTIME_URL与ONEUPTIME_API_KEY（见 ProviderGenerator.ts）。需要特别注意的是，API Key 是必填的：若属性与环境变量都缺失，provider 会在terraform plan启动阶段直接报错 "API key is required for authentication"。

3. 必须使用项目 API Key（project API key）

API Key 必须是在你的实例 Dashboard 的Project Settings（项目设置）> API Keys中创建的项目级 API Key，云端与自托管完全一样。自托管的主密钥（master key）不能使用——因为 provider 是从 Key 本身推导项目归属的，主密钥不绑定任何项目，调用任何资源都会失败并报ProjectId required（详见 Troubleshooting）。最佳实践是：为 Terraform 单独创建一个项目 API Key，并只授予你需要管理的资源类型的 Create/Read/Update/Delete 权限；导入（import）至少需要 Read 权限。

选择 Provider 版本：跟随平台版本

Provider 版本与 OneUptime 平台版本一一对应，自托管场景的核心规则是：

使用小于或等于你的 OneUptime 平台版本的、已发布的最新 provider 版本。

具体有三条纪律：

• 绝不要使用比平台更新的 provider——新版 provider 可能会驱动你的安装尚未具备的 API 字段，导致请求失败或状态漂移；
• 不要锁定精确补丁版本——并非每个平台补丁都会发布到 Registry，= 11.0.7这类精确锁定经常报no matching version found；
• 用有界约束表达规则。例如平台运行在11.2.x：

version = ">= 11.0, <= 11.2"

Terraform 会自动挑选已发布的不超过 11.2 的最新 11.x 版本，跳过任何未发布的补丁。如果你跟踪平台大版本比较松散且保持较新，~> 11.0也可以。

平台版本号可以从 OneUptime 管理后台查看，或从你的 Helm Chart / Docker Compose 部署值（仓库中的 docker-compose.yml 与 HelmChart）中找到。已发布的 provider 版本以 Terraform Registry 上的oneuptime/oneuptime版本列表为准。

升级顺序（重要）：先升级 OneUptime 平台，再调高 provider 的版本约束并执行terraform init -upgrade。顺序反了，旧平台会被新版 provider 用不存在的 API 字段驱动而报错。

离线（Air-Gapped）网络：镜像 Provider

如果运行 Terraform 的机器无法访问registry.terraform.io，可以先把 provider 镜像进内网：

mkdir -p /srv/terraform-mirror cd /path/to/your/terraform/config # 该目录的 required_providers 中需包含 oneuptime terraform providers mirror /srv/terraform-mirror

terraform providers mirror会按照你配置中的版本约束，把所有平台的 provider 发行版下载到 Terraform 认识的目录布局中。之后把该目录拷进内网（用纯 HTTPS 文件服务器托管，或作为文件系统路径共享），并在 CLI 配置（~/.terraformrc）中指向它：

provider_installation { filesystem_mirror { path = "/srv/terraform-mirror" include = ["registry.terraform.io/oneuptime/oneuptime"] } direct { exclude = ["registry.terraform.io/oneuptime/oneuptime"] } }

此时terraform init会从镜像安装 OneUptime provider，其余 provider 仍走正常渠道（删除direct块则强制全部走镜像）。每当你提高版本约束，都要重新执行一次terraform providers mirror，把新版本补进镜像目录。

TLS 注意事项

• Terraform 是 Go 程序：它会用运行 Terraform 的机器的系统信任库来校验你的实例证书。如果实例用的是私有 CA 签发的证书，必须在所有运行 Terraform 的机器（包括 CI Runner）上安装该 CA 证书。Debian/Ubuntu 上：把 CA 复制到/usr/local/share/ca-certificates/，然后运行update-ca-certificates。
• 没有"跳过 TLS 校验"的属性：这是刻意设计。如果报x509: certificate signed by unknown authority，正确的做法是修复信任链，而不是想方设法关掉校验。
• 明文 HTTP 仅限实验室：oneuptime_url = "http://oneuptime.lab.internal"这样的写法在一次性测试环境可行，但项目 API Key 会随每次请求发出，任何非临时环境都应当用 TLS。
• 反向代理 / Ingress 场景：如果 OneUptime 在反向代理或 Ingress 后面，oneuptime_url填的是代理对外暴露的 origin。务必确认代理把/api下所有路径原样转发，不要改写路径前缀。

自托管高频错误快速对照

针对自托管 URL 与 TLS 的更完整排查细节，可参考 Troubleshooting；其余场景均可直接套用云端用法，例如 Quick Start 的首次terraform apply在自托管下同样成立。

相关页面

• Registry Usage（Registry 使用与版本发布机制）
• Troubleshooting（URL、TLS、Key 错误的详细排查）
• Quick Start（首次 apply，自托管下用法相同）

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime