美国服务器如何部署Halo博客?首次启动后怎样检查访问与数据持久化

发布人:A5数据发布时间:2026-10-22 16:21阅读量:87

在美国服务器上部署 Halo,首次启动阶段需要优先确认三件事:容器是否正常监听、服务器公网是否能够访问初始化页面,以及 Halo 的配置、数据库和上传文件是否写入宿主机而不是仅保存在容器内部。本文采用 Ubuntu 22.04/24.04、Docker Compose 和 Halo 2.x 镜像,先通过 8090 端口完成首次访问,再用重启和容器重建验证数据持久化。

示例使用 /opt/halo/data 作为宿主机数据目录,并映射到容器内 Halo 默认的数据目录 /root/.halo2。美国服务器所在地区不会改变 Halo 的部署命令,但需要同时检查云平台安全组、服务器本机防火墙和服务器到镜像仓库的出站网络。

对于采用 Docker 部署 Halo 的博客、企业网站和内容管理业务,A5数据提供美国物理服务器资源,覆盖常规 Xeon 与 AMD EPYC 平台,并配备 SSD 或 NVMe 存储及 CN2 GIA 线路方案。不同配置可承载容器运行、网站访问、数据库及图片等数据存储需求,为博客应用提供独立的计算、磁盘与网络资源基础。

一、准备条件与环境确认

1. 确认服务器与资源

建议使用具备公网 IPv4 的 Linux 云服务器,并准备一个拥有 sudo 权限的账号。小型个人博客可以将 2 vCPU、2 GB 内存和 20 GB 以上 SSD 作为起步参考;主题、插件、图片数量和访问量增加后,需要根据实际内存与磁盘使用情况调整。

本次示例适用于:

  • Ubuntu 22.04 或 Ubuntu 24.04,64 位;
  • 已获得服务器公网 IPv4;
  • 云平台安全组允许 SSH 访问;
  • 能够访问 Docker 镜像仓库的 HTTPS 出站流量;
  • 暂时使用 http://服务器IP:8090 访问 Halo;
  • 服务器上没有其他程序占用 TCP 8090。

先在服务器执行环境检查:

. /etc/os-release
printf '系统:%s %s\n' "$ID" "$VERSION_ID"
printf '架构:%s\n' "$(uname -m)"
free -h
df -h /

预期能够看到 ubuntu、x86_64,并且根分区仍有可用空间。若系统不是 Ubuntu,Docker 安装命令和防火墙管理方式可能不同,不要直接套用下面的 apt 命令。

检查常用端口:

sudo ss -lntp | grep -E ':(22|80|443|8090)\b' || true

如果没有输出 8090,说明该端口通常可以使用。若已经有服务监听 8090,需要改用其他宿主机端口,例如将后续 Compose 配置中的:

ports:
  - "8090:8090"

改为:

ports:
  - "8091:8090"

这里左侧是服务器端口,右侧仍然是 Halo 容器内部端口。改动后访问地址也要改成 http://服务器IP:8091。

2. 检查云防火墙与 UFW

云平台一般有独立的安全组或网络 ACL。首次直接访问 Halo 时,至少需要允许:

  • TCP 22:SSH 管理;
  • TCP 8090:首次访问 Halo;
  • TCP 80、443:只有后续配置域名和反向代理时才需要。

先查看本机 UFW 状态,不要在未确认 SSH 规则的情况下直接启用防火墙:

sudo ufw status verbose

如果 UFW 已经处于 active,可先查看现有规则并保存记录:

sudo ufw status numbered | tee "$HOME/ufw-before-halo.txt"
sudo ufw allow 8090/tcp comment 'Halo temporary access'

如果 UFW 未启用,不建议为了部署 Halo 临时执行 ufw enable。此时应在美国服务器提供商的安全组中放行 TCP 8090,并保留现有的 SSH 管理规则。防火墙变更的影响范围是整个服务器,不仅限于 Halo。

二、安装并验证 Docker 环境

如果服务器已经安装 Docker,可以直接执行本节最后的版本检查。没有安装时,以 Ubuntu 为例执行以下命令。

1. 安装 Docker Engine 与 Compose 插件

先安装证书和下载工具:

sudo apt-get update
sudo apt-get install -y ca-certificates curl

添加 Docker 官方软件源:

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装 Docker Engine、Compose 和常用插件:

sudo apt-get update
sudo apt-get install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

设置 Docker 开机启动并立即运行:

sudo systemctl enable --now docker

为了让当前登录用户直接执行 docker,可以加入 Docker 用户组:

sudo usermod -aG docker "$USER"

