在云服务器部署Halo博客要准备什么,怎样完成首次启动与访问验证
首次部署 Halo 的目标,是让云服务器上的 Halo 容器能够正常启动,完成初始管理账号设置,并从外部浏览器访问站点和管理控制台。对于首次验证,不需要先配置域名、HTTPS 或反向代理,直接使用云服务器公网 IPv4 加端口即可完成基础检查。
以下以 Ubuntu 22.04/24.04、Docker Compose、Halo 2.x 和 PostgreSQL 为例。服务器建议准备 2 vCPU、4 GB 内存、20 GB 以上可用磁盘,并确保具备公网 IPv4、SSH 管理权限以及访问镜像仓库的出网能力。Halo 镜像标签会随版本变化,示例中的 halohub/halo:2.20 仅作为固定版本示例,实际部署前应替换为已经确认可用的目标版本,不建议直接使用 latest。
围绕 Halo 这类容器化博客与内容管理应用,A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器租用资源,覆盖常规建站、业务后台与数据库场景。不同产品配备 SSD 或 NVMe 存储、不同内存与处理器,并提供相应的 CN2、国际及地区线路,可为博客站点的应用容器、数据持久化和多地区访问提供服务器基础。
一、部署前需要准备什么
服务器与网络条件
| 项目 | 建议准备 | 验证方式 |
|---|---|---|
| 操作系统 | Ubuntu 22.04/24.04 64 位 | cat /etc/os-release |
| CPU 与内存 | 2 vCPU、4 GB 内存起步 | nproc、free -h |
| 磁盘 | 至少 20 GB 可用空间 | df -h |
| 管理端口 | TCP 22,仅允许管理来源地址 | 云厂商安全组、UFW |
| 首次访问端口 | TCP 8090,部署期间临时开放 | 云厂商安全组、UFW |
| 数据库端口 | 不对公网开放 | 不在 Compose 中映射 5432 |
| 公网地址 | 固定公网 IPv4 更便于首次配置 | 云服务器控制台 |
Halo 和 PostgreSQL 都运行在 Docker 容器中时,宿主机不需要单独安装 Java、MySQL 或 PostgreSQL。数据库只在 Compose 内部网络中提供服务,Halo 通过服务名连接数据库,因此不应把 PostgreSQL 的 5432 端口发布到公网。
首次安装需要准备两个不同的密码:
- PostgreSQL 数据库密码,用于 Halo 容器连接数据库。
- Halo 管理员密码,用于登录管理控制台。
不要让这两个密码相同,也不要把数据库密码直接写入公开文章、工单或截图。
检查系统基础状态
先通过 SSH 登录服务器,执行:
cat /etc/os-release
uname -m
nproc
free -h
df -h /
预期能够看到 Ubuntu 版本、x86_64 或兼容的 64 位架构、CPU 核数、内存和磁盘空间。如果磁盘可用空间明显不足,先处理无关镜像、日志或旧文件,不要在部署完成后再被磁盘耗尽中断。
如果系统尚未安装 Docker,可以使用 Ubuntu 软件包进行初步安装:
sudo apt update
sudo apt install -y docker.io docker-compose-plugin openssl curl
sudo systemctl enable --now docker
随后验证 Docker 和 Compose:
sudo docker --version
sudo docker compose version
sudo systemctl is-active docker
预期分别能看到 Docker 版本、Compose v2 版本,并返回:
active
如果系统提示找不到 docker-compose-plugin,不要直接安装来源不明的旧版 docker-compose。应改用云厂商镜像中自带的 Docker,或按照 Docker 对应发行版的软件源安装 Docker Engine 和 Compose 插件。部署命令统一使用 docker compose,而不是已经停止维护的 docker-compose。
二、准备 Halo 的目录和配置
创建独立部署目录
使用独立目录保存 Compose 文件、Halo 数据和 PostgreSQL 数据:
sudo install -d -m 750 -o "$USER" -g "$USER" /opt/halo
cd /opt/halo
mkdir -p halo2 postgres
目录用途如下:
/opt/halo/.env:镜像版本、数据库连接参数和外部访问地址。/opt/halo/compose.yaml:容器编排配置。/opt/halo/halo2:Halo 的配置、插件、主题和站点数据。/opt/halo/postgres:PostgreSQL 数据目录。
这里使用宿主机目录挂载,而不是只依赖 Docker 匿名卷,便于后续备份、迁移和回滚。
创建环境变量文件
先生成一个随机数据库密码:
openssl rand -hex 24
复制命令输出的随机字符串,然后创建 .env:
cat > .env <<'EOF'
COMPOSE_PROJECT_NAME=halo
# 示例版本,部署前请替换为已确认的 Halo 版本标签
HALO_IMAGE=halohub/halo:2.20
POSTGRES_DB=halo
POSTGRES_USER=halo
POSTGRES_PASSWORD=replace-with-random-hex
# 替换为云服务器实际公网 IPv4
HALO_EXTERNAL_URL=http://203.0.113.10:8090
EOF
接下来编辑文件:
nano .env
至少修改以下两项:
- 将
POSTGRES_PASSWORD替换为刚才生成的随机字符串。 - 将
HALO_EXTERNAL_URL中的203.0.113.10替换为服务器实际公网 IPv4。
203.0.113.10 是文档示例地址,不能直接作为真实访问地址。首次使用 IP 访问时,外部地址应包含端口,例如:
http://实际公网IPv4:8090
保存后限制配置文件权限:
chmod 600 .env
检查变量是否已经替换,但不要把完整输出发布到公共环境,因为输出可能包含数据库密码:
grep -E '^(HALO_IMAGE|POSTGRES_DB|POSTGRES_USER|HALO_EXTERNAL_URL)=' .env
如果已经启动过 PostgreSQL,不要随意修改 POSTGRES_PASSWORD。PostgreSQL 官方镜像通常只会在空数据目录首次初始化时根据环境变量设置密码,后续仅修改 .env 不一定会同步修改数据库内部密码,可能导致 Halo 无法连接数据库。
三、编写 Docker Compose 配置
创建 compose.yaml:

