使用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安装方式，也是同样道理。

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

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

有网络的话，这个就行：

https://hub.docker.com/r/halohub/halo

docker pull halohub/halo

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

[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足矣。

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

我贴下我的配置：

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

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搞的，密码加密不知道支持不，不支持的话，到时候还得二开一下。

结语

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