Whiskers

<p align="center"> <img src="src/Whiskers/wwwroot/brand.png" alt="Whiskers logo" width="150" height="150" /> </p> <h1 align="center">Whiskers</h1> <p align="center"><strong>人类和AI代理的可控基础设施操作。</strong></p> <p align="center"> Whiskers是一个<strong>自托管控制平面</strong>，适用于Docker主机和Kubernetes工作负载。 它不提供不限权限的SSH访问给操作员或AI代理，而是暴露明确的工具， 这些工具受<strong>权限、代码强制的防护栏、审批和完整的操作历史</strong>的管辖。 </p> <p align="center"><em>只需启动一次主机，然后在网格和mTLS上操作，无需永久的私有SSH密钥。</em></p> <p align="center"> <a href="https://github.com/LupusMalusDeviant/Whiskers/releases"><img src="https://img.shields.io/github/v/release/LupusMalusDeviant/Whiskers?color=orange" alt="发布版本" /></a> <a href="#roadmap--beta"><img src="https://img.shields.io/badge/status-beta-yellow.svg" alt="状态" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="许可证：Apache 2.0" /></a> <a href="https://dotnet.microsoft.com/"><img src="https://img.shields.io/badge/.NET-10.0-512BD4.svg" alt=".NET" /></a> <a href="https://learn.microsoft.com/aspnet/core/blazor/"><img src="https://img.shields.io/badge/Blazor-Server-512BD4.svg" alt="Blazor" /></a> </p> > ⚠️ **测试版.** Whiskers正在积极开发中，尚未达到API稳定。 > 请在受信任的网络上运行，审查[安全策略](SECURITY.md)，并在`1.0`版本之前预期会有破坏性更改。 --- ## 为什么选择Whiskers AI代理可以操作基础设施——但通常的方式是提供SSH密钥或shell，这授予的权限远远超过任何单个任务的需求。Whiskers在两者之间提供了一个受控层： - **限制操作员或代理可以执行的操作。** API密钥、角色和明确的工具访问定义了可用的能力集——没有任意shell。 - **在产生影响之前需要审批。** 代码强制的防护栏允许、阻止或暂停敏感操作以供人类确认。 - **准确知道发生了什么。** 代理历史和审计日志记录执行者、决策、目标、参数（机密已编辑）和结果。 相同的控制平面适用于Docker、Kubernetes、日志、部署、服务和CVE上下文——但这种覆盖范围是证据，而非卖点。卖点是**受控、可追溯的操作**。请参阅[文档/产品/定位.md](docs/product/POSITIONING.md)以获取完整的定位信息。 ### 治理如何工作 ```mermaid flowchart LR H[人类操作员] A[AI代理] CP[Whiskers控制平面] AUTH[身份验证和权限] GR[代码强制的防护栏] AP[人类审批] TOOLS[明确的基础设施工具] INFRA[Docker / Kubernetes / 主机] AUDIT[代理历史和审计日志] H --> CP A --> CP CP --> AUTH AUTH --> GR GR -->|允许| TOOLS GR -->|确认| AP AP -->|已批准| TOOLS GR -->|阻止| AUDIT TOOLS --> INFRA TOOLS --> AUDIT AP --> AUDIT ``` --- ## 目录 - [快速入门](#快速入门) - [英雄工作流](#英雄工作流) - [功能](#功能) - [架构和安全](#架构和安全) - [MCP服务器](#mcp服务器) - [AI代理（可选）](#ai代理（可选）) - [配置](#配置) - [截图](#截图) - [路线图和测试版](#路线图和测试版) - [项目结构](#项目结构) - [开发](#开发) - [贡献](#贡献) - [许可证](#许可证) --- ## 快速入门 > 从**v0.12.0**开始，发布多架构镜像（amd64 / arm64）到**`ghcr.io/lupusmalusdeviant/whiskers`**。在此版本之前，请使用从源代码开始的路径。 ### 快速 - 一个命令 ```bash # 安装程序：拉取镜像，写入一个小的docker-compose文件到./whiskers/，等待健康，打印URL。 curl -fsSL https://raw.githubusercontent.com/LupusMalusDeviant/Whiskers/main/deploy/install.sh | bash # ... 或一个裸docker运行： docker run -d --name whiskers -p 127.0.0.1:5100:8080 \ -v whiskers-data:/app/data -v /var/run/docker.sock:/var/run/docker.sock \ ghcr.io/lupusmalusdeviant/whiskers:latest ``` 打开`http://127.0.0.1:5100`。安装程序接受`--port`、`--bind`、`--data`、`--yes`（`install.sh --help`）；重新运行它会更新到位（`pull` + `up`）。 ### 标准 - Docker Compose 下载`docker-compose.yml`文件从[最新版本](https://github.com/LupusMalusDeviant/Whiskers/releases)（已经固定到镜像），然后`docker compose up -d`。可选设置放在旁边的`.env`文件中 - **所有内容都是可选的**，Whiskers在没有它们的情况下运行（参见[.env.example](.env.example)）。 应用程序默认监听`127.0.0.1:5100`（`HOST_BIND` / `HOST_PORT`），除非您更改绑定，否则永远不会公开绑定。 ### 首次登录 在首次启动时，**引导设置向导**在浏览器中创建管理员帐户 - 不需要`.env`和配置文件。从那时起，您使用该**本地登录**（电子邮件+密码）登录。替代方案：使用`WHISKERS_ADMIN_EMAIL` + `WHISKERS_ADMIN_PASSWORD_FILE`预设管理员无人值守；使用**Google**或**通用OIDC**（参见[配置](#配置)）；或者，对于仅限本地的试用，`AUTH_DISABLED=true`（永远不要在公共绑定上）。 ### 更多安装选项 <details> <summary>在Nginx反向代理后面</summary> ```nginx location /serverwatch/ { proxy_pass http://127.0.0.1:5100/serverwatch/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Prefix /serverwatch; proxy_read_timeout 300s; proxy_buffer_size 128k; proxy_buffers 4 256k; } ``` 在子路径下提供服务时，在`.env`中设置`PATH_BASE=/serverwatch`。 </details> <details> <summary>部署配置文件（完整vs.强化）</summary> - **完整**（`docker-compose.yml`，默认）：特权+主机PID命名空间，以便Whiskers可以管理**其自身**主机（防火墙/Nginx/systemd/`execute_command`通过`nsenter`）并运行容器内VPN。 - **强化**（`docker-compose.hardened.yml`）：仅用于监视**远程**主机 - 非root，无`特权`，丢弃功能，根文件系统只读，Docker访问通过动词限制的socket代理。交易本地主机shell管理以获取更小攻击面。 参见 **[docs/container-hardening.md](docs/container-hardening.md)** 获取完整矩阵和权衡。 </details> <details> <summary>Kubernetes（Helm）</summary> 在集群上运行Whiskers **作为**控制平面，用于您的远程Docker舰队（和Kubernetes集群 - 仪表板上的容器和Pod并排出现）： ```bash helm install whiskers oci://ghcr.io/lupusmalusdeviant/charts/whiskers \ --set vault.key="$(openssl rand -hex 32)" kubectl port-forward svc/whiskers 8080:8080 # → http://localhost:8080 （设置向导） ``` 单副本设计（Blazor Server +状态循环），非root，只读根文件系统，PVC支持数据。所有值，入口/WebSocket注释和Postgres变体： **[deploy/helm/whiskers/README.md](deploy/helm/whiskers/README.md)**。要**管理**集群中的集群，请参见 **[deploy/k8s/README.md](deploy/k8s/README.md)**。 </details> <details> <summary>从源代码（开发）</summary> ```bash git clone https://github.com/LupusMalusDeviant/Whiskers.git cd Whiskers docker compose up -d # 在本地构建镜像 ``` 复制[.env.example](.env.example)到`.env`以覆盖默认值。`.env`被gitignore - 机密永远不会进入存储库。 </details> --- ## 英雄工作流 定义产品的流程 - **观察 → 提出 → 检查策略 → 请求批准 → 执行 → 验证 → 审计**： 1. 容器/工作负载 **不健康**。 2. 代理使用**读取**范围的密钥分析状态和日志 - 不需要写入访问。 3. 代理 **提出重启**。 4. 活动防护栏将重启工具评级为**确认**，因此尚未执行任何操作。 5. Whiskers 引发 **审批请求**：执行者、工具、目标服务器、目标工作负载、编辑参数、理由和到期日。 6. 人类 **批准**。 7. Whiskers 执行 **仅**批准的操作，具有批准的参数。 8. Whiskers **验证**工作负载之后。 9. **代理历史**和**审计日志**显示完整链条，UI在结果、批准和历史之间深度链接。 这是AI操作入职和治理的参考工作流程和验收测试。 --- ## 功能 Docker、Kubernetes等是**目标**，控制平面通过它们可以执行以下操作： ### 治理 - **每个密钥的权限** - MCP API密钥范围为读取/写入/管理员，或明确的工具列表。 - **代码强制的防护栏** - 每个工具 **允许/确认/阻止**，在工具边界（不在提示中）评估，“最严格的赢家”。 - **人类在环中的审批** - `确认`工具暂停执行，直到授权用户批准确切的操作+参数。 - **代理历史** - 记录每个代理工具调用：执行者/密钥、编辑参数、决策、结果、持续时间、目标。 - **审计日志** - 记录每个用户操作，具有可过滤的历史记录。 ### 操作 - **容器** - 所有主机上的实时仪表板（CPU /内存/健康状况）；启动/停止/重启/删除；日志、统计数据、健康报告；按服务器、Compose项目和自由表单**标签**分组。 - **Kubernetes** - 通过kubeconfig添加k3s/Kubernetes集群（存储在vault中加密）；pod在容器旁边出现，具有所有者分组、日志和诚实的扩展/滚动操作。 - **主机管理** - 防火墙（ufw）、Nginx站点、systemd服务、SSL证书和集成的Web终端（主机和容器）。 - **部署** - 部署表单、Compose上传、精选的应用模板、镜像搜索跨注册表，和 **git部署**（repo → 克隆/构建/组成目标主机；通过HMAC签名Webhook触发重新部署）。 ### 安全 - **CVE扫描** - 操作系统和容器镜像（Trivy）具有重复查找的仪表板、严重性和年龄。 - **机密保管库** - 存储的机密在静止时加密（AES-256-GCM）；在日志和持久性之前编辑敏感值。 - **强制HMAC Webhook机密** (`X-Hub-Signature-256`兼容）和 **关闭失败授权** - 每个端点都需要身份验证，除非它明确选择退出。 - **SSH主机密钥验证** （信任首次使用）在每个ssh路径上。 - **网格 + mTLS** 稳态操作（参见[架构和安全](#架构和安全））。 ### 弹性 - **自我备份和恢复** Whiskers自己的数据 - 可选VAULT_KEY加密（AES-256-GCM），可调度，崩溃安全延迟交换恢复。 - **镜像更新回滚** - 每次更新前的快照；仪表板上一键恢复。 - **监控和警报** - 历史CPU/RAM/磁盘指标、健康报告，以及容器不健康/停止/OOM/重启循环/新CVE/可用镜像更新的通知（Mattermost、Matrix、Telegram、ntfy、Discord、Slack、Email/SMTP、通用Webhook），具有持久的应用内日志记录。 ### 集成 - **MCP服务器** - 外部AI客户端的身份验证接口（参见 [MCP服务器](#mcp服务器)）。 - **云控制（带外）** - 提供商无关的电源/快照/指标（Hetzner、Hostinger）通过提供商API，即使SSH/Docker暂时无法访问。 - **注册表** - vault中的私有注册表凭证，在身份验证拉取时自动使用。 - **数据库** - SQLite（零配置）或PostgreSQL通过Entity Framework Core。 - **UI** - 浅色/深色/系统主题和完全本地化的 **英语（默认）/德语** 接口。 --- ## 架构和安全 Whiskers通过三个独立的平面管理主机，每个平面在稳定状态下都移除了SSH： | 平面 | 什么 | 传输 | |---|---|---| | **遥测** | 主机CPU/RAM/磁盘，容器统计数据 | `node_exporter` → VictoriaMetrics（通过网格拉取） | | **Docker控制** | 列出/重启/部署/检查 | Docker Engine API超过 **mTLS** + 动词白名单代理 | | **Shell** | `execute_command`，systemd，journald，编辑 | 一次性特权`nsenter`容器通过相同的mTLS通道 | **一次性启动SSH**连接在启动时建立主机到私有WireGuard网格（Tailscale/NetBird），安装遥测+mTLS Docker代理，然后删除启动凭证。之后，**稳态操作在没有永久私有SSH密钥的情况下运行** - 中央攻击面消失了。完整的设计、PKI（step-ca）、启动流程和权衡在 **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。 ### 安全摘要 - **没有永久SSH密钥** 在稳态下管理的主机；管理端口 **网格绑定**，设计上没有任何管理相关的内容暴露给公共互联网。 - **MCP访问按API密钥限制** （读取/写入/管理员）；执行代理受**代码强制的防护栏**的约束，永远不会超出触发它的用户/客户端的权限。 - **机密** （`.env`、加密的保管库、DB）生活在 `/app/data` / `.env`下，它们都被gitignore并卷挂载 - 永远不会烘焙到镜像中或提交。 - **全仓库安全审查和补丁** （参见 [安全修复的变更日志](docs/reviews/2026-07-07-security-fixes-changelog.md)）：所有关键和高级别的发现，以及大多数中低级别的问题，都已修复 - 每个密钥的基于RBAC的**每个路径**（包括代理和MCP），vault上的 **AES-256-GCM + PBKDF2**，schema通过 **EF Core迁移**，信任关键镜像 **按digest固定**，受限制的转发头信任，以及一个刮刮令牌的`/metrics`。 ### 供应链 每个发布的镜像，从 **v0.12.1**开始： - **扫描后发布** - 发布管道构建镜像，运行Trivy扫描，**如果发现任何CRITICAL问题，则整个运行失败**，从而永远不会推送漏洞镜像； - **构建多架构并提供源代码和SBOM声明** （SLSA源代码和SPDX SBOM附加到镜像，并且作为发布资产的独立SBOM）； - **使用cosign签名[cosign](https://github.com/sigstore/cosign)** （Sigstore）- 签名与发布工作流的GitHub OIDC身份绑定并记录在公共Rekor透明日志中；没有人持有任何签名密钥。 验证签名后运行它： ```bash cosign verify ghcr.io/lupusmalusdeviant/whiskers:0.13.0 \ --certificate-identity-regexp '^https://github.com/LupusMalusDeviant/Whiskers/.github/workflows/release.yml@refs/tags/v0' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com ``` 有效结果意味着镜像由这个仓库的发布工作流程从标签构建 - 而不是重建或篡改。（v0.12.1之前的镜像经过源代码证明，但没有cosign签名。） 如果您发现安全问题，请私下报告 - 参见 [SECURITY.md](SECURITY.md)。 --- ## MCP 服务器 Whiskers 配备了一个集成的MCP服务器，以便AI代理（例如Claude Code）可以操作您的基础设施。将它添加到您的MCP客户端： ```json { "mcpServers": { "serverwatch": { "url": "https://your-server.com/serverwatch/mcp", "headers": { "Authorization": "Bearer <API-KEY>" } } } } ``` **每个API密钥的权限** 被强制执行为读取/写入/管理员。工具范围包括： - **容器**：列出/检查/日志/指标/环境变量，启动/停止/重启/更新 - **服务器和主机**：信息，日志，指标，健康状况总结，`execute_command`（管理员） - **部署**：`deploy_app`，`deploy_compose` - **基础设施**：防火墙，Nginx，systemd，SSL - **数据库**：检测，列出，模式，查询，备份 - **网络**：列出/创建/删除，连接/断开容器 - **日志和警报**：搜索，列出/创建日志警报 - **调度器**：列出/创建/删除/运行调度任务 - **CVE和更新**：服务器/容器CVE摘要，更新状态 - **云（带外）**：Hetzner和Hostinger电源/快照/指标 - **代理**：`instruct_agent`（委托自然语言任务给进程内代理） 完整的当前列表及权限级别在web UI的 *设置 > MCP* 下。 --- ## AI 代理（可选） 除了MCP服务器（为外部代理服务）之外，Whiskers还有一个 **进程内代理**：您可以描述一个操作任务，用自然语言描述，它使用Whiskers自己的工具进行规划和执行。它支持多个LLM提供商（OpenAI，OpenRouter，Ollama，Gemini，Anthropic和Claude Code），在UI中可供选择。可选的 **只读顾问聊天** 也可用 - 它解释和建议但不运行任何操作。 它的安全模型在代码中强制执行，而不是在提示中： - **防护栏**（单独的管理员专用`guardrails.json`）定义了不可避免的允许/确认/拒绝规则，在工具边界处评估，“最严格的赢家”。 - 代理 **继承触发它的用户**（Web用户或MCP密钥）的权限，并且永远不能超过它们。 - **混合自主性**：读取自主运行；写入/管理员操作需要确认。 参见 [src/Whiskers/Services/Agent/](src/Whiskers/Services/Agent/) 获取实现信息。 ## 配置 Whiskers 完全通过环境变量（`.env`）进行配置；**所有配置都是可选的**。最重要的组： | 组 | 键 | 备注 | |---|---|---| | 身份验证 | `GOOGLE_CLIENT_ID`，`GOOGLE_CLIENT_SECRET`，`GOOGLE_ADMIN_EMAIL`，`AUTH_DISABLED` | 设置 `AUTH_DISABLED=true` 以适用于 Google 拒绝私有重定向 URI 的受信任的仅限局域网部署 | | 管理员引导 | `WHISKERS_ADMIN_EMAIL` | 在首次运行时作为 **管理员** 播种（与提供程序无关；`GOOGLE_ADMIN_EMAIL` 对 Google 执行相同操作），因此全新实例永远不会没有管理员。同时，如果存在任何角色，则电子邮件白名单 **关闭**。 现有安装（带有 `roles.json`）不受影响。 | | 本地登录 | `WHISKERS_ADMIN_PASSWORD_FILE`，`Auth__LocalLogin__Enabled` | 无需 IdP 的用户名/密码登录（ASP.NET Identity，其在同一数据库中的表）。 默认启用；设置 `Auth__LocalLogin__Enabled=false` 以仅限联合身份验证。 密码策略：最小 12 个字符。 | | 机密保险库 | `VAULT_KEY` | 静止加密存储的机密（AES-256-GCM）。 留空 = 禁用保险库。 保持稳定 — 丢失它使得存储的机密无法解密 | | OIDC（可选） | `OIDC_ENABLED`，`OIDC_AUTHORITY`，`OIDC_CLIENT_ID`，`OIDC_CLIENT_SECRET`，... | 通用 OpenID Connect（Authentik，Keycloak，Authelia，Zitadel，...）适用于来自 IdP 的真正 2FA/通行密钥 | | 通知 | `MATTERMOST_WEBHOOK_URL`，`MATTERMOST_ENABLED` | 矩阵在 UI 中配置 | | 路由 | `PATH_BASE` | 在子路径下反向代理时的路径前缀 | | AI 聊天 | `AICHAT_ENABLED`，`AICHAT_API_KEY`，`AICHAT_API_URL`，`AICHAT_MODEL`，`AICHAT_PROVIDER` | 只读顾问聊天 | | 代理 | `AGENT_ENABLED`，`AGENT_PROVIDER`，`AGENT_MODEL`，`AGENT_API_KEY`，... | 代理（见上文） | | 网格 VPN | `VPN_PROVIDER`，`TAILSCALE_AUTHKEY`，`NETBIRD_SETUP_KEY`，... | 可插拔 VPN 启动（`none`/`tailscale`/`netbird`）；留空 = 传统容器内 Tailscale | | 镜像搜索 | `HARBOR_URL`，`HARBOR_USERNAME`，`HARBOR_PASSWORD` | 添加自托管 Harbor 市场（Docker Hub + GHCR 默认启用） | | 主机绑定 | `HOST_BIND`，`HOST_PORT` | 容器始终在内部监听 `8080` | | 数据目录 | `WHISKERS_DATA_DIR` | SQLite、JSON 存储、密钥和证书的根目录（默认 `/app/data`）；指向任意卷/主机路径 | | 数据库 | `WHISKERS_DB_PROVIDER`，`WHISKERS_DB_CONNECTION`，`WHISKERS_DB_CONNECTION_FILE` | `sqlite`（默认，零配置）或 `postgres`。 对于 Postgres，设置连接字符串，或将其作为文件挂载并指向 `_FILE`。 即用即配覆盖：`deploy/docker-compose.postgres.yml`。 | 有关完整注释列表，请参阅 [.env.example](.env.example)。 ### 值得注意的运行时详细信息 - **电子邮件白名单**：在 UI 的 *设置 > 身份验证* 下管理；更改立即生效，无需重启。 - **MCP API 密钥**：在首次启动时自动生成并写入 `initial-mcp-key.txt`（模式 `0600`，位于数据卷中的 `api-keys.json` 旁边） — **不** 记录到日志中，日志仅记录文件路径。 检索它，然后删除文件。 - **数据持久性**：指标数据库（默认 SQLite，或 PostgreSQL）、JSON 存储和证书位于数据目录（`WHISKERS_DATA_DIR`，默认 `/app/data`）；永远不会在镜像中。 - **健康探测**：匿名 `/healthz`（活动性）和 `/readyz`（就绪性）端点；镜像附带 Docker `HEALTHCHECK`，Kubernetes 可以使用它们作为探测。（`/health` without the `z` 是应用内状态页面。） ### 技术栈 | 层 | 技术 | |---|---| | 后端 | C# / .NET 10 / ASP.NET Core | | 前端 | Blazor Server + [MudBlazor](https://mudblazor.com/) | | Docker API | [Docker.DotNet](https://github.com/dotnet/Docker.DotNet) | | 数据库 | SQLite（零配置默认）或 PostgreSQL（Entity Framework Core）+ JSON 文件存储 | | 身份验证 | 本地帐户（ASP.NET Identity），Google OAuth 2.0 或通用 OIDC + 角色和电子邮件白名单 | | 实时 | SignalR | | MCP | [ModelContextProtocol.AspNetCore](https://github.com/modelcontextprotocol) | | 指标 | VictoriaMetrics（兼容 Prometheus） | --- ## 屏幕截图 下面的屏幕截图跟踪治理模型从头到尾 — **受控访问**，**强制治理**，**完整的可追溯性**。 项目网站上有关于 hero 工作流程（不健康的 workload → 代理分析 → 护栏决策 → 批准 → 执行 → 审计跟踪）的实时演练： **[whiskers.app.lupusmalus.dev](https://whiskers.app.lupusmalus.dev)**，应用内手册（*帮助*）包含每个部分的屏幕截图。 **护栏 — 强制治理。** 在工具边界（不在提示中）检查的代码强制执行、不可绕过的策略：只读终止开关、允许的最高级别、受保护的资源和禁止的参数模式。  **代理历史记录 — 受控访问。** 每个代理/MCP 工具调用，带有执行者、权限级别（读取/写入/管理员）、护栏判决（允许/确认/拒绝）、持续时间和结果。  **审计日志 — 完整的可追溯性。** 审批和执行轨迹：谁批准了什么、哪个操作被护栏阻止、以及导致的结果。  **安全 AI 操作 — 受控的起点。** 连接客户端、铸造最小特权只读密钥并激活启动器护栏预设（仅观察 / 安全操作 / 需要批准）。  **仪表盘 — 范围。** 跨 Docker 主机和 Kubernetes 工作负载的实时状态，带有实时主机指标 — 治理模型所在表面。  > 屏幕截图是针对匿名演示数据集捕获的。 有关脚本演练，请参阅 [docs/product/demo-script.md](docs/product/demo-script.md)，有关每个图像的复制，请参阅 [docs/product/screenshots.md](docs/product/screenshots.md)。 --- ## 路线图和测试版 测试版功能丰富但尚未完成。 计划/尚未实现： **帐户和角色** - 2FA（TOTP）和通行密钥用于本地登录；更细粒度的每服务器角色/团队。 **监控和触发器** - 适当的流量/异常检测和专用的“极端流量”触发器（今日：持续 CPU/RAM/磁盘阈值 + 简单的滚动 z 分数异常值）。 **舰队和部署** - 实时 Docker 事件（而非轮询）；在就地编辑资源限制；更丰富的 Compose 模板。 - Kubernetes track B.3：**exec 终端**，MCP 工具用于 pod，metrics-server 统计信息（管理和 k3s 集群 + 通过 Helm 在 Kubernetes 上运行 **已在 0.12 中发布**）。 **代理治理**（基于已发布的 Agent-History、审批/人为干预和丰富的聊天小部件） - 将审批扩展到 **阻止外部/直接 MCP 调用** — 今日人为干预门户涵盖进程内代理；直接 `tools/call` 请求被记录但不被批准。 - 审批卡中的工具 **差异**（显示写入的确切更改）。 - 完整的 **rich-widget / MCP-Apps** 目录，超越精选图表 + 状态卡。 **强化和弹性** - **紧急恢复**：通过 step-ca 发出的短时 SSH 证书，作为可审计的紧急访问路径，当正常控制平面不可用时。 - **Distroless/chiseled "remote" 镜像**，适用于强化配置文件（已锁定容器配置文件和可插拔 Tailscale/NetBird VPN — 参见 [docs/container-hardening.md](docs/container-hardening.md)）。 有请求？开启一个问题。 --- ## 项目结构 每个源文件夹都有自己的 `README.md`，描述其中的文件。 高级地图： ``` Whiskers/ ├── src/ │ ├── Whiskers/ # 应用程序 │ │ ├── Components/ # Blazor UI（页面、布局、共享） │ │ ├── Configuration/ # 强类型设置类 │ │ ├── Hubs/ # SignalR 中心（容器 + 终端流） │ │ ├── Mcp/ # MCP 服务器工具 + 权限层 │ │ ├── Models/ # 数据模型（代理、云、CVE、Hetzner、Hostinger） │ │ ├── Services/ # 所有业务逻辑（参见 Services/README.md） │ │ ├── Utils/ # 小助手（机密隐藏、shell 引用） │ │ ├── wwwroot/ # 静态资产 │ │ └── Program.cs # 组合根（DI、中间件、MCP、身份验证） │ └── Whiskers.Tests/ # xUnit 测试套件 ├── deploy/telemetry/ # 网格/mTLS 部署模板（node_exporter、VictoriaMetrics、Tailscale ACL） ├── docs/ARCHITECTURE.md # 无 SSH 密钥架构 ├── docs/product/ # 产品定位（参见 docs/product/POSITIONING.md） ├── Dockerfile ├── docker-compose.yml └── README.md ``` `Services/` 树是应用程序的核心 — 参见 [src/Whiskers/Services/README.md](src/Whiskers/Services/README.md) 以获取引导游览。 ### 代码约定 - **接口优先**：服务在 `IFoo` 接口后定义，并在 DI 中注册；使用者依赖于接口。 - **代码注释和 XML 文档** 中使用英文；面向用户的 UI 是本地化的（默认英文，德语可用）。 --- ## 开发 需求：[.NET 10 SDK](https://dotnet.microsoft.com/download)。 ```bash # 构建 dotnet build src/Whiskers/Whiskers.csproj # 运行测试 dotnet test src/Whiskers.Tests/Whiskers.Tests.csproj # 本地运行（监听 :8080） dotnet run --project src/Whiskers/Whiskers.csproj ``` --- ## 贡献 欢迎提出问题和拉取请求。 请： - 保持接口优先的更改，并添加/扩展 `src/Whiskers.Tests/` 下的测试； - 在打开拉取请求之前运行 `dotnet build`（0 警告）和 `dotnet test`； - 在代码注释和文档中编写英文。 --- ## 许可证 Apache License 2.0，参见 [LICENSE](LICENSE)。 版权所有 © 2026 Whiskers Contributors