使用教程 - Halo 插件主题文档

插件配置教程

前置准备

在使用数据统计插件的访问统计功能之前，您需要先部署 Umami 统计服务。

ℹ️ Umami 部署 Umami 需要自行部署，详细的部署教程可以参考 Umami 官方文档。

插件设置

在 Halo 后台进入「插件」→「数据统计插件」→「设置」，配置以下参数：

站点地址：填写您的 Umami 站点地址，例如：https://umami.example.com
用户名：填写您的 Umami 登录用户名，例如：admin
密码：填写您的 Umami 登录密码
网站 ID：填写您要统计的网站在 Umami 中的 ID

获取网站 ID

打开您已经部署好的 Umami 管理后台
在网站列表中找到您需要统计的网站
点击网站名称进入详情页面，在 URL 或页面信息中可以找到网站 ID

Umami 网站列表页面

Umami 网站详情页面，显示网站 ID

将获取到的网站 ID 填入插件设置中
点击「保存」按钮完成配置

💡 配置提示

确保站点地址可以正常访问

用户名和密码需要具有访问该网站的权限

网站 ID 通常是数字或字符串，可以从 Umami 的网站详情页面获取

在编辑器中使用

使用 Halo 默认编辑器

在 Halo 的文章编辑器中，您可以通过以下方式插入统计组件：

在编辑器中点击 + 按钮
在插入菜单中找到以下选项：
- 插入网站数据统计 - 插入网站内部数据图表
- Umami 插入统计 - 插入 Umami 流量统计
点击对应的选项即可插入

Halo 编辑器插入菜单，显示数据统计选项

配置数据图表

插入「网站数据统计」组件后，您可以选择需要显示的图表模块：

数据图表配置界面，显示可选的图表模块

可以选择特定的图表模块，也可以全选所有模块
可以在同一篇文章中插入多个数据统计组件
每个组件可以配置不同的图表类型组合

💡 使用建议

在数据看板页面中，建议使用「显示所有图表」选项

在普通文章页面中，建议只选择相关的图表类型，避免页面加载过多内容

在模板中使用

如果您需要在网站的任意位置（如主题模板、自定义页面等）插入统计组件，可以使用以下 HTML 代码。

⚠️ 注意事项 此方法需要一定的编程经验，建议熟悉 HTML 和主题开发的用户使用。

Umami 统计组件

流量统计

在页面中插入以下 HTML 代码，即可显示 Umami 流量统计：

<div class="xhhaocom-dataStatistics-v2-traffic"></div>

💡 使用说明 流量统计组件会自动从配置的 Umami 服务中获取数据并展示。请确保已在插件设置中正确配置 Umami 相关参数。

实时活动

在页面中插入以下 HTML 代码，即可显示 Umami 实时活动：

<div class="xhhaocom-dataStatistics-v2-activity"></div>

💡 使用说明 实时活动组件会显示当前网站的实时访问情况，包括在线访客、当前访问页面等信息。

网站统计图表组件

显示所有图表

在页面中插入以下 HTML 代码，将显示所有可用的统计图表：

<div class="xhhaocom-chartboard"></div>

ℹ️ 默认显示 不指定 data-types 属性时，将显示所有可用的统计图表，包括标签统计、分类统计、文章趋势、评论排行和热门文章。

选择特定图表类型

通过 data-types 属性选择要显示的图表类型，多个类型用逗号分隔。

可用的图表类型：

tags - 标签统计
categories - 分类统计
articles - 文章发布趋势
comments - 评论活跃用户 Top10
topArticles - 热门文章 Top10

使用示例：

<!-- 只显示标签和分类 -->
<div class="xhhaocom-chartboard" data-types="tags,categories"></div>

<!-- 只显示文章趋势 -->
<div class="xhhaocom-chartboard" data-types="articles"></div>

<!-- 显示评论排行和热门文章 -->
<div class="xhhaocom-chartboard" data-types="comments,topArticles"></div>

💡 灵活组合 您可以根据需要灵活组合不同的图表类型，只需在 data-types 属性中用逗号分隔即可。例如：data-types="tags,categories,articles" 将同时显示标签统计、分类统计和文章趋势。

Uptime Kuma 配置教程

前置准备

Uptime Kuma 是一个开源的监控工具，用于监控网站和服务的可用性。在使用数据统计插件的 Uptime Kuma 功能之前，您需要先部署 Uptime Kuma 服务。

ℹ️ Uptime Kuma 部署 Uptime Kuma 需要自行部署

插件设置

在 Halo 后台进入「插件」→「设置」，找到 Uptime Kuma 配置部分，配置以下参数：

站点地址：填写您的 Uptime Kuma 状态页地址，例如：https://status.twouu.com/status/handsome

💡 配置提示

状态页地址应该是完整的 URL，包含协议（http:// 或 https://）

确保状态页地址可以正常访问

状态页地址通常格式为：https://status.twouu.com/status/handsome

如何使用

方法一：在模板中使用 HTML 代码