cat > compose.yaml <<'EOF'
services:
halo:
image: ${HALO_IMAGE}
container_name: halo
restart: on-failure:3
depends_on:
halo-postgres:
condition: service_healthy
networks:
- halo
volumes:
- ./halo2:/root/.halo2
ports:
- "8090:8090"
command:
- "--spring.r2dbc.url=r2dbc:pool:postgresql://halo-postgres:5432/${POSTGRES_DB}"
- "--spring.r2dbc.username=${POSTGRES_USER}"
- "--spring.r2dbc.password=${POSTGRES_PASSWORD}"
- "--spring.sql.init.platform=postgresql"
- "--halo.external-url=${HALO_EXTERNAL_URL}"
halo-postgres:
image: postgres:14-alpine
container_name: halo-postgres
restart: on-failure:3
networks:
- halo
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- ./postgres:/var/lib/postgresql/data
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"
]
interval: 10s
timeout: 5s
retries: 12
networks:
halo:
driver: bridge
EOF
这个配置有几个关键点:
- Halo 使用
halo-postgres作为数据库主机名,而不是127.0.0.1。在容器内部,127.0.0.1指向 Halo 自己,不是 PostgreSQL。 - PostgreSQL 没有配置
ports,因此不会监听宿主机的 5432 端口。 depends_on配合 PostgreSQL 健康检查,可以减少 Halo 在数据库尚未准备完成时提前连接失败的情况。./halo2和./postgres是持久化目录,删除容器不会自动删除其中的数据。8090:8090会让 Halo 监听宿主机的 8090 端口,适合首次通过公网 IP 访问验证。
配置文件语法验证
先不启动容器,只检查 Compose 是否能正确读取变量和解析 YAML:
sudo docker compose config >/dev/null && echo "compose config ok"
预期输出:
compose config ok
如果出现变量未定义、缩进错误或 YAML 解析错误,先修复配置再继续。不要直接把 docker compose config 的完整输出粘贴到公共渠道,因为展开后的内容可能包含数据库密码。
四、开放首次验证所需的端口
云服务器通常有两层防火墙:
- 云厂商安全组或网络 ACL。
- 操作系统内的 UFW、firewalld 等防火墙。
在云厂商控制台中增加以下规则:
- TCP 22:仅允许自己的管理 IP 或办公出口 IP。
- TCP 8090:部署验证期间可以先允许自己的访问 IP;如果公网 IP 不固定,才临时允许更宽的来源范围。
- 不开放 TCP 5432。
如果服务器启用了 UFW,可以先查看状态:
sudo ufw status verbose
需要临时开放 8090 时执行:
sudo ufw allow 8090/tcp
sudo ufw status numbered
如果只允许指定来源地址,规则应进一步限制来源,例如:
sudo ufw allow from YOUR_CLIENT_IP to any port 8090 proto tcp
这里的 YOUR_CLIENT_IP 应替换为实际访问端公网 IP。开放端口后,先确认云厂商安全组和 UFW 都已生效,再进行容器启动验证。
五、拉取镜像并完成首次启动
拉取固定版本镜像
执行:
sudo docker compose pull
预期会拉取 Halo 和 PostgreSQL 镜像。如果出现 manifest unknown、pull access denied 或类似错误,优先检查 .env 中的 HALO_IMAGE 是否为实际存在的镜像标签,不要盲目改成 latest。
镜像拉取成功后,启动服务:
sudo docker compose up -d
查看容器状态:
sudo docker compose ps
正常情况下,两个容器都会显示为运行状态,例如:
NAME SERVICE STATUS
halo halo Up
halo-postgres halo-postgres Up (healthy)
具体状态文本会随 Compose 版本有所不同,重点是 halo 没有持续重启,halo-postgres 能够通过健康检查。
检查数据库是否已经准备完成
先查看 PostgreSQL 日志:
sudo docker compose logs --tail=80 halo-postgres
正常情况下,可以看到数据库完成初始化并开始接受连接的提示。若看到 database system is ready to accept connections,说明数据库服务已经达到可连接状态。
再查看 Halo 日志:
sudo docker compose logs --tail=120 halo
重点观察以下情况:
- 是否出现应用启动完成或服务监听端口的日志。
- 是否持续出现
Connection refused。 - 是否出现数据库认证失败、密码错误或迁移异常。
- 容器是否因为异常退出而反复重启。
首次启动可能需要几十秒,尤其是在首次初始化数据库和生成 Halo 配置时。等待一段时间后再进行端口测试,不要在容器刚创建时立即判断失败。
验证宿主机本地访问
从服务器本机执行:
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8090/
预期能够得到 HTTP 200 或 HTTP 3xx。对首次访问而言,返回跳转状态也可能是正常的,关键是不能出现连接失败、超时或 HTTP 000。
继续查看监听端口:
sudo ss -lntp | grep ':8090'
预期能够看到 8090 处于监听状态。若本机 curl 成功但公网访问失败,问题通常不在 Halo 容器内部,而在云安全组、UFW 或公网地址使用错误。

