企业官网建设流程全解析

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

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

本篇指南面向所有将 OneUptime 自托管部署在企业内部，并通过 Terraform 以基础设施即代码方式管理监控资源的工程团队。OneUptime 的 Terraform Provider 在云版本与自托管版本之间完全同构——资源、属性、行为完全一致，唯一需要调整的只有实例地址（oneuptime_url）与版本选择规则。读完本文，你将掌握如何把 Provider 指向自有实例、按平台版本精确选择 Provider 版本、在完全离线的内网中镜像 Provider，以及正确处理 TLS 信任链，从而让 Terraform 在你的私有 OneUptime 环境上顺畅地管理监控器、状态页、标签等全部资源。

本文对应的官方文档为 App/FeatureSet/Docs/Content/en/terraform/self-hosted.md，并配合仓库中的 Terraform Provider 生成器、发布脚本 与本地安装脚本进行源码级佐证。

核心前提：云与自托管共享同一个 Provider

OneUptime 的 Terraform Provider 只有一份，同时面向云端与自托管：

• 同一套资源与数据源：oneuptime_monitor、oneuptime_status_page、oneuptime_label、oneuptime_team、oneuptime_on_call_policy等命名空间完全一致（资源清单与用途可参考 App/FeatureSet/Docs/Content/en/terraform/index.md）。
• 同一套认证模型：均使用在Project Settings > API Keys下创建的项目级 API Key。
• 仅两点不同：一是 Provider 连接的目标 URL，二是版本选择的上界规则。

这意味着，你在云端环境里写好的.tf配置，迁到自托管环境时几乎不需要改动——只需在 provider 块中补充oneuptime_url，并按平台版本收紧版本约束即可。

从源码结构看，这一点也被生成器架构所印证：Provider 完全由 GenerateProvider.ts 从 OneUptime 的 OpenAPI 规范自动生成，并不存在单独的"自托管版"或"云版"产物；生成的 Go 代码里唯一与部署形态相关的输入就是运行时通过 provider 参数传入的 URL。

将 Provider 指向你的实例

配置oneuptime_url

在provider块中设置oneuptime_url，值为你实例的origin（源）——只包含 scheme 与主机名：

• 正确示例：https://oneuptime.example.com
• 不要带/api后缀
• 不要带任何路径（如/dashboard）
• 不要带端口以外的额外内容（除非实例运行在非标准端口）

Provider 会在内部自行拼接所有 API 路径（关于 URL 拼接的规则可参考 troubleshooting 中 "Self-hosted: URL and TLS issues" 一节）。

最小可运行配置如下：

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 }

环境变量方式

两个核心配置均支持环境变量，这能让同一套配置在云与自托管根环境之间保持可移植（无需修改.tf文件）：

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

其中ONEUPTIME_API_KEY是项目 API Key，创建位置与云端完全一致：Project Settings > API Keys。注意：

• 自托管的 master key 不可用。master key 不绑定任何项目，用它发起的每次资源调用都会报ProjectId required。
• 这是 OneUptime 两类凭据的本质区别：项目 API Key 绑定单一项目，Provider 直接从 Key 中推导项目；而 master key / 用户级 token 不携带项目信息，因此无法驱动 Provider。详见 troubleshooting 中的 "ProjectId required" 一节。

若你的环境允许，建议在.tf中使用var.oneuptime_api_key并从环境变量或变量文件注入，避免密钥进入版本库。

选择合适的 Provider 版本

版本跟踪规则

Provider 的版本号跟随 OneUptime 平台版本：Provider 11.x 由 OneUptime 11.x 生成并针对其测试。这一机制在源码中有直接体现——GenerateProvider.ts 在生成 Provider 时，直接读取仓库根目录的 VERSION 文件并将该版本号写入生成的 Provider（当前仓库的 VERSION 为13.0.7），随后由发布脚本按此版本打 tag 发布。因此每次平台发版，Provider 的生成与发布都自动同步。

对于自托管环境，选版本的口诀是：

使用"最新已发布且小于或等于你的 OneUptime 平台版本"的 Provider 版本。

两条硬性禁忌：

1. 绝不使用比平台更新的 Provider——它可能驱动你当前安装尚未具备的 API 字段，导致 plan/apply 异常。
2. 绝不锁定精确 patch 版本——并非每个平台 patch 都会发布到 Registry，= 11.0.7这种精确锁定经常因no matching version found失败。