执行后需要退出 SSH 并重新登录。重新登录前,可以暂时使用 sudo docker;不要在尚未重新登录的会话中误判为 Docker 安装失败。

2. 验证 Docker

重新登录服务器后执行:

docker --version
docker compose version
systemctl is-active docker

预期结果分别是 Docker 版本、Compose 版本和:

active

如果 docker compose version 报命令不存在,说明 Compose 插件没有正确安装。此时先确认系统版本和 Docker 软件源,再检查:

apt-cache policy docker-compose-plugin

不要将旧版 docker-compose 与新版 docker compose 的配置和命令混用,本文统一使用 Compose 插件语法。

三、创建 Halo 数据目录与 Compose 配置

1. 创建独立目录

将配置文件和数据放在独立目录中,便于查看、备份和回滚:

sudo mkdir -p /opt/halo/data
sudo chown -R "$USER":"$USER" /opt/halo
cd /opt/halo

本示例使用 Halo 2.x 的固定版本标签。2.21.0 仅作为配置示例,实际部署时应替换为已经确认存在且准备使用的 Halo 2.x 版本,不建议使用 latest,这样可以避免后续重新拉取镜像时版本无意变化。

创建环境变量文件:

cat > /opt/halo/.env <<'EOF'
HALO_VERSION=2.21.0
EOF

如果准备使用其他版本,可以编辑文件:

nano /opt/halo/.env

将 HALO_VERSION 改为目标版本标签。

2. 编写 Docker Compose 文件

创建 /opt/halo/compose.yaml:

cat > /opt/halo/compose.yaml <<'EOF'
services:
  halo:
    image: registry.fit2cloud.com/halo/halo:${HALO_VERSION}
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - .//root/.halo2
EOF

这份配置包含三个关键点:

三、创建 Halo 数据目录与 Compose 配置配图

  • restart: unless-stopped:服务器重启后自动拉起容器,但手动停止后不会被立即重新启动;
  • 8090:8090:将服务器 8090 端口映射到 Halo 容器的 8090 端口;
  • .//root/.halo2:把 /opt/halo/data 挂载到 Halo 数据目录,容器重建后仍然保留数据。

当前示例使用 Halo 默认的数据存储方式。若后续改用外部数据库,数据库中的内容、数据库账号配置和文件上传目录需要分别纳入备份,不能只备份这一处目录。

3. 验证 Compose 配置

先让 Compose 展开变量并检查语法:

cd /opt/halo
docker compose config

输出中应能看到类似内容:

image: registry.fit2cloud.com/halo/halo:2.21.0
container_name: halo
ports:
  - mode: ingress
    target: 8090
    published: "8090"
volumes:
  - type: bind
    source: /opt/halo/data
    target: /root/.halo2

如果镜像版本仍显示 ${HALO_VERSION},说明 .env 文件位置不对,或者执行命令时不在 /opt/halo 目录中。

四、拉取镜像并启动 Halo

1. 拉取指定版本

cd /opt/halo
docker compose pull

预期能够看到镜像下载进度并最终完成。如果出现超时、DNS 解析失败或连接仓库失败,先不要改用不明镜像源,应检查服务器的 DNS、出站 TCP 443 和云平台网络策略。

查看本地镜像:

docker image ls registry.fit2cloud.com/halo/halo

应能看到与 .env 中一致的版本标签。

2. 启动容器

docker compose up -d

查看 Compose 状态:

docker compose ps

正常情况下,halo 服务的状态会显示为 Up。随后查看最近日志:

docker logs --tail 100 --timestamps halo

首次启动可能需要等待一段时间完成目录初始化。日志中不应持续出现 restarting、数据库初始化失败或端口绑定失败等错误。

检查宿主机端口:

sudo ss -lntp | grep ':8090'

预期能看到 Docker 相关进程监听 0.0.0.0:8090 或对应的 IPv6 地址。

3. 先在服务器本机检查 HTTP

使用本机回环地址测试:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  --max-time 10 \
  http://127.0.0.1:8090/

首次启动正常时,通常会返回 200 或 3xx。不同版本在初始化阶段的响应码可能不同,关键是能够在规定时间内得到 HTTP 响应,而不是连接拒绝或超时。

如果本机访问成功,说明 Halo 进程、容器内部端口和宿主机端口映射基本正常,可以继续测试公网访问。

四、拉取镜像并启动 Halo配图

五、从外部访问首次初始化页面

在本地电脑或另一台不在该服务器上的设备执行:

curl -I --max-time 10 "http://${SERVER_PUBLIC_IP}:8090/"

