如何在美国服务器上用Docker部署Halo博客并完成首次访问?
在一台具备公网 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 LTS | cat /etc/os-release |
| CPU 架构 | x86_64/amd64 | uname -m |
| 计算资源 | 1 vCPU、2 GB 内存起步 | lscpu、free -h |
| 磁盘空间 | 至少预留 20 GB | df -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:8090 | http://服务器公网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
配置中各项作用如下:

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。

如果本地 8090 已经被其他程序占用,可以换一个本地端口,例如:
ssh -N -L 18090:127.0.0.1:8090 <SSH用户名>@<服务器公网IPv4>
然后访问:
http://127.0.0.1:18090
设置初始管理员和站点信息
首次进入初始化页面后,按照页面提示完成基础设置:
- 选择站点语言。
- 创建管理员账号。
- 设置长度足够、没有在其他服务重复使用的密码。
- 设置站点名称和基础信息。
- 如果页面要求填写站点地址,使用访客实际访问的地址。
站点地址应与访问方式相匹配:
- 公网 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
但外部浏览器超时,优先按以下顺序检查:
- 云平台安全组是否允许 TCP 8090。
- UFW 或其他主机防火墙是否允许管理端公网 IP。
- Compose 是否使用了
127.0.0.1:8090:8090。 - 浏览器访问的是否是服务器公网 IP,而不是内网 IP。
- 服务器是否处于 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



