如何在美国服务器上用Docker部署Halo博客并完成首次访问?

发布人:A5数据发布时间:2026-11-14 09:53阅读量:30

在一台具备公网 IPv4 的美国 Linux 服务器上,Halo 的最小可用部署可以收敛为 Docker Engine、Docker Compose 插件、Halo 容器和一个持久化数据目录,不必先搭建独立数据库或复杂运维组件。本文以 Ubuntu 22.04/24.04 LTS、x86_64 架构为例,完成镜像拉取、容器启动、首次设置和页面可用性验证。

首次部署建议先使用 8090 端口完成访问测试,并在云平台安全组和服务器防火墙中限制访问来源。确认 Halo 能正常启动后,再根据实际需求配置域名、HTTPS 和反向代理。本文重点解决“从零启动到第一次打开 Halo 页面”这一目标,不把插件、邮件、对象存储等非必要组件混入基础部署。

A5idc数据提供美国物理服务器租用,覆盖常规Xeon和AMD EPYC等配置,可为Halo博客的Docker部署提供计算、内存与存储资源。美国AMD系列包含搭配DDR5内存和NVMe存储的方案,常规系列提供CN2 GIA线路方案,可为面向美国用户的网站和跨境访问场景提供部署基础。

准备条件

服务器与网络要求

美国服务器所在地区不会改变 Docker 和 Halo 的基本安装命令,但需要确认云平台网络策略、服务器防火墙和公网地址配置正确。首次部署前,至少准备以下条件:

项目建议条件核验方式
操作系统Ubuntu 22.04 或 24.04 LTScat /etc/os-release
CPU 架构x86_64/amd64uname -m
计算资源1 vCPU、2 GB 内存起步lscpu、free -h
磁盘空间至少预留 20 GBdf -h /
管理权限可通过 SSH 登录并使用 sudo执行 sudo -v
出站网络能访问软件仓库和容器镜像仓库的 HTTPS 服务使用包管理器和 Docker 拉取镜像验证
入站网络SSH 22 端口;首次访问时允许 TCP 8090云平台安全组和 UFW

1 vCPU、2 GB 内存适合小规模首次验证。若后续安装较多插件、上传较大的媒体文件,或者访问量增加,应根据内存、磁盘和并发情况进行扩容。

先登录服务器,检查系统版本、架构和资源:

cat /etc/os-release
uname -m
free -h
df -h /

如果输出的架构不是 x86_64,不要直接套用本文的镜像配置,应先确认所选 Halo 镜像标签是否提供对应架构。对于发行版不是 Ubuntu 的服务器,Docker 安装命令也需要按实际系统调整。

规划访问方式

首次访问有两种方式:

方式容器端口配置浏览器地址防火墙要求
临时公网访问8090:8090http://服务器公网IP:8090允许管理端公网 IP 访问 TCP 8090
SSH 隧道访问127.0.0.1:8090:8090本地 http://127.0.0.1:8090不需要开放公网 8090,只需允许 SSH

本文主流程使用临时公网访问,方便直接验证美国服务器上的 Halo 页面。由于该方式使用普通 HTTP,不建议长期用于公开管理后台。如果只想在自己的电脑上完成首次设置,可以在 Compose 文件中使用 SSH 隧道方式,后文会给出修改方法。

如果服务器已经配置了云平台安全组,先在安全组中添加以下规则:

  • TCP 22:仅允许自己的管理端公网 IP。
  • TCP 8090:首次验证时仅允许自己的管理端公网 IP。
  • 如果暂时不做公网访问,可以不开放 TCP 8090,改用 SSH 隧道。

在服务器启用 UFW 前,先确认当前 SSH 会话正常,并保留一个备用 SSH 会话。不要在未确认 22 端口规则的情况下直接启用防火墙。

sudo ufw status verbose

如果需要使用 UFW,可以先添加管理端地址规则:

sudo ufw allow from <管理端公网IPv4> to any port 22 proto tcp
sudo ufw allow from <管理端公网IPv4> to any port 8090 proto tcp
sudo ufw status numbered

确认规则无误后再启用:

sudo ufw enable
sudo ufw status verbose

<管理端公网IPv4> 必须替换为实际访问服务器的公网地址,不能把占位符原样执行。如果管理端公网地址经常变化,首次部署阶段可以暂不启用 UFW,先依靠云平台安全组完成限制。

安装 Docker Engine 和 Compose

检查是否已经安装

部分云服务器镜像已经预装 Docker。先检查 Docker Engine 和 Compose 插件:

docker --version
docker compose version

