From e9e806221b519ca41cff4ca7c90366d65a465441 Mon Sep 17 00:00:00 2001
From: stqfdyr <89149493+stqfdyr@users.noreply.github.com>
Date: Tue, 29 Sep 2026 09:38:28 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=B8=BB=E9=A2=98=E5=8F=AF=E4=BB=A5?=
=?UTF-8?q?=E5=A1=AB=20GitHub=20=E4=BB=93=E5=BA=93=E5=9C=B0=E5=9D=80?=
=?UTF-8?q?=E5=AE=89=E8=A3=85=EF=BC=8C=E4=B8=8A=E4=BC=A0=E8=A6=81=E9=80=89?=
=?UTF-8?q?=20theme.tar.gz=20=E8=80=8C=E4=B8=8D=E6=98=AF=20Source=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
src/content/dev/theme.mdx | 22 ++++++++++++++++------
src/content/reference/faq.mdx | 2 +-
2 files changed, 17 insertions(+), 7 deletions(-)
diff --git a/src/content/dev/theme.mdx b/src/content/dev/theme.mdx
index cd04a3d..43d9f89 100644
--- a/src/content/dev/theme.mdx
+++ b/src/content/dev/theme.mdx
@@ -15,7 +15,8 @@
└── index.html
```
-发布时打成 `theme.tar.gz`，解开就是这个目录。
+发布时打成 `theme.tar.gz`，解开就是这个目录。放进 GitHub release 时文件名保持 `theme.tar.gz`：面板的
+「从 GitHub 安装」和一键更新只认仓库最新正式 release（不含预发布和草稿）里这个名字的文件。
发布前用 `gzip -t` 检查一遍，没有输出就是完整的：
@@ -41,7 +42,7 @@ hub 1.3.0 及更早的版本不做这项检查，所以以前装得上的包，
| `url` | 是 | 源码地址。指向 GitHub 仓库时，面板的一键更新从它的 release 取 `theme.tar.gz` |
| `config` | 可不写 | 数组，站长可调的设置，面板按它画表单。见下文[主题设置](#主题设置) |
-少写一个字段时，在面板上传会被拒绝，并指出缺的是哪个；直接放进 hub 的 `--themes` 目录的，主题不会
+少写一个字段时，在面板安装会被拒绝，并指出缺的是哪个；直接放进 hub 的 `--themes` 目录的，主题不会
出现在列表里，hub 日志里有一条警告。
### 上限
@@ -428,16 +429,25 @@ agent 只有 Linux 版。在 macOS 上开发时节点会一直显示离线，要
[设置](#主题设置)的主题，卡片上多一个设置按钮，保存后公开页刷新即生效。设置存在 hub 的数据库里，
更新、重装、删掉再装回主题都不会丢，数据库备份里也有。
-安装有两种方式：在面板上传 `theme.tar.gz`，或把主题目录直接放进 hub 的 `--themes` 目录（一键脚本部署是
-`/opt/monitor/data/themes/`）。卡片上的「从 GitHub 更新」从 `theme.json` 里 `url` 指向的 GitHub 仓库取
-最新 release，tag 与已装版本相同时不下载。
+安装有三种方式：
+
+- 在**主题**页填主题的 GitHub 仓库地址，点「从 GitHub 安装」，hub 下载它最新 release 里的 `theme.tar.gz`。
+ 不用先把包下到自己电脑上，也就不会因为没下载完而装不上
+- 在**主题**页上传下载好的 `theme.tar.gz`。要下 release 里名为 `theme.tar.gz` 的文件，不是 Source code
+- 把主题目录直接放进 hub 的 `--themes` 目录（一键脚本部署是 `/opt/monitor/data/themes/`）
+
+前两种都是同名主题整体替换。hub 访问不了 GitHub 时，「从 GitHub 安装」和下面的更新都需要在**设置**页填
+GitHub 代理，见[hub 连不上 GitHub](/reference/faq#hub-连不上-github)；能访问时不用填。
+
+卡片上的「从 GitHub 更新」从 `theme.json` 里 `url` 指向的 GitHub 仓库取最新 release，tag 与已装版本相同时
+不下载。
内置默认主题同样可以就地更新，不用升级 hub：更新会把新版装进 `themes/default/`，此后使用磁盘上的这份，
卡片上的「内置」标记随之消失；删掉它就回到二进制里的那份。二进制里的默认主题删不掉也改不了，磁盘上的主题
出问题时总能回落到它。
- 上传的主题是在访客浏览器里运行的第三方代码，和 hub 同源。安装时的检查只防止写到目录外和占满磁盘，
+ 安装的主题是在访客浏览器里运行的第三方代码，和 hub 同源。安装时的检查只防止写到目录外和占满磁盘，
不检查里面的 JS。只装信得过的来源。
diff --git a/src/content/reference/faq.mdx b/src/content/reference/faq.mdx
index f7932fa..253d482 100644
--- a/src/content/reference/faq.mdx
+++ b/src/content/reference/faq.mdx
@@ -26,7 +26,7 @@
### hub 连不上 GitHub
-hub 从 GitHub release 取 agent 二进制转发给节点，主题更新也从那里取。hub 所在机器访问不了 GitHub 时，
+hub 从 GitHub release 取 agent 二进制转发给节点，主题的安装与更新也从那里取。hub 所在机器访问不了 GitHub 时，
在**设置**页的 **GitHub 代理**填一个镜像地址，节点侧不用改。