LeTuR/thurward

# thurward ## 状态 🚧 **架构设计阶段。** 尚无实现代码。 本仓库目前*仅*包含设计文档。架构以一组决策记录 (ADR) 和主题章节文档的形式记录。一旦架构确定，下一阶段将为 unikernel 本身搭建脚手架。 ## 它是什么 - **内联 middlebox 与 NAT。** 位于两个 NIC 之间（LAN ↔ WAN），根据声明式规则转发或丢弃数据包，为 LAN 出口执行 SNAT/masquerade，并为入站服务执行静态 DNAT (port-forward)。 - **基于 source / port / FQDN 的规则。** Source CIDR + destination port + DNS 名称（支持通配符）。DNS-proxy 拦截会诚实地解析 FQDN，并根据响应的 TTL 进行处理。 - **Unikernel，Rust 数据平面。** 基于 [Hermit](https://hermit-os.org) 构建。整个数据路径——解析、conntrack、过滤、NAT、TX 调度——均使用 [Rust](https://rust-lang.org) 和 `smoltcp::wire` 进行类型化数据包解析，在驱动程序和过滤器之间没有镜像内的 TCP/IP socket 层。毫秒级启动，约 MB 级镜像，底层没有通用操作系统。 - **两个 v1 部署目标，一个镜像。** 在 QEMU/KVM 上进行本地开发（`make run`），在 Firecracker 上部署 VPS / 托管主机。Bare-metal 直接启动推迟至 v2。参见 [`docs/architecture/06-deployment.md`](docs/architecture/06-deployment.md)。 - **单一事实来源：一个 git 仓库。** 过滤规则、SNAT 池和 DNAT 条目位于 `rules.yaml` 中，与防火墙源代码并存，并在构建时编译到镜像中。更改规则 = 编辑 YAML → `make build` → 安装。**防火墙上没有运行时管理 API。** 没有单独的“规则仓库”，没有部署控制器，没有 Terraform。 - **用户可验证的供应链。** 可重现的构建、固定的依赖项、cosign 签名的镜像、SLSA-3 来源。操作员在安装前运行 `cosign verify` 和 `slsa-verifier`——在此过程中没有控制器参与。 - **可观测。** 符合 ECS 标准的 JSON 丢弃/接受日志（带有 NAT 转换字段），带有每条规则标签的 Prometheus 指标以及 conntrack / NAT 仪表，每流 OpenTelemetry 追踪。所有出口流量均通过 virtio-vsock 传输至主机端收集器——没有带内遥测流量。 **v1 为单 VM。** HA 和 bare-metal 直接启动均推迟至 v2；如果防火墙崩溃，在重启前将保持默认拒绝状态。参见 [`docs/architecture/09-limitations.md`](docs/architecture/09-limitations.md)。 ## 阅读架构说明 从 [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md) 开始， 然后阅读[决策记录](docs/architecture/decisions/)，接着是主题 章节。 | 章节 | 涵盖内容 | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [00 — 概述](docs/architecture/00-overview.md) | 问题、目标、非目标、词汇表、技术栈一览 | | [01 — 系统上下文](docs/architecture/01-system-context.md) | thurward 外部的内容（客户端、上游 DNS、收集器） | | [02 — 数据包路径](docs/architecture/02-packet-path.md) | NIC → uknetdev → parse → conntrack → filter → NAT → TX | | [03 — 规则模型](docs/architecture/03-rule-model.md) | YAML schema、构建时编译、匹配语义 | | [04 — FQDN 与 DNS](docs/architecture/04-fqdn-and-dns.md) | DNS-proxy 设计、fqdn_set 缓存、TTL 处理 | | [05 — 可观测性](docs/architecture/05-observability.md) | ECS 日志 schema、指标名称、追踪策略、vsock | | [06 — 部署](docs/architecture/06-deployment.md) | QEMU/Firecracker、网桥拓扑、升级流程 | | [07 — 运维](docs/architecture/07-operations.md) | 警报、仪表板、运行手册、安装/回滚 | | [08 — 安全模型](docs/architecture/08-security-model.md) | 威胁模型、攻击面、供应链加固 | | [09 — 限制](docs/architecture/09-limitations.md) | 诚实的清单 | ## 许可证 TBD — 占位符，直到在实现阶段确定所采用的许可证。 ## 发音与命名 `thurward` = `thur`（项目品牌前缀，匹配 *thurbox*、*thurkube*、 *thurspace*、*thurarch*）+ `ward`（防御性动词——*to ward off*）。

标签：Rust, Unikernel, 可视化界面, 架构设计, 用户代理, 网络中间件, 网络地址转换, 网络流量审计, 自定义请求头, 通知系统, 防火墙