六、完成首次访问与管理控制台验证
在本地电脑浏览器中访问:
http://云服务器公网IPv4:8090/
同时可以访问管理入口:
http://云服务器公网IPv4:8090/console
不同 Halo 版本的首次页面路径和跳转表现可能略有差异。如果根路径能够打开初始化页面,但 /console 发生跳转,通常不代表部署失败。
首次进入时,按页面要求设置:
- 管理员用户名。
- 管理员密码。
- 站点名称。
- 站点外部地址。
管理密码应单独设置,不要复用 .env 中的 PostgreSQL 密码。站点外部地址应与当前访问地址一致,例如:
http://实际公网IPv4:8090
如果初始化页面要求填写外部地址,而后续准备绑定域名,可以先使用当前公网 IP 完成首次验证,等域名和反向代理准备好后再修改。首次部署阶段不建议同时引入域名、HTTPS、缓存和反向代理,以免无法区分是 Halo 本身还是代理层的问题。
完成初始化后,至少验证以下动作:
- 关闭初始化页面并重新打开站点首页。
- 打开
/console,使用刚设置的管理员账号登录。 - 刷新管理页面,确认登录状态能够保持。
- 查看 Halo 管理界面中的系统信息,确认应用不是处于初始化失败状态。
- 查看容器日志,确认登录和页面访问期间没有持续报错。
还可以检查 Halo 数据目录是否已经生成内容:
find /opt/halo/halo2 -maxdepth 2 -type f | head
检查 PostgreSQL 数据目录:
sudo du -sh /opt/halo/postgres
这只能证明目录产生了数据,不能替代应用层验证。最终仍应以首页能够访问、管理后台能够登录、容器保持运行作为首次部署成功条件。
七、常见异常与处理顺序
docker compose 不存在或 Docker 服务未运行
先执行:
sudo systemctl status docker --no-pager
sudo docker compose version
如果 Docker 服务未运行:
sudo systemctl enable --now docker
如果当前用户没有访问 Docker Socket 的权限,可以临时在命令前加 sudo。不要为了绕过权限错误而给 Docker Socket 设置全局可写权限。Docker 管理权限本身接近主机管理员权限,应只授予可信运维账号。
镜像无法拉取
检查网络和镜像标签:
getent hosts registry-1.docker.io
sudo docker pull halohub/halo:2.20
如果提示镜像标签不存在,修改 .env 中的 HALO_IMAGE,使用 Halo 对应版本文档或镜像仓库中确认存在的标签。如果只有 Halo 镜像拉取失败而 PostgreSQL 正常,问题集中在 Halo 镜像地址、标签或镜像仓库访问权限,不需要重建数据库目录。
Halo 容器反复重启
查看两边日志:
sudo docker compose ps
sudo docker compose logs --tail=150 halo
sudo docker compose logs --tail=100 halo-postgres
不同结果的含义通常如下:
halo-postgres未达到healthy:优先检查 PostgreSQL 日志和磁盘空间。password authentication failed:检查.env是否被修改过;已有数据库不能仅靠修改环境变量更新密码。Connection refused:检查 Halo 使用的数据库主机名是否仍为halo-postgres,以及 PostgreSQL 容器是否运行。permission denied:检查/opt/halo/halo2和/opt/halo/postgres的目录权限,不要直接对整个/opt执行递归权限修改。- 数据库迁移或版本异常:先停止升级和反复重启,保留当前数据目录,再根据目标 Halo 版本的兼容要求处理。
不要在异常状态下直接执行 docker compose down -v。该命令可能删除 Docker 卷,且会扩大数据丢失范围。
本机访问正常,公网访问失败
按由外到内的顺序检查:

