nPanel/README.md

nPanel

nPanel 是用于 NixOS 单机 Docker 服务器运维的 Web 面板。它是独立维护的 GPLv3 项目，提供 Docker、Compose、应用商店、网站、数据库、备份、文件、终端、监控、 进程与日志等日常运行时运维能力。

nPanel 不编辑、生成、扫描或接管用户的 Flake、hardware-configuration.nix、SSH、 防火墙、磁盘、挂载、Docker daemon 配置或其他持久化 NixOS 系统策略。用户只需在 自己的配置中引入 nPanel 模块，并自行声明 Docker。

NixOS 使用

将本目录作为 Flake input 后，在用户已有的 NixOS 模块中引入：

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

  virtualisation.docker.enable = true;
  services.nPanel.enable = true;
}

可选项：

{
  services.nPanel = {
    stateDir = "/srv/npanel";
    runtimeDir = "/run/npanel";
    initialPasswordFile = "/run/secrets/npanel-initial-password";
  };
}

首次启动时，未提供 initialPasswordFile 则会生成一次性管理员密码并以 0600 权限写入 stateDir/initial-password。账户及密码属于 nPanel 自身的可变状态， 不写入 Nix 配置或 Nix store。

首次启动会额外生成 16 位随机安全入口并以 0600 权限写入 stateDir/initial-entrance。使用 http://127.0.0.1:<port>/<该文件内容> 首次访问； 登录后可在面板安全设置中修改或关闭该入口。

状态与权限

• stateDir 默认是 /var/lib/npanel，存放数据库、Compose 项目、应用数据、上传、备份和日志。
• runtimeDir 默认是 /run/npanel，存放 core 和 agent 的本地 Unix socket。
• agent 需要 Docker socket 访问；Docker socket 在实际效果上等同 root 权限，必须将 nPanel 作为特权控制平面保护。
• NixOS 不可变路径在文件管理器中应被按系统权限拒绝写入，不应由 nPanel 尝试修改。

开发与构建

flake.nix 的应用源码是当前目录的 self；除 nixpkgs 外没有任何源码 input。 前端、core 和 agent 都从本项目源码构建。Nix 固定依赖哈希在首次完整构建后回填， 以保证发布构建可复现。

设计边界与实施计划见 docs/nPanel-nixos-design.md。

许可证

nPanel 以 GNU General Public License v3.0 发布。上游源文件保留其必要的版权与许可证声明。