用有界约束表达选择规则

把规则表达为有界版本约束。例如你的安装运行平台版本11.2.x：

version = ">= 11.0, <= 11.2"

Terraform 会在此区间内自动选择最新已发布的 11.x 版本，自动跳过任何未发布的 patch。如果你对平台大版本跟进较宽松、且保持较新，~> 11.0也同样适用（悲观约束总是能解析到一个真实存在的已发布版本，这正是 registry 文档 所强调的）。

查找平台版本

• 在 OneUptimeadmin dashboard中查看。
• 或从你的Helm / Docker Compose部署配置值中读取——仓库根目录的 docker-compose.yml 与 HelmChart 中的镜像 tag 即平台版本。

升级顺序（重要）

1. 先升级 OneUptime 平台本身；
2. 再上调 Provider 的版本约束；
3. 最后执行terraform init -upgrade让 Terraform 重新解析约束并更新.terraform.lock.hcl。

顺序颠倒（先用新 Provider 连旧平台）会踩到"Provider 驱动了平台还没有的 API 字段"的坑。升级 Provider 后建议紧跟terraform plan确认无意外变更。

离线（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 可识别的目录布局落盘。注意：这一步需要在一个包含required_providers声明的配置目录中执行，约束决定了拉取哪些版本。

第二步：传输并提供镜像

将/srv/terraform-mirror目录整体传输到内网：

• 通过普通 HTTPS 文件服务器对外提供，或
• 直接作为文件系统路径共享。

第三步：配置 CLI 指向镜像

在运行 Terraform 的每台机器上编辑 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，让镜像包含新版本。

从源码佐证看，Terraform 的镜像机制依赖 Provider 的注册表插件目录布局——本地安装脚本 中可见插件被安装到~/.terraform.d/plugins/registry.terraform.io/oneuptime/oneuptime/<version>/<os_arch>/，这与filesystem_mirror期望的目录结构一致，也解释了为什么镜像内容可以无缝替换网络下载。

TLS 注意事项

Terraform 是 Go 程序，校验实例证书时使用运行 Terraform 机器的系统信任库。自托管场景常见的 TLS 坑与对策如下：

私有 CA 证书

如果实例使用私有 CA 签发的证书，必须在**每一台运行 Terraform 的机器（含 CI Runner）**上安装该 CA：

• Debian/Ubuntu：将 CA 复制到/usr/local/share/ca-certificates/后执行update-ca-certificates。
• 其他发行版/系统：使用其对应的系统信任库更新方式。

没有"跳过 TLS 校验"开关

Provider刻意不提供跳过 TLS 验证的属性。如果看到：

x509: certificate signed by unknown authority

正确做法是修复信任链（安装 CA），而不是想办法绕过校验。这也是 OneUptime Provider 的安全设计底线——详见 troubleshooting 中该错误行的处理建议。

明文 HTTP 仅限实验室

明文 HTTP 可用于实验环境：

oneuptime_url = "http://oneuptime.lab.internal"

但项目 API Key 会随每次请求发送，因此任何超出一次性实验室用途的环境都必须启用 TLS。

反向代理 / Ingress 场景

如果 OneUptime 位于反向代理或 Ingress 之后：

• oneuptime_url必须填写代理对外暴露的外部 origin；
• 确保代理原样转发所有/api路径（不做改写、不丢弃路径前缀），否则 Provider 的 API 调用会 404。

常见错误速查（自托管相关）

将 troubleshooting 中与自托管强相关的条目摘录如下，便于按症状快速定位：

关于版本号全貌：Provider 版本追踪平台版本，且并非每个平台 patch 都会发布到 Registry（生成器只在有意义的变化时重新生成并发布，具体发布流程见 publish-terraform-provider.sh），这正是"不要 pin 精确 patch"这一规则的根源。发布机制与版本历史的详细说明见 registry 文档。

相关文档导航

• Registry 使用说明 —— 版本如何发布、版本号规则与发布说明
• 故障排查 —— URL、TLS、Key 错误的详细剖析
• 快速开始 —— 第一次 apply，自托管下完全相同的流程
• 完整指南 —— 认证选项、项目布局、依赖与数据源
• 示例配置 —— 各主要资源类型的可直接复制配置
• Terraform Provider 生成器 —— 理解 Provider 由 OpenAPI 规范自动生成的底层机制

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