nPanel/README.md

nPanel

nPanel 是面向 NixOS 单机 Docker 服务器 的 Web 运维面板。它由 1Panel 社区版分叉而来，作为独立的 GPL-3.0 项目维护。

它保留 Docker、Compose、应用商店、网站、数据库、备份、文件、终端、监控、进程和 日志等运行时运维能力；NixOS 的持久化系统策略仍完全由用户自己的 Flake 管理。

项目仍处于预发布阶段。请先在可恢复的主机或测试环境中部署，并为 nPanel 的状态目录 做独立备份。

适用范围

nPanel 适合需要在 NixOS 上保留 Docker 应用生态，同时希望通过图形界面完成日常运行时 运维的单机服务器。

nPanel 管理	用户的 NixOS 配置管理
Docker 容器、镜像、网络、卷、Compose 和应用商店	Docker daemon 的启用与持久化配置
网站、反向代理、运行时、数据库、备份与任务	防火墙、网络、DNS、主机名、时区与内核参数
文件、终端、系统资源、GPU、进程、日志和 systemd 运行时状态	SSH、用户、密钥、磁盘、挂载、交换与引导配置
nPanel 自己的账户、密码、MFA、通行密钥和 API 设置	Flake、模块层次、hardware-configuration.nix 及其他配置源文件

nPanel 不会扫描、生成、编辑或重组你的 Flake，也不会写入 daemon.json、 sshd_config、fstab、防火墙规则、/etc 生成配置或 systemd 单元文件。

快速开始

1. 在 Flake 中引入 nPanel

以下示例使用本地源码树；将 path: 地址替换为你实际使用的 Git 或本地输入地址即可。

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    npanel.url = "path:/absolute/path/to/nPanel";
  };
}

在任意已有的 NixOS 模块中引入模块并启用 Docker：

{ inputs, ... }:

{
  imports = [ inputs.npanel.nixosModules.default ];

  virtualisation.docker.enable = true;

  services.nPanel = {
    enable = true;
    securityEntrance = "npanelAccess";
  };
}

securityEntrance 必须是 5 至 116 位的字母或数字。它是由你声明的访问路径后缀， 不是随机生成值，也不能在面板中修改。

2. 构建并切换世代

在你的 NixOS 配置目录执行常规切换：

sudo nixos-rebuild switch --flake .#<主机名>

模块会启动以下服务：

• npanel-agent.service：执行 Docker、文件、监控、终端等本机运行时操作；
• npanel-core.service：提供 Web 界面和 API。

3. 获取初始账户密码

首次启动默认创建管理员 admin。若未指定密码文件，模块会生成一次性密码：

sudo cat /var/lib/npanel/initial-password

建议通过秘密管理工具显式提供首次密码，避免密码落入状态目录：

{
  services.nPanel = {
    enable = true;
    securityEntrance = "npanelAccess";
    initialUser = "admin";
    initialPasswordFile = "/run/secrets/npanel-initial-password";
  };
}

initialUser 与 initialPasswordFile 只在状态目录首次初始化时生效。之后请在侧栏的 “用户信息”中修改 nPanel 自身的用户名、密码、MFA 或通行密钥。

4. 访问面板

默认端口为 9999：

http://<服务器地址>:9999/npanelAccess

端口和安全入口均来自 NixOS 配置，并会在每次 nPanel 启动时同步到内部状态。若需要 从网络访问，请自行在 Flake 中配置防火墙、反向代理、TLS 和网络策略。

NixOS 模块选项

{
  services.nPanel = {
    enable = true;

    # 面板运行时状态；默认：/var/lib/npanel
    stateDir = "/var/lib/npanel";

    # Unix socket 等易失运行时文件；默认：/run/npanel
    runtimeDir = "/run/npanel";

    # Web 监听端口；默认：9999
    port = 9999;

    # 必填，5-116 位字母或数字
    securityEntrance = "npanelAccess";

    # 仅首次初始化使用；默认：admin
    initialUser = "admin";

    # 仅首次初始化使用；默认：null（生成一次性密码）
    initialPasswordFile = "/run/secrets/npanel-initial-password";

    # 仅首次初始化使用；可选值：zh、en
    language = "zh";
  };
}

stateDir 保存 nPanel 的数据库、Compose 项目、应用数据、上传、备份、任务记录和日志。 它是可变应用数据，不属于 Nix store；迁移或备份服务器时应将其作为独立数据处理。

日常运维

# 服务状态
systemctl status npanel-agent npanel-core

# 查看本次启动日志
journalctl -u npanel-agent -u npanel-core -b

# 跟踪日志
journalctl -fu npanel-agent

# 重启服务
sudo systemctl restart npanel-agent npanel-core

升级 nPanel 输入并执行常规 nixos-rebuild switch 即可。nPanel 不提供面板内自更新， 软件版本始终由你的 Flake lock 和 NixOS 世代决定。

若主机安装并启用了 NVIDIA 驱动，nvidia-smi 位于当前 NixOS 世代的系统命令路径时， nPanel agent 会自动用于 GPU 监控；无需将独立 NVIDIA 包打进 nPanel 配置。

安全模型

nPanel 的 agent 以 root 运行，并访问 Docker socket。Docker socket 在实际效果上等同 root 权限，因此 nPanel 应被视为特权控制平面：

• 为面板设置唯一、不可猜测的 securityEntrance；
• 使用强密码，并启用 MFA 或通行密钥；
• 将面板置于受信网络、反向代理或 VPN 后；
• 仅向必要的网络开放 services.nPanel.port；
• 定期备份 stateDir，并妥善保护首次密码文件和备份凭据。

文件管理、终端和进程控制遵循服务实际权限。Nix store 与由 NixOS 生成的系统路径不应被 面板当作可持久化配置目标。

开发与构建

本仓库是独立 Flake：应用源码为当前目录 self，Flake 输入仅包含 nixpkgs。

# 仅求值模块和包定义
nix flake check --no-build

# 构建完整 nPanel（前端、core 与 agent）
nix build .#npanel

# 分别构建组件
nix build .#npanel-agent
nix build .#npanel-frontend

架构取舍、功能边界与实施记录见 设计文档。

许可证与归属

nPanel 以 GNU General Public License v3.0 发布。项目源自 1Panel 社区版； 上游源文件中必要的版权与许可证声明予以保留。