项目地址：<https://github.com/shubaocai/sbc-halo> ｜ MIT License

一条命令，在一台干净的 Linux 服务器上把 Halo 博客跑起来。脚本会自动装 Docker、自动配好国内镜像加速、生成 Docker Compose 配置并拉起服务，装完直接进后台初始化。

适合这样的场景：不想手写 docker-compose.yaml；服务器在国内，Docker Hub 直连不通；希望装完就能用。

脚本帮你做了什么

  • 自动装 Docker：没有 Docker 就用官方脚本装，失败会自动回退到发行版仓库（国内的 get.docker.com 时通时不通，靠这一步兜底）
  • 自动配镜像加速：探测可用的 Docker Hub 加速源写进 daemon.json，解决 postgres / mysql 这类基础镜像拉不动的问题
  • 三种数据库：PostgreSQL（默认，Halo 官方推荐）/ MySQL / H2（单容器，仅测试用）
  • 密码随机生成：数据库密码自动生成，只写在权限 600 的 .env 里
  • 开箱可用：自动探测公网 IP 生成访问地址，部署后自动等健康检查通过再返回
  • 幂等安全：已部署过不会覆盖你的配置，加 --force 才会重新生成，且旧文件先备份

环境要求

| 项目 | 要求 |

| --- | --- |

| 系统 | Linux（需 systemd）：Ubuntu / Debian / CentOS / RHEL / Rocky / AlmaLinux / Fedora 等 |

| 权限 | root（或 sudo） |

| Shell | bash |

| 内存 | 建议 ≥ 1GB |

| 架构 | x86_64 / arm64 |

已在 Ubuntu 22.04.5 LTS（腾讯云 CVM，2GB 内存） 实测：从零到服务可访问约 2 分钟，Halo 启动约 17 秒。

快速开始

第一步：下载并执行

curl -fsSL -o /tmp/halo.sh https://cdn.jsdelivr.net/gh/shubaocai/sbc-halo@main/install_halo.sh && sudo bash /tmp/halo.sh

国内服务器建议用上面这条（jsDelivr）。raw.githubusercontent.com 在国内时通时不通，想用原生地址就加一层自动回退：

curl -fsSL -o /tmp/halo.sh https://raw.githubusercontent.com/shubaocai/sbc-halo/main/install_halo.sh \
  || curl -fsSL -o /tmp/halo.sh https://cdn.jsdelivr.net/gh/shubaocai/sbc-halo@main/install_halo.sh
[ -s /tmp/halo.sh ] && sudo bash /tmp/halo.sh

也可以直接 clone 下来跑：

git clone https://github.com/shubaocai/sbc-halo.git
cd sbc-halo
sudo bash install_halo.sh

提示：jsDelivr 会缓存 @main 分支，脚本更新后短时间内可能仍拉到旧版本。需要固定版本可以改用 tag 或 commit，例如 https://cdn.jsdelivr.net/gh/shubaocai/sbc-halo@v1.0.0/install_halo.sh。

第二步：进后台初始化

部署完成后浏览器访问：

http://<服务器IP>:8090/console

首次访问会进入初始化页面，按提示创建管理员账号即可。

打不开怎么办：先查云厂商安全组有没有放行 8090（这是最常见的原因）。本机防火墙可以执行时加 --open-firewall，让脚本自动放行 ufw / firewalld 的端口。

参数说明

| 参数 | 说明 | 默认 |

| --- | --- | --- |

| --postgres / --pg | 使用 PostgreSQL | ✅ 默认 |

| --mysql | 使用 MySQL 8.0 | |

| --h2 | 使用内置 H2 单容器（仅测试，不建议生产） | |

| --port <端口> | Halo 对外端口 | 8090 |

| --dir <目录> | 安装目录（配置与数据都在这里） | /opt/halo |

| --version <版本号> | Halo 社区版版本号 | 2.26.1 |

| --image <镜像仓库> | Halo 镜像仓库 | registry.fit2cloud.com/halo/halo |

| --url <外部地址> | 外部访问地址，不填自动探测公网 IP | 自动探测 |

| --db-password <密码> | 数据库密码（仅限字母数字和 . _ @ % + = -） | 随机生成 |

| --jvm-opts <参数> | JVM 参数 | -Xmx512m -Xms256m |

| --mirror <地址\|none> | 指定 Docker Hub 加速地址；none 表示不配置 | 自动探测 |

| --open-firewall | 自动放行本机 ufw / firewalld 端口 | 关闭 |

| --force | 配置已存在时覆盖（旧文件自动备份） | 关闭 |

| -h, --help | 显示帮助 | |

所有参数都支持用环境变量代替（参数优先），例如：

HALO_PORT=9000 sudo -E bash install_halo.sh --h2

用 sudo 传环境变量记得加 -E，否则变量会被 sudo 丢掉。

