📄 update readme

2026-01-11 14:40:43 +08:00 · 2025-04-11 18:09:11 +08:00 · 2025-04-11 18:09:11 +08:00 · 8dc1aa0154
commit 8dc1aa0154
parent 53cd629119
5 changed files with 176 additions and 120 deletions
--- a/.github/images/nazhua-detail-mobile.webp
+++ b/.github/images/nazhua-detail-mobile.webp
--- a/doc/deploy.md
+++ b/doc/deploy.md
@ -1,15 +1,23 @@
+# 🚀 部署指南

-## 部署
-> Nazhua主题是一个纯前端项目，可以部署在纯静态服务器上；  
-> v0需要解决`/api/v1/monitor/${id}`监控数据、`/ws`WS服务和`/`主页的跨域访问。  
-> v1需要解决`/api/xxx`等数据接口、`/api/v1/ws/server`WS服务的跨域访问。  
-> 简单的处理方法就是采用nginx或caddy反代请求，以此解决跨域问题。  
+## 部署概述
+> Nazhua主题是纯前端项目，可部署在静态服务器上
+> 
+> **跨域解决注重点**：
+> - **V0版本**：需解决 `/api/v1/monitor/${id}`、`/ws` 和 `/` 的跨域
+> - **V1版本**：需解决 `/api/xxx` 和 `/api/v1/ws/server` 的跨域
+> 
+> 推荐使用 Nginx 或 Caddy 反向代理解决跨域问题