如果您熟悉 HTML，可以在需要显示监控状态的位置插入以下代码：

<div class="xhhaocom-dataStatistics-v2-uptime-kuma"></div>

方法二：通过 Halo 设置页面注入代码

如果您不熟悉 HTML，可以通过 Halo 的设置页面来注入代码：

在 Halo 后台进入「设置」页面

Halo 后台设置页面入口

找到「代码注入」选项并点击进入

Halo 代码注入设置页面

在「页脚」输入框中粘贴以下代码：

<div class="xhhaocom-dataStatistics-v2-uptime-kuma"></div>

点击「保存」按钮完成配置

ℹ️ 使用说明

代码注入到页脚后，监控状态将在网站的所有页面底部显示

如果您只想在特定页面显示，建议使用方法一，在对应的模板文件中插入代码

确保插件设置中的状态页地址配置正确

GitHub 统计配置教程

前置准备

GitHub 统计功能用于展示 GitHub 用户的贡献数据。在使用此功能之前，您需要配置域名反代理和 GitHub 用户名。

插件设置

在 Halo 后台进入「插件」→「设置」，找到 GitHub 统计配置部分，配置以下参数：

信息卡代理地址：填写 GitHub 信息卡的反代理地址
活力图代理地址：填写 GitHub 活力图的反代理地址
GitHub 用户名：填写您要展示统计数据的 GitHub 用户名

代理地址说明

GitHub 统计功能需要配置两个代理地址：

代理类型	用途	默认地址
信息卡代理	展示 GitHub 用户统计信息（stars、commits、PRs 等）	`https://github-readme-stats.vercel.app/`
活力图代理	展示 GitHub 用户贡献活动热力图	`https://github-readme-activity-graph.vercel.app/`

⚠️ 国内访问限制 默认地址在国内可能无法访问，建议使用反代理服务。两个代理地址可以相同（使用同一个反代理域名），也可以不同。

反代理配置方法

方法一：使用 Nginx 配置

将以下配置添加到您的 Nginx 服务器配置文件中（通常在 server 块内）：

# ========== 代理 github-readme-stats.vercel.app 接口 ==========
location /api {
    proxy_pass https://github-readme-stats.vercel.app;
    proxy_set_header Host github-readme-stats.vercel.app;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_http_version 1.1;
    add_header X-Cache $upstream_cache_status;
    add_header Cache-Control no-cache;
    proxy_ssl_server_name off;
    proxy_ssl_name $proxy_host;
}

# ========== 代理 github-readme-activity-graph.vercel.app 接口 ==========
location /graph {
    proxy_pass https://github-readme-activity-graph.vercel.app;
    proxy_set_header Host github-readme-activity-graph.vercel.app;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_http_version 1.1;
    add_header X-Cache $upstream_cache_status;
    add_header Cache-Control no-cache;
    proxy_ssl_server_name off;
    proxy_ssl_name $proxy_host;
}

配置说明：

/api - 用于代理 GitHub 信息卡接口
/graph - 用于代理 GitHub 活力图接口

使用步骤：

将上述配置添加到您的 Nginx 配置文件（如 /etc/nginx/sites-available/default）
测试配置：sudo nginx -t
重新加载 Nginx：sudo nginx -s reload 或 sudo systemctl reload nginx
在插件设置中填写代理地址：
- 信息卡代理地址：https://your-domain.com/
- 活力图代理地址：https://your-domain.com/

方法二：使用 1Panel 配置

在 1Panel 中创建两个反向代理，配置如下：

信息卡代理配置（https://github-readme-stats.vercel.app）：

1Panel 信息卡代理配置界面

活力图代理配置（https://github-readme-activity-graph.vercel.app）：

1Panel 活力图代理配置界面

配置对比：

1Panel 两个代理配置对比

ℹ️ 配置区别 两个代理配置的唯一区别：

路径不同：一个是 /api，一个是 /graph

后端代理地址不同：分别指向 github-readme-stats.vercel.app 和 github-readme-activity-graph.vercel.app

💡 配置提示

代理地址应该是完整的 URL，包含协议（http:// 或 https://）

将 your-domain.com 替换为您的实际域名

如果配置了 SSL，请确保使用 HTTPS 协议

两个代理地址可以相同（使用同一个域名），也可以不同

获取 GitHub 用户名

GitHub 用户名就是您在 GitHub 上的账户名称：

登录您的 GitHub 账户
在浏览器地址栏或您的个人资料页面可以看到用户名
例如：如果您的 GitHub 个人主页是 https://github.com/your-username，那么用户名就是 your-username

ℹ️ 注意事项

GitHub 用户名区分大小写，请确保输入正确

用户名不包含 @ 符号

如果用户名包含特殊字符，请完整输入

如何使用

方法一：在 Halo 编辑器中使用

在 Halo 的文章编辑器中，您可以通过以下方式插入 GitHub 统计组件：

在编辑器中点击 + 按钮
在插入菜单中找到 GitHub 统计 相关选项
选择要插入的组件类型（统计卡片、贡献图、语言统计等）
点击对应的选项即可插入

