OneUptime Monitor Secrets 实战指南：加密密钥的创建、注入与访问控制

OneUptime Monitor Secrets 实战指南加密密钥的创建、注入与访问控制【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeMonitor Secrets 是 OneUptime 内置的敏感信息管理能力用于在 API、网站、SNMP、Synthetic 脚本等各类监控检查中安全地存放 API Key、密码、令牌等凭据替代把明文写死在监控配置里的做法。本文以官方文档为主体结合仓库内数据模型、加密实现与注入管线源码完整讲解 Monitor Secret 的创建、授权、引用、轮换与权限管控读完你可以在自托管或云端 OneUptime 中为监控检查接入一套「加密存储、按监控器授权、模板语法注入」的密钥体系。Monitor Secrets 是什么Monitor Secret 是一个可以被监控器使用的加密密钥变量。仓库中数据模型的官方描述见 MonitorSecret.ts定义得很清楚Monitor Secret is a secret variable that can be used in monitors. For example you can store auth tokens, passwords, etc. in Monitor Secret and use them in your monitors. Monitor Secret is encrypted and only accessible by the probe.它解决的是监控场景下最典型的两个痛点避免凭据散落API 的Authorization头、SNMP 的 community string、Synthetic 脚本里的令牌等敏感值不必再以明文形式保存在监控步骤配置中而是集中存放于一处安全可审计密钥值加密落库、保存后永不可回读且每个密钥可以精确控制「哪些监控器有权限使用」从存储到消费全程可控。创建与管理 Monitor Secret操作入口在 OneUptime Dashboard 中按以下路径进入 Monitor Secrets 管理页Monitors - Settings - Secrets - Create Monitor Secret对应的前端页面实现位于 MonitorSecrets.tsx是一个基于ModelTableMonitorSecret的标准 CRUD 表格页支持创建、编辑、删除以及行级操作「Update Secret Value」。表单字段说明创建表单由四个字段组成其中三个与密钥本身相关字段是否必填说明Name是密钥的名称是项目内唯一的标识符。源码校验规则为最短 2 个字符、不含空格、不含特殊字符只能使用字母、数字、连字符-和下划线_见 MonitorSecrets.tsxDescription否便于记忆的友好描述例如「Api Key for GitHub」Secret Value是密钥本体例如sk_test_...这样的真实凭据Monitors which have access to this secret否多选下拉指定哪些监控器可以使用该密钥其中 Name 字段的名称就是后续在监控配置中引用的名字。例如你在上图中创建了一个名为ApiKey的密钥并勾选了APIRequest这个监控器那么在APIRequest的配置里就可以用{{monitorSecrets.ApiKey}}来引用它。三个必须知道的安全行为官方文档特别强调密钥保存后有以下行为这直接决定了密钥的运维方式值永不回显Secret Value 一旦保存就不会再出现在列表中、不会出现在编辑表单里也不会通过 API 返回。前端实现中该字段使用doNotShowWhenEditing: true见 MonitorSecrets.tsx编辑时表单根本不渲染该字段丢失只能重设由于值不可回读如果你遗失了密钥原文只能回到其来源系统如第三方服务后台重新获取然后在 OneUptime 中重新设置轮换不需要删除重建对需要更换的密钥直接点击该行上的Update Secret Value按钮更新值即可无需先删除再创建。这样密钥与监控器的授权关系、引用点都保持不变只是底层的明文凭据被替换。存储模型与加密实现数据模型MonitorSecret是一个标准的 OneUptime 数据库模型定义见 MonitorSecret.ts其核心字段如下字段类型说明projectIdObjectID租户列TenantColumn密钥归属于某个项目nameShortText密钥名称通过UniqueColumnBy(projectId)保证同一项目内唯一descriptionLongText可选描述secretValueVeryLongText密钥值标注encrypted: true即加密后落库monitorsEntityArray与Monitor的多对多关系即授权列表createdByUserId/deletedByUserIdObjectID创建人 / 删除人审计字段其中monitors关系由 TypeORM 的ManyToMany实现通过名为MonitorSecretMonitor的中间表连接monitorSecretId与monitorId两列见 MonitorSecret.ts。该表在数据库迁移中也有对应的建表与外键定义见 InitialMigration外键ON DELETE CASCADE——删除密钥或监控器时关联关系自动清理。模型对外暴露的 CRUD API 路径为/monitor-secretCrudApiEndpoint服务层实现位于 MonitorSecretService.ts继承自通用DatabaseServiceMonitorSecret。此外模型还开启了EnableWorkflow意味着密钥资源本身可以接入 OneUptime 的工作流自动化创建 / 删除 / 更新 / 读取事件均可作为工作流触发点。加密实现secretValue列标记为encrypted: true见 MonitorSecret.ts它归属于 OneUptime 的通用列加密机制。根据 EnvironmentConfig.ts 中的说明所有TableColumn({ encrypted: true })的列值——包括 OAuth 令牌、SMTP 密码、告警日历 feed token 以及 Monitor Secret——都会使用环境变量ENCRYPTION_SECRET进行AES 加密后再写入数据库。这一点对自托管用户尤其重要代码里专门提供了IsEncryptionSecretInsecure检查如果ENCRYPTION_SECRET未设置、为空或仍使用仓库自带的占位符以please-change-this前缀开头启动日志会发出高音量警告——因为任何人拿到数据库导出都可以用公开在仓库中的占位密钥解密所有加密列。因此自托管部署时务必设置一个足够随机的ENCRYPTION_SECRET这是 Monitor Secret 加密存储真正生效的前提。另一个值得注意的细节是secretValue的列级读取权限为空read: []见 MonitorSecret.ts意味着除了项目 Owner / Admin表级read权限任何角色都无法通过查询读取到密钥值——这正是「保存后永不可回读」在数据访问层的落地。权限与计费门槛MonitorSecret模型上同时声明了两类访问控制表级计费控制TableBillingAccessControlcreate / read / update / delete均要求Growth 及以上计划即 Monitor Secrets 属于 Growth 计划才开放的能力表级权限控制TableAccessControl创建需ProjectOwner/ProjectAdmin/CreateMonitorSecret读取需ReadMonitorSecret更新需EditMonitorSecret删除需DeleteMonitorSecret见 MonitorSecret.ts。四个动作均有对应的独立权限点便于按角色精细授权。在监控中使用 Secrets引用语法在监控配置中需要用到密钥的任意字段里写入模板引用即可{{monitorSecrets.SECRET_NAME}}例如官方文档的场景在 API 监控的 Request Headers 中添加一个键APIKEY值为{{monitorSecrets.ApiKey}}探针发起请求时就会携带解析后的真实密钥值。支持的监控类型与可注入位置官方文档明确列出四类而仓库源码进一步证实了更多类型和字段位置。完整清单如下监控类型可注入位置API请求头request headers、请求体request body、URLWebsite / IP / Port / Ping / SSL Certificate监控目标 URLSynthetic Monitor / Custom Code Monitor自定义脚本代码customCodeSNMP MonitorNetwork Devicecommunity stringSNMPv2 团体名、SNMPv3 auth key、SNMPv3 priv keySQL Query Monitor连接 password / username / host / databaseName甚至查询语句本身Database Health Monitor连接 password / username / host / databaseNameDNS Monitor自定义 DNS 服务器 hostname、查询名query nameDomain / DNSSEC Monitor域名External Status Page Monitor状态页 URLAPI / WebsitemTLS 场景TLS 客户端证书、客户端密钥、密钥口令tlsClientCertificate/tlsClientKey/tlsClientKeyPassphrase其中 API、Website、IP、Port、Ping、SSLCertificate 类监控注入的是monitorDestination监控目标地址API / Website 还支持 mTLS 证书与私钥的注入见 MonitorStep.ts 的说明Values can be raw PEM strings or {{monitorSecrets.name}} references。SQL / Database 监控的字段则直接支持用{{monitorSecrets.name}}引用密码、用户名、主机名等敏感连接信息见 MonitorStepSqlMonitor.ts 与 SqlConnectionConfig.ts。注入管线占位符如何变成真实凭据官方文档描述为「Secrets are injected on the probe before Synthetic or Custom Code monitor scripts execute」即脚本执行前引用已解析为明文。从源码看这一过程实际由后端 Telemetry 服务在向探针下发监控配置之前完成。核心实现在 Telemetry/Utils/Monitor.ts主要分四步检测monitorStepsReferenceSecrets()检查监控步骤序列化的 JSON 字符串中是否包含子串monitorSecrets.只有确实存在引用时才触发后续加载避免对每个监控器都做一次多余的数据库查询加载loadMonitorSecrets(monitorId)通过MonitorSecretService.findBy查询「关联了该监控器」的密钥且只select出name与secretValue两个字段使用isRoot: true的根级权限执行见 Monitor.ts。另有批量变体loadMonitorSecretsForMonitors一次查询即可为一批监控器加载各自的密钥并严格按monitors关系分组——某个监控器永远拿不到没有授予它的密钥见 Monitor.ts填充populateSecretsInMonitorSteps()按监控类型遍历所有监控步骤对匹配的字段请求头、URL、脚本、SNMP 字段等逐一执行替换见 Monitor.ts替换fillSecretsInStringOrJSON()把密钥集合构造成{ monitorSecrets: { ApiKey: 真实值 } }这样的映射再交给VMUtil.replaceValueInPlace完成{{monitorSecrets.ApiKey}}→ 真实值的文本替换见 Monitor.ts。替换完成后解析好的监控步骤随配置一起派发给探针。对 Synthetic / Custom Code 监控而言探针执行脚本时拿到的customCode中已是解密后的明文且该明文只存在于探针进程的内存执行上下文中不会随探针回传的检查数据落库——这也是「密钥只对探针可见」的语义所在。此外populateSecretsOnMonitorTest()说明 Monitor Test监控测试运行同样会执行这一套密钥解析让你在正式上线前就能验证引用是否正确见 Monitor.ts。探针侧的 MonitorUtil.test.ts 亦覆盖了 URL 中{{monitorSecrets.ApiKey}}占位符的传递与解析行为。访问控制与最小授权Monitor Secret 的授权模型非常直接monitors多对多关系本身就是授权。创建或编辑密钥时勾选的监控器列表决定了哪些监控器在注入阶段能通过关系查询拿到该密钥而这个授权是随时可更新的——想给新监控器授权或回收某监控器的使用权直接编辑该密钥的「Monitors which have access to this secret」字段即可无需改动任何监控配置。这套「按监控器授权」的机制与 OneUptime 对监控器自身凭据的最小权限设计是一脉相承的。仓库中 MonitorSecretKeyColumnAccessControl.test.ts 专门验证了监控器上三个 bearer 凭据列serverMonitorSecretKey、incomingRequestSecretKey、incomingEmailSecretKey的读取权限——只有具备轮换该密钥能力ProjectOwner / ProjectAdmin / ProjectMember / MonitorAdmin / MonitorMember / EditProjectMonitor的角色才能读取纯粹的 Viewer / MonitorViewer 只读角色一律被拒绝其原则是「能读到凭据的人必须同时具备吊销轮换它的能力」。Monitor Secret 的设计同样贯彻了这一原则密钥的创建与授权由具备管理权限的人掌控而普通只读用户既看不到密钥值也无法把密钥授权给新的监控器。最佳实践建议综合文档与源码以下是使用 Monitor Secrets 的几条建议自托管务必先配置强随机的ENCRYPTION_SECRET这是所有加密列包括 Monitor Secret 值AES 加密的根密钥使用仓库默认占位符会让加密形同虚设一个密钥只授权给必要的监控器借由monitors关系实现最小授权避免某个密钥在项目内被过多监控器共享优先用Update Secret Value轮换而非删除重建轮换保持引用与授权关系不变操作成本最低怀疑泄露时应立即轮换明文只保留在来源系统OneUptime 保存后不会回显密钥值请在自己的密码管理器或来源系统中留存原文以免遗失后无法恢复上线前用 Monitor Test 验证引用通过监控测试运行提前确认{{monitorSecrets.*}}引用解析正确避免正式监控因密钥名拼写错误而失败利用独立权限点做角色隔离CreateMonitorSecret/ReadMonitorSecret/EditMonitorSecret/DeleteMonitorSecret四个权限点可以按团队角色拆分例如只给运维角色分配创建与授权能力给监控维护角色分配使用能力。Monitor Secrets 把「敏感凭据」从监控配置中剥离出来统一收口到加密存储与按监控器授权的密钥体系中配合模板语法注入是 OneUptime 监控配置中处理 API Key、数据库口令、SNMP 凭据等敏感信息的标准姿势。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考