使用 Terraform Provider 为 Onyx 搭建 Day-One 配置Bootstrap 实战指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本指南基于开源仓库中的terraform-provider-onyx/examples/bootstrap/完整示例讲解如何用基础设施即代码IaC的方式为 Onyx AI 平台在一天之内配置好聊天模型 文档索引 文档集 问答 Agent的完整最小可用链路。读完本文你将掌握 Onyx Terraform Provider 的 API Key 认证机制、bootstrap 配置中每个资源onyx_llm_provider、onyx_connector、onyx_cc_pair、onyx_document_set、onyx_agent等的字段语义以及从terraform apply到terraform destroy的完整生命周期操作。背景bootstrap 示例解决什么问题terraform-provider-onyx是一个管理Onyx 应用层配置的 Terraform Provider它通过 Onyx 管理 API 以声明式方式管理 LLM Provider、部署默认模型、API Key、工作区设置等见 terraform-provider-onyx/README.md。需要特别区分的是仓库中的deployment/terraform/负责的是 Onyx 运行所依赖的基础设施EKS、RDS 等而本 Provider 配置的是运行在 Onyx 部署内部的应用配置。examples/bootstrap/入口文档见 examples/bootstrap/README.md是这套 Provider 的第一天day-one示例一套可直接运行的配置一次性创建一个聊天模型chat model索引一个公开的文档站点把索引结果归入一个文档集document set添加一个只基于该文档集回答问题的 Agent。示例中的全部资源在Community Edition社区版上都能工作唯一例外是onyx_user_group资源——它依赖企业版路由默认关闭只有当你设置enable_enterprise_features true时才会启用。示例目录的完整文件构成如下文件作用main.tf全部资源定义variables.tf输入变量声明terraform.tfvars.example变量赋值模板含安全提示注释outputs.tf输出定义agent_id、cc_pair_idmint_api_key.sh脚本化创建 Admin 组 API Key第一步获取 API KeyProvider 使用 Onyx API Key 进行认证。关键机制是一个 Key 的权限来自它所属的用户组因此该 Key 必须位于Admin组中否则会被所有管理路由拒绝。获取方式有两种方式一管理面板手工创建。在 Onyx 管理后台的Settings - Service Accounts下创建一个属于Admin组的 Key。方式二运行示例自带的脚本。直接执行ONYX_SERVER_URLhttp://localhost:8080 \ ONYX_ADMIN_EMAILadminexample.com \ ONYX_ADMIN_PASSWORD... \ ./mint_api_key.sh脚本会以该账号登录并铸造mint一个属于Admin组的 Key。它依赖curl和jq两个命令行工具且列出用户组这一步需要用到与管理面板相同的企业版路由。从 mint_api_key.sh 的源码看整个流程可分为五步注册账号向${base}/auth/register发送POST请求。若部署中尚无用户注册会成功且第一个注册的用户自动成为管理员若账号已存在接口返回 400 也无妨——真正的门槛在登录。登录向${base}/auth/login发送POST用 Cookie Jar 保存会话。解析 Admin 组 ID请求${base}/manage/admin/user-group?include_defaulttrue从返回的 JSON 中筛出name Admin的组。注意脚本中注释说明种子seeded的Admin组在默认列表中是被隐藏的必须显式传include_defaulttrue。铸造 Key向${base}/admin/api-key发送POSTbody 为{name: terraform, group_ids: [admin_group_id]}然后从响应中提取api_key字段并打印。脚本还支持ONYX_API_PREFIX默认留空、直连后端和ONYX_API_KEY_NAMEKey 名称默认terraform两个可选环境变量。为什么凭据必须显式提供不能有默认值脚本刻意要求ONYX_ADMIN_EMAIL和ONYX_ADMIN_PASSWORD必须由用户显式给出绝不提供默认值。原因在脚本头部注释与 README 中都有强调在没有任何用户的部署上脚本会注册该账号而第一个注册的用户会成为管理员——如果这里提供默认密码就等于在任何一个可达的部署上悄悄留下一个已知密码的管理员。这是一个非常典型且值得借鉴的供应链安全设计宁可让自动化流程多一步配置也绝不给攻击者留下可利用的默认凭据。此外脚本对注册失败只发警告不中断因为已存在账号会返回 400但对登录失败找不到 Admin 组未返回 Key 材料则直接报错退出set -euo pipefail避免把部署问题掩盖成后续令人困惑的登录失败。第二步Provider 认证配置Provider 本身接受三个配置项均可通过环境变量回退见 internal/provider/provider.goProvider 属性环境变量说明endpointONYX_SERVER_URLOnyx 服务器源地址如https://cloud.onyx.app或http://localhost:3000api_keyONYX_API_KEY属于种子Admin组的 API Keyon_...或无限制的个人访问令牌onyx_pat_...api_prefixONYX_API_PREFIXAPI 挂载路径前缀默认/apiweb 代理直连后端如http://localhost:8080时需设为空字符串Provider 的Configure实现provider.go会优先采用 HCL 中显式设置的值未设置时回退到环境变量若两者都缺失则直接报错提示必须设置endpoint与api_key。HTTP 客户端层internal/client/client.go会携带版本化 User-Agentterraform-provider-onyx/version并以内置重试策略处理瞬时故障请求超时 3 分钟最多重试 4 次退避 500ms 到 30s。一个值得注意的细节provider 自身的api_key属于 Provider 配置Terraform 根本不会把它写入 state因此官方建议通过ONYX_API_KEY环境变量提供而不是写进.tf文件。第三步Apply 配置使用 tfvars 文件cp terraform.tfvars.example terraform.tfvars # 编辑 terraform.tfvars terraform init terraform plan terraform apply在 terraform.tfvars.example 中可以看到经过精心设计的变量组织方式onyx_server_url http://localhost:8080 # 两个密钥保持注释状态让环境变量优先。 # 这里一旦填入值就会覆盖 ONYX_API_KEY / TF_VAR_openai_api_key # 残留的占位符会被当作真实 Key 发送。 # # export ONYX_API_KEY$(./mint_api_key.sh) # export TF_VAR_openai_api_keysk-... # # 如需把密钥写进本文件取消注释 # onyx_api_key on_... # openai_api_key sk-... company_name ACME Corp docs_base_url https://docs.onyx.app # 仅企业版。 enable_enterprise_features false文件头部注释明确警告务必把terraform.tfvars排除在版本控制之外它包含机密而且一旦在此处填写值就会覆盖环境变量——所以密钥位保持注释状态、让环境变量生效是更安全的默认选择。使用环境变量凭据也可以完全走环境变量避免出现在terraform.tfvars中export 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-...其中TF_VAR_前缀是 Terraform 注入变量的标准机制TF_VAR_openai_api_key会自动填充到var.openai_api_key。变量清单variables.tf 中共声明 5 个变量变量类型默认值说明onyx_server_urlstringnullOnyx 部署的 Base URL未设置时回退到ONYX_SERVER_URLonyx_api_keystringsensitivenull属于 Admin 组的 API Key回退到ONYX_API_KEYopenai_api_keystringsensitive无必填聊天模型使用的 OpenAI API Keycompany_namestringACME Corp工作区名称显示在 Onyx UI 中docs_base_urlstringhttps://docs.onyx.app要索引的公开文档站点enable_enterprise_featuresboolfalse仅企业版部署才设为true社区版会拒绝用户组相关路由第四步逐资源解析 bootstrap 创建的内容运行terraform apply后示例会创建下表所列的资源原文表格见 examples/bootstrap/README.md资源用途onyx_settings.workspace工作区名称onyx_llm_provider.openai聊天模型 Provideronyx_llm_provider_default.this选定部署全局默认模型onyx_credential.web一个空凭据——web 连接器正是需要这种onyx_connector.docs声明索引什么、多久索引一次onyx_cc_pair.docs将连接器与凭据绑定并执行索引onyx_document_set.docs把已索引的配对分组供检索使用onyx_agent.docs基于该文档集回答问题的 Agentonyx_user_group.platform仅企业版默认关闭下面结合 main.tf 与各资源文档逐项展开。工作区设置onyx_settingsresource onyx_settings workspace { company_name var.company_name }onyx_settings是工作区设置的单例资源详情见 docs/resources/settings.md只有你在配置中显式设置的属性才会被管理未设置的属性在服务端保持原样从配置中移除某个属性只是停止管理它并不会重置它。删除该资源也只是把它从 Terraform state 中移除线上设置不变。因此一个部署最多应存在一个onyx_settings资源。除company_name外它还支持invite_only_enabled、query_history_typedisabled/anonymized/normal、anonymous_user_enabled、user_knowledge_enabled等大量可选字段并暴露ee_features_enabled、seat_count、application_status等只读属性。聊天模型onyx_llm_provider与onyx_llm_provider_defaultresource 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 }, ] } resource onyx_llm_provider_default this { provider_id onyx_llm_provider.openai.id model_name gpt-5 }onyx_llm_provider管理一个 LLM ProviderOpenAI、Anthropic、Azure、Bedrock 等及其启用的模型列表。从 internal/provider/llm_provider_resource.go 的 schema 定义可以看到几个关键语义model_configurations是记录全集apply 会用配置中的集合精确替换服务端的模型列表被省略的模型会在服务端被移除如果移除的恰好是当前部署默认模型则校验会失败——需要先把默认模型重新指向别处。源码注释强调引用onyx_llm_provider_default的provider_id能正确排序销毁顺序默认模型会先被释放然后才删除持有它的 Provider。每个模型项除name外还支持is_visible默认true是否可在 UI 选择、max_input_tokens覆盖模型最大输入 token 数、supports_image_input、supports_reasoning、display_nameOpenRouter/Ollama 等动态 Provider 的源 API 显示名、custom_display_name管理员自定义显示名。provider_type是 LiteLLM Provider key如openai、anthropic、azure、bedrock、vertex_ai、ollama必须小写且正则约束为^[a-z0-9_-]$。还支持api_base自定义 API Base URL适合 Azure 或自托管网关、api_versionAzure 专用、deployment_nameAzure 专用、is_public默认true对所有用户可见、is_auto_mode开启后模型列表由 Onyx 托管Terraform 停止漂移检查该列表、groups/agents访问限制以及force_delete即使持有部署默认模型也允许删除。onyx_llm_provider_default则是部署全局默认模型的单例指针见 docs/resources/llm_provider_default.md它指向某个 Provider 模型的组合另外可选配置vision_provider_id/vision_model_name默认视觉模型与chat_naming_provider_id/chat_naming_model_name聊天自动命名模型。由于 Onyx 对文本与视觉默认值没有 unset API销毁该资源会保留线上值只有聊天命名默认值会在被管理时清除。凭据onyx_credentialresource onyx_credential web { source web name public-web credential_json jsonencode({}) }onyx_credential承载连接器认证所需的密钥载荷见 docs/resources/credential.md。Web 连接器读取的是公开页面不需要任何机密所以credential_json传一个空 JSON 对象{}即可。source必须与配对的onyx_connector的source一致。需要注意的 API 行为Onyx API永远以掩码形式返回载荷因此credential_json永远不会被读回——Terraform 无法刷新它也无法检测到 Terraform 之外的变更。这正是本 Provider 引入write-only 参数credential_json_wo的原因Terraform 1.11 会把该值从 plan 和 state 中剥离密钥只存在于你的配置文件中永不落盘。write-only 参数还配有_wo_version轮换计数器详见 terraform-provider-onyx/README.md 的 Keeping secrets out of state 一节。连接器onyx_connectorresource 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 }) }onyx_connector声明索引什么、多久索引一次见 docs/resources/connector.md。一个连接器本身不索引任何东西——必须与凭据配对后才开始索引。关键字段input_type连接器的读取方式可选load_state、poll、event、slim_retrievalrefresh_freq两次索引运行之间的秒数未设置表示只索引一次、不刷新示例用24 * 60 * 6086400 秒实现每日重新索引prune_freq修剪运行的间隔秒数。注意 Onyx 会在首次更新时把未设置值重写为默认 6048007 天Terraform 随后会保持该值connector_specific_config源相关的 JSON 配置。web 源在此接收base_url与web_connector_typerecursive表示递归抓取整站indexing_start最早要索引的文档时间戳RFC 3339 格式Onyx 在更新时忽略它因此修改它会替换连接器。访问控制不在这里设置Onyx 在凭据关联时才应用访问控制因此access_type与groups属于连接器-凭据配对onyx_cc_pair。索引执行者onyx_cc_pairresource onyx_cc_pair docs { name docs-site connector_id onyx_connector.docs.id credential_id onyx_credential.web.id access_type public }onyx_cc_pair是真正执行索引的对象见 docs/resources/cc_pair.md它把onyx_connector与onyx_credential绑定在一起并承载其产出的文档的访问控制。创建配对即启动索引销毁配对也会连带移除已索引文档后台异步执行Terraform 会等待其完成可通过timeouts块调大删除超时如delete 2h。access_type决定谁可读已索引文档public所有人、private配合groups限制到特定用户组、sync从源系统镜像权限需要 Business 版 License 且源支持权限同步。此外还有paused暂停索引但保留已有文档、auto_sync_options权限同步设置仅sync模式有意义、processing_mode默认REGULAR全量索引流水线RAW_BINARY只存文件不抽取文本FILE_SYSTEM已废弃。文档集onyx_document_setresource onyx_document_set docs { name docs description Public product documentation cc_pair_ids [onyx_cc_pair.docs.id] }onyx_document_set把一组连接器-凭据配对命名分组使用户与 Agent 可以把它作为一个整体检索见 docs/resources/document_set.md。Onyx 会在后台把变更传播到搜索引擎只读属性is_up_to_date反映传播是否完成——通常在 apply 后短暂读为false。示例把上一步的docs配对收进名为docs的文档集。Agentonyx_agentresource 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? }, ] }onyx_agent定义 Agent助手一组命名的指令、知识与动作用户可与它对话见 docs/resources/agent.md。document_set_ids把上一步的文档集挂给 Agent使它只能基于该文档集回答starter_messages为会话提供开场白还可选task_prompt追加到每条用户消息后的指令、tool_ids关联自定义工具、is_listed、is_featured、display_priority、icon_name、search_start_date等。值得注意的 Agent 语义Agent 名称全局唯一删除 Agent 会留下墓碑记录行被标记删除而并非移除名称仍被占用之后用同一名称创建会复活原 Agent 并保留原 ID。用户组onyx_user_group仅企业版resource onyx_user_group platform { count var.enable_enterprise_features ? 1 : 0 name Platform # 权限使用 Onyx 自身的令牌而不是枚举名。 permissions [ manage:connectors, manage:document_sets, ] }onyx_user_group管理用户组的成员、管理员与权限授予仅企业版可用——社区版上这些路由不存在任何调用都返回 404见 docs/resources/user_group.md。示例用count条件创建enable_enterprise_features默认false因此在社区版上该资源保持 0 实例、完全不生效。一个重要的权限模型认知Onyx 中权限只来自用户组授权所以该资源是一个人获得任何权限的途径但用户组能看到什么不在此处设置——连接器、文档集、Agent、LLM Provider、MCP 服务器与凭据各自携带自己的groups属性并拥有这条边的所有权onyx_user_group只读回这些关联而从不写回从而避免两侧互相冲突。permissions字段使用 Onyx 的线上令牌如manage:connectors、manage:document_sets、read:query_history而非枚举名basic、admin、craft_sandbox、manage:skills等由 Onyx 托管不可设置。输出outputs.tf 定义了两个输出方便 apply 后直接获取资源 IDoutput agent_id { description Id of the documentation agent. value onyx_agent.docs.id } output cc_pair_id { description Id of the indexing connector-credential pair. value onyx_cc_pair.docs.id }索引时序为什么 Agent 不会立即回答问题索引在terraform apply之后才开始且在后台异步运行因此 Agent 只有在第一次索引运行完成之后才能基于该站点回答问题。期间可以在管理后台的Connectors页面观察索引进度。从 Provider 的客户端实现internal/client/client.go与资源文档可以印证这一异步模型onyx_cc_pair的创建即触发索引而文档集的is_up_to_date属性反映的是后台传播是否完成。换句话说terraform apply成功只代表配置已声明并下发不代表知识已就绪——这是把 IaC 用于 AI 平台时一个需要习惯的时序概念。清理terraform destroyterraform destroy销毁配对时Onyx 会在后台一并移除它索引过的文档Terraform 会等待该流程完成。onyx_settings是唯一例外销毁它只是停止管理设置不会重置已写入的线上设置。安全与运维要点总结API Key 必须属于 Admin 组Key 的权限来自其所属组无组 Key 会被所有管理路由拒绝种子Admin组默认隐藏列组时需include_defaulttrue。凭据绝不提供默认值mint_api_key.sh要求显式传入管理员邮箱与密码防止在空部署上悄悄创建已知密码的管理员。terraform.tfvars不进版本库它包含机密示例的模板刻意把密钥位留空注释让环境变量ONYX_API_KEY、TF_VAR_openai_api_key优先。优先使用 write-only 参数api_key_wo、credential_json_wo、custom_config_wo等需 Terraform 1.11保证机密永不落入 state 文件配合_wo_version计数器完成轮换。理解记录全集语义model_configurations是全量替换删除默认模型会失败onyx_llm_provider_default通过引用provider_id帮助 Terraform 正确排序销毁顺序。异步索引时序apply 后索引在后台运行Agent 就绪需要等待首次索引完成销毁配对同样在后台删除文档。对于希望把 Onyx 应用配置纳入 GitOps/CI 流程的团队而言这套 bootstrap 示例是一个可以直接作为起点的参考实现一条terraform apply命令即可完成从 LLM Provider 到可回答问题 Agent 的全链路交付。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考