Halo 域名主题路由插件完整配置手册

插件地址：https://www.halo.run/store/apps/app-rgfjzxsx

适用环境：1Panel + Docker 部署 Halo-Pro，多域名共用同一个 Halo 实例，根据访问域名自动切换站点主题

⚠️ 核心原理：依靠 Nginx 反向代理传递 Host、X-Forwarded-Host 请求头，插件读取请求头识别当前访问域名，匹配预设绑定规则。缺少 / 传错这两个请求头，插件无法识别域名，主题切换失效。

一、前置准备

所有域名 DNS 解析到当前服务器公网 IP
服务器安全组 / 防火墙开放 80、443 端口
域名 SSL 证书已申请并在 1Panel 网站配置完成
Halo 容器正常运行，状态 healthy
在 Halo 应用市场安装【域名主题路由】插件

二、1Panel Nginx 反向代理配置（关键步骤）

警告：不要使用 1Panel 可视化反向代理新增location /，会出现duplicate location "/"重复 location 报错，直接编辑网站配置文件

进入 1Panel → 网站 → docs.jingdiekeji.com → 切换【配置文件】标签，全选原有内容，替换为下方完整 Server 配置

server {
    listen 80 ; 
    listen 443 ssl ; 
    server_name docs.jingdiekeji.com app.jingdiekeji.com nav.jingdiekeji.com; 
    index index.php index.html index.htm default.php default.htm default.html; 
    access_log /www/sites/docs.jingdiekeji.com/log/access.log main; 
    error_log /www/sites/docs.jingdiekeji.com/log/error.log; 

    location ~ ^/(\.user.ini|\.htaccess|\.git|\.env|\.svn|\.project|LICENSE|README.md) {
        return 404; 
    }
    location ^~ /.well-known/acme-challenge {
        allow all; 
        root /usr/share/nginx/html; 
    }
    if ( $uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$" ) {
        return 403; 
    }

    location / {
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Host $host; 
        proxy_set_header X-Real-IP $remote_addr; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_set_header Connection upgrade; 
        proxy_set_header Upgrade $http_upgrade; 
        proxy_http_version 1.1; 
        proxy_ssl_server_name off; 
        proxy_ssl_name $proxy_host; 
        proxy_pass http://172.18.0.3:8090; 
    }

    http2 on; 
    if ($scheme = http) {
        return 301 https://$host$request_uri; 
    }
    ssl_certificate /www/sites/docs.jingdiekeji.com/ssl/fullchain.pem; 
    ssl_certificate_key /www/sites/docs.jingdiekeji.com/ssl/privkey.pem; 
    ssl_protocols TLSv1.3 TLSv1.2; 
    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:!aNULL:!eNULL:!EXPORT:!DSS:!DES:!RC4:!3DES:!MD5:!PSK:!KRB5:!SRP:!CAMELLIA:!SEED; 
    ssl_prefer_server_ciphers off; 
    ssl_session_cache shared:SSL:10m; 
    ssl_session_timeout 10m; 
    error_page 497 https://$host$request_uri; 
    add_header Strict-Transport-Security "max-age=31536000"; 
}

配置修改要点说明

proxy_pass http://172.18.0.3:8090;：填写 Halo 容器内网 IP，禁止使用 127.0.0.1，OpenResty 在 Docker 容器内，127.0.0.1 指向自身。
proxy_set_header X-Forwarded-Host $host;：必须是$host，不能写$server_name，$host 代表用户真实访问域名，插件依靠该 Header 识别域名。
保留Connection upgrade和Upgrade：用于 Halo 后台 WebSocket 实时通信，后台编辑器、通知功能依赖此项。

保存后，1Panel 自动校验 Nginx 配置，无报错即代表 Nginx 配置生效。 ⚠️ 注意：Halo 容器重启后内网 IP 可能变动，出现 502 Bad Gateway 时，进入容器页面查看新 IP 并更新proxy_pass地址。

三、Halo 后台基础设置

登录 Halo 后台 → 【系统设置】→【基本设置】
外部访问地址（站点 URL）：填写主域名 https://docs.jingdiekeji.com

多域名场景只需要填写主站点 URL，域名主题路由插件会接管多域名识别，无需修改此项为多个地址。

保存设置。

四、域名主题路由插件后台配置

Halo 后台 → 【插件】→ 找到【域名主题路由】→ 点击【设置】
点击【添加绑定】，逐个添加域名绑定规则：

表格

访问域名	绑定主题	启用状态
docs.jingdiekeji.com	选择文档站点主题	✅ 开启
app.jingdiekeji.com	选择应用站点主题	✅ 开启
nav.jingdiekeji.com	选择导航站点主题	✅ 开启

⚠️ 填写规则：访问域名只填写纯域名，不要加 http/https，不要带末尾斜杠。每个域名单独一条绑定记录，绑定的主题需要提前在【主题管理】中安装并存在。

全部添加完成后保存插件配置。

五、验证测试步骤

分别打开浏览器无痕窗口访问 3 个域名：

观察每个域名加载的主题是否和插件绑定设置一致。
辅助校验（查看请求头）：浏览器 F12 开发者工具 → Network，查看请求的 Request Headers，确认Host和X-Forwarded-Host为当前访问域名。

六、常见故障排查

1. 访问出现 502 Bad Gateway

原因：proxy_pass 的 Halo 容器 IP 错误，或 Halo 容器未启动
解决：进入 1Panel 容器页面，确认 Halo 容器状态，获取最新内网 IP，修改 Nginx 配置的 proxy_pass。

2. 所有域名都只显示同一个主题，切换失效

99% 为请求头传递错误，按顺序检查：

Nginx 配置内 X-Forwarded-Host 是否设置为 $host，不是$server_name
保存 Nginx 配置，确认 Nginx 重载成功无报错
插件绑定的域名拼写是否完全一致，没有多余 http、斜杠、空格
绑定规则【启用状态】已打开，选中的主题已安装

3. 后台跳转异常，域名变成 172.18.0.3:8090

缺少X-Forwarded-Host请求头，或者 Halo 后台【外部访问地址】没有正确填写主域名。

4. 静态资源（图片、CSS）404

Host $host请求头缺失，检查 Nginx 配置中proxy_set_header Host $host;是否存在。

七、维护备注

Halo 容器重启后，Docker 内网 IP 可能发生变化。网站出现 502 报错时优先排查容器 IP。新增域名：在 Nginx 的server_name追加域名，再到插件后台新增一条域名 - 主题绑定记录即可。

Halo 域名主题路由插件 完整配置手册

一、前置准备

二、1Panel Nginx 反向代理配置（关键步骤）

配置修改要点说明

三、Halo 后台基础设置

四、域名主题路由插件后台配置

五、验证测试步骤

六、常见故障排查

1. 访问出现 502 Bad Gateway

2. 所有域名都只显示同一个主题，切换失效

3. 后台跳转异常，域名变成 172.18.0.3:8090

4. 静态资源（图片、CSS）404

七、维护备注

Halo 域名主题路由插件完整配置手册