📝 docs: Add documentation

docs/zh/guide/node/installation.md

@@ -0,0 +1,168 @@
+# 节点端安装
+
+`ppanel-node` 是部署在边缘服务器上的轻量代理守护进程，基于 `xray-core`，负责同步路由、订阅、心跳与密钥。本指南提供最快速的一键安装方式，并补充源码与容器方案。
+
+## 快速开始
+
+```bash
+wget -N https://raw.githubusercontent.com/perfect-panel/ppanel-node/master/scripts/install.sh
+sudo bash install.sh --api-host https://panel.example.com --server-id 1 --secret-key <SECRET>
+```
+
+脚本会自动识别系统/架构、拉取最新版、安装 geo 数据，并配置 `ppnode` CLI 与系统服务。
+
+### 环境要求
+
+- 64 位 Linux（Debian/Ubuntu ≥16、CentOS ≥7、Alpine、Arch 等）
+- 拥有 root 权限，且可访问 `github.com`
+- 防火墙需放通对外协议端口及访问面板的 443 端口
+- 面板后台已生成匹配的 **Server ID** 与 **Secret Key**
+
+### 可选参数
+
+- 位置参数 `vX.Y.Z`：安装指定 tag。
+- `--api-host https://panel.example.com`
+- `--server-id <ID>`（对应运维→服务器 管理页面中的记录）
+- `--secret-key <KEY>`
+
+若未传入参数，脚本会在安装过程中交互式询问。
+
+### 服务管理
+
+安装完成后可通过 CLI 管理：
+
+```bash
+ppnode status      # 查看状态
+ppnode start       # 启动
+ppnode restart     # 重启 + 重新加载配置
+ppnode log         # 查看日志
+ppnode update      # 升级至最新版本
+ppnode update v1.2 # 安装指定版本
+ppnode uninstall   # 卸载
+ppnode generate    # 重新生成 /etc/PPanel-node/config.yml
+```
+
+## 安装方式
+
+### 方式一：一键脚本（推荐）
+
+执行上方快速开始命令或运行 `sudo bash install.sh` 并按提示填写信息。脚本包含以下步骤：
+
+1. 根据发行版安装依赖（`wget`、`curl`、`tar`、`socat`、cron 等）。
+2. 下载 `ppanel-node-linux-<arch>.zip`（支持 amd64/arm64/s390x）。
+3. 解压到 `/usr/local/PPanel-node`，安装 `geoip.dat`、`geosite.dat`，配置系统服务。
+4. 安装 `/usr/bin/ppnode` 管理脚本并设置开机自启。
+
+### 方式二：从源码构建
+
+1. 安装 Go 1.21+，并启用 JSON v2 实验特性：
+
+    ```bash
+    export GOEXPERIMENT=jsonv2
+    ```
+
+2. 克隆仓库并编译：
+
+    ```bash
+    git clone https://github.com/perfect-panel/ppanel-node.git
+    cd ppanel-node
+    GOEXPERIMENT=jsonv2 go build -v -o ./ppnode -trimpath -ldflags "-s -w -buildid="
+    ```
+
+3. 复制二进制与 geo 数据：
+
+    ```bash
+    sudo install -Dm755 ./ppnode /usr/local/PPanel-node/ppnode
+    sudo install -Dm644 ./geoip.dat /etc/PPanel-node/geoip.dat
+    sudo install -Dm644 ./geosite.dat /etc/PPanel-node/geosite.dat
+    ```
+
+4. 创建 systemd 服务：
+
+    ```bash
+    sudo tee /etc/systemd/system/PPanel-node.service <<'EOF'
+    [Unit]
+    Description=PPanel Node
+    After=network.target
+
+    [Service]
+    Type=simple
+    ExecStart=/usr/local/PPanel-node/ppnode server
+    Restart=always
+    RestartSec=10
+
+    [Install]
+    WantedBy=multi-user.target
+    EOF
+    sudo systemctl daemon-reload
+    sudo systemctl enable --now PPanel-node
+    ```
+
+5. 复制仓库中的 `config.yml` 或手动创建（见配置章节），最后重启服务。
+
+### 方式三：容器化部署
+
+仓库自带 `Dockerfile`，可在不方便直接安装的宿主机上运行：
+
+```bash
+git clone https://github.com/perfect-panel/ppanel-node.git
+cd ppanel-node
+docker build -t ppanel-node:latest .
+docker run -d --name ppanel-node \
+  --net host \
+  -v /etc/PPanel-node:/etc/PPanel-node \
+  ppanel-node:latest server
+```
+
+建议挂载的目录：
+
+- `/etc/PPanel-node/config.yml` —— 保存 API/密钥配置。
+- `/etc/PPanel-node/geoip.dat` 与 `/etc/PPanel-node/geosite.dat` —— 持久化 Geo 数据文件。
+- `/var/log/ppanel-node`（可选）—— 在宿主机收集日志。
+
+## 配置节点
+
+运行时配置位于 `/etc/PPanel-node/config.yml`，结构如下：
+
+```yaml
+Log:
+  Level: warn      # debug | info | warn | error
+  Output: ""       # 为空代表 stdout，也可以写入文件
+  Access: none     # 访问日志路径，none 为关闭
+
+Api:
+  ApiHost: https://panel.example.com
+  ServerID: 3
+  SecretKey: b23d8ee1cfe44d7f
+  Timeout: 30
+```
+
+修改完成后重启服务：
+
+```bash
+sudo systemctl restart PPanel-node
+# 或
+ppnode restart
+```
+
+### 与面板的映射关系
+
+1. 在 **运维管理 → 服务器管理** 中创建记录，获取对应的 Server ID 与 Secret Key。
+2. 将上述信息填入 `config.yml`，`ApiHost` 必须是面板的公网可访问地址。
+3. 确保节点能够访问面板 443 端口，且面板允许节点 IP 回连。
+4. 节点上报后会在面板中显示为在线，通常 30 秒内即可看到心跳。
+
+## 升级与回滚
+
+- `ppnode update` 仅替换二进制，保留配置与 geo 文件。
+- `ppnode update vX.Y.Z` 可按版本号回滚。
+- 源码部署时，重新构建目标 tag，替换 `/usr/local/PPanel-node/ppnode` 并 `systemctl restart PPanel-node`。
+
+## 故障排查
+
+- `ppnode log` 或 `journalctl -u PPanel-node -f` 查看运行日志。
+- 确认 `/etc/PPanel-node/config.yml` 中 `ApiHost`、`SecretKey` 填写正确。
+- 保证服务器可访问 GitHub（更新）与面板域名的 443 端口。
+- 面板显示离线时检查防火墙是否放行心跳、系统时间是否同步（`chronyc tracking`）。
+
+更多细节可参阅源仓库：[`github.com/perfect-panel/ppanel-node`](https://github.com/perfect-panel/ppanel-node)。