Onyx Terraform Provider 使用指南通过 Onyx 管理 API 声明式管理 LLM Provider、API Key 与工作区配置【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本文以terraform-provider-onyx为核心介绍如何使用 Terraform 通过 Onyx 管理 API 对 OnyxAI 聊天平台应用层配置进行声明式管理——涵盖 Provider 认证配置、可管理的资源与数据源、密钥安全实践write-only 参数以及已知 API 限制。读完本文你将掌握从零接入 Onyx Provider、编写首个可落地的 Terraform 配置以及安全托管 API Key 与 LLM Provider 的完整方案。Provider 定位管理运行在 Onyx 内部的配置terraform-provider-onyx是 Onyx 官方 Terraform Provider其目标是在 Terraform 中以声明式方式管理Onyx 应用配置LLM Provider、部署默认模型、API Key、工作区设置、Embedding Provider 等全部经由 Onyx 管理 API 完成读写。官方文档的描述非常精炼Manage Onyx application configuration (LLM providers, API keys, workspace settings, ...) declaratively via the Onyx admin API.需要特别区分的是仓库 deployment/terraform 目录用于部署 Onyx 运行所需的基础设施EKS、RDS 等而本 Provider 配置的是某个 Onyx 部署内部运行的东西。两者互补但职责完全不同——前者回答Onyx 跑在哪里后者回答Onyx 里配了什么。Provider 源码位于 terraform-provider-onyx 目录核心入口是 internal/provider/provider.go基于 HashiCorp 的terraform-plugin-framework框架实现。Provider 认证与三项核心配置参数Provider 的全部配置集中在endpoint、api_key、api_prefix三个参数上均可在.tf文件中声明也可通过环境变量注入。依据 index.md 的 Schema 定义参数说明如下参数类型说明环境变量endpointStringOnyx 服务器源地址origin例如https://cloud.onyx.app或http://localhost:3000ONYX_SERVER_URLapi_keyString, Sensitive位于种子Admin组的 Onyx API Keyon_...或不受限的个人访问令牌onyx_pat_...ONYX_API_KEYapi_prefixStringAPI 挂载的路径前缀默认/apiWeb 代理直连后端如http://localhost:8080时设为ONYX_API_PREFIX最小可用配置terraform { required_providers { onyx { source onyx-dot-app/onyx } } } variable onyx_api_key { type string sensitive true } # Credentials can also come from ONYX_SERVER_URL / ONYX_API_KEY env vars. provider onyx { endpoint https://onyx.internal.example.com api_key var.onyx_api_key # an API key in the Admin group (on_...) }其中api_prefix不写时默认取/api。当你直连后端服务http://localhost:8080时需显式置空例如本地开发或接测试套件时。配置优先级与校验逻辑从源码看provider.go 的Configure阶段对环境变量与属性做了明确的优先级合并endpoint先取ONYX_SERVER_URL若配置中显式设置了endpoint则以配置为准api_key先取ONYX_API_KEY配置中的api_key优先api_prefix默认/apiONYX_API_PREFIX可覆盖配置中的api_prefix优先级最高。若endpoint或api_key最终为空Provider 会直接报错并给出创建密钥的指引。同时Provider 拒绝接收未知unknown的配置值——当endpoint/api_key/api_prefix派生自尚未 apply 的资源时会在 plan 阶段直接报错而不是静默当作空值处理。客户端实现见 internal/client/client.go请求会同时携带Authorization与X-Onyx-Authorization两个 Bearer 头后者优先被服务端检查可穿透会消费Authorization头的代理并以terraform-provider-onyx/version作为 User-Agent对 429 限流一律重试而 POST 等可能已产生副作用的请求遇到传输错误则不重放。认证方式与 API Key 的获取Provider 需要一个位于种子Admin组的 API Key或无组限制的 PAT。获取方式有两种管理面板在 Onyx 管理后台的Settings - Service Accounts中创建命令行调用管理 API 手工铸造注意必须传入 Admin 组 id——不带组的 Key 没有任何管理权限curl -X POST https://your-onyx/api/admin/api-key \ -H Cookie: fastapiusersauthadmin session \ -H Content-Type: application/json \ -d {name: terraform, group_ids: [admin group id]}仓库提供了自动化脚本 examples/bootstrap/mint_api_key.sh完整执行注册 → 登录 → 解析 Admin 组 → 铸造 Key的流程适合 CI 或脚本化首次部署。它强制要求ONYX_ADMIN_EMAIL与ONYX_ADMIN_PASSWORD而不提供默认值在无用户的部署上脚本会注册该账号且第一个注册的用户自动成为管理员——若给默认密码等于在任何可达部署上悄悄创建一个已知口令的管理员。值得注意的两点API Key 的有效性与部署的人类用户AUTH_TYPEbasic/OIDC/SAML/cloud无关在 Onyx Cloud 上租户信息内嵌于 Key 本身。资源与数据源总览Provider 注册了 13 个资源与 4 个数据源见 provider.go 的Resources/DataSources方法。依据 README.md 汇总如下名称管理内容Import idonyx_api_keyAPI Key/admin/api-key数字 idonyx_llm_providerLLM Provider 及其模型列表/admin/llm/provider数字 idonyx_llm_provider_default部署默认及视觉模型——单例defaultonyx_settings工作区设置——单例部分托管settingsonyx_embedding_provider云端 Embedding Provider 凭据provider 类型如openaionyx_credential连接器凭据/manage/credential数字 idonyx_connector连接器定义/manage/admin/connector数字 idonyx_cc_pair连接器-凭据配对/manage/connector/.../credential/...数字 idonyx_document_set文档集/manage/admin/document-set数字 idonyx_custom_tool自定义动作/admin/tool/custom数字 idonyx_agentAgent / 助手/persona数字 idonyx_mcp_serverOnyx 连接的 MCP 服务器/admin/mcp数字 idonyx_user_group用户组成员、管理者、权限授予仅企业版数字 iddata.onyx_llm_providers只读Provider 列表 默认模型—data.onyx_embedding_providers只读Embedding Provider 列表—data.onyx_settings只读当前设置含许可证tier—data.onyx_connectors只读连接器列表—每个资源的生成文档位于 terraform-provider-onyx/docs 下的data-sources/与资源对应页面。实战一个完整的第一天配置examples/bootstrap/ 提供了一个可运行的 day-one 配置创建一个聊天模型、索引一个公开文档站点、将结果归入文档集并添加一个从该文档集作答的 Agent全部工作在 Community Edition 上可用onyx_user_group是唯一例外需开启企业特性。terraform { required_version 1.5 required_providers { onyx { source onyx-dot-app/onyx } } } # Reads ONYX_SERVER_URL and ONYX_API_KEY when the variables are unset. provider onyx { endpoint var.onyx_server_url api_key var.onyx_api_key }工作区与聊天模型# 仅管理此处设置的属性。销毁该资源不会重置已写入的设置。 resource onyx_settings workspace { company_name var.company_name } resource onyx_llm_provider openai { name openai provider_type openai api_key var.openai_api_key # 完整的启用模型集合任何被省略的模型都会在 apply 时被移除。 model_configurations [ { name gpt-5 }, { name gpt-5-mini }, ] } # 引用 provider id 也保证了销毁顺序默认模型先于持有它的 provider 被释放。 resource onyx_llm_provider_default this { provider_id onyx_llm_provider.openai.id model_name gpt-5 }onyx_settings是部分托管的单例——从源码 settings_resource.go 可见未在配置中设置的属性在服务端保持不动从配置中移除某属性意味着停止管理而非重置。可写属性包括company_name、maximum_chat_retention_days、anonymous_user_enabled、invite_only_enabled、deep_research_enabled、multi_model_chat_enabled、search_ui_enabled、query_history_type、user_knowledge_enabled、disable_default_assistant、craft_default_enabled等只读属性则包括application_status、tier、ee_features_enabled、seat_count、used_seats等部分每次读取时从后端环境变量覆盖。知识库连接器、凭据与配对# Web 连接器读取公开页面因此其凭据不含任何秘密。 resource onyx_credential web { source web name public-web credential_json jsonencode({}) } resource onyx_connector docs { name docs-site source web input_type load_state # 每天重新索引一次。 refresh_freq 24 * 60 * 60 connector_specific_config jsonencode({ base_url var.docs_base_url web_connector_type recursive }) } # 配对才是真正执行索引的对象同时承载其产出文档的访问控制。 resource onyx_cc_pair docs { name docs-site connector_id onyx_connector.docs.id credential_id onyx_credential.web.id access_type public } resource onyx_document_set docs { name docs description Public product documentation cc_pair_ids [onyx_cc_pair.docs.id] }注意access_type与groups放在onyx_cc_pair上——Onyx 在凭据被关联时应用访问控制连接器端点本身虽然要求access_type字段却会忽略它。Agent 与企业版用户组resource onyx_agent docs { name Docs description Answers product questions from the documentation system_prompt -EOT You answer questions from the product documentation. If the documentation does not cover the question, say so. EOT document_set_ids [onyx_document_set.docs.id] starter_messages [ { name Getting started message How do I get started? }, ] } # 用户组需要企业版。Community Edition 上请保持关闭Onyx 会拒绝这些路由。 resource onyx_user_group platform { count var.enable_enterprise_features ? 1 : 0 name Platform # 权限使用 Onyx 自己的令牌而非枚举名。 permissions [ manage:connectors, manage:document_sets, ] }应用与清理cp terraform.tfvars.example terraform.tfvars # 编辑 terraform.tfvars terraform init terraform plan terraform apply凭据也可以走环境变量从而避免写入terraform.tfvarsexport ONYX_SERVER_URLhttp://localhost:8080 export ONYX_API_KEY$(ONYX_ADMIN_EMAILadminexample.com \ ONYX_ADMIN_PASSWORD... ./mint_api_key.sh) export TF_VAR_openai_api_keysk-...terraform destroy会销毁配对并后台移除其索引的文档onyx_settings是例外——销毁只停止托管设置不会重置它们。索引在 apply 后后台执行Agent 需等待首个索引周期完成才能基于站点作答可在管理后台Connectors下观察进度。密钥安全write-only 参数与轮换每个 Provider 接收的密钥都有两种形态见 README.md普通属性值写入 Terraform state任何能读到 state 文件的人都能读到密钥_wo孪生属性Terraform 的 write-only 参数值会从 plan 与 state 中剥离只存在于你的配置文件中。资源存入 stateWrite-onlyonyx_llm_providerapi_key、custom_configapi_key_wo、custom_config_woonyx_embedding_providerapi_keyapi_key_woonyx_credentialcredential_jsoncredential_json_woonyx_mcp_serverapi_token、admin_credentialsapi_token_wo、admin_credentials_woonyx_custom_toolcustom_headerscustom_headers_wo两者只能二选一设置不能同时给出。onyx_credential因载荷必填必须且只能提供其一。示例resource onyx_llm_provider openai { name openai provider_type openai api_key_wo var.openai_api_key api_key_wo_version 1 model_configurations [{ name gpt-5-mini }] }Write-only 参数要求Terraform 1.11 或更高旧版 CLI 会拒绝包含它的配置。三个无法使用 write-only 的例外onyx_api_key.api_key这是 Onyx 铸造的 Key 而非你提供的Terraform 只能通过 state 交回生成值须将 state 文件视同持有该 Keyonyx_mcp_server.auth_template_headers该属性是 computedOnyx 为共享令牌自行写入模板Terraform 不允许一个参数既是 computed 又是 write-only其占位符值来自admin_credentials_woProvider 自身的api_keyProvider 配置本就不会写入 state建议直接用ONYX_API_KEY环境变量提供而非写进.tf文件。轮换 write-only 密钥Terraform 从不存储的值也无法做 diff因此仅修改api_key_wo不会触发任何计划。每个孪生属性配有一个_wo_version计数器把它加一产生的 diff 会让下一次 apply 发送当前密钥。注意不要用密钥派生计数器如md5(var.token)——计数器会存进 state不能反推出密钥。计数器只决定何时触发 apply由于 Onyx 更新时替换所有字段Provider 每次 apply 都会发送当前密钥。两个需要知晓的行为onyx_custom_tool停止刷新其请求头Onyx 原样返回 action headers而非掩码所以custom_headers能正常刷新、面板外的改动会出现在terraform plan中但对custom_headers_wo做不到这一点刷新会把密钥写进 state因此面板中改动的 header 在下次 apply 覆盖前不会被报告——这是 write-only 形式唯一的让步。导入多一次 apply导入读取的是服务端现状若 Onyx 未掩码返回密钥它会进入存储属性第一次 apply 使用孪生属性时将其从 state 清除资源随即转入 write-only 路径。已知限制API 设计使然需要绕行而非等待这些限制源于 Onyx API 本身的行为属于需要设计规避的特性而非等待修复的 bug。Fixed upstream表示后端已改进但修复尚未进入已发布的 Onyx因此 Provider 保留绕行方案限制仍然适用。完整清单见 README.md 的Known limitations章节以下为要点密钥秘密漂移不可检测API 读取时对密钥做掩码面板轮换对terraform plan不可见配置值是权威下次 apply 会重新断言。设置与部署默认值onyx_settings与onyx_llm_provider_default并非真正删除Onyx 没有重置设置 API也没有取消文本/视觉默认值的 API销毁只会把它们从 state 移除聊天命名默认值有 unset API会被真正清空。LLM 与 Embedding Provideronyx_embedding_provider更新会替换全部字段配置中必须保留api_key或api_key_wo否则更新会清空已存密钥当前生效的 Embedding Provider 不可删除。model_configurations是权威记录被省略的模型会在服务端移除移除当前部署默认模型会失败——先改指onyx_llm_provider_default引用顺序已正确处理。模型列表读取的是 API 的显示视图隐藏过时与重复模型写操作无法保留未返回的行管理面板行为一致。Fixed upstreamupsert 已支持keep_existing_models。凭据与连接器onyx_credential载荷永不被读回API 总是掩码载荷admin_public、curator_public、groups无更新端点会强制替换。私有凭据可能看起来像被删除admin_public false的凭据对创建者以外的管理员隐藏与删除不可区分Terraform 会删了重建。托管凭据请保持默认admin_public true。onyx_connector不拥有访问控制access_type与groups在配对cc_pair上设置未设置prune_freq时首次更新会变成 7 天Provider 随后将其作为权威值。Agent 与动作删除 Agent 留下墓碑行被标记删除名称仍被占用同名重建会复活原 Agent销毁-重建返回原 id 而非新 id。已删除的 Agent 返回 400 而非 404Provider 依据 Agent 列表确认存在性。Fixed upstream路由现返回类型化的PERSONA_NOT_FOUND。onyx_agent并非拥有全部字段附加的文件夹与文档省略即清空、显式 null 则被拒绝Provider 读取后写回存在一个往返窗口可能回滚期间的并发附加。Fixed upstream两个字段已可空。另外search_start_date只写不读头像不受管理。display_priority在 upsert 上仅创建时生效后续写忽略变更需第二次调用显示优先级端点。两个内置动作对 API 隐藏OktaProfileTool与MemoryTool不在 Agent 快照中持有它们的 Agent 报告的tool_ids少于写入值且永不收敛。删除自定义动作会将其从每个使用它的 Agent包括 Terraform 未管理的上摘除且无任何报错或警告。用户组企业版onyx_user_group仅企业版存在路由Community Edition 上所有调用返回 404。用户组不管理组能看见什么连接器、文档集、Agent、LLM Provider、MCP 服务器与凭据各自携带自己的groups组暴露只读的cc_pair_ids、document_set_ids、agent_ids两侧不会争夺同一条边。移除成员可能覆盖并发的连接器共享组同步期间 Onyx 拒绝成员变更/重命名/删除而新组从同步中开始Provider 会在每次操作前等待同步中的组在成员与删除路由上返回 404 而非冲突因此 404 不代表组已消失。Fixed upstream门禁现抛出RESOURCE_SYNCING冲突。权限使用 Onyx 的 wire 令牌如manage:connectors而非枚举名只有可切换的权限可设置basic、admin、craft_sandbox、manage:skills及隐含读令牌由 Onyx 管理。种子默认组Admin、Basic只持有成员管理名册可行重命名、删除、权限与隐身变更会被拒绝。Onyx 拒绝会让某人脱离所有组的移除销毁组同样受检——若某成员只有这一个组销毁会失败管理员权限存续、经理自移除、权限放大均有防护。MCP 服务器只管理无需交互登录的服务器NONE与API_TOKEN可用OAUTH、PT_OAUTH需要浏览器往返plan 阶段即被拒绝。服务器暴露哪些工具不受管理Onyx 通过调用服务器来学习工具拒绝命名未见过工具的选择。省略的description会被清空而非保留groups、users同理从配置移除即清空服务端含管理面板添加的条目。从管理面板添加但从未配置的服务器导入为空字符串auth_type、transport未设置首次 plan 后移入 schema 默认值一次 apply 收敛。服务器 URL 不能指向 Onyx 主机SSRF 防护在所有保护级别都拒绝localhost与链路本地地址。本地开发、测试与文档生成开发需要 Go见 go.mod与 Terraform CLIgo build ./... # 构建 go test ./... # 单元测试无需 Onyx使用本地构建在~/.terraformrc中写dev_overrides指向本地二进制provider_installation { dev_overrides { onyx-dot-app/onyx /path/to/onyx/terraform-provider-onyx } direct {} }然后go build在任意使用该 Provider 的配置中直接terraform plan/apply跳过terraform init。验收测试验收测试针对真实 Onyx 部署执行完整 CRUD 周期会创建/销毁 Provider 与 Key并短暂修改工作区设置请使用开发部署TF_ACC1 ONYX_TF_ACC_SERVER_URLhttp://localhost:8080 go test ./internal/provider/ -vONYX_TF_ACC_API_PREFIX默认为直连后端走 Web 服务器时设为/api认证设置ONYX_TF_ACC_API_KEY使用现有管理 Key或让测试装置以ONYX_TF_ACC_ADMIN_EMAIL/ONYX_TF_ACC_ADMIN_PASSWORD登录自助引导默认admin_userexample.com/TestPassword123!全新部署上第一个注册用户自动成为管理员。未设置TF_ACC时这些测试自动跳过因此go test ./...在无 Onyx 环境下保持绿色——CI 的pr-golang-tests.yml即如此不跑验收套件pr-terraform-provider-tests.yml是会跑验收套件的通道它用 docker compose 拉起 api_server 与 background并让套件跑两遍自引导 Key 与先用mint_api_key.sh铸造的 Key。onyx_cc_pair、onyx_document_set、onyx_user_group测试还需要 Celery 与 beat用户组测试尤其依赖 beat 的check-for-vespa-sync每 20 秒清除同步状态否则每次重命名/成员变更/销毁都会等到超时配对测试特意使用mock_connector源以覆盖全生命周期而无需真实数据源。文档生成docs/是生成产物——编辑 schema 的MarkdownDescription与examples/后执行go generate . # 运行 tfplugindocs需要 terraform 在 PATH 上小结terraform-provider-onyx将 Onyx 应用层配置完整地带入 Terraform 的声明式工作流通过endpoint/api_key/api_prefix三个参数完成认证接入13 个资源与 4 个数据源覆盖 API Key、LLM Provider、默认模型、工作区设置、连接器与凭据、文档集、Agent、MCP 服务器乃至企业版用户组write-only 孪生属性与_wo_version计数器为密钥安全与轮换提供了 state 之外的路径。理解其API 设计使然的已知限制秘密漂移不可检测、部分资源不可真删、删除行为与 404 语义等即可在真实部署中做出正确的建模与绕行设计。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考