常用环境变量：HALO_VERSION、HALO_IMAGE_REPO、DB_TYPE、HALO_PORT、HALO_DIR、HALO_EXTERNAL_URL、DB_PASSWORD、JVM_OPTS、DOCKER_MIRROR。

几个常见用法

# 默认安装：PostgreSQL + Halo 2.26.1，端口 8090
sudo bash install_halo.sh

# 换 MySQL，换 8080 端口
sudo bash install_halo.sh --mysql --port 8080

# 指定域名，并自动放行本机防火墙
sudo bash install_halo.sh --url https://blog.example.com --open-firewall

# 单容器 + 内置 H2（仅体验）
sudo bash install_halo.sh --h2

# 装指定版本到自定义目录
sudo bash install_halo.sh --version 2.26.0 --dir /data/halo

# 重新生成配置（旧文件自动备份为 .bak.时间戳）
sudo bash install_halo.sh --force

装完之后

目录结构

/opt/halo
├── docker-compose.yaml     # 容器编排
├── .env                    # 端口、镜像、数据库密码（权限 600）
├── halo2/                  # Halo 数据：文章、附件、主题、插件、密钥（务必备份）
└── db/                     # PostgreSQL 数据（MySQL 模式为 mysql/）

容器与网络：

| 名称 | 说明 |

| --- | --- |

| halo | Halo 应用容器，映射 主机端口:8090 |

| halo-db | 数据库容器（--h2 模式没有） |

| halo_halo_network | 应用与数据库之间的内部网络 |

日常运维

在安装目录下执行：

cd /opt/halo

docker compose ps                  # 查看状态
docker compose logs -f halo        # 实时日志
docker compose restart halo        # 重启
docker compose down                # 停止（数据保留）
docker compose up -d               # 启动

# 备份（数据都在这个目录，整目录打包，存到 /root 下）
tar czf /root/halo-backup-$(date +%F).tar.gz -C /opt/halo .

升级 Halo

把 .env 里的镜像版本号改成目标版本，再重新拉起：

sed -i 's|^HALO_IMAGE=.*|HALO_IMAGE=registry.fit2cloud.com/halo/halo:新版本号|' /opt/halo/.env
cd /opt/halo && docker compose pull && docker compose up -d

常见问题

1. 拉取镜像超时：dial tcp ...: i/o timeout

国内直连 Docker Hub 基本不通，postgres / mysql 这类镜像只存在于 Docker Hub。脚本会自动探测并配置加速源，通常无需干预。如果自动探测没找到可用源，手动指定一个：

sudo bash install_halo.sh --mirror https://docker.m.daocloud.io

2. 容器退出了 / Halo 突然打不开（Exited）

cd /opt/halo
docker compose ps                    # STATUS 显示 Exited 就是退出了
docker compose up -d                 # 原地拉起，数据不会丢
docker compose logs --tail=50 halo   # 反复退出时看具体报错

比较典型的一种：数据库容器被停掉（手动 docker stop，或 Docker 守护进程重启过）后，Halo 会因为解析不到 halodb 这个服务名而崩溃，报 Cannot connect to halodb/<unresolved>:5432。compose 里配的是 restart: on-failure:3（沿用 Halo 官方示例的写法），只重试 3 次，耗尽之后容器就永久退出、不会自己再起来，需要手动 docker compose up -d。数据都在 /opt/halo 下，不会丢。

想让数据库恢复后 Halo 自动接上，可以把两个服务的 restart: on-failure:3 改成 unless-stopped。

3. 提示"配置文件已存在，未做任何修改"

脚本默认幂等，不覆盖已有配置。要重新生成就加 --force。

4. 数据库密码在哪看

grep DB_PASSWORD /opt/halo/.env

5. H2 能用吗

不要用于生产。H2 是内嵌文件数据库，操作不当可能损坏数据文件，只适合内存很小的机器或纯体验。

卸载

# 删除 Halo（数据一起删掉，先备份）
cd /opt/halo && docker compose down --remove-orphans
rm -rf /opt/halo

# 卸载 Docker 软件包（自动识别装的是 docker.io 还是 docker-ce）
sudo systemctl disable --now docker.socket docker.service containerd.service
sudo apt-get purge -y $(dpkg -l | awk '/^ii/ && $2 ~ /^(docker|containerd|runc)/ {print $2}')
sudo apt-get autoremove --purge -y
sudo rm -rf /var/lib/docker /var/lib/containerd /etc/docker /etc/containerd
sudo groupdel docker 2>/dev/null

CentOS / RHEL 系把 apt-get 换成 dnf 即可。

参考文档

  • Halo 官方文档：<https://docs.halo.run>
  • 使用 Docker Compose 部署：<https://docs.halo.run/guide/install/docker-compose>
  • 使用 Docker 部署（单容器 H2）：<https://docs.halo.run/guide/install/docker>

MIT License © 2026 鼠宝财 ｜ 项目地址：<https://github.com/shubaocai/sbc-halo>