使用halo快速搭建应用文档中心
背景
之前我写了一篇，用gitbook搭建文档中心，gitbook是一款搭建博客的技术，是静态博客技术，不带后台管理系统、不带数据库，要发文章的话，是通过提供markdown文件，渲染成html，通过nginx对外访问。后来也给他们展示过其他静态博客技术如docsify搭建出来的样子，我自己还是蛮喜欢的，比较简洁，但是产品最终还是选择了带后台管理系统的方案-halo。
这个halo，属于动态博客技术，国产的，java开发的，数据库支持h2（内存数据库，重启丢数据，不要用于生产）、postgreSql、mysql。既然是动态博客技术，那就是带后台管理系统的，适合给不懂技术的人员使用，好些人还是不习惯markdown的，markdown的话，图床也是个问题（倒是可以用公司内部的oss服务）。
这个方案还是比较适合我们这边，为啥呢，因为我们现在在搞信创，数据库是国产的，国产数据库有几款是基于pg改的，我们的国产数据库就属于pg改的，所以这个方案也能满足信创要求。
本文只是简单记录下搭建过程以及部分踩坑过程以备忘。
halo简介
演示站点：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搞的，密码加密不知道支持不，不支持的话，到时候还得二开一下。
结语
大概就是这些了，成都马上又迎来几个月的冬天了，瑟瑟发抖。
