Terraform Rag

⬡

Terraform RAG

为 Terraform 模块打造的 AI 知识库。
在一个地方完成索引、搜索、组合和审计。

在线演示 - 架构 - 快速开始 - MCP 服务

---

试用在线演示

Web 界面 - 浏览 175+ 个仓库中的 2700+ 个模块（AWS / Azure / GCP）：

https://terraform-rag.io

登录：[email protected] / demo（只读）

MCP - 将 IDE 连接到知识库：

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "https://terraform-rag.io/mcp",
      "headers": {
        "Authorization": "Bearer trag_6c495d7a027369cb5d324d877626c272"
      }
    }
  }
}

提供 9 个工具：query_modules、pick_modules、list_modules、 get_module_details、get_dependencies、get_module_usage、 find_similar_usages、fetch_example_code、get_stats（list_modules 还接受 semantic_query，用于自然语言搜索）。

---

功能介绍

指定 Terraform 模块仓库后，它会克隆这些仓库，解析每个 HCL 文件，生成嵌入，并在 PostgreSQL + pgvector 中构建可搜索的知识库。随后，它会学习这些模块在使用方仓库中的实际用法——命名模式、变量惯例、标记策略、部署布局——并将其提炼为权威指南。

智能体工作流会通过多个工具调用轮次探索知识库，使用 Claude、Bedrock 或任何兼容 OpenAI 的模型，整理出有依据、可供审核的答案——这是人在回路中的辅助检索，而不是自主代码生成器。你可以通过 Web 界面、REST API，或直接在 IDE 中通过 MCP 查询。

实际效果

模块浏览器 - 175+ 个仓库中的 2700+ 个模块	智能体组合 - 实时查看工具调用和推理过程
生成的 HCL - 带语法高亮的输出	知识浏览器 - 惯例和使用模式
索引任务 - 仓库索引仪表板	审计日志 - LLM、MCP 和 API 调用的完整记录

## 功能特性

Agentic 查询管道——不止是单次 RAG 检索。LLM 会浏览模块、核查细节、阅读规范，并在多个工具调用回合中获取示例代码，然后生成答案供你审核。提供四种查询模式：编写、搜索、优化和审计。

知识层——索引使用方代码仓库，学习真实世界的使用模式。提炼六个维度的规范（命名、变量、标记、布局、版本、部署），并将其作为所有提示词中的权威指导。

MCP 服务——Streamable HTTP 端点可与 Claude Code、Cursor、Windsurf 及任何兼容 MCP 的客户端配合使用。可直接从 IDE 查询模块知识库。

依赖关系图——使用 PostgreSQL 递归 CTE 映射模块之间的完整依赖树。查找依赖关系、追踪影响，并通过 D3 力导向图可视化关系。

版本跟踪——自动发现 git 标签，并跟踪各模块的版本历史。代码哈希缓存可在重新索引时避免重复调用 LLM/嵌入模型。

灵活的 LLM 后端——支持 Anthropic（直接调用或 Bedrock）、OpenRouter、Ollama，或任何兼容 OpenAI 的端点。无需更改代码即可切换模型。

CI/CD 集成——提供 GitHub Actions 工作流和 webhook 端点，以便在 .tf 文件变更时自动重新索引。

身份验证——可禁用（默认），也可使用本地邮箱/密码和 JWT，或通过 AWS Identity Center / OIDC 使用由 ALB 终止的 SSO。

快速开始

# 1. Clone and configure
git clone https://github.com/krzysztofgawrys/rag-for-terraform.git
cd rag-for-terraform
cp .env.example .env
# Edit .env - set POSTGRES_PASSWORD, JWT_SECRET, and your LLM API key

# 2. Start everything
docker compose up -d

# 3. Index your first repo
curl -X POST http://localhost:8000/index/ \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "[email protected]:org/tf-modules.git", "branch": "main"}'

服务	URL
前端	http://localhost:3000
API 文档	http://localhost:8000/docs
MCP 端点	http://localhost:8000/mcp/

对于私有代码仓库，请将 SSH 部署密钥放在 ./worker_deploy_key （或在 .env 中设置 SSH_KEY_PATH）。

MCP 服务

将任何兼容 MCP 的客户端连接到 http://localhost:8000/mcp/。

Claude Code（.mcp.json）：

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

可用工具：query_modules、pick_modules、list_modules、 get_module_details、get_dependencies、get_module_usage、 find_similar_usages、fetch_example_code、get_stats。

LLM 配置

模式	LLM_BASE_URL	LLM_MODEL 示例
Anthropic（直接调用）	(empty)	claude-sonnet-4-6
AWS Bedrock	（设置 AWS_BEDROCK_REGION）	us.anthropic.claude-sonnet-4-6-20250514-v1:0
OpenRouter	https://openrouter.ai/api/v1	anthropic/claude-sonnet-4-6
Ollama（本地）	http://ollama:11434/v1	qwen2.5-coder:32b

索引期间可使用单独的低成本模型来生成模块描述 （DESCRIPTION_LLM_* 变量）。

架构

  Browser         AI Agent / IDE
     |               |
+---------+      +--------+      +----------------+
| Frontend|----->|  API   |----->| PostgreSQL 16  |
| (Vite)  |      | FastAPI|      | + pgvector     |
+---------+      +---+----+      +----------------+
                     |
                +----+----+
                | Worker  |      +-------+
                | (Celery)|----->| Redis |
                +---------+      +-------+

有关完整的技术深入介绍——技术栈详情、目录结构、API 端点、 Agent 内部机制、知识层管道、已知限制和部署说明——请参阅 docs/ARCHITECTURE.md。

许可证

Business Source License 1.1——详情请参阅 LICENSE。

• 允许非生产用途（评估、测试、开发）
• 生产用途需获得作者的商业许可证
• 许可证将于 2029-05-25 转换为 AGPL-3.0