AngelP17/Cellguard

# CellGuard [](https://github.com/AngelP17/Cellguard/actions/workflows/gate-proof.yml) **CellGuard 将 xyOps 从自动化平台转变为受管可靠性系统。** 在旗舰模式下，CellGuard 在 **xyOps** 上运行，它是您用于作业、工作流、监控、警报和自动化的本地执行层。xyOps 执行并观察。CellGuard 决定什么安全，强制执行策略，触发修复，并证明每个操作。 它们共同构成一个完整、零成本、自托管的可靠性操作系统。 CellGuard 评估实时 SLO 和工作流证据，使用 `HTTP 423 Locked` 阻止风险部署，协调自主可靠性代理（budget_guard、healing、incident_response、chaos_orchestrator），并记录每个特权操作在不可变跨系统审计跟踪中。 ``` flowchart LR U["Operator or CI"] --> API["CellGuard API"] API --> BG["Release Gate"] API --> CH["Chaos Service"] API --> EV["Budget Evaluator"] CH --> RD["Redis / Infra Target"] EV --> DB["Postgres"] AG["Agent Scheduler"] --> SQ["Sidekiq"] SQ --> AGT["Agents"] AGT --> API UI["Dashboard + WebSocket Activity"] --> API ``` ## 旗舰演示（闭环治理） ``` ALLOW_DEMO_ENDPOINTS=true CLASSIFIER_STUB=true bin/run-all ``` 然后： ``` # 全天游戏日：xyOps 降级，CellGuard 上下文，423 锁定，修复，重新开放，审计 make gameday ``` 仪表板和操作层面板显示完整的工作循环： ``` flowchart LR A["xyOps runs workflow"] --> B["Latency and error degradation"] B --> C["Alert, job context, and snapshot emitted"] C --> D["CellGuard ingests operational evidence"] D --> E["SLO evaluation with xyOps penalty"] E --> F["Release gate locks: HTTP 423"] F --> G["Incident created with evidence links"] G --> H["Healing agent requests remediation"] H --> I["xyOps remediation completes"] I --> J["CellGuard re-evaluates healthy signal"] J --> K["Release gate reopens: HTTP 200"] K --> L["Audit trail links decision, incident, and remediation"] ``` 在 打开仪表板，查看操作层、丰富的门证据和跨系统证明。 ## UI 入口 | 路径 | 目的 | |------|---------| | `/` | 带有实时门快照的着陆页 | | `/dashboard` | 命令仪表板 | | `/incidents` | 事件分诊工作区 | | `/runbooks/:slug` | 运行手册查看器 | ## 截图 下面的截图使用一种命令系统语言：相同的深色控制平面调色板、翡翠治理强调色、红色锁定状态、单色证据、紧凑的面板和基于 DB 的 xyOps 证明。这套集合故意很小，以便 README 显示一个连贯的产品，而不是一个无关状态的画廊。 ### 着陆：产品证明 实时可靠性操作系统信号在页面上方：门状态、燃烧、预算、xyOps 层、活动代理和审计。  ### 仪表板：开放门 一个命令驾驶舱，其中包含发布门、层证据、代理状态和审计上下文在一个视图中。 **再生：** 在 UI 变更后运行 `npm run screenshot:open`、`npm run screenshot:locked`、`npm run screenshots`，以及 `make go-ui-smoke`。`screenshot:open` 拥有 `dashboard-open.png` 和 `dashboard-mobile.png`；`screenshot:locked` 拥有 `dashboard-locked.png`；`screenshots` 拥有着陆和事件。始终在提交前检查新的 PNG 文件。有关前端完成标准，请参阅 AGENTS.md。 ## 架构（CellGuard 管理 xyOps） ``` flowchart TB subgraph UI["CellGuard UI (Hotwire)"] direction TB D["Dashboard, Release Gate with xyOps evidence, Agents"] I["Incidents with xyOps panel, Audit cross-system"] end subgraph CP["CellGuard Control Plane"] direction TB SLO["SLO & Error Budget Engine (workflow-aware)"] GE["Gate Engine (xyops signals accelerate burn/lock)"] AE["Agent Engine (healing triggers xyops remediation safely)"] AD["xyOps Adapter (client, ingestor, remediation_runner)"] end subgraph XY["xyOps Execution Fabric"] WF["Jobs, Workflows, Monitoring, Alerts, Snapshots"] NOTE["(simulated in demo via Xyops::Simulator; real self-hosted in prod)"] end UI --> CP CP --> XY style UI fill:#0f172a,stroke:#64748b,color:#e2e8f0 style CP fill:#1e2937,stroke:#64748b,color:#e2e8f0 style XY fill:#0f172a,stroke:#64748b,color:#e2e8f0 ``` **责任划分** | 层 | CellGuard 拥有 | xyOps 拥有 | |--------------------------|-----------------------------------------------------|-------------------------------------------------| | 可靠性智能 | SLOs、错误预算、发布门、锁定决策 | 运营上下文（作业、工作流、警报） | | 安全策略 | 门规则、代理护栏、完整审计跟踪 | 工作流执行约束 | | 事件响应 | 状态、严重性、运行手册、审计链接 | 作业历史、服务器快照、警报上下文 | | 自动化 | budget_guard、healing、incident_response、chaos | 跨系统工作流、计划自动化 | | 证明 | “为什么门会锁定？” | “什么在运行，在哪里，有什么变化？” | **CellGuard 管理 xyOps。** xyOps 运行工作。CellGuard 使自动化安全、SLO 感知、可审计和影响发布。 ## 功能证明 此 README 反映了一个经过验证的本地系统，而不是静态的模拟。证明路径如下： ``` flowchart LR T["Rails, Go classifier, and Go runner tests"] --> S["Local stack boot"] S --> G["make gameday"] G --> L["Gate opens, locks at 423, then reopens"] L --> U["UI smoke and screenshot regeneration"] U --> R["README screenshots refreshed from generated artifacts"] ``` ## 本地开发 ### 预先条件 - Ruby `3.3.0` - Bundler `2.5.x` - PostgreSQL `16` - Redis（本地或容器） ### 一键启动 ``` ALLOW_DEMO_ENDPOINTS=true CLASSIFIER_STUB=true bin/run-all ``` 这启动了 Rails 网络加 Sidekiq 工作员加调度器，并使用进程内 Ruby 分类器存根。 ### 三终端模式 终端 1（Web）： ``` bin/dev ``` 终端 2（工作员）： ``` bundle exec sidekiq -C config/sidekiq.yml ``` 终端 3（Go 分类器在 :8081）： ``` make go-classifier-run ``` ### 重置演示状态 ``` make reset-demo make enable-chaos-orchestrator # optional, default disabled for safety ``` ## 生产 Docker 部署 应用程序包含一个生产就绪的 Dockerfile。有关完整说明，请参阅 [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md）。 最小示例： ``` docker build -t cellguard-web . docker run -d --name cellguard-web -p 3000:3000 \ -e DATABASE_URL=postgres://cellguard:secret@db:5432/cellguard_production \ -e REDIS_URL=redis://redis:6379/0 \ -e SECRET_KEY_BASE=$(openssl rand -hex 64) \ -e CELLGUARD_TOKEN=$(openssl rand -hex 32) \ -e CLASSIFIER_URL=http://classifier:8081 \ cellguard-web ``` 必需环境变量：`DATABASE_URL`、`REDIS_URL`、`SECRET_KEY_BASE`、`CELLGUARD_TOKEN`、`CLASSIFIER_URL`。 可选：`ALLOW_DEMO_ENDPOINTS`（开发/演示仅限）、`GIT_SHA`（审计跟踪）、代理切换。 ## 验证 ### 测试 ``` bundle exec rails test # Rails test suite make go-classifier-test # Go classifier tests make go-agent-runner-test # Go agent-runner tests ``` ### 游戏日证明 ``` make gameday ``` 此确定性脚本证明了策略执行：门开始打开，注入故障，评估运行，门锁定到 423，恢复它。 ### UI 证据 ``` make go-ui-smoke ``` 渲染仪表板并保存 `tmp/ui-dashboard.png`。 ### 健康检查 ``` curl -s http://localhost:3000/api/healthz # liveness curl -s http://localhost:3000/api/readyz # readiness (DB + Redis + Sidekiq + classifier) curl -s http://localhost:3000/api/status # detailed status with version ``` ## API 参考 ### 公共（无需令牌） | 端点 | 目的 | |----------|---------| | `GET /api/healthz` | 活跃性探测 | | `GET /api/readyz` | 准备就绪探测 | | `GET /api/status` | 详细状态与版本 | | `GET /api/release-gate/check` | CI 门检查（200 打开 / 423 锁定） | | `GET /api/agents/status` | 代理启用和执行计数 | | `GET /api/agents/activity?limit=20` | 最近代理执行源 | ### 特权（生产中需要 `X-CELLGUARD-TOKEN`） | 端点 | 目的 | |----------|---------| | `POST /api/release-gate/override` | 审计手动覆盖 | | `POST /api/evaluate` | 触发预算评估 + 分类 | | `POST /api/ingest/job-stat` | 摄入运营指标 | | `POST /api/inject-failures` | 演示：模拟故障（仅限演示模式） | | `POST /api/chaos/partition` | 注入网络分区（仅限演示模式） | | `POST /api/chaos/heal` | 从混沌中恢复（仅限演示模式） | | `GET /api/audit-logs` | 读取审计跟踪 | | `POST /api/incidents/:id/acknowledge` | 承认事件 | | `POST /api/incidents/:id/resolve` | 解决事件 | | `POST /api/incidents/:id/escalate` | 升级事件 | | `POST /api/incidents/:id/note` | 向事件添加注释 | | `POST /api/agents/run-all` | 运行所有启用的代理（默认异步） | | `POST /api/agents/:name/run` | 运行特定代理 | | `POST /api/agents/:name/toggle` | 启用/禁用代理 | ## 安全性与治理 - 所有门覆盖、混沌操作、代理切换和事件生命周期变更都写入 `audit_logs`，包括操作者、方法、路径、IP 和时间戳。 - 特权端点需要 `X-CELLGUARD-TOKEN`（开发/演示除外）。 - 混沌端点需要 `ALLOW_DEMO_ENDPOINTS=true` 或开发模式。 - 自主代理具有安全护栏（营业时间、预算检查、事件意识）。 - 生产模式下，API 端点不会泄露原始异常消息。 - 有关完整安全模型和不变合同，请参阅 [AGENTS.md](./AGENTS.md)。 ## 文档 - [AGENTS.md](./AGENTS.md) - 架构、命令、安全模型、完成标准 - [docs/AGENTS.md](./docs/AGENTS.md) - 代理运行时合同 - [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) - 生产 Docker 部署 - [docs/runbooks/](./docs/runbooks/) - 运营运行手册（游戏日等） ## 故障排除 ### `bundle exec rails test` 失败，出现 `ActiveRecord::NoEnvironmentInSchemaError` 首先运行迁移： ``` bundle exec rails db:setup ``` ### 在 `make gameday` 后门保持打开 检查分类器响应： ``` curl -s -X POST http://localhost:3000/api/evaluate \ -H "Content-Type: application/json" \ -d '{"shard":"shard-default","window_minutes":60}' ``` 如果 `is_violation` 为 `false`，注入的错误率低于 SLO 阈值。在注入调用中增加 `error_rate`。 ### Sidekiq 调度器未运行 验证调度器已注册： ``` bundle exec sidekiq -C config/sidekiq.yml ``` 检查 `config/sidekiq.yml` 中的 `scheduler` 块。默认情况下，调度器每 60 秒运行一次。 ### 特权端点返回 401 设置令牌： ``` export CELLGUARD_TOKEN=your-secret-token curl -X POST http://localhost:3000/api/release-gate/override \ -H "X-CELLGUARD-TOKEN: $CELLGUARD_TOKEN" \ -H "Content-Type: application/json" \ -d '{"shard":"shard-default","actor":"you","justification":"reason"}' ``` ## 许可证 MIT

标签：NIDS, PostgreSQL, Redis, Sidekiq, SLO监控, WebSocket, 仪表盘, 依赖分析, 分布式系统, 可靠性控制, 响应大小分析, 审计追踪, 容器化, 工作流管理, 开源框架, 执行环境, 持续部署, 持续集成, 搜索引擎查询, 操作面板, 故障响应, 日志审计, 服务网格, 治理框架, 测试用例, 混沌工程, 监控告警, 策略即代码, 系统稳定性, 聊天机器人安全, 自动化平台, 自动化运维, 自我修复, 请求拦截, 风险预算