强大易用的开源 建站工具Halo

在这里插入图片描述

特点

可插拔架构

Halo 采用可插拔架构,功能模块之间耦合度低、灵活性提高。支持用户按需安装、卸载插件,操作便捷。同时提供插件开发接口以确保较高扩展性和可维护性。
☑ 支持在运行时安装和卸载插件
☑ 更加方便地集成三方平台
☑ 统一的可配置设置表单
☑ 支持自定义模型,自动生成 RESTful API

功能丰富的主题机制

Halo 提供完整的主题模板机制,用于构建前台界面。这意味着用户可以根据自己的喜好选择不同类型的主题模板来定制化自己的站点外观。
☑ 动态切换主题模板
☑ 支持实时编辑和预览效果
☑ 多语言支持
☑ 与插件配合实现更多功能

编辑器

Halo 的富文本编辑器提供了方便丰富的功能,包括添加标题、段落、引用、列表、代码块等元素,并支持设置样式属性、上传图片、插入视频等功能。这些工具让你的文章创作更加便捷和生动。
☑ 完备的富文本格式支持
☑ 支持拖拽和粘贴图片上传
☑ 支持通过插件扩展编辑器

更多特性

代码开源
Halo 的项目代码开源在 GitHub 上且处于积极维护状态,截止目前已经发布了 109 个版本。你也可以在上面提交你的问题或者参与代码贡献。

易于部署
推荐使用 Docker 的方式部署 Halo,便于升级,同时避免了各种环境依赖的问题。统一管理在工作目录中的应用数据也能方便地进行备份和迁移。

插件机制
支持在插件运行时为系统添加新功能,同时保持 Halo 自身的简洁轻量。这种灵活的插件机制让用户根据自身需求自由扩展 Halo 的功能,帮助用户实现富有想象力的站点。

模板机制
支持自定义配置、主题预览、多语言等功能。这种灵活的模板系统让用户可以针对自己的需求进行自定义配置,为网站带来更加个性化的外观和交互体验。

附件管理
支持多种存储策略,并支持通过插件扩展外部存储位置,可以让用户更加灵活地地上传、查看和管理附件。

搜索引擎
内置全文搜索引擎,支持关键字搜索文章和页面内容。同时支持通过插件扩展外部搜索引擎,做到让用户按需选择、自由扩展。

部署

快速部署

docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo:2.9

环境要求

硬件配置

提示
如果您要使用服务器进行部署 Halo,您需要注意的是,Halo 目前不支持市面上的云虚拟主机,请使用云服务器或者 VPS。
CPU
无特别要求。目前我们的 Docker 镜像 也已经支持多平台。
内存
为了获得更好的体验,我们建议至少配置 1G 的 RAM。
磁盘
无特别要求,理论上如果不大量在服务器上传附件,Halo 对磁盘的容量要求并不是很高。但我们推荐最好使用 SSD 硬盘的服务器,能更快的运行 Halo。
网络
Halo 目前必须在外网畅通的情况下使用,否则会导致页面异常

软件环境

Halo 理论上可以运行在任何支持 Docker 及 Java 的平台。
Docker
必须在运行环境安装好 Docker 环境,目前 Halo 的默认安装运行方式均使用容器。
JRE(可选)
目前 Halo 的默认及推荐安装方式为 Docker 容器运行,使用 jar 包运行的方式需要用户自行构建 jar 包。
信息:
当前版本(2.0)需要 JRE 17 的版本,推荐使用 OpenJDK 17。

PostgreSQL(可选)
也可以使用系统自带的 H2 Database 数据库,无需安装。但不推荐在生产环境中使用 H2 Database。

Web 服务器(可选)
如果您部署在生产环境,那么你很可能需要进行域名绑定,这时候我们推荐使用诸如 Nginx、Caddy 之类的 Web 服务器进行反向代理。但需要注意的是,目前 Halo 不支持代理到子目录(如:halo.run/blog)。

Wget(可选)
后续的文档中,我们会使用 wget 为例,用于下载所需要的文件,所以请确保服务器已经安装好了这个软件包。当然,下载文件不限制工具,如果你对其他工具熟悉,可以忽略。

VIM(可选)
后续的文档中,我们会使用 vim 为例,用于修改一些必要的配置文件,所以同样请确保服务器已经安装了这个软件包。当前,修改文档也不限制工具,如果你对其他编辑软件熟悉,也可以忽略。

