NimanthaSupun/WithOps
GitHub: NimanthaSupun/WithOps
一款企业级 AI 驱动的 DevSecOps 平台，整合威胁建模、CI/CD 治理审计和代码安全分析，帮助团队在 GitHub 组织中实现安全左移与持续合规。
Stars: 0 | Forks: 0
# WithOps DevSecOps 平台
**代码之后的一切** — 为现代开发团队提供的智能 AI 驱动的安全自动化。
WithOps 是一个企业级 DevSecOps 平台，可跨 GitHub 组织自动化安全分析、威胁建模、CI/CD 治理和工作区智能。基于生产就绪的架构、全面的监控和事件驱动的微服务构建。
## 目录
- [概述](#overview)
- [架构](#architecture)
- [技术栈](#technology-stack)
- [核心功能](#key-features)
- [前置条件](#prerequisites)
- [快速开始](#quick-start)
- [部署](#deployment)
- [本地开发](#local-development)
- [Docker Compose (生产环境)](#docker-compose-production)
- [Kubernetes](#kubernetes)
- [配置](#configuration)
- [微服务](#microservices)
- [监控与可观测性](#monitoring--observability)
- [开发](#development)
- [贡献](#contributing)
## 概述
WithOps 为 DevOps 和安全团队提供跨其 GitHub 组织的可行情报。该平台将 AI 驱动的分析、自动化威胁建模、CI/CD 治理审计和实时协作功能集成到一个统一的仪表板中。
### 目标用户
- **DevOps 工程师** — 自动化安全合规和 CI/CD 治理
- **架构工程师** — 评估 DevSecOps 成熟度并确定需要改进的领域
- **安全团队** — 检测威胁、漏洞和错误配置
- **开发负责人** — 确保代码质量和安全最佳实践
### 核心能力
- **威胁建模画布** — AI 驱动的 DFD 分析，支持 STRIDE/LINDDUN/CIA 威胁检测
- **工作区智能** — OWASP DSOMM 成熟度框架评估 (L0-L4)
- **Action 审计** — GitHub Actions 治理与自动升级 PR
- **AI 驱动的代码分析** — 漏洞检测和安全建议
- **实时监控** — 基于 WebSocket 的事件源，带有即时通知
- **协作会话** — 基于 Liveblocks 的多用户威胁建模
## 架构
WithOps 采用分布式微服务架构，具有事件驱动通信、集中式 API 网关路由和全面的可观测性。
### 系统架构
```
┌────────────────────────────────────────────────────────────────┐
│ Clients (Frontend) │
│ SvelteKit + Auth0 (5173) │
└──────────────────────────────────────────────────────────────┬─┘
│
┌─────────────────────────────┐
│ Kong API Gateway (9000) │
│ • Route requests │
│ • CORS handling │
│ • Rate limiting │
└──────────────┬──────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
┌────▼────────┐ ┌────────▼────────┐ ┌─────────▼────────┐
│ Microservices│ │ Events Hub │ │ External Services │
│ (8 total) │ │ (WebSocket) │ │ │
│ │◄───────────┤ • Event Bus │ │ • GitHub API │
│ • AI Service │ Events │ • Broadcasts │ │ • Auth0 JWT │
│ • GitHub Svc │ │ • Broadcasting │ │ • Claude/Ollama │
│ • Threat Mdl │ │ │ │ • Groq/GPT-4 │
│ • Workspace │ └─────────────────┘ └──────────────────┘
│ • Collab │ ▲
│ • Workflow │ │
│ • RAG │ ┌────────┴────────┐
│ • Pipeline │ │ Redis Pub/Sub │
└──────────────┘ │ (Event Channel) │
│ └──────────────────┘
│
┌────┴────────────────────────────────────┐
│ │
┌───▼──────┐ ┌────────────┐ ┌──▼─────────┐
│ PostgreSQL│ │ Redis Cache│ │ Qdrant VDB │
│(Supabase) │ │ (16379) │ │ (Embeddings)
│ • Users │ │ │ │ │
│ • Orgs │ │ • Sessions │ │ • Knowledge│
│ • Models │ │ • Workflows│ │ • Vectors │
│ • Scans │ │ • Settings │ └────────────┘
└───────────┘ └────────────┘
┌───────────────────────────────────────────────┐
│ Monitoring & Observability Stack │
│ • Prometheus (metrics) • Grafana (dashboards) │
│ • Jaeger (tracing) • OpenTelemetry │
└───────────────────────────────────────────────┘
```
### 通信流
1. **REST API 调用** — 前端 → Kong 网关 → 微服务
2. **异步事件** — 微服务 → Redis 发布/订阅 → 事件中心 → WebSocket → 前端
3. **数据库** — 所有服务使用共享的 PostgreSQL (Supabase) 进行持久化
4. **缓存** — Redis 层用于性能优化和速率限制
5. **监控** — OpenTelemetry/Prometheus 指标发送到 Grafana，链路追踪发送到 Jaeger
## 技术栈
### 前端
| 组件 | 技术 |
| ------------ | ------------------- |
| 框架 | SvelteKit (Vite) |
| 样式 | Tailwind CSS |
| 可视化 | Three.js, D3.js |
| 实时协作 | Liveblocks |
| 认证 | Auth0 (JWT) |
| 测试 | Vitest + Playwright |
| Node 版本 | 20.x LTS |
**Package.json 依赖：**
- `@auth0/auth0-spa-js` — Auth0 集成
- `@liveblocks/react` — 协作功能
- `d3`, `three` — 数据可视化
- `svelte`, `vite` — 构建工具
### 后端与微服务
| 组件 | 技术 |
| -------- | ------------------------------------------ |
| 框架 | FastAPI (Python 3.11+) |
| Web 服务器 | Uvicorn (async ASGI) |
| 异步 | asyncio, asyncpg, aiohttp |
| 数据库 | PostgreSQL (via Supabase) |
| ORM | SQLAlchemy 2.0 |
| 缓存 | Redis (async) |
| AI 模型 | Claude 3 Opus, GPT-4, Groq Llama 3, Ollama |
| 向量数据库 | Qdrant (embeddings/RAG) |
| 监控 | Prometheus, OpenTelemetry |
| 任务队列 | 后台工作器 |
**主要依赖：**
- `fastapi==0.104.1`, `uvicorn[standard]`
- `sqlalchemy==2.0.23`, `asyncpg==0.29.0`
- `redis[asyncio]==5.0.1`
- `httpx[http2]==0.25.0` — GitHub API 调用
- `python-jose[cryptography]` — JWT 验证
- `opentelemetry-*` — 分布式链路追踪
- `prometheus-client` — 指标导出
### 基础设施
| 组件 | 角色 |
| ---------- | ------------------------------------- |
| Kong | API 网关，路由，CORS |
| Redis | 缓存，发布/订阅事件总线 (端口 16379) |
| PostgreSQL | 数据持久化 (Supabase 托管) |
| Ollama | 本地 LLM 推理 (端口 11434) |
| Qdrant | 向量数据库 (端口 6333-6334) |
| Prometheus | 指标收集 (端口 9091) |
| Grafana | 指标仪表板 (端口 3001) |
| Jaeger | 分布式链路追踪 (端口 16686) |
| Docker | 容器化 |
| Kubernetes | 编排 (生产环境) |
### DevOps 与 CI/CD
| 工具 | 用途 |
| ------------------------- | ---------------------------------- |
| Docker | 所有服务的容器镜像 |
| Docker Compose | 本地开发编排 |
| Kubernetes | 生产环境编排 (1.24+) |
| GitHub Actions | CI/CD 流水线 (测试、构建、扫描) |
| GitHub Container Registry | Docker 镜像仓库 |
| Gitleaks | CI 中的密钥扫描 |
| Ruff | Python 代码检查 (所有服务) |
| Prometheus | 指标抓取 |
| OpenTelemetry | 遥测标准 |
| OTLP | 将链路追踪导出至 Jaeger |
## 核心功能
### 1. 威胁建模画布
实时协作设计数据流图 (DFD) 并结合 AI 驱动的威胁分析。
- **可视化设计** — 绘制 DFD 组件（过程、数据存储、外部实体、信任边界）
- **AI 分析** — 使用 STRIDE、LINDDUN 或 CIA 框架进行自动威胁检测
- **实时协作** — 多用户在同一模型上带光标跟踪进行协作
- **导出** — 将威胁模型保存为 JSON 或图表
- **审计追踪** — 用于合规性的会话记录
**端点：** `POST /api/threat-modeling/models`
### 2. 工作区智能仪表板
使用 OWASP DSOMM 框架评估整个组织的 DevSecOps 成熟度。
- **成熟度评分** — 5 个维度（构建、实现、测试、信息收集、文化）的 0-100 分制
- **工具检测** — 识别 CodeQL、SonarQube、Dependabot、Gitleaks、SAST/DAST 工具
- **实践评估** — 检测安全实践（密钥扫描、依赖检查、SAST）
- **AI 聊天** — 询问分数为何偏低并获取改进建议
- **基准测试** — 与行业标准进行比较
**端点：** `POST /api/workspace-intelligence/analyze`
### 3. Action 审计 (GitHub Actions 治理)
审计跨仓库的所有 GitHub Actions 并自动升级过时的版本。
- **抓取工作流** — 扫描组织范围内的 `.github/workflows/*.yml` 文件
- **版本跟踪** — 列出所有带有版本的 actions（例如，`actions/checkout@v2.4.1`）
- **状态分类** — 最新、过时、建议升级、需要重大升级
- **通过 PR 自动修复** — 生成 PR 以将 actions 升级到最新版本
- **审计报告** — 跟踪哪些 actions 需要关注
**端点：** `GET /api/workflows/analyze`, `POST /api/workflows/security/create-upgrade-prs`
### 4. AI 驱动的代码分析
分析仓库中的漏洞和安全配置错误。
- **漏洞检测** — 识别常见的 OWASP Top 10、密钥、不安全的依赖项
- **PR 描述生成** — 自动生成以安全为中心的 PR 描述
- **建议** — 基于代码模式的最佳实践
- **模型选择** — Claude 3 Opus、GPT-4、Groq Llama 3 或 Ollama
- **缓存** — 通过 Redis 进行性能优化
**端点：** `POST /api/ai/analyze`, `POST /api/ai/chat`
### 5. 实时监控
带有即时威胁、扫描和活动通知的实时事件源。
- **WebSocket 事件** — 推送式更新（非轮询）
- **事件类型** — `threat.analysis.completed`、`threat_detected`、`pr_created`、`scan_complete`
- **多用户** — 所有连接的客户端即时接收更新
- **活动流** — 按组织的活动跟踪
**端点：** `WebSocket /ws/events/{user_id}`
### 6. 协作威胁会话
多名团队成员同时处理威胁模型。
- **光标跟踪** — 实时查看其他用户的光标位置
- **形状编辑** — 带冲突解决机制的协作式 DFD 创建
- **评论** — 针对特定威胁的嵌套讨论
- **缓解措施** — 分配和跟踪缓解任务
- **历史记录** — 维护用于审计合规性的会话记录
**技术：** Liveblocks 实时协作
## 前置条件
### 系统要求
- **操作系统** — Windows 10+、macOS 10.15+ 或 Linux (Ubuntu 18.04+)
- **Docker** — 20.10+ (包含 Docker Compose 2.0+)
- **Kubernetes** — 1.24+ (用于生产环境部署)
- **内存** — 8GB 最小（推荐 16GB）
- **磁盘** — 20GB 可用空间
### 所需账户和凭证
1. **GitHub**
- GitHub App (或 OAuth 应用程序)
- 用于安装该应用的组织访问权限
- GitHub Container Registry (GHCR) 访问权限
2. **Auth0**
- Auth0 账户
- 已配置的 API 和 SPA 应用程序
- 域名、Client ID、Client Secret
3. **LLM 服务** (至少一项)
- **Anthropic** — Claude 3 API 密钥 (推荐)
- **OpenAI** — GPT-4 API 密钥 (可选)
- **Groq** — Groq API 密钥 (可选)
- **Ollama** — 本地推理 (包含在 docker-compose 中)
4. **云数据库** (生产环境推荐)
- **Supabase** — PostgreSQL + 认证服务
- 或者：自托管 PostgreSQL
### 环境配置
在部署之前创建 `.env` 文件：
```
# backend/.env (本地开发)
GITHUB_APP_ID=YOUR_GITHUB_APP_ID
GITHUB_APP_CLIENT_ID=YOUR_CLIENT_ID
GITHUB_APP_CLIENT_SECRET=YOUR_CLIENT_SECRET
GITHUB_PRIVATE_KEY_PATH=/app/config/keys/withops-devsecops-platform-local.2026-01-22.private-key.pem
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_API_AUDIENCE=https://api.withops.com
SUPABASE_URL=https://YOUR-PROJECT.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...
REDIS_URL=redis://localhost:16379
OLLAMA_URL=http://localhost:11434
QDRANT_URL=http://localhost:6333
FRONTEND_URL=http://localhost:5173
ENVIRONMENT=local
```
有关完整的配置详细信息，请参阅 `/doc/CONFIGURATION-STATUS.md` 和 `/k8s/SECRETS_MANAGEMENT.md`。
## 快速开始
### 选项 A: Docker Compose (推荐用于开发)
在大约 30 秒内启动所有本地服务栈：
```
# 克隆并导航至项目
cd d:\project\dev-testing\DevSecOps
# 启动所有服务 (Kong, Redis, Ollama, 通过 Supabase 的 PostgreSQL, 所有 microservices)
docker-compose up --build
# 前端访问地址: http://localhost:5173
# Kong Gateway 地址: http://localhost:9000
# Prometheus 地址: http://localhost:9091
# Grafana 地址: http://localhost:3001
# Jaeger 地址: http://localhost:16686
```
### 选项 B: 手动微服务 (带热重载的开发)
单独启动后端服务以加快迭代速度：
```
# 1. 启动 infrastructure 服务
docker-compose up -d kong redis ollama
# 2. 启动 Python backend (需要 Python 3.11+)
cd backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# 3. 启动 microservices (在独立的终端中)
cd services/ai-service
uvicorn main:app --host 0.0.0.0 --port 8001 --reload
cd services/github-service
uvicorn main:app --host 0.0.0.0 --port 8002 --reload
# 4. 启动 frontend (在另一个终端中)
cd frontend
npm install
npm run dev # Vite dev server with hot-reload
```
### 选项 C: Kubernetes (生产环境)
部署到 Kubernetes 集群：
```
# 1. 构建 production 镜像
.\k8s\BUILD-PRODUCTION-IMAGES.ps1
# 2. 创建 namespace 和 secrets
kubectl create namespace withops
kubectl create secret generic app-secrets -n withops \
--from-literal=SUPABASE_ANON_KEY='YOUR_KEY' \
--from-literal=ANTHROPIC_API_KEY='sk-ant-YOUR_KEY'
# 3. 部署 manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/
# 4. 验证部署
kubectl get pods -n withops
kubectl logs -n withops -f deployment/backend
# 5. 通过 port-forward 访问 (或配置 Ingress)
kubectl port-forward -n withops svc/kong 8000:8000
```
## 部署
### 本地开发
**文件：** `docker-compose.yml`
使用本地环境变量启动所有服务：
```
docker-compose up --build
docker-compose down -v # Clean up volumes
docker-compose logs -f # View logs
```
**环境：** 使用 `backend/.env` 和 `services/github-service/.env`
**端口：**
- 前端: 5173
- Kong 网关: 9000
- 微服务: 8001-8009
- Redis: 16379
- Ollama: 11434
- Qdrant: 6333, 6334
- Prometheus: 9091
- Grafana: 3001
- Jaeger: 16686
### Docker Compose (生产环境)
**文件：**带有 `--env-file` 标志的 `docker-compose.yml`
使用生产环境变量进行部署：
```
# 方法 1: 使用 .env.production (推荐)
docker-compose --env-file backend/.env.production up -d --build
# 方法 2: 临时复制 production 配置
Copy-Item backend\.env.production backend\.env -Force
docker-compose up -d --build
```
**环境：** 使用 `backend/.env.production` 和 `services/github-service/.env.production`
**与本地环境的主要区别：**
- 生产环境 Auth0 凭证
- 生产环境 GitHub App 配置
- 生产环境 Supabase 数据库
- 生产环境 URL (app.withops.com, api.withops.com)
- 启用 HTTPS (通过反向代理/负载均衡器)
### Kubernetes (生产级别)
**文件：** `k8s/*.yaml` 清单
具有适当扩展、健康检查和可观测性的 Kubernetes 部署。
#### 前置条件
```
kubectl cluster-info
kubectl get nodes
```
#### 部署步骤
```
# 1. 创建 namespace
kubectl create namespace withops
# 2. 创建 secrets (部署前的关键步骤)
kubectl create secret generic app-secrets -n withops \
--from-literal=SUPABASE_ANON_KEY='YOUR_KEY' \
--from-literal=SUPABASE_SERVICE_ROLE_KEY='YOUR_KEY' \
--from-literal=SUPABASE_DATABASE_URL='postgresql://...' \
--from-literal=ANTHROPIC_API_KEY='sk-ant-...' \
--from-literal=GITHUB_APP_ID='YOUR_ID' \
--from-literal=GITHUB_APP_CLIENT_SECRET='YOUR_SECRET'
# 3. 验证 secrets
kubectl get secrets -n withops
# 4. 部署服务
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/redis.yaml
kubectl apply -f k8s/kong-gateway.yaml
kubectl apply -f k8s/backend-events-hub.yaml
kubectl apply -f k8s/github-service.yaml
kubectl apply -f k8s/ai-service.yaml
# ... 部署其余服务
# 5. 验证部署
kubectl get pods -n withops
kubectl get svc -n withops
# 6. 检查日志
kubectl logs -n withops -f deployment/backend
# 7. 访问应用
# 为 app.withops.com 配置 DNS → 负载均衡器 IP
# 或使用 port-forward 进行测试:
kubectl port-forward -n withops svc/kong 8000:8000
```
#### Kubernetes 功能
- **Deployments** — 每个服务一个 Deployment，带有用于扩展的 replicaset
- **Services** — ClusterIP 用于服务间通信，NodePort/LoadBalancer 用于外部访问
- **ConfigMaps** — Kong 路由规则，Prometheus 抓取配置
- **Secrets** — 用于凭证的加密 secret 管理
- **RBAC** — 用于 pod 权限的基于角色的访问控制
- **Probes** — 用于健康监控的存活和就绪探针
- **资源限制** — 每个服务的 CPU 和内存请求/限制
- **StatefulSets** — Redis，PostgreSQL 持久化 (如果不使用托管服务)
**参见：** `/k8s/PRODUCTION-DEPLOYMENT.md` 和 `/k8s/SECRETS_MANAGEMENT.md` 以获取详细的 K8s 部署指南。
## 配置
### 环境变量
#### 核心配置
| 变量 | 用途 | 本地 | 生产环境 |
| --------------- | ---------------- | ---------------------- | ------------------------- |
| `ENVIRONMENT` | 部署环境 | `local` | `production` |
| `FRONTEND_URL` | 前端源 | `http://localhost:5173` | `https://app.withops.com` |
| `BACKEND_URL` | 后端 API | `http://localhost:8000` | `https://api.withops.com` |
| `CORS_ORIGINS` | 允许的 CORS 源 | `http://localhost:5173` | `https://app.withops.com` |
#### 数据库
| 变量 | 用途 |
| --------------------------- | -------------------------- |
| `SUPABASE_URL` | Supabase 项目 URL |
| `SUPABASE_ANON_KEY` | 公共匿名密钥 (前端) |
| `SUPABASE_SERVICE_ROLE_KEY` | 服务角色密钥 (后端) |
| `DATABASE_URL` | PostgreSQL 连接字符串 |
| `DATABASE_ENCRYPTION_KEY` | 字段级加密 (base64) |
#### GitHub 集成
| 变量 | 用途 |
| ---------------------------- | ------------------------------------- |
| `GITHUB_APP_ID` | GitHub App ID (来自应用设置) |
| `GITHUB_APP_CLIENT_ID` | GitHub App Client ID |
| `GITHUB_APP_CLIENT_SECRET` | GitHub App Client Secret (机密) |
| `GITHUB_PRIVATE_KEY_PATH` | 私钥 PEM 文件路径 |
| `GITHUB_OAUTH_CLIENT_ID` | OAuth 应用 Client ID (用于发现) |
| `GITHUB_OAUTH_CLIENT_SECRET` | OAuth 应用 Client Secret |
#### 身份验证 (Auth0)
| 变量 | 用途 |
| ------------------- | ----------------------------- |
| `AUTH0_DOMAIN` | Auth0 租户域名 |
| `AUTH0_API_AUDIENCE` | Auth0 API 标识符 |
| `AUTH0_CLIENT_ID` | Auth0 应用程序 Client ID |
| `AUTH0_CLIENT_SECRET` | Auth0 应用程序 Client Secret |
| `JWT_SECRET_KEY` | 备用 JWT 密钥 (可选) |
#### AI/LLM 服务
| 变量 | 用途 |
| ----------------- | --------------------------- |
| `ANTHROPIC_API_KEY` | Claude API 密钥 |
| `OPENAI_API_KEY` | OpenAI GPT-4 密钥 (可选) |
| `GROQ_API_KEY` | Groq Llama 3 密钥 (可选) |
| `OLLAMA_URL` | 本地 Ollama 端点 |
| `QDRANT_URL` | Qdrant 向量数据库 URL |
#### 基础设施
| 变量 | 用途 |
| ---------------- | ---------------------------------------------- |
| `REDIS_URL` | Redis 连接字符串 |
| `REDIS_PASSWORD` | Redis 认证密码 (如果启用) |
| `ENABLE_METRICS` | 启用 Prometheus 指标导出 |
| `ENABLE_TRACING` | 启用 OpenTelemetry 链路追踪 |
| `OTLP_ENDPOINT` | Jaeger OTLP HTTP 端点 |
| `LOG_LEVEL` | 日志详细程度 (DEBUG, INFO, WARNING, ERROR) |
### 文件位置
```
backend/
├── .env # Local dev configuration
├── .env.production # Production configuration
├── config/
│ └── keys/
│ ├── withops-devsecops-platform-local.2026-01-22.private-key.pem
│ └── withops-devsecops-platform-production.private-key.pem
services/github-service/
├── .env # Local dev
├── .env.production # Production
frontend/
├── .env # Vite environment
├── vite.config.js # Build configuration
└── src/lib/config.js # Runtime config utilities
infra/
├── kong/kong.yml # API Gateway routing
├── monitoring/
│ ├── prometheus.yml # Metrics scrape config
│ └── grafana/dashboards/ # Grafana dashboard definitions
└── ollama/
└── init-models.sh # Ollama model initialization
k8s/
├── namespace.yaml # Kubernetes namespace
├── redis.yaml # Redis deployment
├── kong-gateway.yaml # Kong deployment
├── backend-events-hub.yaml # Backend deployment
├── secrets.yaml # Secret template
└── *.yaml # Other microservice deployments
```
### 动态 URL 配置
平台支持基于环境的动态 URL：
**前端 Vite 构建：**
```
// Build-time variables (vite.config.js)
VITE_API_BASE_URL=http://localhost:8000
VITE_WS_BASE_URL=http://localhost:9100
VITE_AUTH0_DOMAIN=dev-sabxychpf6paj41u.us.auth0.com
VITE_AUTH0_CLIENT_ID=YOUR_CLIENT_ID
VITE_AUTH0_CALLBACK_URL=http://localhost:5173/callback
```
**后端运行时：**
```
# 运行时配置 (backend/core/config.py)
FRONTEND_URL = os.getenv('FRONTEND_URL', 'http://localhost:5173')
GITHUB_SERVICE_URL = os.getenv('GITHUB_SERVICE_URL', 'http://localhost:8002')
CORS_ORIGINS = os.getenv('CORS_ORIGINS', 'http://localhost:5173').split(',')
```
## 微服务
WithOps 由 9 个以上的独立微服务组成，每个微服务都有特定的领域职责：
### 1. 后端事件中心 (端口 8000)
**用途：** 中央 WebSocket 管理器和实时事件协调器
**主要功能：**
- WebSocket 连接管理
- Redis 发布/订阅订阅
- 向连接的客户端广播事件
- 用于多用户会话的基于频道的路由
**事件类型：**
- `threat.analysis.completed` — 威胁分析已完成
- `threat_detected` — 识别出新威胁
- `pr_created` — 自动创建 Pull Request
- `scan_complete` — 安全扫描已完成
- `github.refresh` — GitHub 数据已刷新
**端点：**
- `WebSocket /ws/events/{user_id}` — 实时事件流
- `GET /api/health` — 健康检查
**监控：** 端口 9100 上的 Prometheus
### 2. AI 服务 (端口 8001)
**用途：** AI 驱动的代码分析和安全建议
**主要功能：**
- 代码漏洞分析
- 安全最佳实践建议
- 集成 Claude 3 Opus、GPT-4、Groq Llama 3、Ollama
- 用于异步威胁分析的后台工作器
- 使用 Redis 进行响应缓存
**端点：**
- `POST /api/ai/analyze` — 分析代码的安全问题
- `POST /api/ai/chat` — 交互式 AI 助手
- `GET /api/ai/suggestions` — 安全建议
- `POST /api/ai/analyze-async` — 带有事件回调的异步分析
**技术：** FastAPI，httpx (异步 HTTP)，Redis 缓存
**监控：** 端口 9101 上的 Prometheus
**模型：**
```
# 模型选择优先级
1. Claude 3 Opus (via Anthropic API) — Primary
2. Groq Llama 3 (via Groq API) — Fallback
3. GPT-4 (via OpenAI API) — Alternative
4. Ollama (Local) — Offline capability
```
### 3. GitHub 服务 (端口 8002)
**用途：** 用于仓库管理和工作流自动化的 GitHub 集成
**主要功能：**
- GitHub App 和 OAuth 集成
- 组织和仓库发现
- 工作流文件解析和验证
- 带有智能缓存的仓库树管理
- GitHub Actions 版本跟踪和审计
- 自动创建用于 action 升级的 PR
**端点：**
- `GET /api/github/organizations` — 列出用户的组织
- `GET /api/github/repositories` — 仓库列表
- `GET /api/github/workspace/{org}` — 工作区分析
- `GET /api/github/workflows` — 工作流列表
- `POST /api/github/create-pr` — 创建用于升级的 PR
- `GET /api/github/actions-audit` — action 版本审计
**技术：** FastAPI，带有连接池的 httpx，GitHub App 认证
**缓存策略：** Redis，对于工作区/工作流数据有 1-2 小时的 TTL
**速率限制：** 通过 Redis 的令牌桶
**监控：** 端口 9102 上的 Prometheus
### 4. 威胁建模服务 (端口 8003)
**用途：** STRIDE/LINDDUN/CIA 安全威胁分析引擎
**主要功能：**
- 从 DFD 自动生成威胁
- STRIDE 方法论（默认）
- LINDDUN 方法论（侧重隐私）
- CIA 框架（机密性/完整性/可用性）
- OWASP Top 10 映射
- MITRE ATT&CK 框架集成
- 威胁严重性评分
**端点：**
- `POST /api/v1/models` — 创建威胁模型
- `GET /api/v1/models/{id}` — 获取模型
- `POST /api/v1/models/{id}/analyze` — 生成威胁
- `POST /api/v1/models/{id}/comprehensive-analysis` — 深度分析
- `GET /api/v1/models/{id}/threats` — 列出已识别的威胁
**技术：** FastAPI，威胁分析算法，知识库
**监控：** 端口 9103 上的 Prometheus
### 5. 工作区智能服务 (端口 8004)
**用途：** 组织范围的 DevSecOps 成熟度评估
**主要功能：**
- OWASP DSOMM 框架评估
- 5 个维度分析：构建、实现、测试、信息收集、文化
- 成熟度级别：L0-L4 (无 → 基础 → 高级 → 成熟 → 优化)
- 安全工具检测 (CodeQL、SonarQube、Dependabot、Gitleaks 等)
- AI 聊天用于获取见解和建议
- 实践检测：SAST、SCA、DAST、密钥扫描
- 与行业标准的基准对比
**端点：**
- `POST /api/workspace-intelligence/analyze` — 分析工作区
- `GET /api/workspace-intelligence/{org_id}/assessment` — 获取评估结果
- `POST /api/workspace-intelligence/{org_id}/chat` — AI 聊天获取见解
- `GET /api/workspace-intelligence/{org_id}/practices` — 列出已检测到的实践
**技术：** FastAPI，成熟度评估算法，知识库
**监控：** 端口 9104 上的 Prometheus
### 6. 协作服务 (端口 8105)
**用途：** 团队协作和工作区共享
**主要功能：**
- 组织成员管理
- 协作邀请和权限
- 活动跟踪
- 工作区共享和访问控制
- 协作者的实时通知
**端点：**
- `GET /api/collaboration/teams` — 列出团队
- `POST /api/collaboration/share` — 共享工作区
- `GET /api/collaboration/{org_id}/members` — 列出成员
- `POST /api/collaboration/invite` — 发送邀请
**技术：** FastAPI，PostgreSQL 关系
**监控：** 端口 9105 上的 Prometheus
### 7. 工作流编排服务 (端口 8007)
**用途：** CI/CD 工作流管理和安全扫描编排
**主要功能：**
- GitHub Actions 版本管理
- 工作流分析和审计
- 自动创建 action 升级 PR
- 安全扫描编排
- 工作流健康检查
**端点：**
- `GET /api/workflows/analyze` — 分析工作流
- `POST /api/workflows/scan` — 扫描问题
- `POST /api/workflows/security/create-upgrade-prs` — 创建升级 PR
- `GET /api/workflows/{org}/actions-audit` — action 版本审计
**技术：** FastAPI，GitHub API 集成
**监控：** 端口 9107 上的 Prometheus
### 8. AI RAG 服务 (端口 8008)
**用途：** 带有检索增强生成的对话式 AI
**主要功能：**
- 关于 DevSecOps 最佳实践的自然语言查询
- 基于知识库的上下文感知响应
- 自动文档索引和嵌入
- 带有记忆的多轮对话
- 来自 Qdrant 向量存储的知识库
**端点：**
- `POST /api/conversations/start` — 开始对话
- `POST /api/conversations/{id}/message` — 发送消息
- `GET /api/conversations/{id}` — 获取对话
- `POST /api/rag/index` — 索引文档
- `POST /api/rag/query` — 查询知识库
**技术：** FastAPI，Qdrant，Ollama embeddings，Redis会话管理
**监控：** 端口 9108 上的 Prometheus
### 9. 流水线预测服务 (端口 8009)
**用途：** 基于机器学习的 CI/CD 故障预测和异常检测
**主要功能：**
- 历史流水线数据分析
- 工作流的故障预测
- 流水线模式中的异常检测
- 性能趋势分析
- 改进建议
**端点：**
- `POST /api/pipeline-prediction/analyze` — 预测故障
- `GET /api/pipeline-prediction/{org_id}/trends` — 流水线趋势
- `POST /api/pipeline-prediction/train` — 训练模型
**技术：** FastAPI，机器学习模型 (scikit-learn 或 TensorFlow)
**监控：** 端口 9109 上的 Prometheus
### 服务通信
**REST API：**
- 前端 ↔ Kong 网关 ↔ 微服务
- 服务间通过 Kong 调用以保持一致性
**异步事件：**
- 微服务发布到 Redis 频道
- 事件中心订阅并通过 WebSocket 广播
- 示例：AI 服务发布 `threat.analysis.completed` → 事件中心 → 前端
**身份验证：**
- 所有服务上的 Auth0 JWT 验证中间件
- 在 `core/auth.py` 中进行集中式 JWT 验证
- 服务间调用使用内部 token
## 监控与可观测性
WithOps 包含生产级别的监控、可观测性和分布式链路追踪。
### 指标
**收集：** Prometheus 在端口 9091 抓取指标
**服务指标：**
```
http_requests_total{service="backend", endpoint="/api/threat-modeling", status="200"}
http_request_duration_seconds{service="github-service", endpoint="/api/github/organizations"}
websocket_connections_active{service="events-hub", user_count=42}
redis_commands_total{service="cache", command="get", status="hit"}
database_queries_total{service="backend", query_type="select"}
ai_analysis_duration_seconds{service="ai-service", model="claude-3-opus"}
```
**保留：** 15 天 (可在 `infra/monitoring/prometheus.yml` 中配置)
### 仪表板
**访问：** http://localhost:3001 (默认 admin/admin)
**预建仪表板：**
1. **系统概览** — 请求率、延迟、错误、正常运行时间
2. **服务健康** — 每个服务的指标和可用性
3. **数据库性能** — 查询计数、连接池、最慢的查询
4. **缓存效率** — 命中率、驱逐、内存使用
5. **AI 服务分析** — 模型使用情况、分析持续时间、成功率
6. **GitHub 集成** — API 速率限制、工作流分析、PR 创建率
**参见：** `infra/monitoring/grafana/dashboards/` 目录
### 分布式链路追踪
**访问：** http://localhost:16686
**链路追踪：** OpenTelemetry 通过 OTLP HTTP 导出到 Jaeger
**遥测：**
- FastAPI 中间件
- 数据库查询
- Redis 操作
- HTTP 客户端调用
- WebSocket 连接
**链路追踪流示例：**
```
HTTP POST /api/threat-modeling/analyze
├── [FastAPI] Request received
│ └── [Auth] JWT validation
├── [Service] Threat analysis logic
│ ├── [Database] Query threat model
│ ├── [AI Service] Call Claude API
│ └── [Redis] Cache result
├── [EventBus] Publish analysis.completed
│ └── [Jaeger] Export span
└── HTTP 200 OK
```
**查看链路追踪：** 带有时间线、span 详情、日志和错误消息的 Jaeger UI
### 结构化日志
**格式：** JSON (用于 ELK Stack 或 Loki 集成)
```
{
"timestamp": "2026-01-15T10:23:45.123Z",
"level": "INFO",
"service": "github-service",
"request_id": "abc-123-def",
"user_id": "user_12345",
"message": "Fetched 42 repositories for organization github",
"duration_ms": 234,
"status": "success"
}
```
**日志级别：** DEBUG, INFO, WARNING, ERROR, CRITICAL
**参见：** `backend/core/logging_config.py`
### 健康检查
**存活探针** — 服务正在运行
```
GET /api/health
GET /api/health/live
```
**就绪探针** — 服务已准备好接受流量
```
GET /api/health/ready
```
**完整健康检查** — 所有依赖项
```
GET /api/health/full
# 检查项: database, redis, 外部 APIs
```
## 开发
### 本地开发设置
#### 前置条件
- Python 3.11+
- Node.js 20.x LTS
- Docker 和 Docker Compose
- Git
#### 初始设置
```
# 克隆仓库
git clone https://github.com/your-org/withops.git
cd withops
# 复制环境文件
cp backend/.env.example backend/.env
cp services/github-service/.env.example services/github-service/.env
cp frontend/.env.example frontend/.env
# 启动 infrastructure
docker-compose up -d kong redis ollama
```
#### 后端开发
```
# 导航至 backend
cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 使用 auto-reload 运行
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# 运行测试
pytest
# 使用 Ruff 进行 Lint
ruff check .
```
#### 前端开发
```
# 导航至 frontend
cd frontend
# 安装依赖
npm install
# 启动带 hot-reload 的开发服务器
npm run dev
# 打开 http://localhost:5173
# 为 production 构建
npm run build
# 预览 production 构建
npm run preview
# 运行测试
npm test
# Lint & 格式化
npm run lint
npm run format
```
#### 添加新的微服务
```
# 1. 创建服务目录
mkdir -p services/my-service
cd services/my-service
# 2. 复制模板结构
# 从现有服务复制 main.py, requirements.txt, Dockerfile
# 3. 使用 FastAPI 应用创建 main.py
# app = FastAPI()
# @app.get("/health")
# async def health(): return {"status": "ok"}
# 4. 添加到 docker-compose.yml
# my-service:
# build: ./services/my-service
# ports:
# - "8010:8000"
# 5. 添加 Kong 路由 (infra/kong/kong.yml)
# 6. 添加 Kubernetes deployment (k8s/my-service.yaml)
```
### 项目结构
```
withops/
├── backend/ # Events Hub + core utilities
│ ├── main.py # WebSocket server & event coordinator
│ ├── core/ # Shared utilities
│ │ ├── event_bus.py # Redis pub/sub manager
│ │ ├── websocket_manager.py # WebSocket connections
│ │ ├── auth.py # JWT validation
│ │ ├── github_client.py # GitHub integration
│ │ └── ai_helper.py # AI model selection
│ ├── database/ # ORM models & queries
│ ├── config/keys/ # GitHub App private keys
│ └── requirements.txt
│
├── services/ # 9+ microservices
│ ├── ai-service/
│ │ ├── main.py # FastAPI app
│ │ ├── api/ # Route handlers
│ │ ├── core/ # Service logic
│ │ └── Dockerfile
│ ├── github-service/ # GitHub integration
│ ├── threat-modeling-service/
│ ├── workspace-intelligence-service/
│ ├── ai-rag-service/
│ ├── collaboration-service/
│ ├── workflow-orchestration-service/
│ ├── auth-service/
│ └── pipeline-prediction-service/
│
├── frontend/ # SvelteKit application
│ ├── src/
│ │ ├── routes/ # Pages (SvelteKit routing)
│ │ │ ├── dashboard/
│ │ │ ├── github/
│ │ │ └── [org]/ # Dynamic routes
│ │ ├── lib/ # Shared components & utilities
│ │ │ ├── auth.js # Auth0 setup
│ │ │ ├── api/ # API client functions
│ │ │ └── stores/ # Svelte stores (state management)
│ │ └── app.html # Root template
│ ├── package.json
│ └── Dockerfile
│
├── infra/ # Infrastructure configs
│ ├── kong/
│ │ └── kong.yml # API Gateway routing rules
│ ├── monitoring/
│ │ ├── prometheus.yml # Metrics scrape config
│ │ └── grafana/
│ │ └── dashboards/ # Dashboard JSON definitions
│ └── ollama/
│ └── init-models.sh # Model initialization
│
├── k8s/ # Kubernetes manifests
│ ├── namespace.yaml
│ ├── redis.yaml
│ ├── kong-gateway.yaml
│ ├── backend-events-hub.yaml
│ ├── *-service.yaml # Microservice deployments
│ ├── monitoring.yaml # Prometheus & Grafana
│ ├── secrets.yaml # Secret template
│ ├── PRODUCTION-DEPLOYMENT.md
│ └── SECRETS_MANAGEMENT.md
│
├── doc/ # Documentation
│ ├── MICROSERVICES-ARCHITECTURE.md
│ ├── CONFIGURATION-STATUS.md
│ ├── DEPLOYMENT-CHECKLIST.txt
│ ├── QUICK-START-CHECKLIST.md
│ └── TEST-VALIDATION-GUIDE.md
│
├── .github/
│ └── workflows/
│ └── ci-cd.yml # GitHub Actions pipeline
│
├── docker-compose.yml # Local development
├── docker-compose.prod.yml # Production overrides
├── ruff.toml # Python linting config
└── README.md # This file
```
### 代码规范
**Python (后端与服务)**
- 带有类型提示的 Python 3.11+
- PEP 8 风格指南 (由 Ruff 强制执行)
- 针对受 I/O 限制的操作使用 Async/await
- 使用 SQLAlchemy 进行 ORM 查询
- 使用 FastAPI 处理 HTTP 端点
**配置：**
```
# ruff.toml (项目根目录)
[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "W", "I", "N", "UP"] # Error, Flake8, Warning, Import, Naming, Upgrade
ignore = ["E501"] # Line too long (handled by formatter)
```
**JavaScript/SvelteKit (前端)**
- 开启严格模式的 Node.js 20+
- ES6+ 模块
- Prettier 格式化
- ESLint 保证代码质量
- Vitest 用于单元测试
**配置：**
```
// eslint.config.js
export default [
{
languageOptions: { globals: { browser: true, node: true } },
rules: { "no-unused-vars": "error" },
},
];
```
### 测试
**后端**
```
# 单元测试
pytest
# 包含覆盖率
pytest --cov=services/ai-service tests/
# 特定测试
pytest tests/test_ai_analysis.py::test_threat_detection
```
**前端**
```
# 单元测试 (Vitest)
npm test
# Watch 模式
npm test -- --watch
# 包含覆盖率
npm test -- --coverage
# 浏览器测试 (Playwright)
npm test -- --browser
```
**集成测试**
```
# 启动 full stack
docker-compose up -d
# 运行 integration 测试套件
./test-validation.ps1 -Mode full -Org test-org
# 清理
docker-compose down
```
### CI/CD 流水线
**GitHub Actions：** `.github/workflows/ci-cd.yml`
**阶段：**
1. **密钥扫描** (Gitleaks)
- 扫描完整的 git 历史以查找泄露的凭证
- 如果检测到密钥则构建失败
2. **前端 CI** (Node 20)
- 安装依赖 (`npm ci`)
- 使用 Prettier + ESLint 进行代码检查
- 运行 Vitest 单元测试
- 安装 Playwright 浏览器
3. **后端 CI** (Python 3.11)
- 并行矩阵中的 10 个服务
- 安装依赖
- 使用 Ruff 进行代码检查
- (可选：单元测试)
4. **构建与推送** (Docker)
- 需要所有 CI 阶段通过
- 使用矩阵构建所有镜像
- 使用 `sha-` 和 `latest` 打标签
- 推送到 GitHub Container Registry (GHCR)
**矩阵服务：**
```
- backend
- ai-service
- ai-rag-service
- auth-service
- collaboration-service
- github-service
- threat-modeling-service
- workflow-orchestration-service
- workspace-intelligence-service
- pipeline-prediction-service
```
**成功后：**
- 镜像推送到 `ghcr.io/your-org/withops/{service}:latest`
- 镜像准备好进行 Kubernetes 部署
## 贡献
### 在您开始之前
1. 阅读 [doc/MICROSERVICES-ARCHITECTURE.md](doc/MICROSERVICES-ARCHITECTURE.md)
2. 了解事件驱动架构
3. 审查现有的服务模式
4. 查看未解决的问题以了解已知限制
### 工作流
1. **创建分支**
git checkout -b feature/new-feature
2. **遵循代码规范进行更改**
- 提交前进行检查：`ruff check .` (后端)，`npm run lint` (前端)
- 为新逻辑编写测试
- 更新文档
3. **使用清晰的消息提交**
git commit -m "feat: Add threat severity scoring"
4. **推送并创建 Pull Request**
git push origin feature/new-feature
5. **运行 CI/CD 流水线**
- 密钥扫描
- 代码检查与测试
- Docker 构建
- 镜像推送到 GHCR
6. **代码审查** — 团队审查并批准
7. **合并** — 将提交压缩到 main 分支
### 添加新的 API 端点
**后端示例：**
```
# services/ai-service/api/v1/ai.py
from fastapi import APIRouter, Depends
from core.auth import verify_token
router = APIRouter(prefix="/api/ai", tags=["ai"])
@router.post("/analyze-code")
async def analyze_code(
code: str,
user_id: str = Depends(verify_token),
db: AsyncSession = Depends(get_db)
):
"""Analyze code for vulnerabilities."""
# Implementation
return {"vulnerabilities": [...]}
```
**前端示例：**
```
```
### 添加新的微服务
1. 复制服务模板目录
2. 使用 FastAPI 应用更新 `main.py`
3. 添加 `Dockerfile`
4. 添加到 `docker-compose.yml`
5. 在 `infra/kong/kong.yml` 中添加 Kong 路由
6. 在 `k8s/` 中添加 Kubernetes 清单
7. 在 `.github/workflows/ci-cd.yml` 中添加到 GitHub Actions 矩阵
8. 在 [doc/MICROSERVICES-ARCHITECTURE.md](doc/MICROSERVICES-ARCHITECTURE.md) 中记录端点
## 故障排除
### 服务无法启动
```
# 检查日志
docker-compose logs -f
# 验证网络连通性
docker network ls
docker network inspect withops_default
# 从头开始重启
docker-compose down -v
docker-compose up --build
```
### 数据库连接问题
```
# 检查 Supabase 凭证
echo $SUPABASE_URL
echo $SUPABASE_ANON_KEY
# 测试连接
psql $DATABASE_URL -c "SELECT 1"
# 从容器中检查 PostgreSQL
docker-compose exec backend psql $DATABASE_URL -c "SELECT 1"
```
### Redis 连接问题
```
# 检查 Redis 是否正在运行
docker-compose ps redis
# 测试 Redis 连接
docker-compose exec redis redis-cli ping
# 应返回 "PONG"
# 检查 Redis URL
echo $REDIS_URL
```
### Auth0 配置
1. 前往 https://manage.auth0.com
2. 应用程序 → 您的应用 → 设置
3. 添加到 **Allowed Callback URLs**：
- `http://localhost:5173/callback` (开发环境)
- `https://app.withops.com/callback` (生产环境)
4. 点击 **Save Changes**
### GitHub App 配置
1. 前往 https://github.com/settings/apps
2. 编辑您的 GitHub App
3. 更新 **Webhook URL** 和 **Callback URL**
4. 如有需要，重新生成 **Client Secret**
5. 如果已过期，下载新的 **Private Key**
### 密钥扫描失败
```
# 检查硬编码的 secrets
git log -S "sk-ant" --oneline
git log -p -S "YOUR_SECRET"
# 在本地使用 gitleaks
gitleaks detect --source . --verbose
```
## 支持与资源
### 文档
- [微服务架构](doc/MICROSERVICES-ARCHITECTURE.md) — 服务规范
- [Kubernetes 部署](k8s/PRODUCTION-DEPLOYMENT.md) — K8s 设置指南
- [密钥管理](k8s/SECRETS_MANAGEMENT.md) — 密钥最佳实践
- [配置状态](doc/CONFIGURATION-STATUS.md) — 环境设置状态
- [部署检查清单](doc/DEPLOYMENT-CHECKLIST.txt) — 生产环境部署步骤
### 外部参考
- [FastAPI 文档](https://fastapi.tiangolo.com/)
- [SvelteKit 指南](https://kit.svelte.dev/)
- [Kong API 网关](https://konghq.com/kong/)
- [PostgreSQL / Supabase](https://supabase.com/docs)
- [Kubernetes 文档](https://kubernetes.io/docs/)
- [Prometheus 监控](https://prometheus.io/docs/)
- [OpenTelemetry](https://opentelemetry.io/)
### 获取帮助
1. 查看 `/doc` 目录中的文档
2. 查看现有的 GitHub issues
3. 查阅 `.github/workflows/ci-cd.yml` 获取 CI/CD 示例
4. 在 `/services` 中查看服务示例以了解模式
## 许可证
本项目是专有软件。禁止未经授权的使用、分发或修改。
## 版本
**WithOps DevSecOps 平台 v2.0**
- **发布日期：** 2026 年 1 月
- **状态：** 生产就绪
- **Python 版本：** 3.11+
- **Node 版本：** 20.x LTS
- **Kubernetes：** 1.24+
## 总结
WithOps 是一个专为企业设计的综合性、生产就绪的 DevSecOps 平台。凭借 9 个以上的微服务、企业级监控、Kubernetes 支持和 AI 驱动的安全分析，它为团队提供了用于 DevSecOps 成熟度评估、威胁建模和 CI/CD 治理的智能自动化。
基于行业标准技术（FastAPI、SvelteKit、PostgreSQL、Redis、Kubernetes）构建，该平台可扩展以支持大型组织，同时保持安全性、可观测性和易于部署。
**核心优势：**
- ✅ 事件驱动的微服务架构
- ✅ 全面的监控和可观测性
- ✅ 生产就绪的 Kubernetes 部署
- ✅ AI 驱动的安全建议
- ✅ 实时协作功能
- ✅ 企业级身份验证 (Auth0)
- ✅ 多种 LLM 集成
- ✅ 自动化的 CI/CD 治理
标签：AI代码分析, API集成, ASN信息, CIA模型, CI/CD安全, CI/CD治理, CISA项目, DevOps工具, DevSecOps, Docker Compose, GitHub集成, LINDDUN模型, Llama, OWASP DSOMM, STRIDE模型, StruQ, 上游代理, 事件驱动架构, 人工智能, 企业级平台, 协作平台, 可观测性, 威胁建模, 子域名突变, 安全合规, 微服务架构, 搜索引擎查询, 测试用例, 用户代理, 用户模式Hook绕过, 研发安全, 网络代理, 自定义请求头, 请求拦截, 逆向工具