2025-10-05

Halo 博客系统部署配置

概述

本文档描述了如何使用 Docker Compose 部署 Halo 博客系统，并配置 Nginx 反向代理和 HTTPS 证书的完整过程。

系统环境

操作系统：CentOS/RHEL
服务器 IP：your-server-ip
域名：example.com（支持 www.example.com 和根域名 example.com）
Docker 和 Docker Compose 已安装
PostgreSQL 镜像：postgres:17.4（本地导入）

一、Docker Compose 配置

1.1 基础配置文件

创建 docker-compose.yaml 文件：

services:
  halo:
    image: registry.fit2cloud.com/halo/halo:2.21
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./halo2:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s
    environment:
      - JVM_OPTS=-Xmx256m -Xms256m
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
      - --spring.r2dbc.username=halo
      - --spring.r2dbc.password=openpostgresql
      - --spring.sql.init.platform=postgresql
      # 配置外部访问地址，可以使用 www 或根域名
      - --halo.external-url=https://www.example.com/
  halodb:
    image: postgres:17.4
    restart: on-failure:3
    networks:
      halo_network:
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD", "pg_isready" ]
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_PASSWORD=openpostgresql
      - POSTGRES_USER=halo
      - POSTGRES_DB=halo
      - PGUSER=halo
networks:
  halo_network:

1.2 配置说明

端口映射：Halo 服务映射到 8090 端口，通过 Nginx 反向代理提供 80/443 端口访问
数据库配置：使用 PostgreSQL 17.4，数据持久化到 ./db 目录
健康检查：配置了服务健康检查，确保服务正常启动
外部访问地址：配置为 HTTPS 域名访问

1.3 启动服务

# 启动服务
docker compose up -d

# 检查服务状态
docker compose ps

# 查看日志
docker compose logs halo

二、DNS 域名解析配置

2.1 添加 DNS 记录

在域名服务商管理控制台添加以下记录（将 example.com 替换为你的实际域名）：

记录类型	主机记录	记录值	TTL	说明
A	www	your-server-ip	600	www.example.com
A	@	your-server-ip	600	example.com（根域名）

2.2 验证解析

# 测试 DNS 解析（替换为你的实际域名）
nslookup www.example.com
nslookup example.com
ping www.example.com

三、Nginx 反向代理配置

3.1 安装 Nginx

# CentOS/RHEL 系统
yum install -y nginx

# 启动并启用服务
systemctl start nginx
systemctl enable nginx

3.2 配置反向代理

创建 /etc/nginx/conf.d/halo.conf 文件：

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name www.example.com example.com;
    return 301 https://www.example.com$request_uri;
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    server_name www.example.com example.com;
    
    # Let's Encrypt 证书路径（替换为你的实际域名）
    ssl_certificate /etc/letsencrypt/live/www.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.example.com/privkey.pem;
    
    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # 设置客户端上传文件大小限制
    client_max_body_size 1024m;
    
    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

3.3 测试并重新加载配置

# 测试配置文件语法
nginx -t

# 重新加载配置
nginx -s reload

四、SSL 证书配置

4.1 安装 Certbot

# 安装 certbot
yum install -y certbot python3-certbot-nginx

4.2 申请 Let's Encrypt 证书

# 申请证书（替换为你的实际域名）
certbot --nginx -d www.example.com -d example.com

4.3 处理证书安装问题

如果 certbot 无法自动配置 Nginx，证书文件会保存到：

证书：/etc/letsencrypt/live/www.example.com/fullchain.pem
私钥：/etc/letsencrypt/live/www.example.com/privkey.pem

需要手动配置 Nginx（参考上面的 Nginx 配置）。

4.4 设置自动续期

# 测试续期命令
certbot renew --dry-run

# 添加 crontab 任务
crontab -e

添加以下内容：

# 每天凌晨 2:30 检查证书续期，续期后重新加载 nginx
30 2 * * * /usr/bin/certbot renew --quiet --post-hook "nginx -s reload"

验证 crontab 任务：

crontab -l

五、防火墙和安全组配置

5.1 系统防火墙

# 检查防火墙状态
systemctl status firewalld

# 如果防火墙开启，添加端口规则
firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload

5.2 云服务商安全组

确保以下端口在阿里云安全组中开放：

80 (HTTP)
443 (HTTPS)
8090 (可选，直接访问 Halo)

六、验证和测试

6.1 服务状态检查

# 检查 Docker 服务
docker compose ps

# 检查 Nginx 状态
systemctl status nginx

# 检查端口监听
netstat -tlnp | grep :80
netstat -tlnp | grep :443
netstat -tlnp | grep :8090

6.2 访问测试

# 测试 HTTPS 访问（替换为你的实际域名）
curl -I https://www.example.com

# 测试 HTTP 重定向
curl -I http://www.example.com
curl -I http://example.com

# 测试后端服务
curl -I http://localhost:8090

6.3 浏览器访问

主站：https://www.example.com
管理后台：https://www.example.com/console

注意：也可以使用根域名 example.com 访问，会自动重定向到 www.example.com

七、故障排除

7.1 常见问题

端口占用问题

# 查看端口占用
netstat -tlnp | grep :80
# 强制停止占用进程
pkill -f nginx

Docker 容器启动失败

# 查看详细日志
docker compose logs halo
docker compose logs halodb

Nginx 配置错误

# 测试配置语法
nginx -t
# 查看错误日志
tail -20 /var/log/nginx/error.log

SSL 证书问题

# 检查证书状态
certbot certificates
# 测试续期
certbot renew --dry-run

7.2 服务重启

# 重启 Halo 服务
docker compose down
docker compose up -d

# 重启 Nginx
systemctl restart nginx

# 重新加载 Nginx 配置
nginx -s reload

八、维护和监控

8.1 定期维护

监控证书到期时间（每 90 天自动续期）
定期备份数据库和配置文件
更新 Docker 镜像版本

8.2 备份建议

数据库数据：./db 目录
Halo 数据：./halo2 目录
Nginx 配置：/etc/nginx/conf.d/halo.conf
Docker 配置：docker-compose.yaml

8.3 日志查看

# Halo 应用日志
docker compose logs -f halo

# Nginx 访问日志
tail -f /var/log/nginx/access.log

# Nginx 错误日志
tail -f /var/log/nginx/error.log

# SSL 证书日志
tail -f /var/log/letsencrypt/letsencrypt.log