将 SERVER_PUBLIC_IP 替换为美国服务器的实际公网 IPv4。也可以直接在浏览器打开:

http://服务器公网IPv4:8090

首次访问应进入 Halo 初始化页面。按页面提示创建管理员账号和密码。管理员密码不要复用服务器 SSH 密码,也不要写入 Compose 文件、Shell 历史或公开工单。

首次页面能够打开时,至少完成以下检查:

  1. 初始化页面可以从外部网络加载;
  2. 管理员账号可以创建;
  3. 初始化完成后,前台页面可以打开;
  4. 管理后台能够登录;
  5. 刷新页面后不会反复回到初始化页面。

如果服务器本机 curl 正常,但外部访问超时,优先检查以下位置:

sudo ufw status verbose
sudo ss -lntp | grep ':8090'
docker compose ps

同时检查云平台安全组是否放行 TCP 8090,以及访问使用的是否为服务器公网地址。若 DNS 设置了 AAAA 记录,但服务器 IPv6 未正确配置,浏览器也可能优先连接 IPv6 并出现超时;首次验证时可以直接使用公网 IPv4。

六、首次启动后验证数据持久化

仅看到页面能够打开,并不能证明数据已经持久化。需要同时检查挂载关系、宿主机文件和应用层数据。

1. 检查容器挂载关系

执行:

docker inspect halo --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

预期至少包含:

/opt/halo/data -> /root/.halo2

如果没有这条映射,或者目标目录不是 /root/.halo2,说明当前容器没有使用本文的持久化配置。此时不要直接删除容器,先执行:

docker compose config
docker compose ps

确认实际使用的 Compose 文件和挂载目录。

2. 检查宿主机是否产生数据

初始化完成后,在服务器执行:

cd /opt/halo
sudo find data -mindepth 1 -maxdepth 2 -printf '%M %u:%g %p\n' | head -30
sudo du -sh data

预期能看到配置、数据库或其他数据文件,并且 data 目录大小不再是零。文件名和具体层级可能随 Halo 版本变化,不建议手工修改目录中的数据库或配置文件。

3. 用应用数据完成一次重启验证

在 Halo 管理后台新建一篇仅保存为草稿的测试文章,例如标题使用:

持久化验证-首次部署

确认草稿已经保存后,在服务器执行:

cd /opt/halo
docker compose restart halo

等待几秒后验证 HTTP:

sleep 10
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  --max-time 10 \
  http://127.0.0.1:8090/

再次登录管理后台,检查测试草稿是否仍然存在。如果草稿和管理员账号都能保留,说明普通容器重启不会清空应用数据。

4. 用容器重建验证挂载是否真正有效

普通 restart 不会删除容器本身。为了验证容器被移除后数据仍然存在,可以在初次部署阶段执行一次重建测试:

cd /opt/halo
docker compose down
docker compose up -d

这里的 down 只停止并移除容器,不要追加 --volumes。启动后检查:

docker compose ps
docker logs --tail 100 halo
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  --max-time 10 \
  http://127.0.0.1:8090/

然后从浏览器确认管理员账号和测试草稿仍然存在。若重建后又出现初始化页面,优先判断为数据目录挂载错误、挂载目录为空,或启动时使用了另一份 Compose 配置。

六、首次启动后验证数据持久化配图

七、首次部署后的数据备份

验证持久化后,建议制作第一份可回滚备份。默认数据目录可能同时包含数据库文件、Halo 配置和上传内容,备份时应停掉容器,避免嵌入式数据库在写入过程中被直接打包。

cd /opt/halo
mkdir -p backup

docker compose stop halo

sudo tar --xattrs --acls -czf \
  "backup/halo-data-$(date +%F-%H%M%S).tar.gz" \
  -C /opt/halo data

docker compose start halo

检查备份文件:

ls -lh /opt/halo/backup
docker compose ps

备份成功后,归档文件应当有合理大小,容器状态应恢复为 Up。如果只看到几百字节的压缩包,或者 data 目录本身为空,不要把该文件当作有效恢复点。

备份文件与服务器放在同一块磁盘,只能应对误删配置、容器异常等局部问题,无法应对整台服务器故障。正式使用时还应将备份复制到独立存储位置,并限制备份文件的访问权限。

八、常见失败情况与处理顺序

1. 镜像拉取失败

先单独执行:

docker pull registry.fit2cloud.com/halo/halo:2.21.0

如果仍然失败,检查:

getent hosts registry.fit2cloud.com
curl -I --max-time 10 https://registry.fit2cloud.com

