# nPanel

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

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

## NixOS 使用

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

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

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

可选项：

```nix
{
  services.nPanel = {
    stateDir = "/srv/npanel";
    runtimeDir = "/run/npanel";
    port = 9999;
    securityEntrance = "npanelAccess";
    initialPasswordFile = "/run/secrets/npanel-initial-password";
  };
}
```

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

使用 `http://127.0.0.1:<port>/<securityEntrance>` 访问面板。`port` 与
`securityEntrance` 是 NixOS 声明配置，在每次 nPanel 启动时同步到内部数据库；面板
不会提供修改它们的入口。

## 状态与权限

- `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](docs/nPanel-nixos-design.md)。

## 许可证

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