如果两个命令都能正常返回版本号,可以跳过安装步骤,直接执行 Docker 运行验证。若其中一个命令不存在,或者 Docker 包来源混杂,建议统一使用同一套安装方式,不要同时混用发行版的 docker.io、第三方脚本和 Docker 官方软件包。

在 Ubuntu 上安装 Docker

以下命令适用于 Ubuntu 22.04/24.04。先安装仓库所需的基础工具:

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、容器运行时、Buildx 和 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
sudo systemctl status docker --no-pager

验证 Docker 环境

先查看版本:

sudo docker version
sudo docker compose version

再运行一次测试容器:

sudo docker run --rm hello-world

看到包含 Hello from Docker! 的输出,说明 Docker Engine 可以创建并运行容器。该测试容器执行结束后会自动删除,不会影响 Halo 部署。

本文后续统一使用 sudo docker 和 sudo docker compose,不建议为了省略 sudo 而直接把普通用户加入 docker 用户组。Docker 用户组通常具备接近 root 的主机控制能力,首次部署时保持明确的权限边界更容易排查问题。

创建 Halo 部署目录

建立持久化数据目录

在当前登录用户的家目录下创建 Halo 部署目录:

mkdir -p "$HOME/halo-deploy/halo-data"
cd "$HOME/halo-deploy"

这里的 halo-data 用于保存 Halo 的应用数据。容器本身可以被删除或重新创建,但这个目录不应随意删除。首次部署、容器重建、升级和回滚都依赖该目录中的数据。

编写 Compose 配置

在 ~/halo-deploy 下创建 compose.yaml:

cat > compose.yaml <<'EOF'
services:
  halo:
    image: halohub/halo:2
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./halo-/root/.halo2
EOF

配置中各项作用如下:

创建 Halo 部署目录 / 编写 Compose 配置配图

  • image:使用 Halo 2.x 镜像。这里使用主版本标签,适合首次验证。
  • container_name:固定容器名称,便于查看日志和执行检查命令。
  • restart: unless-stopped:服务器重启后自动拉起容器,手动停止后不会被自动启动。
  • 8090:8090:将服务器的 8090 端口映射到容器内 Halo 的 8090 端口。
  • ./halo-/root/.halo2:把应用数据保存到服务器目录,避免容器删除后数据消失。

halohub/halo:2 便于快速完成首次启动,但它不是严格的版本锁定方式。完成验证后,如果准备长期运行,建议根据实际使用的 Halo 版本,将 image 修改为已经核对过的具体 2.x 标签,并同时保存 Compose 文件和镜像版本信息。不要在没有备份的情况下直接更换版本标签。

检查配置文件

先让 Compose 解析配置,不要急于启动:

sudo docker compose config

命令能够输出解析后的配置且没有报错,说明 YAML 格式、缩进和字段基本正确。常见错误包括:

  • mapping values are not allowed:YAML 缩进或冒号格式错误。
  • additional property ... is not allowed:字段位置不正确。
  • no configuration file provided:当前目录不是 ~/halo-deploy,或者文件名不是 compose.yaml。

确认目录和文件:

pwd
ls -la

预期可以看到:

compose.yaml
halo-data

拉取镜像并启动 Halo

拉取镜像

在部署目录执行:

cd "$HOME/halo-deploy"
sudo docker compose pull

首次拉取会下载 Halo 镜像,耗时取决于美国服务器到镜像仓库的网络质量、磁盘速度和镜像大小。拉取过程中不要反复执行 up,先等待命令结束。

如果拉取成功,再启动容器:

sudo docker compose up -d

-d 表示后台运行。启动后查看容器状态:

sudo docker compose ps

正常情况下,halo 服务状态应为 Up 或类似运行状态。若状态为 Exited、Restarting 或没有任何容器,进入异常处理部分查看日志。

查看启动日志

首次启动时,Halo 需要初始化应用数据,日志可能会持续输出一段时间。查看最近 120 行:

sudo docker logs --tail=120 halo

如果需要持续观察启动过程:

sudo docker logs -f --tail=100 halo

按 Ctrl+C 只会退出日志查看,不会停止容器。

没有看到持续报错时,可以在服务器本机请求 Halo:

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

返回 200 或其他正常的 3xx 状态,通常说明 HTTP 服务已经能够响应。若返回 connection refused,说明主机端口没有服务监听,应该先检查容器状态和日志。

再确认端口监听情况:

sudo ss -lntp | grep ':8090'