- 浏览器使用的是否是云服务器实际公网 IPv4,而不是内网地址。
- 云厂商安全组是否允许 TCP 8090。
- UFW 是否放行 8090。
ss -lntp是否显示宿主机正在监听 8090。- Compose 端口映射是否仍为
8090:8090。
如果服务器本机执行 curl http://127.0.0.1:8090/ 成功,而外部访问超时,优先处理安全组和 UFW,不要先修改 Halo 数据库配置。
页面能打开但外部链接异常
检查 .env 中的 HALO_EXTERNAL_URL 是否仍是 localhost、错误 IP 或错误端口:
grep '^HALO_EXTERNAL_URL=' .env
修改后重新创建 Halo 容器:
sudo docker compose up -d --force-recreate halo
该操作会重建 Halo 容器,但不会删除 ./halo2 和 ./postgres 中的数据。重新创建后,再次查看日志和浏览器访问结果。
八、验收与回滚检查项
首次部署验收清单
- [ ] Ubuntu、Docker 和 Compose 版本已确认。
- [ ]
/opt/halo/.env权限为600,数据库密码不是公开示例值。 - [ ]
docker compose config能够通过。 - [ ]
halo容器处于运行状态,没有持续重启。 - [ ]
halo-postgres通过健康检查。 - [ ] 宿主机 8090 端口处于监听状态。
- [ ] 服务器本机访问
127.0.0.1:8090返回 200 或 3xx。 - [ ] 外部浏览器可以打开公网 IP 加 8090 端口。
- [ ] Halo 初始化页面能够完成。
- [ ] 管理员账号可以登录
/console。 - [ ] PostgreSQL 5432 未发布到公网。
- [ ] 云安全组和 UFW 规则与实际访问来源一致。
保留数据的常规停止方式
需要停止本次部署但保留数据时,使用:
cd /opt/halo
sudo docker compose down
这里不使用 -v,也不删除 halo2 和 postgres 目录。之后可以重新启动:
sudo docker compose up -d
首次部署失败时的安全回滚
如果这是全新部署,尚未创建文章、主题或插件,可以通过移动数据目录重新初始化,而不是直接删除:

cd /opt/halo
sudo docker compose down
sudo mv halo2 "halo2.failed.$(date +%Y%m%d-%H%M%S)"
sudo mv postgres "postgres.failed.$(date +%Y%m%d-%H%M%S)"
mkdir -p halo2 postgres
sudo docker compose up -d
移动目录会保留失败现场,便于后续检查。该操作会使新的 Halo 和 PostgreSQL 从空目录开始,只有在确认旧目录中没有需要保留的数据时才能执行。
如果只是要回退 Halo 镜像版本,应先备份 halo2 和 postgres 目录,再修改 HALO_IMAGE 并重新拉取镜像。数据库已经执行过版本迁移时,不要直接降级应用版本;先确认目标版本是否支持当前数据库结构。完成验收后,如果暂时不打算让公网直接访问 8090,可以删除云安全组中的 8090 规则,并撤销 UFW 规则:
sudo ufw delete allow 8090/tcp
这样可以保留容器运行状态,同时关闭首次验证用的公网入口,后续再根据正式访问方案配置域名或反向代理。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8057.html



