rbac-catalog

# Azure RBAC 内置角色定义目录 [](https://github.com/atomassi/rbac-catalog/actions/workflows/build.yml) [](https://github.com/atomassi/rbac-catalog/actions/workflows/deploy.yml) [](https://github.com/atomassi/rbac-catalog/actions/workflows/github-code-scanning/codeql) [](https://codecov.io/gh/atomassi/rbac-catalog) [](https://www.python.org/downloads/) [](https://github.com/atomassi/rbac-catalog/releases/latest) [](LICENSE) > [!IMPORTANT] > **公共网站 [rbac-catalog.dev](https://rbac-catalog.dev/) 将于 2026 年 6 月 12 日停止服务。** > > 完整的源代码（应用程序代码、Bicep 模板和部署后脚本）保留在此仓库中，遵循 MIT 许可证。您有两种方法继续使用它： > > - **本地运行** — 参见 [`docs/run-local.md`](docs/run-local.md)。 > - **在 Azure 上部署您自己的副本** — 参见 [`infra/README.md`](infra/README.md) 中的逐步指南。 --- **实时网站：** [rbac-catalog.dev](https://rbac-catalog.dev/) 一个用于 [Azure 内置 RBAC 角色](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles) 的综合目录和监控工具。浏览角色，探索其权限，跟踪随时间的变化，根据操作需求查找最少权限角色，并获取 AI 驱动的角色建议。 [](https://rbac-catalog.dev/) ## 目录 - [功能](#features) - [快速入门](#quick-start) - [文档](#documentation) - [技术栈](#tech-stack) - [基础设施和成本](#infrastructure--costs) - [AI 推荐模式](#ai-recommendation-modes) - [MCP 服务器集成](#mcp-server-integration) - [测试](#testing) - [部署](#deployment) - [项目结构](#project-structure) - [参考](#references) ## 功能 - **角色目录** — 浏览所有 800 多个 Azure 内置角色，包含完整的权限详细信息 - **操作资源管理器** — 搜索 20,000 多个资源提供程序操作，查看哪些角色授予每个操作 - **最少权限计算器** — 输入所需操作，获取按多余权限排序的角色 - **反向查找** — "哪些角色授予此操作？"瞬间回答 - **变更跟踪** — 每天扫描检测 Microsoft 添加、修改或弃用角色时 - **差异查看器** — 精确查看角色版本之间的变化 - **相关角色** — 查看按权限重叠排序的相似角色，带有子集/超集指示器 - **角色比较** — 并排比较任意两个角色 - **分析** — 可视化权限分布、角色随时间变化和提供程序统计数据 - **AI 角色推荐器** — 用自然语言描述需求，获取最少权限建议（实验性） - **MCP 服务器** — 通过模型上下文协议与 AI 代理（Copilot、Claude）集成 - **RSS/Atom 源** — 在您喜欢的源阅读器中订阅角色变更 ## 快速入门 在几分钟内本地运行目录。您需要 **Python 3.12、3.13 或 3.14** 和 **Git**。 ```bash git clone https://github.com/atomassi/rbac-catalog.git cd rbac-catalog python3 -m venv .venv && source .venv/bin/activate pip install --upgrade pip && pip install -r requirements.txt ``` 目录启动时为空。要填充它，请运行 `az login` 一次，然后运行一次性扫描： ```bash # 填充所有内容（角色 + 操作），然后退出 python -m rbaccatalog.backgroundjobs.scan_once ``` 命令运行扫描一次并退出 — 没有后台工作线程保持运行。您可以随时重新运行它来刷新本地目录。（在生产环境中，目录通过始终在线的后台工作线程与 Web 应用程序一起保持最新。） 然后启动 Web 应用程序： ```bash # 使用轻量级推荐引擎快速启动 ENABLED_AI_ENGINES=tfidf uvicorn rbaccatalog.web.app:app --port 8000 --reload ``` 打开 <http://localhost:8000>。 更喜欢容器吗？构建并运行镜像： ```bash docker build -t rbaccatalog:local --build-arg VERSION=local-dev . docker run --rm -p 8000:8000 rbaccatalog:local ``` 有关先决条件、环境变量和完整指南，请参见 [`docs/run-local.md`](docs/run-local.md)。 ## 文档 | 指南 | 内容 | |-------|----------------| | [`docs/run-local.md`](docs/run-local.md) | 在本地使用原生 Python 或 Docker 运行应用程序 — 先决条件、环境变量和完整指南 | | [`infra/README.md`](infra/README.md) | 使用 Bicep 模板逐步部署您自己的副本到 Azure | | [`docs/ai-recommender.md`](docs/ai-recommender.md) | 7 种 AI 模式的工作原理，以及 LLM 微调管道（Unsloth + Qwen） | | [`docs/mcp.md`](docs/mcp.md) | MCP 服务器工具、示例查询、直接调用和速率限制 | ## 技术栈 | 层 | 技术 | |-------|-------------| | **后端** | Python 3.12+、FastAPI、SQLAlchemy、Pydantic | | **前端** | Jinja2 模板、Tailwind CSS、Alpine.js | | **数据库** | PostgreSQL | | **AI/ML** | PyTorch、Ollama、sentence-transformers、Qwen（微调） | | **托管** | Azure 应用服务、Cloudflare CDN | | **CI/CD** | GitHub Actions、Azure 容器注册表、Docker | | **测试** | pytest、Playwright | | **运维自动化** | Azure 自动化 | ## 基础设施和成本 架构优先考虑简单性而不是可扩展性：托管的 Azure 服务负责繁重的工作，Cloudflare 的免费层提供前端，并由单个 PostgreSQL 实例支持。没有 Kubernetes，没有自动缩放，也没有多区域故障转移 — 只需要一个低流量公共目录实际需要的组件。 自托管的 LLM 推理在两个 **可选** 的虚拟机上运行，目录在没有它们的情况下运行良好。它们存在是因为该项目的一个目标是从头到尾使用自托管的 LLM 进行实验：使用 Unsloth 进行微调，通过 Ollama 提供结果。 ### 架构 ```mermaid flowchart TD subgraph Clients[" "] direction LR USER((👥 用户)):::user AI((🤖 代理)):::ai end GH[GitHub Actions]:::github CDN[Cloudflare]:::cdn subgraph AZ ["<span style='font-size:22px;font-weight:bold'>Azure</span>"] direction TB CR[(容器<br/>注册表)]:::azure AS[应用服务]:::appsvc subgraph DATA [" "] direction LR PG[(PostgreSQL)]:::db INSIGHTS[应用洞察]:::monitor end subgraph OPT ["<span style='font-weight:bold'>可选 — 自托管 LLM</span>"] direction LR GPU[GPU 虚拟机<br/>NVIDIA A10]:::gpu OL[Ollama 虚拟机<br/>B2ms]:::ollama end end %% 传入流量 USER -->|Web 流量| CDN AI -->|MCP 流量| CDN CDN -->|代理流量| AS %% CI/CD 管道 GH -->|推送 Docker 镜像| CR CR -->|被| AS 拉取 %% 应用程序依赖项 AS <-->|查询和摄取| PG AS -->|发送遥测数据| INSIGHTS AS <-->|LLM 推理| OL GPU -->|导出模型| OL classDef user fill:#F5B82E,color:#000,stroke:#C98A00,stroke-width:2px classDef ai fill:#10B981,color:#fff,stroke:#059669,stroke-width:2px classDef github fill:#24292e,color:#fff,stroke:#1a1e22,stroke-width:2px classDef cdn fill:#F6821F,color:#fff,stroke:#d4700f,stroke-width:2px classDef azure fill:#0078D4,color:#fff,stroke:#005a9e,stroke-width:2px classDef appsvc fill:#4F46E5,color:#fff,stroke:#3730A3,stroke-width:2px classDef db fill:#C2410C,color:#fff,stroke:#7C2D0A,stroke-width:2px classDef ollama fill:#7C3AED,color:#fff,stroke:#5B21B6,stroke-width:2px classDef gpu fill:#76B900,color:#fff,stroke:#5a8c00,stroke-width:2px classDef monitor fill:#B5179E,color:#fff,stroke:#86116F,stroke-width:2px style AZ fill:#EEF4FA,stroke:#0078D4,stroke-width:2px,rx:10 style DATA fill:none,stroke:none style OPT fill:#F3EEFB,stroke:#7C3AED,stroke-width:1.5px,stroke-dasharray:6 4,rx:10 style Clients fill:none,stroke:none ``` ### 当前成本 > [!TIP] > 目录在 **核心** 服务上运行舒适，费用约为 **~65 美元/月**。 **可选** 的自托管推理虚拟机大致使账单翻倍；跳过它们，依赖本地 LLM 的 AI 功能不可用，而目录的其他部分按原样工作。 **核心服务** — 运行目录所需： | 服务 | $/月 | 备注 | |---------|--------:|-------| | Cloudflare | $0 | 免费计划 — 通过全球 CDN 缓存、TLS 终止、DDoS 保护、自定义安全规则、速率限制和 OpenAPI 架构验证在边缘提供前端。 | | 应用服务 | ~$45 | P0v3 Linux，单个实例。支持部署槽的最便宜 SKU。 | | PostgreSQL | ~$13 | 灵活服务器，B1ms（可突发，1 vCPU / 2 GiB）。 | | 容器注册表 | ~$5 | 基础 SKU。 | | 应用洞察 + 日志分析 | ~$2 | 按 GB 收费，30 天保留。 | | 自动化账户 | $0 | 基础 SKU，在 500 分钟/月的免费层内。 | | **小计** | **~$65** | | **可选服务** — 自托管 LLM 推理和微调： | 服务 | $/月 | 备注 | |---------|--------:|-------| | Ollama 虚拟机（推理） | ~$50 | B2ms（2 vCPU，8 GiB），始终在线。运行微调的 Qwen 0.5B 模型。 | | GPU 虚拟机（训练/微调） | 按需（~$1/小时） | NV12ads A10 v5（1× NVIDIA A10）。仅在微调运行期间启动。 | | **小计** | **~$50** | | **总计：~115 美元/月** 基线（核心 + 始终在线的 Ollama 虚拟机）。GPU 虚拟机被排除 — 仅在微调运行时按 ~1 美元/小时计费，因此在 GPU 小时上添加大约该费用。 ## AI 推荐模式 > [!NOTE] > AI 模式是实验性的，构建为不同推荐方法的试验台，并用于学习 LLM 微调（Unsloth + Qwen，通过 Ollama 提供）。结果应经过验证。通过“显示 AI 工具”切换按钮在“推荐”页面上访问它们。 AI 角色推荐器支持 **7 种不同模式**，每种模式具有不同的速度/精度权衡： | 模式 | 描述 | 需要 | |------|-------------|----------| | **TF-IDF** | 增强的 TF-IDF + BM25 关键词匹配 | 仅限 CPU | | **语义** | 纯句子嵌入相似性 | 嵌入 | | **交叉编码器** | 双编码器检索 + 神经重新排序 | 嵌入 | | **LLM** | 微调 Qwen 模型直接推理 | Ollama | | **RAG** | 带有 LLM 重新排序的检索增强生成 | 嵌入 + Ollama | | **HyDE** | 假设文档生成 + 语义搜索 | 嵌入 + Ollama | | **混合** | 多阶段：TF-IDF → 嵌入 → LLM 管道 | 所有组件 | 有关 LLM 微调方法和底层知识库（`document_text`）的构建，请参见 [docs/ai-recommender.md](docs/ai-recommender.md)。 ## MCP 服务器集成 Azure RBAC 目录在 `https://rbac-catalog.dev/mcp/` 处公开一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，供 GitHub Copilot、Claude 和 Cursor 等 AI 助手使用。通过在 `.vscode/mcp.json` 中添加以下内容将其添加到 VS Code： ```json { "servers": { "azure-rbac-catalog": { "type": "http", "url": "https://rbac-catalog.dev/mcp/" } } } ``` 然后询问您的助手类似的问题： *"查找用于读取 Key Vault 机密的最少权限角色"*。 有关完整的工具参考、示例查询、直接调用和速率限制详细信息，请参见 [docs/mcp.md](docs/mcp.md)。 ## 测试 ```bash # 单元测试（Python 3.12、3.13 或 3.14） pytest tests/ -q --cov=rbaccatalog # 端到端测试 npm ci npx playwright install chromium npm run test:e2e # 烟雾测试（生产前验证） pip install httpx python scripts/smoke_tests.py --url https://your-staging-url.azurewebsites.net ``` ## 部署 ### CI 管道 到实时网站的部署使用 **先上 staging** 的方法，并自动促进： ```mermaid flowchart LR A[手动触发 main] --> B[构建 Docker 镜像] B --> C[推送到 ACR] C --> D[部署到 staging 插槽] D --> E[运行烟雾测试] E -->|通过| F[交换到生产] E -->|失败| G[中止部署] ``` 1. **构建** — GitHub Actions 构建一个版本化的 Docker 镜像 2. **推送到 ACR** — 镜像被推送到 Azure 容器注册表 3. **部署到 Staging** — 镜像部署到应用服务 Staging 插槽 4. **烟雾测试** — 自动化测试验证页面、API 和 AI 推荐器端点 5. **插槽交换** — 如果所有测试通过，则 Staging 交换到生产 这确保每次生产部署在用户看到之前都经过验证。 > 有关更多详细信息，请参阅 [Azure 应用服务 Staging 插槽](https://learn.microsoft.com/en-us/azure/app-service/deploy-staging-slots)。 ## 项目结构 ``` rbaccatalog/ ├── airecommender/ # AI 推荐引擎（7 种模式） ├── analytics/ # 权限分布、随时间变化和提供程序统计数据 ├── azure/ # Azure SDK 集成（角色、操作） ├── backgroundjobs/ # 调度任务和后台工作线程 ├── cache/ # 角色和操作的缓存层 ├── comparer/ # 角色比较逻辑（三向权限差异） ├── core/ # 数据库模型和实用程序 ├── matching/ # 操作到角色匹配，用于最少权限角色组成 ├── mcp/ # MCP 服务器，用于 AI 助手集成 ├── telemetry/ # 应用洞察集成 └── web/ # FastAPI 应用程序、路由、模板 infra/ # Bicep IaC + 脚本，用于部署您自己的副本到 Azure scripts/ # 部署和烟雾测试脚本 tests/ # 单元测试 e2e/ # Playwright 端到端测试 ``` ## 参考 - **TF-IDF/BM25**：Robertson & Zaragoza，[概率相关性框架：BM25 及以后](https://www.staff.city.ac.uk/~sbrp622/papers/foundations_bm25_review.pdf)（2009） - **Sentence-BERT**：Reimers & Gurevych，[使用 Siamese BERT-Networks 的句子嵌入](https://arxiv.org/abs/1908.10084)（2019） - **Cross-Encoder**：Humeau et al.，[多编码器架构和预训练策略](https://arxiv.org/abs/1905.01969)（2019） - **Qwen**：Bai et al.，[Qwen 技术报告](https://arxiv.org/abs/2309.16609)（2023） - **RAG**：Lewis et al.，[知识密集型 NLP 任务的检索增强生成](https://arxiv.org/abs/2005.11401)（2020） - **HyDE**：Gao et al.，[没有相关性标签的精确零射密度检索](https://arxiv.org/abs/2212.10496)（2022）