由于当前配置使用 8090:8090,通常可以看到 0.0.0.0:8090 或 IPv6 对应的监听记录。只有 127.0.0.1:8090 时,外部浏览器无法直接访问,需要确认 Compose 文件中的端口映射是否与预期一致。

完成首次访问

通过公网 IP 访问

如果云平台安全组和服务器防火墙已经允许管理端公网 IP 访问 TCP 8090,在本地浏览器输入:

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

如果已经把域名 A 记录指向服务器,也可以使用:

http://<你的域名>:8090

首次打开时,页面可能需要等待镜像初始化和应用准备完成。浏览器出现 Halo 的初始化页面、站点页面或设置入口,说明网络链路和容器服务已经接通。

这里使用的是 HTTP,不要在尚未配置证书和 HTTPS 终止服务时直接把地址改成 https://。如果浏览器提示连接不安全,这是明文 HTTP 的正常表现,不代表 Docker 或 Halo 启动失败。

通过 SSH 隧道访问

如果不希望把 8090 暴露到公网,可以将 Compose 文件中的端口改为只监听本机:

services:
  halo:
    image: halohub/halo:2
    container_name: halo
    restart: unless-stopped
    ports:
      - "127.0.0.1:8090:8090"
    volumes:
      - ./halo-/root/.halo2

保存后重新创建容器:

cd "$HOME/halo-deploy"
sudo docker compose up -d

在本地电脑上建立 SSH 隧道:

ssh -N -L 8090:127.0.0.1:8090 <SSH用户名>@<服务器公网IPv4>

保持该终端运行,然后在本地浏览器打开:

http://127.0.0.1:8090

此时浏览器访问的是本地端口,SSH 将请求转发到美国服务器上的 Halo。使用隧道方式时,不需要在云平台安全组和 UFW 中开放公网 TCP 8090。

完成首次访问 / 通过 SSH 隧道访问配图

如果本地 8090 已经被其他程序占用,可以换一个本地端口,例如:

ssh -N -L 18090:127.0.0.1:8090 <SSH用户名>@<服务器公网IPv4>

然后访问:

http://127.0.0.1:18090

设置初始管理员和站点信息

首次进入初始化页面后,按照页面提示完成基础设置:

  1. 选择站点语言。
  2. 创建管理员账号。
  3. 设置长度足够、没有在其他服务重复使用的密码。
  4. 设置站点名称和基础信息。
  5. 如果页面要求填写站点地址,使用访客实际访问的地址。

站点地址应与访问方式相匹配:

  • 公网 IP 访问:http://服务器公网IPv4:8090
  • 域名访问:http://你的域名:8090
  • 仅使用 SSH 隧道暂时测试:可以先使用本地地址完成验证,但后续公开访问前要改为实际域名或公网地址。

不要把 127.0.0.1 或 localhost 作为长期公开站点地址。它们只代表访问者自己的本机,其他访客无法通过这个地址打开服务器上的站点。

如果初始化页面没有提供站点地址设置,完成登录后,在站点基础设置中找到站点地址或外部访问地址,将其改为访客实际使用的 URL。未来如果增加 HTTPS 反向代理,站点地址也应同步改为类似下面的形式:

https://blog.example.com

首次部署阶段不需要先安装独立数据库、缓存或插件。先确认核心站点能够打开、管理员能够登录,再逐项增加其他组件,可以减少问题定位范围。

常见异常处理

镜像拉取失败

如果执行 docker compose pull 时出现超时、解析失败或连接仓库失败,先检查服务器的 DNS 和出站 HTTPS:

getent hosts registry-1.docker.io
curl -I https://download.docker.com

如果域名无法解析,问题在服务器 DNS 或云平台网络配置,不是 Halo Compose 配置。若 DNS 正常但 HTTPS 连接失败,需要检查云平台是否限制出站 TCP 443、服务器时间是否正确,以及系统代理或网络策略是否影响 Docker。

检查 Docker 服务状态:

sudo systemctl status docker --no-pager
sudo journalctl -u docker --no-pager -n 100

不要因为一次拉取失败就删除 halo-data。镜像问题和应用数据没有直接关系。

显示架构不匹配

如果日志包含 no matching manifest 或类似架构错误,先确认:

uname -m
sudo docker info --format '{{.OSType}}/{{.Architecture}}'

如果服务器是 ARM 架构,而当前 Halo 镜像标签没有对应架构,不能仅通过修改 Compose 缩进解决。应选择提供兼容镜像的版本,或改用 x86_64 服务器。不要在首次部署时默认使用模拟执行方式,因为它会增加性能和故障排查变量。

