mirror of
https://github.com/Melorise/nPanel.git
synced 2026-11-07 14:49:35 +00:00
206 lines
11 KiB
Markdown
206 lines
11 KiB
Markdown
# NixOS 上的 nPanel：设计与执行计划
|
||
|
||
## 状态
|
||
|
||
本文档记录 nPanel 的已批准设计、执行边界与实施结果。实现位于本仓库：独立
|
||
Flake 只将 `nixpkgs` 作为输入，应用源码为当前项目的 `self`。
|
||
|
||
## 产品定义
|
||
|
||
nPanel 是独立维护的、源自社区版 1Panel 的 NixOS 单机 Docker 服务器运维面板。它保留 Docker 运维面板的核心价值，同时将 NixOS 的声明式系统配置完全保留在用户自己的 Flake 中。
|
||
|
||
用户在既有配置中引入 nPanel 提供的 NixOS 模块，并自行启用所需的 Docker 运行时。nPanel 不生成、发现、编辑、迁移或接管用户的 Flake、`hardware-configuration.nix`、存储布局或模块组织方式。
|
||
|
||
从概念上说，用户配置只需处理部署事项，例如：
|
||
|
||
```nix
|
||
{
|
||
imports = [ inputs.npanel.nixosModules.default ];
|
||
|
||
virtualisation.docker.enable = true;
|
||
services.nPanel = {
|
||
enable = true;
|
||
securityEntrance = "npanelAccess";
|
||
};
|
||
}
|
||
```
|
||
|
||
`services.nPanel.port` 与 `services.nPanel.securityEntrance` 是服务访问面的声明式
|
||
配置。它们在每次 core 启动时覆盖 nPanel 内部数据库，面板不提供修改入口。以上示例
|
||
不意味着用户需要按任何特定方式重组其配置文件。
|
||
|
||
## 所有权边界
|
||
|
||
### 用户拥有的 NixOS 配置
|
||
|
||
用户配置仍是下列持久化系统策略的唯一权威来源：
|
||
|
||
- Docker 守护进程的配置与启用；
|
||
- 防火墙、网络、DNS、主机名、时间同步、sysctl 与内核选项；
|
||
- SSH 守护进程配置、用户、授权密钥与服务启用；
|
||
- 磁盘布局、加密、文件系统、挂载、交换分区与引导配置；
|
||
- 持久化 systemd 单元的定义与启用。
|
||
|
||
nPanel 不得写入 `daemon.json`、`sshd_config`、`fstab`、systemd 单元文件、防火墙规则集、`/etc/sysctl.conf` 或任何用户配置源文件。
|
||
|
||
### nPanel 拥有的可变状态
|
||
|
||
nPanel 保留自己的数据库、应用定义、备份、任务记录、日志、上传数据、Compose 项目及其他运行时状态，并统一存放于其配置的状态目录。这些数据是可变应用数据，而不是 Nix 配置。
|
||
|
||
### 仍由 nPanel 承担的运行时操作
|
||
|
||
Nix 配置不能替代日常运维。下列功能保留在 nPanel 范围内：
|
||
|
||
- Docker、Compose、容器、镜像、网络、卷、镜像仓库、模板与日志；
|
||
- 应用商店、已安装应用、网站、运行时、反向代理、数据库、SSL 与 AI；
|
||
- 仪表盘、主机监控、资源历史、进程查看与进程终止；
|
||
- 用于运维数据与故障处理的 root 级文件操作。Nix store 与 `/etc` 生成链接等路径由系统权限拒绝写入；在未知用户 Flake 位置的前提下，面板不能自动识别和保护任意用户配置文件；
|
||
- 本地与远程 SSH 终端、容器终端与数据库终端；
|
||
- systemd 单元状态、journal 查看，以及运行时的启动、停止、重启与重载操作；
|
||
- 备份、恢复、告警与 1Panel 领域内的计划任务。
|
||
|
||
Docker socket 在实际效果上等同于 root 权限。因此，即使移除了系统配置类功能，nPanel 的认证、审计、Unix socket 传输和服务加固仍必须按特权控制平面设计。
|
||
|
||
## 删除或限制的功能
|
||
|
||
### 删除持久化系统配置功能
|
||
|
||
- 防火墙管理与规则持久化。
|
||
- SSH 守护进程配置、SSH 密钥归属和 SSH 服务启用变更。
|
||
- 磁盘分区、格式化、持久化挂载、卸载和交换配置。
|
||
- 主机名、DNS、hosts、时区、NTP、密码、sysctl、内核和持久化网络配置页面。
|
||
- 会持久化修改 Docker daemon 配置的功能，包括镜像仓库、镜像加速、IPv6、日志驱动和 socket 路径配置。
|
||
- systemd 单元编辑，以及启用和禁用操作。
|
||
- 会持久化改变主机策略的计划任务类型。
|
||
|
||
可在有价值时保留只读状态视图；不宣称接管 NixOS 持久化配置的运行时操作仍可保留。
|
||
|
||
### 删除的独立系统管理产品
|
||
|
||
- 脚本库及其共享脚本引用。
|
||
- 主机监控守护、FTP 服务、Fail2ban、ClamAV 和全主机清理工具。
|
||
- 系统快照功能，其存储和恢复语义与用户自行管理的 NixOS 和文件系统配置重叠。
|
||
|
||
Docker 专项清理和 1Panel 应用清理仍保留在范围内。
|
||
|
||
### 商业、企业与高级发行版功能
|
||
|
||
删除全部商业和企业功能，以及每一个可见入口、路由、API 注册、启动钩子、迁移初始数据和升级提示。
|
||
|
||
范围包括：
|
||
|
||
- 许可证、版本、定价、试用、升级至 Pro 和企业授权流程；
|
||
- XPack 菜单及其全部子项：WAF、多节点或节点管理、集群、同步、用户页、防篡改、UPage、XPack 设置和增强监控；
|
||
- 企业用户、运维报告和虚拟机管理；
|
||
- 企业 AI 代理、Skills Hub 和基准测试入口；
|
||
- 跨节点选择器、`CurrentNode` / `operateNode` 前端交互、多节点代理、同步与节点元数据；
|
||
- XPack 路由加载、仅为企业兼容性存在的社区占位实现，以及会写入 XPack 菜单的迁移逻辑。
|
||
|
||
基础 OSS 告警与保留的单节点功能不得仅因现有代码引用 XPack 兼容辅助函数而被删除；实施时应将这些调用点与纯企业行为分离。
|
||
|
||
## 命名与品牌规则
|
||
|
||
- 面向用户展示的产品名为 `nPanel`。
|
||
- 新增文件、Nix 选项、systemd 单元、软件包名、命令和新引入的代码标识符，按语言和平台约定使用 `nPanel` 或 `npanel` 命名。
|
||
- 现有上游实现标识符、Go 模块导入路径、数据库 schema、迁移键、协议兼容字段和不值得为品牌更改而冒兼容性风险的应用行为，可以保留 `1Panel`。
|
||
- 所有可见的前端品牌、默认 Logo、页面标题、翻译文本中的产品名称和可见元数据均改为 `nPanel`。
|
||
- GPLv3 许可证文本以及必要的上游版权与归属声明必须保留。
|
||
|
||
## 外部链接与社区内容
|
||
|
||
nPanel 不向用户导向上游社区或商业站点。删除：
|
||
|
||
- 论坛和讨论链接；
|
||
- 上游使用手册与文档链接；
|
||
- 上游 GitHub 项目、Issue、Star、定价、版本、厂商和产品链接；
|
||
- 页脚和关于页面中的上游公司链接；
|
||
- 登录页的社区许可证同意复选框、对话框、校验逻辑及关联的上游许可证 URL。
|
||
|
||
仓库中的项目许可证文件保留。移除登录点击同意不改变软件仍受 GPLv3 约束这一事实。
|
||
|
||
应用商店与资源端点需要单独进行兼容性审计：只要它们是保留 Docker 应用生态所必需的，就不自动删除；但 UI 不得展示上游品牌、商业、支持或社区链接。
|
||
|
||
应用商店使用单独的内部兼容级别 `v2.2.3`。它表示 nPanel 已审计应用目录及其版本门槛所需的上游协议基线，不是 nPanel 的产品版本，也不写入用户配置或开放给用户覆盖。nPanel 的产品版本仍独立维护。该级别会与缓存的应用目录一起记录；级别变化强制刷新目录详情，不能因远端目录时间戳未变而继续使用按旧规则筛选的缓存。
|
||
|
||
## 架构
|
||
|
||
### 打包与服务布局
|
||
|
||
NixOS 模块从本项目源码打包 core、agent 和前端，并提供：
|
||
|
||
- 来自 Nix store 的不可变可执行文件与前端静态资源；
|
||
- 可配置的状态目录和运行时目录；
|
||
- core 和 agent 的 systemd 单元；
|
||
- 仅本机可用、经过认证的 core 到 agent 通信；
|
||
- 明确的 Docker socket 访问权限；
|
||
- 不再依赖安装器管理的 `/usr/local` 二进制文件，也不保留自行更新路径。
|
||
|
||
### 权限模型
|
||
|
||
浏览器与 core 通信；需要本机运行时权限的操作经由 Unix socket 流向 agent。服务以 root 运行，因为 Docker socket 本身等同 root 权限；agent 不暴露 TCP 管理端点。
|
||
|
||
## 执行计划
|
||
|
||
### 阶段 0：基线与兼容性清单
|
||
|
||
1. 记录当前上游修订、构建输入、生成资源和测试命令。
|
||
2. 枚举硬编码的可变路径、安装器假设、自更新路径和服务生命周期调用。
|
||
3. 追踪全部保留的 Docker 与应用流程，识别所需主机二进制和运行时权限。
|
||
4. 建立保留、删除和只读功能的路由/API 对照表。
|
||
|
||
退出条件：实施清单将每一个删除的前端入口映射到对应后端路由和启动/迁移行为。
|
||
|
||
### 阶段 1：产品身份与上游脱钩
|
||
|
||
1. 引入 nPanel 品牌资源，替换可见前端品牌和默认标题。
|
||
2. 删除上游社区、手册、仓库、厂商、定价与支持链接。
|
||
3. 删除登录许可证同意 UI 和客户端校验，但不改动仓库 GPLv3 许可证。
|
||
4. 删除商业/企业路由加载器、页面、菜单、提示、API 客户端和迁移初始数据。
|
||
5. 验证生产前端除产品 UI 外所需的法律归属声明外，不再出现可见 `1Panel` 品牌或上游社区 URL。
|
||
|
||
退出条件：前端类型检查与构建通过，且任何被删除路由均不能通过 URL 访问。
|
||
|
||
### 阶段 2：功能范围收缩
|
||
|
||
1. 删除持久化主机配置路由及其 agent 路由注册。
|
||
2. 删除独立系统产品路由、脚本库路由、模型与执行路径。
|
||
3. 保留运行时监控、文件、进程控制、终端、Docker/应用管理、备份和保留的任务行为。
|
||
4. 将当前会写入持久化主机配置的保留视图改为只读诊断视图，或直接删除。
|
||
|
||
退出条件：保留 API 无法调用防火墙、SSH 配置、fstab、daemon 配置或其他被禁止的持久化系统写操作。
|
||
|
||
### 阶段 3：Nix 打包与 NixOS 模块
|
||
|
||
1. 新增 nPanel Flake，提供软件包和 NixOS 模块。
|
||
2. 无需上游安装器即可构建 core、agent 和前端。
|
||
3. 以 NixOS 状态/运行时路径替换可变路径和 socket 假设。
|
||
4. 定义 systemd 单元、所有权、状态目录处理、Docker socket 访问与符合保留运行时功能的沙箱策略。
|
||
5. 禁用或删除全部自更新与二进制替换行为。
|
||
|
||
退出条件：干净的 NixOS 虚拟机可在普通用户自己维护的 Flake 中启用 Docker 和 nPanel，而 nPanel 不会写入用户配置源文件。
|
||
|
||
### 阶段 4：功能集成与加固
|
||
|
||
1. 验证应用商店、Compose 安装生命周期、容器、网站、数据库、备份、文件、终端、监控、进程与日志。
|
||
2. 验证文件管理器对不可变路径的行为，尤其是 `/nix/store` 与生成的 `/etc` 符号链接。
|
||
3. 验证 core/agent 认证、socket 权限、CSRF/session 行为与审计日志。
|
||
4. 删除运行时路径中的上游更新检查和外部商业/社区调用。
|
||
|
||
退出条件：面板可完成保留的运行时操作，而被禁止的主机配置修改不存在，且不能通过隐藏 API 访问。
|
||
|
||
### 阶段 5：回归、文档与发布准备
|
||
|
||
1. 为路由删除、品牌、路径策略与服务配置补充聚焦测试。
|
||
2. 运行前端 lint/类型检查/构建、Go 测试、Nix 求值/构建和 NixOS VM 冒烟测试。
|
||
3. 更新项目文档，说明确切的 NixOS 安装模块和受支持范围。
|
||
4. 审计源代码与构建后的前端资源，检查被删除的 URL、XPack 路由和可见 `1Panel` 品牌。
|
||
|
||
退出条件：项目文档明确其单机 nPanel 范围，并提供可复现的 NixOS 部署路径。
|
||
|
||
## 实施结果
|
||
|
||
- 独立 Flake、可配置状态目录、运行时目录和 systemd core/agent 服务已实现。
|
||
- 前端与后端已移除持久化系统策略、工具箱、脚本库、快照、多节点和商业入口的可达路由。
|
||
- 保留 Docker、Compose、应用、网站、数据库、备份、文件、终端、监控、进程和日志的运行时运维能力。
|
||
- 核心、agent、前端和 Flake 求值必须在发布前持续执行构建与边界审计；NixOS VM 冒烟测试是发布门槛，本轮受限修正不执行 VM 测试。
|