nPanel/docs/nPanel-nixos-design.md

NixOS 上的 nPanel：设计与执行计划

状态

本文档记录 nPanel 的已批准设计、执行边界与实施结果。实现位于本仓库：独立 Flake 只将 nixpkgs 作为输入，应用源码为当前项目的 self。

产品定义

nPanel 是独立维护的、源自社区版 1Panel 的 NixOS 单机 Docker 服务器运维面板。它保留 Docker 运维面板的核心价值，同时将 NixOS 的声明式系统配置完全保留在用户自己的 Flake 中。

用户在既有配置中引入 nPanel 提供的 NixOS 模块，并自行启用所需的 Docker 运行时。nPanel 不生成、发现、编辑、迁移或接管用户的 Flake、hardware-configuration.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 测试。