方法二：通过 HTML 插入

如果您需要在模板或自定义页面中使用，可以直接插入 HTML 代码。

GitHub 组件说明

GitHub Pin - 仓库置顶卡片

显示指定 GitHub 仓库的统计信息。

基本用法

<div class="xhhaocom-dataStatistics-v2-github-pin" data-repo="plugin-data-statistics"></div>

支持的属性

属性	类型	说明	必填
`data-repo`	string	仓库名称，格式：`plugin-data-statistics`	是

GitHub Stats - 用户统计卡片

显示 GitHub 用户的总体统计信息。

基本用法

<div class="xhhaocom-dataStatistics-v2-github-stats"></div>

完整示例

<!-- 默认样式 -->
<div class="xhhaocom-dataStatistics-v2-github-stats"></div>

<!-- 显示图标 -->
<div class="xhhaocom-dataStatistics-v2-github-stats" data-show-icons="true"></div>

<!-- 指定主题 -->
<div class="xhhaocom-dataStatistics-v2-github-stats" data-theme="dark"></div>

<!-- 指定语言 -->
<div class="xhhaocom-dataStatistics-v2-github-stats" data-locale="zh"></div>

<!-- 组合使用 -->
<div class="xhhaocom-dataStatistics-v2-github-stats" 
     data-show-icons="true" 
     data-theme="dark" 
     data-locale="zh">
</div>

支持的属性

属性	类型	说明	必填	默认值
`data-show-icons`	string	是否显示图标，值为 `"true"` 时显示	否	-
`data-theme`	string	主题样式	否	-
`data-locale`	string	语言/地区代码	否	-

主题选项

常见的主题包括：

default - 默认主题
dark - 暗色主题
radical - 激进主题
merko - Merko 主题
gruvbox - Gruvbox 主题
tokyonight - Tokyo Night 主题
onedark - One Dark 主题
cobalt - Cobalt 主题
synthwave - Synthwave 主题
highcontrast - 高对比度主题
dracula - Dracula 主题

语言代码示例

zh - 中文
en - 英文
ja - 日文
ko - 韩文
es - 西班牙文
fr - 法文
de - 德文

GitHub Top Langs - 最常用语言

显示 GitHub 用户最常用的编程语言统计。

基本用法

<div class="xhhaocom-dataStatistics-v2-github-top-langs"></div>

完整示例

<!-- 默认样式 -->
<div class="xhhaocom-dataStatistics-v2-github-top-langs"></div>

<!-- 紧凑布局 -->
<div class="xhhaocom-dataStatistics-v2-github-top-langs" data-layout="compact"></div>

<!-- 隐藏进度条 -->
<div class="xhhaocom-dataStatistics-v2-github-top-langs" data-hide-progress="true"></div>

<!-- 指定统计格式 -->
<div class="xhhaocom-dataStatistics-v2-github-top-langs" data-stats-format="percentage"></div>

<!-- 组合使用 -->
<div class="xhhaocom-dataStatistics-v2-github-top-langs" 
     data-layout="compact" 
     data-hide-progress="true" 
     data-stats-format="percentage">
</div>

支持的属性

属性	类型	说明	必填	默认值
`data-layout`	string	布局样式	否	-
`data-hide-progress`	string	是否隐藏进度条，值为 `"true"` 时隐藏	否	-
`data-stats-format`	string	统计格式	否	-

布局选项

default - 默认布局
compact - 紧凑布局

统计格式选项

percentage - 百分比格式
count - 数量格式

GitHub Graph - 贡献图

显示 GitHub 用户的贡献活动图（类似 GitHub 主页的贡献日历）。

基本用法

<div class="xhhaocom-dataStatistics-v2-github-graph"></div>

完整示例

<!-- 默认主题（minimal） -->
<div class="xhhaocom-dataStatistics-v2-github-graph"></div>

<!-- 指定主题 -->
<div class="xhhaocom-dataStatistics-v2-github-graph" data-theme="dark"></div>

<!-- 其他主题 -->
<div class="xhhaocom-dataStatistics-v2-github-graph" data-theme="github"></div>
<div class="xhhaocom-dataStatistics-v2-github-graph" data-theme="github-dark"></div>
<div class="xhhaocom-dataStatistics-v2-github-graph" data-theme="github-dark-dimmed"></div>
<div class="xhhaocom-dataStatistics-v2-github-graph" data-theme="dracula"></div>

支持的属性

属性	类型	说明	必填	默认值
`data-theme`	string	主题样式	否	`minimal`

主题选项

minimal - 简约主题（默认）
github - GitHub 主题
github-dark - GitHub 暗色主题
github-dark-dimmed - GitHub 暗色调暗主题
dracula - Dracula 主题
dark - 暗色主题
light - 亮色主题

💡 使用说明 GitHub 统计组件会自动从配置的 GitHub API 中获取用户贡献数据并展示。请确保已在插件设置中正确配置信息卡代理地址、活力图代理地址和 GitHub 用户名。