-### Docker Compose + Cloudflare Tunnels部署
-**请关注配置文件备注中的提示内容**  
-`favicon.ico`可以映射进去，也可以通过配置文件设置，默认不存在该文件  
-`config.js`需要单独映射进去，可以通过[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)直接生成并下载  
-`style.css`用于自定义css样式，如果不出现页面结构大规模变更的情况下，我会尽可能保证选择器不变  
+## 🐳 Docker Compose + Cloudflare Tunnels 部署
+此方案便于后续更新，只需通过 `docker compose pull` 命令即可更新主题（镜像）。
+
+### 配置说明
+- **favicon.ico**：可通过挂载或配置文件指定（默认无）
+- **config.js**：需单独挂载，建议使用[配置生成器](https://hi2shark.github.io/nazhua-generator/)生成
+- **style.css**：用于自定义CSS样式，尽量保持选择器稳定
+
+### 部署示例
 ```yaml
 services:
  nazhua:
@ -23,20 +31,25 @@ services:
      # - ./style.css:/home/wwwroot/html/style.css:ro # 自定义样式文件
    environment:
      - DOMAIN=_ # 监听的域名，默认为_（监听所有）
-      - NEZHA=http://nezha-dashboard.example.com/ # 可以被反代nezha主页地址
+      - NEZHA=http://nezha-dashboard.example.com/ # 可以被反向代理nezha主页地址
    restart: unless-stopped
 ```
-Tips: 建议通过docker-compose部署nazhua与nezha，然后通过cloudflare的tunnels向外提供服务，也可以不用自己配置https证书。  
-Tips: 如果不想加载完整的内置库，可以使用cdn引用镜像  
-> 例如：`ghcr.io/hi2shark/nazhua:latest`替换为`ghcr.io/hi2shark/nazhua:cdn`  
-----
-> 如果你想隐藏原面板，只暴露nazhua出来，你可以用Zero Trust的Tunnels；  
-> 三个容器：Tunnels、nezha-dashboard、nazhua  
-> nazhua用docker内的地址访问nezha-dashboard，然后Tunnels绑定nazhua给公开访问的域名  
-> Tunnels绑定nezha-dashboard到私密域名，需要邮箱|IP等匹配的才能访问  
-----

-### 单独使用NGINX的配置示例（Caddy可以通过这个配置进行AI推理生成）
+### 💡 小贴士
+- 推荐使用 docker-compose 部署 Nazhua 与 Nezha Dashboard，并通过 Cloudflare Tunnels 对外提供服务
+- 如需减少内置库体积，可使用 CDN 版本镜像：`ghcr.io/hi2shark/nazhua:cdn`
+- 隐藏原面板方案：使用 Zero Trust Tunnels 部署三个容器 (Tunnels、nezha-dashboard、nazhua)
+  - nazhua 通过 docker 内部地址访问 nezha-dashboard
+  - Tunnels 绑定 nazhua 到公开域名
+  - Tunnels 绑定 nezha-dashboard 到需要邮箱/IP验证的私密域名
+
+## 🌐 自定义Web服务部署
+
+### 安装步骤
+1. 在 [Releases页面](https://github.com/hi2shark/nazhua/releases) 下载最新版 `v{Nazhua版本号}-all.zip`
+2. 解压后将 `dist` 目录文件上传到Web服务目录
+
+### Nginx配置示例
 ```nginx
 map $http_upgrade $connection_upgrade {
  default upgrade;
@ -92,10 +105,16 @@ server {
  }
 }
 ```
+----  
+**Tips:** V0环境下若想与面板使用同域名，下载 `v0-nazhua.zip` 并将文件上传至面板目录下的 `nazhua` 文件夹
+
+----  
+
+## ⚙️ 配置文件

 ### config.js 配置说明
-`config.js`建议通过[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)生成，然后通过docker的volumes映射到容器内。  
-例如：(*参考内容在文档上不一定是最新，具体参考public/config.js*)
+建议使用 [Nazhua 配置生成器](https://hi2shark.github.io/nazhua-generator/) 生成配置文件。
+
 ```javascript
 window.$$nazhuaConfig = {
  title: '哪吒监控', // 网站标题
@ -136,7 +155,7 @@ window.$$nazhuaConfig = {
  monitorChartTypeToggle: true, // 监控图表类型切换
  filterGPUKeywords: ['Virtual Display'], // 如果GPU名称中包含这些关键字，则过滤掉
  customCodeMap: {}, // 自定义的地图点信息
-  nezhaVersion: 'v1', // 哪吒版本
+  nezhaVersion: 'v1', // 哪吒版本 不填写则尝试自动识别
  apiMonitorPath: '/api/v1/monitor/{id}',
  wsPath: '/ws',
  nezhaPath: '/nezha/',
@ -152,10 +171,10 @@ window.$$nazhuaConfig = {
  customFavicon: '', // 自定义favicon, 填写完整的url地址
 };
 ```
-可以通过[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)快速生成config.js配置文件

-通过修改根目录下的`style.css`文件来自定义样式  
-例如：
+### 🎨 自定义样式
+通过修改根目录下的 `style.css` 文件实现样式定制：
+
 ```css
 :root {
  /* 修改颜色 */
@ -166,18 +185,15 @@ window.$$nazhuaConfig = {
  /* 购买链接的主要颜色 */
  --list-item-buy-link-color: #f00;
 }
-```
-自定义背景图的实例：
-```css
+
+/* 自定义背景图示例 */
 :root {
-  /* 图片太亮了，需要图片前面的前景色（也是背景色）更暗一些 */
+  /* 图片太亮时，增加背景遮罩透明度 */
  --layout-main-bg-color: rgba(0, 0, 0, 0.75);
 }
-/* 自定义背景图 */
 .layout-group .layout-bg {
-  /* 添加important强制背景图替换，此处的替换设计不是很优雅，后期会改进 */
+  /* 添加!important强制背景图替换 */
  background: url(./bg.jpg) no-repeat 50% 50% !important;
  background-size: cover;
 }
 ```
-`./bg.jpg` 这个是图片地址，可以替换为外链图片；也可以把背景图片放到项目里面去，通常是docker的volumes映射，根据你自己的实际情况来。  
--- a/doc/public-note.md
+++ b/doc/public-note.md
@ -1,34 +1,39 @@
-# 公开备注
+# 📝 公开备注配置指南

-## 点阵地图显示节点  
-Nazhua采用的点阵地图是一个失真的地图，地图边际与城市位置都不是真实的经纬度坐标，因此无法通过经纬度来定位城市。  
-需要在是[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)中，拾取点阵地图上的坐标，然后在`config.js`中配置`customCodeMap`来自定义地图点信息。  
-如何指定节点的地理位置？  
-在哪吒监控后台，给节点的公开备注对象中，添加一个`customData`对象，并指定`location`的代码；  
-关于都有哪些内置的地理位置代码，需要在[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)中查看。  
-示例
+## 🗺️ 点阵地图节点显示
+
+### 地图说明
+Nazhua采用的点阵地图是一个并非精准的变形地图，不能使用真实经纬度坐标进行换算定位，因此需要通过自定义坐标来指定位置。  
+
+### 配置方法
+使用[Nazhua配置生成器](https://hi2shark.github.io/nazhua-generator/)获取内置的点阵地图坐标或者自定义坐标（可以在`config.js`中配置`customCodeMap`添加自定义地图点）  
+在节点的公开备注对象中设置位置代码：  
 ```json
 {
  "customData": {
-    "location": "HKG"
+    "location": "HKG"  // 位置代码
  }
 }
 ```
-对于几个我常见的国别位置，添加了默认映射位置，会自动显示在地图上。  
-Tips: 中国大陆地区默认在首都：北京（该映射在0.4.6后补充）  
-Tips: 美国默认在最常买的位置：洛杉矶  

-## customData字段说明
-`customData`中还可以添加子对象`slogan`、`orderLink`、`flag`、`buyBtnText`、`buyBtnIcon`字符串；  
- - `slogan`用于显示节点的标语；  
- - `orderLink`用于显示购买链接；  
- - `flag`用于显示自定义国家/地区旗帜；  
- - `buyBtnText`用于显示购买按钮的文案；  
- - `buyBtnIcon`用于显示购买按钮的图标；  
+### 默认位置映射
+部分常见地区已有默认映射：
+- 中国大陆默认显示在北京（v0.4.6后添加）
+- 美国默认显示在洛杉矶

-`flag`字段在`0.6.4`后支持  
-`buyBtnText`和`buyBtnIcon`字段在`0.5.3`后支持  
+## 🔧 customData 字段详解

+### 可用字段
+| 字段 | 用途 | 版本支持 |
+|------|------|---------|
+| `location` | 指定节点地理位置代码 | 全版本 |
+| `slogan` | 显示节点标语 | 全版本 |
+| `orderLink` | 购买链接地址 | 全版本 |
+| `flag` | 自定义国家/地区旗帜 | v0.6.4+ |
+| `buyBtnText` | 购买按钮文案 | v0.5.3+ |
+| `buyBtnIcon` | 购买按钮图标 | v0.5.3+ |
+
+### 示例配置
 ```json
 {
  "customData": {
@ -41,12 +46,18 @@ Tips: 美国默认在最常买的位置：洛杉矶
  }
 }
 ```
-Tips: 由于配置数据获取的方式特殊，无法正常解析符号`&`，建议在[https://www.bejson.com/enc/urlencode/](https://www.bejson.com/enc/urlencode/)进行编码后，将encodeURIComponent编码内容添加到orderLink中。当然，你也可以通过浏览器的console（控制台），执行`encodeURIComponent('链接内容')`，获取编码后的内容。  

-## 对于原版公开备注的支持
+### 💡 链接编码提示
+由于配置数据无法正常解析符号`&`，请使用URL编码：
+- 在线工具：[https://www.bejson.com/enc/urlencode/](https://www.bejson.com/enc/urlencode/)
+- 浏览器控制台：执行`encodeURIComponent('链接内容')`获取编码后内容
+
+## 📊 原版公开备注支持
 在哪吒的主题ServerStatus迭代中，nap0o增加了一个公开备注的功能，可以给节点添加额外的展示信息  
 具体字段定义参考 [https://github.com/nezhahq/nezha/pull/425](https://github.com/nezhahq/nezha/pull/425)  
-Nazhua对这个支持大概在90%左右，参与数据处理了的字段如下：  
+Nazhua支持原版ServerStatus主题的公开备注字段，支持的字段如下：
+
+### 账单信息 (billingDataMod)
 ```json
 {
  "billingDataMod": {
@ -55,7 +66,13 @@ Nazhua对这个支持大概在90%左右，参与数据处理了的字段如下
    "autoRenewal": "1",
    "cycle": "月",
    "amount": "$3.99"
-  },
+  }
+}
+```
+
+### 配置信息 (planDataMod)
+```json
+{
  "planDataMod": {
    "bandwidth": "30Mbps",
    "trafficVol": "1TB/月",
@ -67,13 +84,9 @@ Nazhua对这个支持大概在90%左右，参与数据处理了的字段如下
  }
 }
 ```
-~~其中IPv4、IPv6暂未参与到处理中，后续可能会支持。~~  
- - 都有显示标签：双栈IP;  
- - 单IPv4显示标签：仅IPv4;  
- - 单IPv6显示标签：仅IPv6;  

+## 🔍 完整公开备注示例

-### 公开备注的完整示例
 ```json
 {
  "billingDataMod": {
@ -101,4 +114,4 @@ Nazhua对这个支持大概在90%左右，参与数据处理了的字段如下
    "flag": "cn"
  }
 }
-```
+```
--- a/doc/update.md
+++ b/doc/update.md
@ -1,20 +1,30 @@
-# 更新说明
-大概记录一下功能性更新，修复BUG不在此记录
+# 📝 更新日志

-### v0.6.4 更新
-新增：支持网络监控折线图拆分单一图表功能；  
-新增：公开备注中设定节点的flag，自定义国家/地区旗帜；  
-新增：支持地图在首页与详情页的上下位置切换；  
+> 此处仅记录功能性更新，Bug修复不在此记录

-### v0.5.7 更新
-新增：添加自定义favicon支持；  
+## 📦 v0.6.4 更新
+- ✨ **新增**: 网络监控折线图拆分单一图表功能
+- 🌍 **新增**: 公开备注中支持自定义国家/地区旗帜 (`flag` 字段)
+- 🔄 **新增**: 支持地图在首页与详情页的上下位置切换

-### v0.5.4 更新
-新增：新增内置搜索，支持`Ctrl+K`快速打开搜索；  
+## 📦 v0.5.7 更新
+- 🖼️ **新增**: 自定义favicon支持

-### v0.5.3 更新
-新增：支持单独给服务器设置购买按钮的文案和图标，需要在公开备注的customData中添加`buyBtnText`和`buyBtnIcon`字段。  
-> 使用方法：`buyBtnText`用于设置购买按钮的文案，`buyBtnIcon`用于设置购买按钮的图标，图标支持Remixicon的图标名称，例如：`ri-gift-2-line`。  
-> 示例：点击复制图标名称，然后填写到`buyBtnIcon`字段中，补齐`ri-`前缀即可。  
-> ![remixicon使用方法](../.github/images/remixicon-select.jpg)
-> 在线图标网站：[www.remixicon.com](https://www.remixicon.com/) 目前支持版本为4.6.0
+## 📦 v0.5.4 更新
+- 🔍 **新增**: 内置搜索功能，支持 `Ctrl+K` 快速打开搜索
+
+## 📦 v0.5.3 更新
+- 🛒 **新增**: 支持单独设置服务器购买按钮的文案和图标
+
+### 使用方法
+- `buyBtnText`: 设置购买按钮文案
+- `buyBtnIcon`: 设置购买按钮图标，支持Remixicon图标
+
+### 图标配置示例
+1. 访问 [Remixicon官网](https://www.remixicon.com/)
+2. 选择并复制图标名称
+3. 在 `buyBtnIcon` 字段中填写，补齐 `ri-` 前缀
+
+![remixicon使用方法](../.github/images/remixicon-select.jpg)
+
+> 当前支持版本: Remixicon 4.6.0（cdn版本，受限于更新原因，支持到4.3.0）
--- a/readme.md
+++ b/readme.md
@ -1,34 +1,47 @@
 # Nazhua
-<div align="center">
-  <img src="./.github/images/nazhua-main.webp" alt="Nazhua"/>
-  <img src="./.github/images/nazhua-mobile.webp" width="300px" alt="Nazhua"/>
+
+<div>
+  <img src="./.github/images/nazhua-main.webp" style="max-height: 500px;" alt="Nazhua桌面版"/>
+  <img src="./.github/images/nazhua-mobile.webp" style="max-height: 500px;" alt="Nazhua移动版"/>
+  <img src="./.github/images/nazhua-detail-mobile.webp" style="max-height: 500px;" alt="Nazhua详情页"/>
 </div>

+## 📢 使用须知

-**使用前，请务必阅读Readme的内容，对你有帮助**  
-> 基于哪吒监控(nezha.wiki)v0版本构建的前端主题，目前兼容与v0相同数据结构的v1版本。  
-> ~~主题有点**重**，因为内置了一个带中文的`SarasaTermSC-SemiBold`字体。~~  
-> ~~根据不同场景，可以选择是否打包带入或者是否加载这个字体。~~   
-> 考虑到多数国内直连用户无法访问jsdelivr，所以默认使用cdnjs的loli.net引用版本。  
-> 同时默认关闭SarasaTermSC字体，如果需要使用，请使用Docker镜像全量包。  
+**使用前，请务必阅读本文档，对您的部署会有很大帮助**

-## 部署
-推荐使用Docker Compose进行部署Nazhua  
-[参考文档](./doc/deploy.md)  
-nazhua提供了很多细节配置，包括点阵地图显示/隐藏、首页风格的切换等功能；  
-如果你是使用v1内置版本，可以直接通过[配置生成器](https://hi2shark.github.io/nazhua-generator/)生成配置文件，然后填写在控制台的自定义代码中；  
-如果你是使用docker部署（包括v0版本），则需要手动配置`config.js`，具体参考文档说明；  
+- 基于哪吒监控(nezha.wiki)v0版本构建的前端主题，兼容v1版本数据结构
+- 考虑到国内用户访问需求，默认使用cdnjs的loli.net作为CDN引用源
+- 如需使用SarasaTermSC字体，请选择Docker镜像全量包进行部署

+## 🚀 部署指南

-## 公开备注
-涉及到地图上节点位置的显示，需要在公开备注中指定`location`字段，具体参考公开备注的说明文档  
-[参考文档](./doc/public-note.md)  
+**推荐使用Docker Compose + Cloudflare Tunnels部署Nazhua**

-## 更新
-[功能更新日志](./doc/update.md)  
+👉 [详细部署文档](./doc/deploy.md)
+
+Nazhua提供了丰富的配置选项：
+- 支持点阵地图显示/隐藏
+- 首页风格切换等多种个性化设置
+
+配置方式：
+- **V1内置版本**：使用[配置生成器](https://hi2shark.github.io/nazhua-generator/)生成配置，填入控制台自定义代码
+- **Docker部署**：手动配置`config.js`文件（包括v0版本）
+
+## 🗺️ 节点位置配置
+
+要在地图上显示节点位置，需在公开备注中指定`location`字段
+
+👉 [公开备注配置文档](./doc/public-note.md)
+
+## 📝 更新日志
+
+👉 [功能更新记录](./doc/update.md)
+
+## 🤝 赞助商
+
+> 按服务商字母排序，不分先后

-## 赞助
-> 按服务商字母排序，不分先后。
 <table>
  <tr>
    <td align="center">
@ -36,31 +49,35 @@ nazhua提供了很多细节配置，包括点阵地图显示/隐藏、首页风
        <img src="./.github/images/vmiss-logo.jpg" width="200px;" alt="VMISS"/>
      </a>
      <br />
-      <span style="font-weight: bold;">VMISS</span>
+      <strong>VMISS</strong>
    </td>
    <td align="center">
      <a href="https://yxvm.com" target="_blank" title="YXVM，提供香港、新加坡、日本的云服务器与物理服务器">
        <img src="./.github/images/yxvm-logo.jpg" width="200px;" alt="YXVM"/>
      </a>
      <br />
-      <span style="font-weight: bold;">YXVM</span>
+      <strong>YXVM</strong>
    </td>
  </tr>
-</table>  
+</table>
+
+## 💻 开发者指南
+
+### 环境配置
+
+在`.env.development.local`中配置以下变量：

-## 二次开发提示
-`.env.development.local`配置变量
 ```bash
-#### Sarasa Term SC字体的配置
+#### Sarasa Term SC字体设置
 # VITE_DISABLE_SARASA_TERM_SC=1
 # VITE_SARASA_TERM_SC_USE_CDN=1

-#### 引用库的CDN配置
+#### CDN配置
 # VITE_USE_CDN=1
 # VITE_CDN_LIB_TYPE=jsdelivr # jsdelivr | cdnjs | loli

-#### 哪吒的默认版本控制
-# VITE_NEZHA_VERSION=v1 # v0 | v0
+#### 哪吒版本控制
+# VITE_NEZHA_VERSION=v1 # v0 | v1

 #### 本地开发设置
 # PROXY_WS_HOST= # 本地开发时，可以代理WS服务的地址，启用后，自动转发至 {PROXY_WS_HOST}/proxy?wsPath={WS_HOST}
@ -70,11 +87,11 @@ nazhua提供了很多细节配置，包括点阵地图显示/隐藏、首页风
 # NEZHA_HOST= # 本地开发时，代理的哪吒主页地址
 ```

-## 数据来源（参考）
-1-v0. 公开的全量配置，其中包括“公开备注”（PublicNote），来自探针主页上暴露的服务器节点列表配置信息。此处是根据正则匹配的方式，获取到的节点列表。在主题项目中，默认将访问`/nezha/`的指向此处。  
-2-v0. 实时数据，v0来自公开的ws服务接口，`/ws`。  
-2-v1. 实时数据/全量数据，v1来自公开的ws服务接口，`/api/v1/ws/server`。  
-3-v0. 监控数据，v0来自公开的api接口，`/api/v1/monitor/${id}`。  
-3-v1. 监控数据，v1来自公开的api接口，`/api/v1/service/${id}`。  
-4-v0. 分组数据，v0来自服务器节点列表的`Tag`字段匹配。  
-4-v1. 分组数据，v1来自公开的api接口，`/api/v1/server-group`。  
+### 数据来源参考
+
+| 数据类型 | V0版本 | V1版本 |
+|---------|--------|--------|
+| 全量配置 | 公开备注(PublicNote)：通过正则匹配节点列表，默认访问`/nezha/` | - |
+| 实时数据 | WS接口：`/ws` | WS接口：`/api/v1/ws/server` |
+| 监控数据 | API接口：`/api/v1/monitor/${id}` | API接口：`/api/v1/service/${id}` |
+| 分组数据 | 服务器节点列表的`Tag`字段匹配 | API接口：`/api/v1/server-group` |