mirror of
https://github.com/Melorise/nPanel.git
synced 2026-11-07 14:49:35 +00:00
docs: rewrite Chinese project readme
This commit is contained in:
@@ -1,22 +1,56 @@
|
||||
# nPanel
|
||||
|
||||
nPanel 是用于 NixOS 单机 Docker 服务器运维的 Web 面板。它是独立维护的 GPLv3
|
||||
项目，提供 Docker、Compose、应用商店、网站、数据库、备份、文件、终端、监控、
|
||||
进程与日志等日常运行时运维能力。
|
||||
|
||||
|
||||
nPanel 不编辑、生成、扫描或接管用户的 Flake、`hardware-configuration.nix`、SSH、
|
||||
防火墙、磁盘、挂载、Docker daemon 配置或其他持久化 NixOS 系统策略。用户只需在
|
||||
自己的配置中引入 nPanel 模块，并自行声明 Docker。
|
||||
nPanel 是面向 **NixOS 单机 Docker 服务器** 的 Web 运维面板。它由 1Panel
|
||||
社区版分叉而来，作为独立的 GPL-3.0 项目维护。
|
||||
|
||||
## NixOS 使用
|
||||
它保留 Docker、Compose、应用商店、网站、数据库、备份、文件、终端、监控、进程和
|
||||
日志等运行时运维能力；NixOS 的持久化系统策略仍完全由用户自己的 Flake 管理。
|
||||
|
||||
将本目录作为 Flake input 后，在用户已有的 NixOS 模块中引入：
|
||||
> 项目仍处于预发布阶段。请先在可恢复的主机或测试环境中部署，并为 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 或本地输入地址即可。
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
|
||||
npanel.url = "path:/absolute/path/to/nPanel";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
在任意已有的 NixOS 模块中引入模块并启用 Docker：
|
||||
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
|
||||
{
|
||||
imports = [ inputs.npanel.nixosModules.default ];
|
||||
|
||||
virtualisation.docker.enable = true;
|
||||
|
||||
services.nPanel = {
|
||||
enable = true;
|
||||
securityEntrance = "npanelAccess";
|
||||
@@ -24,43 +58,147 @@ nPanel 不编辑、生成、扫描或接管用户的 Flake、`hardware-configura
|
||||
}
|
||||
```
|
||||
|
||||
可选项：
|
||||
`securityEntrance` 必须是 5 至 116 位的字母或数字。它是由你声明的访问路径后缀，
|
||||
不是随机生成值，也不能在面板中修改。
|
||||
|
||||
### 2. 构建并切换世代
|
||||
|
||||
在你的 NixOS 配置目录执行常规切换：
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake .#<主机名>
|
||||
```
|
||||
|
||||
模块会启动以下服务：
|
||||
|
||||
- `npanel-agent.service`：执行 Docker、文件、监控、终端等本机运行时操作；
|
||||
- `npanel-core.service`：提供 Web 界面和 API。
|
||||
|
||||
### 3. 获取初始账户密码
|
||||
|
||||
首次启动默认创建管理员 `admin`。若未指定密码文件，模块会生成一次性密码：
|
||||
|
||||
```bash
|
||||
sudo cat /var/lib/npanel/initial-password
|
||||
```
|
||||
|
||||
建议通过秘密管理工具显式提供首次密码，避免密码落入状态目录：
|
||||
|
||||
```nix
|
||||
{
|
||||
services.nPanel = {
|
||||
stateDir = "/srv/npanel";
|
||||
runtimeDir = "/run/npanel";
|
||||
port = 9999;
|
||||
enable = true;
|
||||
securityEntrance = "npanelAccess";
|
||||
initialUser = "admin";
|
||||
initialPasswordFile = "/run/secrets/npanel-initial-password";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
首次启动时，未提供 `initialPasswordFile` 则会生成一次性管理员密码并以 `0600`
|
||||
权限写入 `stateDir/initial-password`。账户及密码属于 nPanel 自身的可变状态，
|
||||
不写入 Nix 配置或 Nix store。
|
||||
`initialUser` 与 `initialPasswordFile` 只在状态目录首次初始化时生效。之后请在侧栏的
|
||||
“用户信息”中修改 nPanel 自身的用户名、密码、MFA 或通行密钥。
|
||||
|
||||
使用 `http://127.0.0.1:<port>/<securityEntrance>` 访问面板。`port` 与
|
||||
`securityEntrance` 是 NixOS 声明配置，在每次 nPanel 启动时同步到内部数据库；面板
|
||||
不会提供修改它们的入口。
|
||||
### 4. 访问面板
|
||||
|
||||
## 状态与权限
|
||||
默认端口为 `9999`：
|
||||
|
||||
- `stateDir` 默认是 `/var/lib/npanel`，存放数据库、Compose 项目、应用数据、上传、备份和日志。
|
||||
- `runtimeDir` 默认是 `/run/npanel`，存放 core 和 agent 的本地 Unix socket。
|
||||
- agent 需要 Docker socket 访问；Docker socket 在实际效果上等同 root 权限，必须将 nPanel 作为特权控制平面保护。
|
||||
- NixOS 不可变路径在文件管理器中应被按系统权限拒绝写入，不应由 nPanel 尝试修改。
|
||||
```text
|
||||
http://<服务器地址>:9999/npanelAccess
|
||||
```
|
||||
|
||||
端口和安全入口均来自 NixOS 配置，并会在每次 nPanel 启动时同步到内部状态。若需要
|
||||
从网络访问，请自行在 Flake 中配置防火墙、反向代理、TLS 和网络策略。
|
||||
|
||||
## NixOS 模块选项
|
||||
|
||||
```nix
|
||||
{
|
||||
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；迁移或备份服务器时应将其作为独立数据处理。
|
||||
|
||||
## 日常运维
|
||||
|
||||
```bash
|
||||
# 服务状态
|
||||
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.nix` 的应用源码是当前目录的 `self`；除 `nixpkgs` 外没有任何源码 input。
|
||||
前端、core 和 agent 都从本项目源码构建。Nix 固定依赖哈希在首次完整构建后回填，
|
||||
以保证发布构建可复现。
|
||||
本仓库是独立 Flake：应用源码为当前目录 `self`，Flake 输入仅包含 `nixpkgs`。
|
||||
|
||||
设计边界与实施计划见 [docs/nPanel-nixos-design.md](docs/nPanel-nixos-design.md)。
|
||||
```bash
|
||||
# 仅求值模块和包定义
|
||||
nix flake check --no-build
|
||||
|
||||
## 许可证
|
||||
# 构建完整 nPanel（前端、core 与 agent）
|
||||
nix build .#npanel
|
||||
|
||||
nPanel 以 GNU General Public License v3.0 发布。上游源文件保留其必要的版权与许可证声明。
|
||||
# 分别构建组件
|
||||
nix build .#npanel-agent
|
||||
nix build .#npanel-frontend
|
||||
```
|
||||
|
||||
架构取舍、功能边界与实施记录见
|
||||
[设计文档](docs/nPanel-nixos-design.md)。
|
||||
|
||||
## 许可证与归属
|
||||
|
||||
nPanel 以 [GNU General Public License v3.0](LICENSE) 发布。项目源自 1Panel 社区版；
|
||||
上游源文件中必要的版权与许可证声明予以保留。
|
||||
|
||||
Reference in New Issue
Block a user