Hugo Panel — 安装与使用指南

系统要求

Hugo Panel 以单个可执行文件运行，前端资源和 SQLite 都已内置。

项目	要求
操作系统	Linux（amd64 / arm64）或 macOS（Intel / Apple Silicon）
Hugo	Hugo Extended 0.120 或更高版本，并已加入 `PATH`
端口	默认 `55530`，可通过 `PORT` 或 `ADDR` 修改
磁盘	约 100 MB 用于程序、SQLite 和缓存；Hugo 站点内容另计

使用 Docker 部署时无需在宿主机安装 Hugo，镜像内已包含 Hugo Extended、rsync 和 openssh-client。

一键安装（Linux / macOS）

安装脚本会自动识别系统与架构，下载对应的发布包并校验 SHA-256。默认安装到 ~/.local/bin；使用 root 运行时安装到 /usr/local/bin。

install

curl -fsSL https://github.com/Kaiyuan/hugo-panel/releases/latest/download/install.sh | sh

可选环境变量：HP_VERSION=v0.0.7 安装指定版本，HP_INSTALL_DIR=/path 指定安装目录。安装完成后可运行 hugo-panel --version 验证。

手动下载

也可以从 Releases 页面下载对应压缩包，解压后把 hugo-panel 放入 PATH。

系统	架构	文件
Linux	amd64	`hugo-panel_linux_amd64.tar.gz`
Linux	arm64	`hugo-panel_linux_arm64.tar.gz`
macOS	amd64	`hugo-panel_darwin_amd64.tar.gz`
macOS	arm64	`hugo-panel_darwin_arm64.tar.gz`

安装 Hugo Extended

面板负责内容管理和构建调度，实际构建由 Hugo 完成。请安装 Hugo Extended 0.120 或更高版本，可参考 Hugo 官方安装文档，并确认命令可用：

hugo

hugo version

如果安装脚本提示目录不在 PATH 中，把下面一行加入 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）：

PATH

export PATH="$HOME/.local/bin:$PATH"

Docker 安装

Docker 镜像已包含 Hugo Extended、rsync 和 openssh-client，适合服务器部署，也支持 linux/amd64 与 linux/arm64。

docker run

docker run -d \
  --name hugo-panel \
  --restart unless-stopped \
  --network bridge \
  -p 55530:55530 \
  -v /srv/hugo-panel/data:/app/hugo-panel/data \
  -v /srv/my-hugo-site:/app/hugo \
  -v /srv/media:/app/media \
  -e PUBLIC_URL=https://panel.example.com \
  -e TZ=Asia/Shanghai \
  kaiyuan/hugo-panel:latest

Docker Compose

把下面的内容保存为 docker-compose.yml，按需修改挂载路径和 PUBLIC_URL，然后启动：

docker-compose.yml

services:
  hugo-panel:
    image: kaiyuan/hugo-panel:latest
    container_name: hugo-panel
    restart: unless-stopped
    network_mode: bridge
    ports:
      - "55530:55530"
    environment:
      TZ: Asia/Shanghai
      HUGO_DIR: /app/hugo
      PUBLIC_URL: http://localhost:55530
    volumes:
      - "./data:/app/hugo-panel/data"
      - "./hugo:/app/hugo"
      - "./media:/app/media"

start

docker compose up -d
docker compose logs -f hugo-panel

容器默认以 UID/GID 1000 运行，并在启动时调整挂载目录权限。/app/media 是预置的本地媒体库挂载点，在媒体 → 存储库设置中添加「本机目录」并填入该路径即可。由外部工具管理权限时，可设置 CHOWN_DATA=false、CHOWN_HUGO=false 和 CHOWN_MEDIA=false。

首次启动

启动后打开 http://localhost:55530，按向导完成初始化。

创建管理员 首次打开会进入向导，设置管理员用户名和密码。密码使用 bcrypt 存储。
配置 Hugo 站点目录 在设置 → 通用中填写 Hugo 站点根目录，也就是包含 hugo.toml 或 config.toml 的目录。
确认 Hugo 可执行文件 默认使用 PATH 中的 hugo；也可以填写 Hugo 可执行文件的绝对路径。
设置 PUBLIC_URL 如果通过域名或反向代理访问，填写完整的外部地址，用于密码重置链接和绝对 URL。