浏览器支持

1、用户前台:视主题所支持的情况而定,由于目前的评论模块使用了 Vuejs 开发,所以在 Vuejs 不支持的某些浏览器中无法正常显示评论区域。
2、管理后台:支持目前常见的现代浏览器,具体视 Vuejs 框架的支持情况而定。

名词解释

~(符号)
代表当前系统下的 用户目录。
镜像
指 Halo 构建所产生的 Docker 镜像。用户通过该镜像启动 Halo 应用。
工作目录
指 Halo 所依赖的工作目录,在 Halo 运行的时候会在系统当前用户目录下产生一个.halo2的文件夹,绝对路径为 ~/.halo2。由于这个工作目录是固定的,所以上面所说的 运行包 不限制所存放的位置,里面通常包含下列目录或文件:
☑ db:存放 H2 Database 的物理文件,如果你使用其他数据库,那么不会存在这个目录。
☑ themes:里面包含用户所安装的主题。
☑ plugins:里面包含用户所安装的插件。
☑ attachments:附件目录。
☑ logs:运行日志目录。
☑ application.yaml:配置文件。
主题
包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。
插件
用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。

使用Docker-Compose

注意
目前 Halo 2 并未更新 Docker 的 latest 标签镜像,主要因为 Halo 2 不兼容 1.x 版本,防止使用者误操作。我们推荐使用固定版本的标签,比如 halohub/halo:2.9 或者 halohub/halo:2.9.0。
☑ halohub/halo:2.9:表示最新的 2.9.x 版本,即每次发布 patch 版本都会同时更新 halohub/halo:2.9 镜像。
☑ halohub/halo:2.9.0:表示一个具体的版本。
后续文档以 halohub/halo:2.9 为例。

1、在系统任意位置创建一个文件夹,此文档以 ~/halo 为例。

mkdir ~/halo && cd ~/halo

2、创建 docker-compose.yaml

此文档提供两种场景的 Docker Compose 配置文件,请根据你的需要选择一种。

创建 Halo + PostgreSQL 的实例:

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s          
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
      - --spring.r2dbc.username=halo
      # PostgreSQL 的密码,请保证与下方 POSTGRES_PASSWORD 的变量值一致。
      - --spring.r2dbc.password=openpostgresql
      - --spring.sql.init.platform=postgresql
      # 外部访问地址,请根据实际需要修改
      - --halo.external-url=http://localhost:8090/
  halodb:
    image: postgres:latest
    container_name: halodb
    restart: on-failure:3
    networks:
      halo_network:
    volumes:
      - ./db:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: [ "CMD", "pg_isready" ]
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_PASSWORD=openpostgresql
      - POSTGRES_USER=halo
      - POSTGRES_DB=halo
      - PGUSER=halo

networks:
  halo_network:

创建 Halo + MySQL 的实例:

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s
    command:
      - --spring.r2dbc.url=r2dbc:pool:mysql://halodb:3306/halo
      - --spring.r2dbc.username=root
      # MySQL 的密码,请保证与下方 MYSQL_ROOT_PASSWORD 的变量值一致。
      - --spring.r2dbc.password=o#DwN&JSa56
      - --spring.sql.init.platform=mysql
      # 外部访问地址,请根据实际需要修改
      - --halo.external-url=http://localhost:8090/

  halodb:
    image: mysql:8.0.31
    container_name: halodb
    restart: on-failure:3
    networks:
      halo_network:
    command: 
      - --default-authentication-plugin=mysql_native_password
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_general_ci
      - --explicit_defaults_for_timestamp=true
    volumes:
      - ./mysql:/var/lib/mysql
      - ./mysqlBackup:/data/mysqlBackup
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 3s
      retries: 5
      start_period: 30s
    environment:
      # 请修改此密码,并对应修改上方 Halo 服务的 SPRING_R2DBC_PASSWORD 变量值
      - MYSQL_ROOT_PASSWORD=o#DwN&JSa56
      - MYSQL_DATABASE=halo

networks:
  halo_network:

仅创建 Halo 实例(使用默认的 H2 数据库,不推荐用于生产环境,建议体验和测试的时候使用):

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s          
    command:
      # 外部访问地址,请根据实际需要修改
      - --halo.external-url=http://localhost:8090/