DNS 无法解析时检查服务器 DNS;HTTPS 连接超时时检查云平台出站规则。不要因为拉取失败就把镜像标签改成 latest,这会增加版本不可控因素。

2. 8090 端口已被占用

错误通常类似:

Bind for 0.0.0.0:8090 failed: port is already allocated

查找占用者:

sudo ss -lntp | grep ':8090'

如果确认不能停止现有服务,将 Compose 改为:

ports:
  - "8091:8090"

然后执行:

docker compose up -d

同时在云防火墙和 UFW 中放行 TCP 8091,并使用 http://服务器IP:8091 访问。不要修改为 8091:8091,除非确认 Halo 容器内部也配置为监听 8091。

3. 本机访问失败,容器不断重启

依次查看:

docker compose ps
docker logs --tail 200 --timestamps halo
docker inspect halo --format '{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}'

如果日志显示端口、镜像或配置错误,先修正对应问题;如果显示数据目录权限问题,先停止容器并备份 /opt/halo/data,再根据实际容器用户调整权限。不要直接执行 chmod -R 777 /opt/halo/data,这会扩大敏感配置和数据库文件的访问范围。

4. 本机正常,公网无法访问

这类结果通常说明 Halo 本身已经启动,问题在服务器外层网络。检查顺序如下:

八、常见失败情况与处理顺序配图

  1. 云平台安全组是否放行 TCP 8090;
  2. UFW 是否拦截了 8090;
  3. 访问的 IP 是否为公网 IP,而不是内网地址;
  4. 是否存在错误的 IPv6 记录;
  5. 服务器是否位于额外的 NAT 或网络防护之后。

不要先修改 Halo 容器端口。只有本机访问也失败时,才需要回到容器日志和端口映射检查。

5. 重启后重新进入初始化页面

先停止继续写入数据,检查挂载:

docker inspect halo --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
sudo du -sh /opt/halo/data

如果挂载为空,可能是首次启动时使用了错误的工作目录,导致 ./data 指向了其他位置。应统一在 /opt/halo 执行 Compose 命令,并确认 compose.yaml 与 .env 都位于该目录。

不要使用以下命令进行“清理”:

docker compose down -v

它可能删除卷数据。本文使用的是宿主机绑定目录,正常回滚和重建不需要删除卷。

九、交付前的验收与回滚检查项

验收清单

检查项目验证方法通过标准
系统环境cat /etc/os-release、uname -mUbuntu 22.04/24.04、64 位
Docker 服务systemctl is-active docker返回 active
镜像版本docker image ls与 .env 中的固定版本一致
容器状态docker compose psHalo 服务为运行状态
本机访问curl http://127.0.0.1:8090/返回 HTTP 响应
外部访问浏览器或外部 curl能打开初始化后前台页面
数据挂载docker inspect halo/opt/halo/data 映射到 /root/.halo2
应用数据创建草稿后重启管理员账号和草稿仍存在
容器重建down 后再 up -d不重复进入初始化页面
备份文件ls -lh /opt/halo/backup存在可用的非空备份归档

回滚检查项

如果首次启动失败但还没有有效内容,可以先停止并移除容器,保留宿主机数据目录:

cd /opt/halo
docker compose down

不要删除 /opt/halo/data。需要暂时隔离故障目录时,可以改名保留:

sudo mv /opt/halo/data \
  "/opt/halo/data.failed-$(date +%F-%H%M%S)"

如果需要回退到此前验证过的 Halo 镜像版本,先备份当前配置:

cd /opt/halo
cp .env ".env.before-rollback-$(date +%F-%H%M%S)"
nano .env

将 HALO_VERSION 改为此前确认可用的版本,再执行:

docker compose pull
docker compose up -d

涉及数据库结构变化时,不要只通过修改镜像标签进行降级。应优先停止服务,使用部署前的完整数据备份恢复,再启动已验证版本。恢复前保留当前故障目录,避免误覆盖:

cd /opt/halo
docker compose stop halo

sudo mv data "data.before-restore-$(date +%F-%H%M%S)"
sudo tar -xzf backup/指定的备份文件.tar.gz -C /opt/halo

docker compose start halo

确认 Halo 可以访问并完成数据检查后,如果不再需要临时开放直连端口,可先确保后续访问入口已经准备好,再移除防火墙规则:

sudo ufw status numbered
sudo ufw delete allow 8090/tcp

同时删除云平台安全组中对应的 TCP 8090 入站规则。若尚未配置其他访问入口,不能直接关闭 8090,否则会导致当前 Halo 页面无法访问。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5100.html

相关推荐