使用halo快速搭建应用文档中心

背景

之前我写了一篇,用gitbook搭建文档中心,gitbook是一款搭建博客的技术,是静态博客技术,不带后台管理系统、不带数据库,要发文章的话,是通过提供markdown文件,渲染成html,通过nginx对外访问。后来也给他们展示过其他静态博客技术如docsify搭建出来的样子,我自己还是蛮喜欢的,比较简洁,但是产品最终还是选择了带后台管理系统的方案-halo。

这个halo,属于动态博客技术,国产的,java开发的,数据库支持h2(内存数据库,重启丢数据,不要用于生产)、postgreSql、mysql。既然是动态博客技术,那就是带后台管理系统的,适合给不懂技术的人员使用,好些人还是不习惯markdown的,markdown的话,图床也是个问题(倒是可以用公司内部的oss服务)。

这个方案还是比较适合我们这边,为啥呢,因为我们现在在搞信创,数据库是国产的,国产数据库有几款是基于pg改的,我们的国产数据库就属于pg改的,所以这个方案也能满足信创要求。

本文只是简单记录下搭建过程以及部分踩坑过程以备忘。

halo简介

官网: https://www.halo.run/

演示站点:https://docs.halo.run/#在线体验

文档:https://docs.halo.run/category/安装指南

我们搭建出来的效果最终大概这样(用的earth主题):

搭建过程

docker安装

之前也写了个内网环境没网如何用rpm搭建docker的文章,后来有好心人提示我可以用更简单的办法。

可以参考官网这里,https://docs.docker.com/engine/install/binaries/

这个是直接利用静态链接的方式,把docker需要的所有的二进制都搞到这一个压缩包里了,比如说,大家安装nginx的时候,经常提示大家缺少了openssl、pcre等动态库,这种就属于动态链接了,其实你也可以不依赖系统的动态库,直接指定openssl、pcre的源码,然后直接编译进最终的nginx的二进制文件里,这种就是静态链接了,这种的问题是,如果运维统一升级了openssl这些,但你自己编译的这个nginx还是老版本,就会有风险,这里的这种docker安装方式,也是同样道理。

但是我这边反正是用这种方式,文档中心也不怎么重要,内网也很少遇到需要升级这些基础组件的场景,开整。

shell 复制代码
https://download.docker.com/linux/static/stable/x86_64/
下载了 docker-24.0.7.tgz 

tar xzvf docker-24.0.7.tgz 
cp docker/* /usr/bin/

[root@AppDevPlatform3 upload]# docker -v
Docker version 24.0.7, build afdd53b

启动:
dockerd &
检查:
[root@AppDevPlatform3 upload]# ps -ef|grep docker
root     1101154 1005806  1 15:34 pts/0    00:00:00 dockerd
root     1101163 1101154  0 15:34 ?        00:00:00 containerd --config /var/run/docker/containerd/containerd.toml

如果生产安装的话,可以再多搞点事,比如开机自启动、非root用户启动:

https://docs.docker.com/engine/install/linux-postinstall/

加载halo的image

有网络的话,这个就行:

shell 复制代码
https://hub.docker.com/r/halohub/halo

docker pull halohub/halo

内网机器没网的话,我是先在有网的机器上把镜像拉下来后,用docker save后传输到内网机器后,docker load来解决这个问题。(公司内docker私服ok也行,但是生产上我们这边是完全没网,估计还是得这样)

shell 复制代码
[root@xxx local-image]# docker load <halo.tar 
01d4e4b4f381: Loading layer [==================================================>] 80.35MB/80.35MB
...
3.072kB/3.072kB

创建数据库

这个就大家自己弄吧,假设建了个库叫test,url为:1.1.1.1:5432/test

启动docker

我这边是没打算用docker compose方式,因为安装docker compose还要多费点事情,然后docker compose的话,是会自己给我们整一个halo进程 + mysql/postgre进程,我这边都有外置的db了,单跑个docker足矣。

shell 复制代码
docker run -it -d --privileged  --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2  halohub/halo:2.10 
--server.port=8090  
--spring.r2dbc.url=r2dbc:pool:postgresql://1.1.1.1/test?currentSchema=test 
--spring.r2dbc.username=abc 
--spring.r2dbc.password=def 
--spring.sql.init.platform=postgresql

这块主要是数据库相关的参数,我这个是连接pg库的,参数的详细信息,大家参考官网文档:

https://docs.halo.run/getting-started/install/docker

我这边加了个--privileged参数,是因为我遇到个什么报错来着,启动不了,加了后就ok了。

参数详解:https://www.python100.com/html/100478.html

使用docker-compose启动(可选)

如果还是选择用docker-compose,这里也简单记录下,安装docker-compose插件:

https://docs.docker.com/compose/install/linux/#install-the-plugin-manually

然后就照着这里弄吧:

https://docs.halo.run/getting-started/install/docker-compose

我贴下我的配置:

shell 复制代码
docker-compose.yaml

version: "3"

services:
  halo:
    image: halohub/halo:2.10
    container_name: halo
    restart: on-failure:3
    network_mode: "host"
    volumes:
      - ./halo2:/root/.halo2
    ports:
      - "8090:8090"
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://1.1.1.15432/test?currentSchema=abc
      - --spring.r2dbc.username=abc
      - --spring.r2dbc.password=def
      - --spring.sql.init.platform=postgresql
      - --server.port=8090
shell 复制代码
docker-compose -f docker-compose.yaml up -d
 
docker-compose -f docker-compose.yaml logs -f

访问网站及后台

访问对应的ip:8090端口即可。

安装markdown插件

在内网服务器上安装会失败,因为这个需要请求外网服务器

离线安装markdown插件:

插件首页:

https://www.halo.run/store/apps/app-HTyhC

安装主题

如果安装报错,请检查"本地未安装"中是否存在未安装成功的主题。

备份恢复

这个功能对我很重要,我在开发环境搭好后,就是产品自己去搞成自己想要的效果了,为了避免转测试、上线后,他需要再重复弄,这个整站的迁移功能就很重要,省了我很多事。

https://docs.halo.run/user-guide/backup

使用该机制,可以快速备份环境再导入新环境,不用手动重新配置一遍。

搭建过程中涉及国产db的一个小坑

创建数据库时,我是新建了一个专门的用户,然后把新建的库分给这个用户。结果这个halo连上后,启动时,一直说用户名密码错误,但是同样的用户名密码,用dbeaver都是可以连接的,报错的就是程序会报错,当时还以为halo程序有问题。

后来也是抓包解决了:

是国产库那边,说,密码第一次设置后,首次使用的话,必须要再改一次还是怎么的,我改来改去都有问题。后来把问题反馈给那边,那边说这个首次使用的密码必须强制修改的机制可以关闭,也是坑爹。

遗留问题

我们现在要上生产的话,数据库密码必须是配置成加密的,所以,我这个上线部署方案估计都有点问题,后面可能还是要看下halo的代码,我大概知道是用spring boot 3.x + jdk 17搞的,密码加密不知道支持不,不支持的话,到时候还得二开一下。

结语

大概就是这些了,成都马上又迎来几个月的冬天了,瑟瑟发抖。