8090 端口已被占用

如果启动时出现 address already in use,检查占用进程:

sudo ss -lntp | grep ':8090'

如果是其他业务正在使用 8090,可以把主机端口改为 18090,容器内部端口仍保持 8090:

ports:
  - "18090:8090"

重新创建容器:

cd "$HOME/halo-deploy"
sudo docker compose up -d

之后使用下面的地址访问:

http://<服务器公网IPv4>:18090

如果使用 SSH 隧道,远端映射端口也要改为 18090:

ssh -N -L 18090:127.0.0.1:18090 <SSH用户名>@<服务器公网IPv4>

容器不断重启

先查看状态和最近日志:

sudo docker compose ps
sudo docker logs --tail=200 halo

再检查内存和磁盘:

free -h
df -h /
sudo docker stats --no-stream halo

如果日志出现进程被系统终止、内存不足或磁盘写满,应先释放资源或扩容,再重新启动。不要通过删除数据目录来处理内存或磁盘问题。

如果需要确认容器退出状态:

sudo docker inspect halo \
  --format 'status={{.State.Status}} exit={{.State.ExitCode}} error={{.State.Error}}'

exit=0 可能表示进程正常结束但没有保持前台运行;非零退出码通常需要结合日志判断具体原因。

本机 curl 正常,外部浏览器无法访问

如果服务器本机执行以下命令正常:

curl -I http://127.0.0.1:8090

但外部浏览器超时,优先按以下顺序检查:

  1. 云平台安全组是否允许 TCP 8090。
  2. UFW 或其他主机防火墙是否允许管理端公网 IP。
  3. Compose 是否使用了 127.0.0.1:8090:8090。
  4. 浏览器访问的是否是服务器公网 IP,而不是内网 IP。
  5. 服务器是否处于 NAT 后面,云控制台显示的公网地址是否真正绑定到实例。

检查端口绑定:

sudo ss -lntp | grep ':8090'

如果端口只绑定在 127.0.0.1,请使用 SSH 隧道,或者确认确实需要公网访问后再改成 8090:8090。

页面打开后数据没有保留

检查容器挂载关系:

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

预期应看到服务器上的 halo-data 目录映射到:

/root/.halo2

也可以检查目录是否存在内容:

cd "$HOME/halo-deploy"
sudo find halo-data -maxdepth 2 -type f | head -n 20

如果每次删除并重建容器后都回到初始化页面,通常说明没有正确挂载持久化目录,或者启动时使用了其他 Compose 文件。不要继续操作前先确认当前工作目录和挂载配置。

数据目录权限异常

如果日志出现 permission denied,先查看目录权限和容器运行用户:

cd "$HOME/halo-deploy"
ls -ld halo-data
sudo docker inspect halo --format '{{.Config.User}}'
sudo docker logs --tail=100 halo

不要直接执行 chmod -R 777 halo-data。如果容器不是以 root 身份运行,应根据日志和镜像实际 UID/GID 对数据目录进行最小范围授权;无法确认 UID 时,先保留日志,不要猜测权限值。

可用性与持久化验证

首次向导完成后,按照以下顺序验证:

验证容器状态

cd "$HOME/halo-deploy"
sudo docker compose ps

服务应保持运行状态,而不是启动后立即退出。

验证 HTTP 响应

在服务器本机执行:

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

返回 200 或正常的 3xx 响应即可作为基础连通性结果。浏览器端还需要额外通过安全组和防火墙验证。

验证管理员登录

在浏览器完成首次登录,确认以下项目:

  • 初始化页面不再重复出现。
  • 站点首页能够正常打开。
  • 管理页面能够进入。
  • 刷新页面后登录状态和站点设置仍然存在。
  • 站点名称、语言和地址与预期一致。

验证容器重启后的数据

先执行一次容器重启:

cd "$HOME/halo-deploy"
sudo docker compose restart
sleep 5
sudo docker compose ps
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8090/

再次打开站点并登录。如果设置和内容仍然存在,说明数据目录挂载基本有效。

检查自动重启策略:

sudo docker inspect halo \
  --format '{{.HostConfig.RestartPolicy.Name}}'

预期输出:

unless-stopped

长期公开访问前的边界

直接使用 http://公网IP:8090 适合首次测试,不适合长期公开管理。正式对外提供服务时,通常需要:

  • 使用域名指向服务器公网 IP。
  • 由支持 HTTPS 的反向代理接收 80/443 请求。
  • 将 Halo 容器端口限制在本机或内网监听。
  • 把 Halo 站点地址改为实际的 HTTPS 域名。
  • 根据实际访问量和媒体文件规模评估磁盘、内存和备份策略。