仅创建 Halo 实例(使用已有外部数据库,MySQL 为例):

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    network_mode: "host"
    volumes:
      - ./:/root/.halo2
    command:
      # 修改为自己已有的 MySQL 配置
      - --spring.r2dbc.url=r2dbc:pool:mysql://localhost:3306/halo
      - --spring.r2dbc.username=root
      - --spring.r2dbc.password=
      - --spring.sql.init.platform=mysql
      # 外部访问地址,请根据实际需要修改
      - --halo.external-url=http://localhost:8090/
      # 端口号 默认8090
      - --server.port=8090

参数详解:

参数名描述
spring.r2dbc.url数据库连接地址,详细可查阅下方的 数据库配置
spring.r2dbc.username数据库用户名
spring.r2dbc.password数据库密码
spring.sql.init.platform数据库平台名称,支持 postgresqlmysqlh2
halo.external-url外部访问链接,如果需要在公网访问,需要配置为实际访问地址
halo.cache.page.disabled是否禁用页面缓存,默认为禁用,如需页面缓存可以手动添加此配置,并设置为 false。 开启缓存之后,在登录的情况下不会经过缓存,且默认一个小时会清理掉不活跃的缓存,也可以在 Console 仪表盘的快捷访问中手动清理缓存。

数据库配置:

链接方式链接地址格式spring.sql.init.platform
PostgreSQLr2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}postgresql
MySQLr2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}mysql
MariaDBr2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}mysql
H2 Databaser2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSEh2

3、启动 Halo 服务

docker-compose up -d

实时查看日志:

docker-compose logs -f

4、用浏览器访问 /console 即可进入 Halo 管理页面,首次启动会进入初始化页面。

提示:
如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 http://ip:端口号 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。

更新容器组

1、停止运行中的容器组

cd ~/halo && docker-compose down

2、备份数据(重要)

需要注意的是,halo.archive 文件名不一定要根据此文档命名,这里仅仅是个示例。

cp -r ~/halo ~/halo.archive

3、更新 Halo 服务
修改 docker-compose.yaml 中配置的镜像版本。

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
docker-compose pull halo
docker-compose up -d

反向代理

更多信息请访问https://docs.halo.run/category/%E5%85%B6%E4%BB%96%E6%8C%87%E5%8D%97
Nginx
简介
顾名思义,Nginx Proxy Manager 就是一个 Nginx 的代理管理器,它最大的特点是简单方便。
即使是没有 Nginx 基础的小伙伴,也能轻松地用它来完成反向代理的操作,而且因为自带面板,操作极其简单,非常适合配合 docker 搭建的应用使用。
Nginx Proxy Manager 后台还可以一键申请 SSL 证书,并且会自动续期,方便省心。

upstream halo {
  server 127.0.0.1:8090;
}
server {
  listen 80;
  listen [::]:80;
  server_name www.yourdomain.com;
  client_max_body_size 1024m;
  location / {
    proxy_pass http://halo;
    proxy_set_header HOST $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Caddy 2

www.yourdomain.com

encode gzip

reverse_proxy 127.0.0.1:8090

Traefik
Traefik 是一款开源的反向代理与负载均衡工具,它监听后端的变化并自动更新服务配置。
它与传统反向代理最大的区别,是支持声明式的动态路由规则,大大简化网关规则的配置。而且还有诸多实用特性,例如:健康检查、多实例负载均衡、能够实现 Let’s Encrypt 证书的自动签发、验证与续期等等。
更新 halo 容器组的配置
1、networks 中引入已存在的网络 traefik(此网络需要 提前创建)
2、services.halo.networks 中添加网络 traefik
3、修改外部地址为你的域名
4、声明路由规则、开启 TLS

version: "3.8"

networks:
  traefik:
    external: true
  halo:

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    volumes:
      - ./:/root/.halo2
    networks:
      - traefik
      - halo
    command:
      # 外部访问地址,请根据实际需要修改
      - --halo.external-url=https://yourdomain.com
    labels:
      traefik.enable: "true"
      traefik.docker.network: traefik
      traefik.http.routers.halo.rule: Host(`yourdomain.com`)
      traefik.http.routers.halo.tls: "true"
      traefik.http.routers.halo.tls.certresolver: myresolver
      traefik.http.services.halo.loadbalancer.server.port: 8090

Any limitation starts from your own heart.