内容
# 无瑕
[](#快速入门)
[](#开发)
[](#Kubernetes部署)
[](#Docker)
[](#Langfuse)
[](#许可证)
**您的基础设施可以自我解释、自我修复并证明其恢复。**<br>
**让基础设施自己解释故障、安全完成修复，并证明它真的恢复了。**
**无瑕** 是 **COSCOAI SRE** 平台的开源工程基础：一个面向 Kubernetes 和云基础设施的 AI 原生 SRE 控制平面。它在单一可审计的 AgenticOps 环路中连接警报、证据、拓扑、人工审批、受控修复和恢复验证。
它不是另一个只会给建议的运维聊天框。无瑕将“发现问题、收集证据、生成预演、人工授权、执行变更、恢复验证、经验沉淀”连接成一个可审计闭环。
由 **陆宣宇 (Xuanyu Lu)** 在上海创建。
## 产品预览
这些是运行平台的真实控制台截图，而不是概念性模拟。
| AI 检测和可执行预览 | SRE 对话和实时证据 |
|---|---|
|  |  |
当前版本：**3.2.0**。
版本 3.2 添加了持久化修复谱系：每个失败的策略、动作、验证结果和替换计划在操作员批准的后续作业中保持链接。效果账本在运行时卷上持久化，以便模型比较和恢复记录在 Pod 重启后存活。
> **兼容性注意：** 公共产品名称为 **无瑕**。现有的 `LUXYAI_*` 环境变量、`charts/luxyai` 目录、存储路径和 Kubernetes 资源标识符仍然受支持，因此当前安装可以在不进行破坏性迁移的情况下升级。
## AgenticOps 环路
`发现 → 诊断 → 预览 → 审批 → 执行 → 验证 → 学习`
- **证据优先**：连接警报、事件、日志、指标、拓扑、运行手册和最近的更改。
- **受控动作**：保留 RBAC、策略、干预运行、人工审批和审计在模型边界之外。
- **验证恢复**：在执行后测试原始症状，而不是将成功的命令视为成功。
## 实战笔记
仅列出已发布的笔记；链接指向此存储库中的版本文件：
- [从警报到可验证恢复](blog/posts/2026-07-13-from-alert-to-verified-recovery.md)
- [AI 是否允许修复 Kubernetes？](blog/posts/2026-07-13-ai-should-earn-the-right-to-act.md)
- [下一代 SRE 控制平面不仅仅是一个聊天框](blog/posts/2026-07-13-not-another-chatbox.md)
- [在上海构建 AgenticOps](blog/posts/2026-07-13-building-agenticops-in-shanghai.md)
## 为什么存在
现代云系统以难以从单个日志行推理的方式失败：
- Pod 重启可能会隐藏 PVC、镜像、调度、网络、配额或滚动问题；
- 小的工作负载更改可能会影响服务、数据管道、中间件和下游用户；
- 重复的人工紧急响应会将宝贵的运维知识留在平台之外；
- 模型输出仅在受到证据、策略、权限和回滚约束时才有用。
无瑕构建为 SRE 控制平面。它使用模型作为规划器和解释器，但平台保留执行边界：RBAC、动作目录、干预运行、审批、审计和恢复验证。
## 核心功能
- **SRE 聊天**：具有集群、命名空间、工作负载和风险上下文的 ChatGPT 式运维控制台。
- **检测队列**：在 Rancher/Kubernetes 范围内定时或手动扫描，并按严重性排名。
- **受控修复**：证据收集、更改预览、人工审批、执行、更改后验证和证据驱动的重新规划，记住跨后续作业的失败策略。
- **拓扑影响**：2D/3D 拓扑、CMDB 式依赖关系、eBPF/数据流适配器、爆炸半径分析。
- **发布治理**：SLO、错误预算、金丝雀/风险门、紧急修复路径和发布审计链。
- **技能库**：可移植的运维技能，编码专家知识，可被其他代理重用。
- **知识库**：上传文本、Markdown、PDF、Word、Excel、日志、YAML 和运维 RAG 的运行手册。
- **模型实验室**：配置多个 OpenAI 兼容或 OAuth 保护的模型网关并比较结果。
- **可衡量结果**：持久化修复谱系、更改资源历史、恢复证据和模型效果比较。
- **可观察性**：Prometheus 指标、Loki 日志、Tempo 跟踪、Grafana 链接和可选的 Langfuse 跟踪。
- **可扩展基础设施**：Kubernetes、Rancher、数据库、虚拟机、存储和中间件的适配器。
## 架构
```text
前端控制台
├─ SRE 聊天 / 检测 / 拓扑 / 发布 / 技能 / 模型
│
▼
控制平面 API
├─ 证据管道
├─ 修复作业状态机
├─ 发布门和 SLO 预算
├─ 知识和模型注册表
├─ 可观察性存储
└─ 集成健康检查
│
├─ MCP Kubernetes 工具
├─ A2A 自愈 / 事件 / 事后分析代理
├─ Rancher / Prometheus / CMDB / eBPF 流适配器
├─ Langfuse / Loki / Tempo / Grafana 适配器
└─ 可选的自定义算法扩展
```
## 快速入门
### 1. 克隆
```bash
git clone https://github.com/William-Lu-stack/Flawless.git
cd Flawless
```
### 2. 配置
```bash
cp .env.example .env
```
对于简单的本地 OpenAI 兼容端点：
```env
LLM_API_BASE=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5:7b
LLM_AUTH_TYPE=api_key
```
对于 OAuth 客户端凭证网关：
```env
LLM_AUTH_TYPE=oauth_client_credentials
OAUTH_TOKEN_URL=https://your-iam/realms/main/protocol/openid-connect/token
OAUTH_CLIENT_ID=your-client
OAUTH_CLIENT_SECRET=your-secret
LLM_API_BASE=https://your-llm-gateway/engines/default
LLM_MODEL=your-model
LLM_VERIFY_SSL=true
```
### 3. 构建控制台
```bash
cd frontend/modern
npm install
npm run build
cd ../..
```
构建输出到 `frontend/dist`，由 Python 控制平面提供服务。
### 4. 本地运行
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
```
打开 `http://localhost:8080`。
对于本地代理兼容性端口：
```bash
uvicorn agents.observability_agent:app --host 0.0.0.0 --port 8100 &
uvicorn agents.healing_agent:app --host 0.0.0.0 --port 8101 &
uvicorn agents.incident_agent:app --host 0.0.0.0 --port 8102 &
uvicorn agents.postmortem_agent:app --host 0.0.0.0 --port 8103 &
uvicorn mcp_servers.mcp_http_server:app --host 0.0.0.0 --port 8105 &
uvicorn openwebui.openwebui_adapter:app --host 0.0.0.0 --port 8200 &
```
## Docker
构建一体化后端镜像：
```bash
docker build --target backend-runtime -t flawless:latest .
```
在本地运行：
```bash
docker run --rm \
--env-file .env \
-p 8080:8080 \
flawless:latest \
python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
```
推送到 GHCR 或内部注册表：
```bash
IMAGE=ghcr.io/william-lu-stack/flawless:latest ./scripts/build-push.sh
```
对于隔离或中国大陆网络，Dockerfile 和 scripts/build-push.sh 已经暴露了镜像构建参数：
```bash
NODE_IMAGE=docker.m.daocloud.io/library/node:24-slim \
PYTHON_IMAGE=docker.m.daocloud.io/library/python:3.14.6-slim \
NPM_REGISTRY=https://registry.npmmirror.com \
PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple \
IMAGE=your-registry/flawless:latest \
./scripts/build-push.sh
```
## Kubernetes 部署
### 推荐：Helm
图表安装控制平面、六个代理服务、受控集群范围 RBAC、通用 NAS 持久化、NodePort 访问、可选 Ingress 和 Secret 钩子：
```bash
kubectl create namespace k8s-agent
helm upgrade --install flawless ./charts/luxyai \
--namespace k8s-agent \
--set image.repository='<internal-registry>/flawless' \
--set image.tag='<release-tag>' \
--set persistence.storageClass=standard
```
在生产环境中使用 `rbac.mode=controlled`。`rbac.mode=cluster-admin` 仅存在于隔离的验证环境中，应该需要安全例外。
渲染和审查后再部署：
```bash
helm lint ./charts/luxyai --strict
helm template flawless ./charts/luxyai -n k8s-agent > rendered.yaml
```
### 原始清单
#### 1. 创建命名空间
```bash
kubectl create namespace k8s-agent
```
#### 2. 创建 Secret
不要提交真实的 Secret。从终端或 Secret 管理器创建它们：
```bash
kubectl -n k8s-agent create secret generic k8s-agent-oauth \
--from-literal=OAUTH_CLIENT_ID='<client-id>' \
--from-literal=OAUTH_CLIENT_SECRET='<client-secret>' \
--from-literal=RANCHER_TOKEN='<optional-rancher-token>'
```
对于 Langfuse：
```bash
kubectl -n k8s-agent create secret generic k8s-agent-langfuse \
--from-literal=public-key='<pk-lf-...>' \
--from-literal=secret-key='<sk-lf-...>'
```
默认情况下，管理员配置已禁用。密码永远不应存储在 `values.yaml`、ConfigMap 或存储库中：
```bash
kubectl -n k8s-agent create secret generic luxyai-console-auth \
--from-literal=CONSOLE_BASIC_AUTH_USERNAME='admin' \
--from-literal=CONSOLE_BASIC_AUTH_PASSWORD='<password-from-vault>'
helm upgrade --install flawless ./charts/luxyai \
-n k8s-agent \
--reuse-values \
--set admin.enabled=true
```
当管理员模式关闭时，控制台仍然可读，操作审批继续有效，但模型、知识和技能写入被阻止。当它开启时，这三个写入表面需要 Secret 支持的管理员身份。
#### 3. 配置运行时
编辑 `manifests/deployment.yaml`:
- `LLM_AUTH_TYPE`
- `OAUTH_TOKEN_URL`
- `LLM_API_BASE` / `LLM_GATEWAY_BASE`
- `LLM_MODEL`
- `PROMETHEUS_URL`
- `CMDB_URL`
- `RANCHER_URL`
- `RANCHER_CLUSTER_IDS`
- `ALLOWED_NAMESPACES`
- `OPS_MUTATION_ENABLED`
- `AUTO_HEALING_ENABLED`
#### 4. 应用清单
```bash
kubectl apply -f manifests/rbac.yaml
kubectl apply -f manifests/deployment.yaml
kubectl apply -f manifests/frontend.yaml
```
默认服务通过 NodePort `30080` 暴露控制台：
```bash
kubectl get svc -n k8s-agent
```
在生产环境中，使用公司 Ingress/Gateway 和 TLS 和身份中间件代替暴露的未经身份验证的公共 NodePort。
## 模型配置
无瑕支持两种常见的模型访问模式。
### OAuth Token URL + Base URL
当您的网关需要动态 bearer token 时使用：
```json
[
{
"id": "primary",
"provider": "oauth-gateway",
"model": "your-model",
"base_url": "https://your-gateway/engines/default",
"auth_type": "oauth_client_credentials",
"token_url": "https://your-iam/token",
"client_id": "your-client",
"client_secret": "from-secret",
"role": "primary",
"max_tokens": 4096,
"verify_ssl": true
}
]
```
### Base URL + API Key
用于 OpenAI 兼容的提供商：
```json
[
{
"id": "openai-compatible",
"provider": "openai-compatible",
"model": "your-model",
"base_url": "https://api.example.com/v1",
"auth_type": "api_key",
"api_key": "from-secret",
"role": "candidate",
"max_tokens": 4096
}
]
```
在 `MODEL_PROFILES_JSON` 中设置 JSON 或从 **模型实验室** 页面添加模型。Secret 应来自 Kubernetes Secret 或您的企业 Secret 平台。
## Langfuse
Langfuse 是可选的。当配置后，平台记录模型调用、延迟、token 使用量、成本估算、工具跨度、质量分数和跟踪 ID。
环境变量：
```env
LANGFUSE_ENABLED=true
LANGFUSE_HOST=http://langfuse-web.langfuse.svc.cluster.local:3000
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
```
部署参考：
- Docker Compose：https://langfuse.com/self-hosting/deployment/docker-compose
- Kubernetes Helm：https://langfuse.com/self-hosting/deployment/kubernetes-helm
该存储库还包含 `manifests/langfuse-local.yaml` 作为本地参考清单。它默认被 Git 忽略，因为生产 Langfuse 凭证和存储设置应单独管理。
## 自定义算法扩展
公共存储库包括 `agents/aiops_algorithms.py` 处的可运行基线算法模块。
如果您有自定义评分实现，请在存储库外部保留它，并在运行时加载：
```bash
export LUXYAI_CUSTOM_ALGORITHM_PATH=.local/custom_algorithms/aiops_algorithms_custom.py
uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
```
Docker：
```bash
docker run --rm \
--env-file .env \
-e LUXYAI_CUSTOM_ALGORITHM_PATH=/var/lib/luxyai-custom/aiops_algorithms_custom.py \
-v "$PWD/.local/custom_algorithms:/var/lib/luxyai-custom:ro" \
-p 8080:8080 \
flawless:latest \
python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
```
Kubernetes：
```bash
kubectl -n k8s-agent create secret generic luxyai-custom-algorithms \
--from-file=aiops_algorithms_custom.py=.local/custom_algorithms/aiops_algorithms_custom.py
kubectl rollout restart deploy/luxyai -n k8s-agent
kubectl rollout restart deploy/k8s-agent-api -n k8s-agent
```
如果 Secret 不存在，平台仍将使用开放的基线运行。
要显式测试开放基线路径：
```bash
LUXYAI_DISABLE_CUSTOM_ALGORITHMS=1 uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
```
## 技能
技能是可移植的操作知识包。它们描述：
- 症状和触发条件；
- 所需证据；
- 允许的对象；
- 允许的动作；
- 恢复标准；
- 回滚指南；
- 可选的引用和运行手册。
技能存储在 `OPS_SKILL_ROOT` 下，可以从控制台创建。它们故意是可移植的，以便可以在其他代理或环境之间重用。
每个技能都持久化为一个独立的软件包目录，而不是编译到应用程序中。这使得技能存储库可以单独版本控制、审查、导出和被其他兼容的代理重用。
## 统一资源 API
`GET /api/resources` 通过一个稳定的契约公开 Kubernetes、数据库、虚拟机、中间件、存储和云资源：
```text
GET /api/resources?resource_type=pod&cluster=prod&namespace=orders&limit=200
```
响应使用合同 `luxyai.resource.v1`，包括源和健康摘要，并支持游标分页。新基础设施团队应该添加适配器并规范为此契约，而不是引入平行资源 API。
## 安全模型
该平台围绕最小特权设计：
- 没有浏览器端的 shell 或任意命令执行；
- 除非服务器开关允许，否则不进行变异；
- 高风险操作需要明确的操作员确认；
- 动作目录限制了模型可以请求的内容；
- 命名空间/工作负载范围由 RBAC 和允许列表控制；
- 每个更改都记录了预览、执行者、差异、结果和验证状态；
- 绝不提交秘密，应该通过 Kubernetes Secret 或秘密管理器提供。
## 存储库布局
```text
Flawless/
├── agents/ # SRE 工作流代理和执行引擎
├── backend/app/ # 控制平面 API、模式、服务、领域逻辑
├── mcp_servers/ # Kubernetes MCP 工具
├── cmdb/ # 本地 CMDB/拓扑服务
├── cloud/ # 云和基础设施适配器接口
├── frontend/modern/ # React + TypeScript + Vite 控制台
├── charts/luxyai/ # 生产 Helm 图表
├── manifests/ # Kubernetes 清单
├── scripts/ # 构建和镜像帮助脚本
├── docs/ # 架构和维护者文档
├── examples/ # 示例警报
└── tests/ # 后端和工作流测试
```
## 开发
```bash
python -m compileall -q backend agents mcp_servers cmdb cloud a2a openwebui
python -m unittest discover -s tests -v
cd frontend/modern && npm run build
```
在本地运行安全门：
```bash
python -m pip install pip-audit
pip-audit -r requirements.lock --no-deps --disable-pip
```
## GitHub
公共工程基线位于 [`William-Lu-stack/Flawless`](https://github.com/William-Lu-stack/Flawless)。自定义算法扩展、凭证、生产拓扑和公司数据在运行时加载，故意从公共存储库中排除。
路线Flawless 设计 Kubernetes SRE 控制台发展成为现代基础设施的 AgenticOps 操作系统 **Kubernetes 自动驾驶**: 覆盖从警报、证据、根本原因分析、修复预览、审批、执行滚和恢复验证的完整生命周期 **Rancher 多集群舰队**: 使每个集群、命名空间、工作事件、指标和操作记录都可从一个控制平面搜索和治理全栈基础设施运维**: 将相同的证据到行动的循环数据库、虚拟机、存储、中间件、服务网格和资源。
- **运行时数据流智能**: 将 Kubernetes 库存、CMPrometheus、Loki、Tempo 和 eBPF 流数据融合到一个动态依赖图，解释影响、影响范围和流量方向。
- **发布平面**: 将 SLO、错误预算、金丝雀范围、镜像风险、YAML 策略、拓扑风险修复路径转化为可编程的发布门控。
- **运维技能 让工程师将宝贵的故障排除成可移植的技能，以便事件时平台都变得更- **模型基准竞技场**: 根据修复成功率、MTTR 降低、安全评分、证据质量、代币成本和回滚正确性评估不同模型。
- **变更风险数字孪生**: 在生产环境被触及之前，模拟针对拓扑、历史事件、依赖路径和 SLO 预算的变更。
- **10 万节点规模架构**: 将重度发现转移到事件驱动的收集器、分片缓存、异步作业队列、流式证据管道和可存储。
- **企业信任层**: 提供生产环境的 Helm、空气隔离包、OIDC/SSO、RBAC 预设、审计保留、策略即代码、机密管理器集成和合规报告。
- **云与边缘扩展**: 为阿里云、通用云、腾讯云、AWS、Azure、私有云、和跨区域灾难恢复添加一流的适配器。
- **自愈平台运行时**: 让平台在严格的审批和审计边界下检查其自身的代理、收集器、队列、存储和集成。
## 许可证
根据标准化的 [PolyForm 非商业许可证 1.0.0](LICENSE) 发布。
您可以在非商业目的下使用、研究、重新分发源代码。商业使用、托管商业服务、转售、企业产品捆绑、付费支持服务和删除作者署名需要 **陆宣宇 (Xuanyu Lu)** 的事先书面授权。
化的源代码可用非商业许可证，而不是 OSI 批准的开源许可证。商业授权：**陆宣宇 (Xuanyu Lu)**，18616350794`，微信 `Lxylxy_-`。
连接信息
猜你喜欢
暂无推荐服务器