这些配置不是首次启动 Halo 的必要条件,不应在基础容器尚未验证时一次性加入。

备份与回滚

备份前的影响说明

Halo 的应用配置、内容和相关持久化数据都依赖 halo-data。备份本地数据目录前,建议短暂停止容器,以减少写入过程中产生不一致数据。停止期间站点会暂时不可访问。

在部署目录执行:

cd "$HOME/halo-deploy"

sudo docker compose stop

BACKUP="$HOME/halo-backup-$(date +%F-%H%M).tar.gz"
sudo tar -czf "$BACKUP" -C "$HOME/halo-deploy" halo-data compose.yaml

sudo docker compose start
sudo ls -lh "$BACKUP"

备份成功后,确认容器恢复运行:

sudo docker compose ps
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8090/

备份文件应保存到服务器之外的可靠位置。仅把备份放在同一块磁盘上,无法应对磁盘损坏或实例整体丢失。

回滚 Compose 配置

修改 Compose 文件前先保留副本:

cd "$HOME/halo-deploy"
cp compose.yaml compose.yaml.before-change

如果修改端口、挂载或其他配置后启动失败,可以恢复文件:

cp compose.yaml.before-change compose.yaml
sudo docker compose down
sudo docker compose up -d

这里没有使用 docker compose down -v,也没有删除 halo-data,因此不会主动清理持久化数据。回滚后重新检查:

sudo docker compose ps
sudo docker logs --tail=100 halo

如果更换了镜像版本,回滚时必须恢复到原来的具体镜像标签。使用浮动的 halohub/halo:2 时,重新拉取到的内容可能已经变化,因此正式环境应提前固定具体版本并保留对应镜像。

从备份恢复数据

恢复数据前先停止应用,并把当前数据目录改名保留,不要直接删除:

cd "$HOME/halo-deploy"
sudo docker compose stop

sudo mv halo-data "halo-data.failed-$(date +%F-%H%M)"
sudo mkdir halo-data

假设备份文件为 ~/halo-backup-2025-01-01-1200.tar.gz,可以只恢复其中的数据目录:

sudo tar -xzf "$HOME/halo-backup-2025-01-01-1200.tar.gz" \
  -C "$HOME/halo-deploy" halo-data

如需同时恢复备份中的 Compose 文件:

sudo tar -xzf "$HOME/halo-backup-2025-01-01-1200.tar.gz" \
  -C "$HOME/halo-deploy" compose.yaml

启动并验证:

sudo docker compose up -d
sudo docker compose ps
sudo docker logs --tail=120 halo
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8090/

确认站点和管理员数据恢复后,再考虑清理带有 failed 后缀的旧目录。没有完成恢复验证前,不要执行递归删除数据目录的命令。

验收与回滚核对项

验收项

  • [ ] Ubuntu 版本、CPU 架构、内存和磁盘空间符合部署条件。
  • [ ] Docker Engine 和 docker compose 命令可用。
  • [ ] hello-world 测试容器运行成功。
  • [ ] compose.yaml 能通过 docker compose config 检查。
  • [ ] Halo 镜像拉取成功。
  • [ ] docker compose ps 显示 Halo 处于运行状态。
  • [ ] docker logs halo 没有持续性的启动错误。
  • [ ] 服务器本机访问 127.0.0.1:8090 能获得正常 HTTP 响应。
  • [ ] 管理端能够通过公网 IP、域名或 SSH 隧道打开首次设置页面。
  • [ ] 初始管理员账号创建成功并能够登录。
  • [ ] 站点地址没有错误地设置为长期使用的 localhost。
  • [ ] 重启容器后,站点配置和已保存数据仍然存在。
  • [ ] 8090 端口的安全组和防火墙来源范围符合当前测试目的。
  • [ ] 已保存 Compose 文件和数据目录备份。

回滚项

  • [ ] 回滚前已停止 Halo 容器,避免恢复过程中继续写入数据。
  • [ ] 修改前的 compose.yaml 已单独保存。
  • [ ] 当前数据目录已改名保留,没有直接删除。
  • [ ] 恢复使用的备份文件能够在服务器上读取。
  • [ ] 镜像标签与回滚前版本一致,未使用无法确认内容的浮动版本。
  • [ ] 恢复后容器状态、HTTP 响应和管理员登录均已重新验证。
  • [ ] 验证完成前,没有清理旧数据目录或执行带有 -v 的容器删除命令。

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

相关推荐