foxly-it/rootguard-core

# RootGuard Core  **RootGuard Core 是 RootGuard 自托管 DNS 技术栈背后的已认证控制平面。** 它负责部署和管理 AdGuard Home 与 Unbound，验证配置更改，监控 DNS 链路，并执行带有自动回滚功能的受保护更新。 [](https://github.com/foxly-it/rootguard-core/actions/workflows/ci.yml) [](go.mod) [](LICENSE) [](https://github.com/foxly-it/rootguard) [RootGuard](https://github.com/foxly-it/rootguard) · [官方网站](https://rootguard.foxly.de/) · [架构](https://github.com/foxly-it/rootguard/blob/main/docs/architecture.md) · [路线图](https://github.com/foxly-it/rootguard/blob/main/ROADMAP.md) ## Core 的功能 - 部署受管理的 AdGuard Home 和 Unbound DNS 数据平面。 - 生成、预览、验证、版本控制以及恢复 Unbound 配置。 - 验证 DNS 解析、DNSSEC 拒绝以及受保护的 AdGuard 上游。 - 在服务更新前创建备份，并对失败的替换执行回滚。 - 通过独立的更新路径协调 Core/WebApp 的原子更新。 - 将镜像、挂载点、Compose 内容和可执行命令排除在浏览器输入之外。 ``` Browser → RootGuard WebApp → RootGuard Core → Docker API ├── AdGuard Home └── Unbound ``` ## 本地开发 环境要求：Go 1.26+、Docker Engine 以及本地的 RootGuard 开发环境。 ``` git clone https://github.com/foxly-it/rootguard-core.git cd rootguard-core go test ./... go vet ./... go build ./... ``` 使用随机生成的内部 API token 运行 Core： ``` ROOTGUARD_API_TOKEN="$(openssl rand -hex 32)" go run ./cmd/rootguard ``` Core 默认监听 `8081` 端口。除 `/api/health` 外，所有路由均需要 `Authorization: Bearer `。 如需获取完整的开发技术栈，请克隆 [RootGuard 主仓库](https://github.com/foxly-it/rootguard) 及其子模块，并运行 `docker compose up --build -d`。 ## API 领域 | 领域 | 职责 | | --- | --- | | 安装 | 预检查、持久化进度、受管理的 DNS 部署 | | Unbound | 设置、预览、验证、历史记录、恢复、诊断 | | AdGuard Home | 引导、健康状态、受保护的管理代理 | | 服务生命周期 | Allowlisted 镜像检查、备份、更新、回滚 | | 控制平面 | 配对的 Core/WebApp 更新请求与状态 | 每一项配置更改在激活前都会经过验证。如果 Unbound 无法重启，或者 DNS 链路未通过健康检查，Core 将恢复到之前的已知良好状态。 ## 安全模型 - 采用 token 认证的内部 API，并带有极简的公共健康检查 endpoint。 - 无 UI 渲染，且不接收用户提供的 container 规范。 - 仅限 Allowlisted 的服务、镜像、路径和操作。 - 确定性的配置生成和有界的版本历史记录。 - 支持备份的更新，并带有 DNS 和 DNSSEC 验证。 请参阅项目的[架构文档](https://github.com/foxly-it/rootguard/blob/main/docs/architecture.md)以了解信任边界和网络设计。 ## 贡献指南 在发起 pull request 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。建议从带有 [`good first issue`](https://github.com/foxly-it/rootguard-core/labels/good%20first%20issue) 或 [`help wanted`](https://github.com/foxly-it/rootguard-core/labels/help%20wanted) 标签的 issue 入手。 请按照 [SECURITY.md](SECURITY.md) 中的说明，私下报告安全漏洞。 ## 许可证 RootGuard Core 采用 [GNU AGPL-3.0-or-later](LICENSE) 许可证。该软件许可证不授予使用 RootGuard 或 Foxly IT 名称及徽标的权利。

标签：AdGuard Home, DNS服务器, Docker, EVTX分析, Go, Ruby工具, Unbound, 安全防御评估, 控制平面, 日志审计, 版权保护, 请求拦截, 运维管理