数据默认保存在 ./data（Docker 内为 /app/hugo-panel/data），包含 SQLite 数据库、备份、自定义翻译和缓存。请定期备份该目录。

日常使用

所有操作都在面板内完成，不需要直接编辑配置文件。

内容管理

新建、编辑、重命名、搜索和删除 Markdown 页面或文章；支持 YAML / TOML / JSON front matter、草稿、定时发布、标签、分类和实时预览。

主题与模块

从 themes/ 启用本地主题，或从 Git 安装、更新和移除主题；主题设置会读取 config/_default/ 拆分配置，并列出 params.toml 中的主题参数及其它非常规顶层参数。以 Hugo Modules 安装插件并执行 hugo mod tidy。

媒体库

浏览本机目录、S3 兼容存储和 WebDAV；上传、预览、移动、复制文件，并一键复制 URL 或 Markdown 链接。面板会记住每个用户上次选择的存储库，并在媒体页和文章中插入媒体时默认使用它。

构建

运行 hugo --gc --minify --cleanDestinationDir，保留最后一次输出；构建失败时可发送邮件通知。

自动部署

构建成功后通过 rsync over SSH 同步到远程服务器，支持自定义端口、私钥、known_hosts 校验和 --delete。

翻译与 AI

在设置中接入 LibreTranslate、DeepL 或兼容 OpenAI 的服务，用于标题翻译、润色、续写和摘要；密钥只保存在服务端。

设置与安全

设置页分为通用、部署、邮件、翻译、AI、语言和账户。SMTP、翻译、AI 和 SSH 私钥只保存在服务端。

常用环境变量

变量	默认值	说明
`PORT`	`55530`	监听端口
`DATA_DIR`	`./data`	数据目录，存放 SQLite、备份和缓存
`HUGO_DIR`	`./hugo`	Hugo 站点目录
`MEDIA_DIR`	`./media`	本地媒体库目录，可在存储库设置中加为本机目录
`HUGO_BINARY`	`hugo`	Hugo 可执行文件路径
`PUBLIC_URL`	空	面板外部地址，用于密码重置和绝对链接
`COOKIE_SECURE`	`auto`	HTTPS 反代建议保持 auto
`PANEL_LATEST_URL`	Releases 页面	侧栏更新检查地址；留空关闭检查

HTTPS 与反向代理

除 localhost 外，PWA 安装和 Service Worker 需要 HTTPS。建议使用 Caddy、Nginx 或 Traefik 终止 TLS，把请求转发到 127.0.0.1:55530，并设置 PUBLIC_URL=https://你的域名。

不要把面板直接暴露在公网而不加 HTTPS。首次启动后请使用强密码，并定期备份数据目录。

升级、备份与卸载

升级

单文件安装：重新运行安装脚本即可覆盖二进制。Docker：拉取新镜像并重建容器。升级前建议先备份 data 目录。

备份

备份 data 目录即可保留设置、用户、媒体索引和自定义翻译；Hugo 站点本身建议使用 Git 管理。

卸载

删除安装的可执行文件；Docker 用户删除容器和镜像。数据目录不会自动删除，请确认后再手动清理。

常见问题

端口 55530 被占用怎么办？

设置环境变量 PORT=其他端口 后重启。Docker 用户还需要同时修改宿主机端口映射和 PUBLIC_URL。

页面提示找不到 Hugo？

确认 hugo version 可用，或在设置 → 通用中填写 Hugo 可执行文件的绝对路径。Docker 镜像已内置 Hugo。

忘记管理员密码怎么办？

配置 SMTP 后可在登录页使用找回密码。若无法收信，可在备份数据后删除 data/hugo-panel.db 重新初始化，但这会丢失已有数据。

如何通过域名提供 HTTPS？

使用反向代理终止 TLS，把请求转发到 127.0.0.1:55530，并设置 PUBLIC_URL=https://你的域名。

更新检查失败会影响使用吗？

不会。侧栏只读取 GitHub Releases 页面，网络受限时会静默失败；也可以设置 PANEL_LATEST_URL 或留空关闭检查。