yunzerwebsite/yunzerwebsiteallinone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
yunzerwebsiteallinone/docs/关于租户官网服务器端nginx的配置.md
T

31 KiB
Raw Permalink Blame History

关于租户官网服务器端 nginx 的配置

适用场景：多租户官网系统。访客访问租户域名（如 ceshi.yunzer.com.cn）时，由 nginx 转发给 Go 服务，Go 按请求 Host 识别租户，用标签引擎解析 themes/{模板编码}/ 模板后直出 HTML。

本文给出宝塔环境下两个主域名（dh2.fun、yunzer.com.cn）的完整 nginx 配置、设计原则与注意事项。

一、架构原理

访客浏览器
   │  https://ceshi.yunzer.com.cn/
   ▼
nginx（宝塔）
   │  全部请求 proxy_pass → Go 服务（upstream 统一管理地址）
   │  透传 Host 头（Go 靠它识别租户）
   ▼
Go 服务（beego，默认 8081 端口）
   │  resolveTid：按 Host 查库识别租户
   │  tagengine：渲染 themes/{模板编码}/ 下的模板
   ▼
直出 HTML（无需前端 SPA）

1.1 Go 侧提供的站点路由

路径 说明
GET / 租户官网首页（渲染 index.html 模板）
GET /news 新闻列表（?page=N 分页）
GET /news/:id 文章详情
GET /page/:path 单页（如 /page/about）
/themes/* 模板静态资源（beego SetStaticPath("/themes", "themes")，对应 go/themes/ 目录）
/uploads/* 上传文件静态访问
/backend/*、/platform/* 等 管理端接口（nginx 以 /api/ 前缀转发并剥掉前缀）

Go 的官网渲染路由在 APP_MODE=all（默认值）或 APP_MODE=index 时注册。

1.2 Go 按 Host 识别租户的规则（tenant_site.go）

按顺序匹配：

  1. dev 环境：支持 X-Tenant-ID 请求头切换租户（生产无效）；
  2. localhost / 127.0.0.1 → 租户 1；
  3. yz_system_domain_pool.main_domain 命中（status=1）→ 租户 1（平台主站）；
  4. yz_system_tenant_domain.full_domain 命中（status=1、未软删）→ 对应租户；
  5. 全部未命中 → 返回"站点不存在"404 页（不再默认回落租户 1）。

所以平台端"域名发放"时必须保证 yz_system_tenant_domain.full_domain 精确等于实际访问域名（如 ceshi.yunzer.com.cn）。

二、配置核心策略（为什么这么写）

2.1 upstream 统一管理后端地址 —— 迁移只改一行

所有 proxy_pass 不写死 IP，统一引用 upstream。迁移服务器时只改 upstream 里的 server 一行。

upstream 写在哪里：直接写在宝塔对应站点的配置文件里、整个文件最顶部（第一个 server { 块之前），不需要配置到其他地方。宝塔站点配置文件会被 include 进主配置的 http {} 上下文，upstream 定义在 server 块之外即合法。常见报错：unknown "go_backend_dh2" upstream（顶部漏了 upstream 定义）、"upstream" directive is not allowed here（误写进了 server 块内）。

注意：两个站点配置文件都会被 include 进同一个 http 上下文，upstream 重名会导致 duplicate upstream 启动失败，必须各起各的名字（本文用 go_backend_dh2 / go_backend_yunzer）。

2.2 默认全量转发 —— 以后加功能零配置

不采用"白名单式"逐个转发（location /news、location /page/……），而是：

  • nginx 只保留必须拦截的规则：敏感文件/目录返回 404、/api/ 剥前缀；
  • 其余一切请求走兜底 location / 转发给 Go；
  • Go 对不认识的路径返回自己的 404 页，行为闭环。

这样以后 Go 增加任何路由（新功能页面、新接口页），nginx 一行都不用改。

2.3 管理端 SPA 的放置建议

主域名与所有子域名都转发给 Go 后，这些域名上就不能再跑 history 模式的 SPA 了。建议：

  • platform / backend 管理端部署在专属子域名（如 admin.yunzer.com.cn）或独立站点；
  • nginx 里为它单独建一个 server_name 精确匹配的 server 块。nginx 匹配顺序是精确 server_name 优先于正则，不会被"所有子域名"的正则块抢走；
  • 若确实需要静态文件与 Go 共存（纯静态、无 SPA 深链接），可用折中写法：
location / {
    try_files $uri @go;   # 本地存在的文件先出静态，其余转 Go
}
location @go {
    proxy_pass http://go_backend_yunzer;
    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 $scheme;
}

2.4 /api/ 的尾部斜杠不能删

location /api/ {
    proxy_pass http://go_backend_xxx/;   # 尾部 / 负责把 /api/backend/login 映射成 /backend/login
    ...
}

Go 的路由注册在 /backend/*、/platform/*（没有 /api 前缀），靠这个尾部斜杠剥前缀。

2.5 七牛图片统一通过官网域名代理

完整配置已在两个主域名的 server 块中加入 location /qiniu/。该规则会把官网域名下的 /qiniu/ 请求通过 HTTP 代理到历史七牛域名 http://7colud.yunzer.cn/，并去掉 /qiniu/ 前缀；浏览器仍通过官网 HTTPS 接收图片。

例如，浏览器请求：

https://yunzer.com.cn/qiniu/2026/06/02/1780371759517804300.png

nginx 实际请求：

http://7colud.yunzer.cn/2026/06/02/1780371759517804300.png

存储配置填写规则：平台后台“存储配置”中的 qiniu_domain 必须与实际复制的主站配置一致，且末尾不要加 /：

  • 复制 yunzer.com.cn 配置时填写 https://yunzer.com.cn/qiniu；
  • 复制 dh2.fun 配置时填写 https://dh2.fun/qiniu。

Go 官网渲染会将数据库中已有的 http(s)://7colud.yunzer.cn/路径（兼容历史拼写 7cloud.yunzer.cn）替换为此配置的地址；之后新上传的七牛文件也会直接使用该代理地址。location /qiniu/ 的 proxy_pass 末尾斜杠不能删除，否则七牛会收到包含 /qiniu/ 的错误对象路径。

三、完整配置 —— 宝塔站点 dh2.fun

文件位置：宝塔 → 网站 → dh2.fun → 设置 → 配置文件。整份替换。

# ===== 后端 Go 服务地址统一定义，迁移时只改这一行 =====
upstream go_backend_dh2 {
    server 10.31.100.2:8081;   # 若 nginx 与 Go 同机，建议改为 127.0.0.1:8081（迁移零改动）
}

# ==================== 主域名 dh2.fun（全量托管给 Go）====================
server {
    listen 80;
    listen 443 ssl;
    listen 443 quic;
    http2 on;

    # 只匹配主域名（子域名由下方独立 server 块处理）
    server_name dh2.fun;

    #CERT-APPLY-CHECK--START
    include /www/server/panel/vhost/nginx/well-known/dh2.fun.conf;
    #CERT-APPLY-CHECK--END
    include /www/server/panel/vhost/nginx/extension/dh2.fun/*.conf;

    #SSL-START SSL相关配置，请勿删除或修改下一行带注释的404规则
    #error_page 404/404.html;

    #HTTP_TO_HTTPS_START
    set $isRedcert 1;
    if ($server_port != 443) {
        set $isRedcert 2;
    }
    if ( $uri ~ /\.well-known/ ) {
        set $isRedcert 1;
    }
    if ($isRedcert != 1) {
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END

    ssl_certificate    /www/server/panel/vhost/cert/dh2.fun/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/dh2.fun/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_tickets on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;
    #SSL-END

    # --- 安全拦截：敏感文件 ---
    location ~* (\.user.ini|\.htaccess|\.htpasswd|\.env.*|\.project|\.bashrc|\.bash_profile|\.bash_logout|\.DS_Store|\.gitignore|\.gitattributes|LICENSE|README\.md|CLAUDE\.md|CHANGELOG\.md|CHANGELOG|CONTRIBUTING\.md|TODO\.md|FAQ\.md|composer\.json|composer\.lock|package(-lock)?\.json|yarn\.lock|pnpm-lock\.yaml|\.\w+~|\.swp|\.swo|\.bak(up)?|\.old|\.tmp|\.temp|\.log|\.sql(\.gz)?|docker-compose\.yml|docker\.env|Dockerfile|\.csproj|\.sln|Cargo\.toml|Cargo\.lock|go\.mod|go\.sum|phpunit\.xml|phpunit\.xml|pom\.xml|build\.gradl|pyproject\.toml|requirements\.txt|application(-\w+)?\.(ya?ml|properties))$ {
        return 404;
    }

    # --- 安全拦截：敏感目录 ---
    location ~* /(\.git|\.svn|\.bzr|\.vscode|\.claude|\.idea|\.ssh|\.github|\.npm|\.yarn|\.pnpm|\.cache|\.husky|\.turbo|\.next|\.nuxt|node_modules|runtime)/ {
        return 404;
    }

    # SSL 证书验证目录
    location ~ \.well-known {
        allow all;
    }

    if ( $uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$" ) {
        return 403;
    }

    # /api/ 转发并剥掉 /api 前缀（尾部斜杠不能删）
    location /api/ {
        proxy_pass http://go_backend_dh2/;
        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 $scheme;
    }

    # 七牛图片代理：/qiniu/ 前缀会被剥掉，转发到七牛对象路径
    # 存储配置 qiniu_domain 填 https://dh2.fun/qiniu（末尾不要加 /）
    location /qiniu/ {
        proxy_pass http://7colud.yunzer.cn/;
        proxy_set_header Host 7colud.yunzer.cn;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 浏览器缓存图片 7 天，减少重复请求
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }

    # 其余一切请求全部交给 Go：首页、/news、/page/xxx、/themes/ 静态资源、
    # /uploads/ 以及以后新增的任何路由，自动生效，nginx 永远不用再改
    location / {
        proxy_pass http://go_backend_dh2;
        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 $scheme;
    }

    access_log  /www/wwwlogs/dh2.fun.log;
    error_log   /www/wwwlogs/dh2.fun.error.log;
}

# ==================== 租户官网渲染：*.dh2.fun 所有子域名 ====================
server {
    listen 80;
    listen 443 ssl;
    http2 on;

    # 匹配所有子域名，如 ceshi.dh2.fun（租户域名发放后无需再改 nginx）
    server_name ~^(?<subdomain>.+)\.dh2\.fun$;

    #CERT-APPLY-CHECK--START
    include /www/server/panel/vhost/nginx/well-known/dh2.fun.conf;
    #CERT-APPLY-CHECK--END

    #HTTP_TO_HTTPS_START
    set $isRedcert 1;
    if ($server_port != 443) {
        set $isRedcert 2;
    }
    if ( $uri ~ /\.well-known/ ) {
        set $isRedcert 1;
    }
    if ($isRedcert != 1) {
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END

    # 注意：子域名 HTTPS 要求泛域名证书（*.dh2.fun），见文档"注意事项"
    ssl_certificate    /www/server/panel/vhost/cert/dh2.fun/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/dh2.fun/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;

    location ~ \.well-known {
        allow all;
    }

    # 全部请求转发给 Go，由 Go 按 Host（如 ceshi.dh2.fun）识别租户并渲染官网
    location / {
        proxy_pass http://go_backend_dh2;
        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 $scheme;
    }

    access_log  /www/wwwlogs/dh2.fun.tenant.log;
    error_log   /www/wwwlogs/dh2.fun.tenant.error.log;
}

四、完整配置 —— 宝塔站点 yunzer.com.cn

文件位置：宝塔 → 网站 → yunzer.com.cn → 设置 → 配置文件。整份替换。

# ===== 后端 Go 服务地址统一定义，迁移时只改这一行 =====
# 注意：不能与 dh2.fun 配置里的 upstream 同名，否则 nginx 报 duplicate upstream
upstream go_backend_yunzer {
    server 10.31.100.2:8081;   # 若 nginx 与 Go 同机，建议改为 127.0.0.1:8081（迁移零改动）
}

# ==================== 主域名 yunzer.com.cn（全量托管给 Go）====================
server {
    listen 80;
    listen 443 ssl;
    listen 443 quic;
    http2 on;

    # 只匹配主域名（子域名由下方独立 server 块处理）
    server_name yunzer.com.cn;

    #CERT-APPLY-CHECK--START
    include /www/server/panel/vhost/nginx/well-known/yunzer.com.cn.conf;
    #CERT-APPLY-CHECK--END
    include /www/server/panel/vhost/nginx/extension/yunzer.com.cn/*.conf;

    #SSL-START SSL相关配置，请勿删除或修改下一行带注释的404规则
    #error_page 404/404.html;

    #HTTP_TO_HTTPS_START
    set $isRedcert 1;
    if ($server_port != 443) {
        set $isRedcert 2;
    }
    if ( $uri ~ /\.well-known/ ) {
        set $isRedcert 1;
    }
    if ($isRedcert != 1) {
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END

    ssl_certificate    /www/server/panel/vhost/cert/yunzer.com.cn/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/yunzer.com.cn/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_tickets on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;
    #SSL-END

    # --- 安全拦截：敏感文件 ---
    location ~* (\.user.ini|\.htaccess|\.htpasswd|\.env.*|\.project|\.bashrc|\.bash_profile|\.bash_logout|\.DS_Store|\.gitignore|\.gitattributes|LICENSE|README\.md|CLAUDE\.md|CHANGELOG\.md|CHANGELOG|CONTRIBUTING\.md|TODO\.md|FAQ\.md|composer\.json|composer\.lock|package(-lock)?\.json|yarn\.lock|pnpm-lock\.yaml|\.\w+~|\.swp|\.swo|\.bak(up)?|\.old|\.tmp|\.temp|\.log|\.sql(\.gz)?|docker-compose\.yml|docker\.env|Dockerfile|\.csproj|\.sln|Cargo\.toml|Cargo\.lock|go\.mod|go\.sum|phpunit\.xml|phpunit\.xml|pom\.xml|build\.gradl|pyproject\.toml|requirements\.txt|application(-\w+)?\.(ya?ml|properties))$ {
        return 404;
    }

    # --- 安全拦截：敏感目录 ---
    location ~* /(\.git|\.svn|\.bzr|\.vscode|\.claude|\.idea|\.ssh|\.github|\.npm|\.yarn|\.pnpm|\.cache|\.husky|\.turbo|\.next|\.nuxt|node_modules|runtime)/ {
        return 404;
    }

    # SSL 证书验证目录
    location ~ \.well-known {
        allow all;
    }

    if ( $uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$" ) {
        return 403;
    }

    # /api/ 转发并剥掉 /api 前缀（尾部斜杠不能删）
    location /api/ {
        proxy_pass http://go_backend_yunzer/;
        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 $scheme;
    }

    # 七牛图片代理：/qiniu/ 前缀会被剥掉，转发到七牛对象路径
    # 存储配置 qiniu_domain 填 https://yunzer.com.cn/qiniu（末尾不要加 /）
    location /qiniu/ {
        proxy_pass http://7colud.yunzer.cn/;
        proxy_set_header Host 7colud.yunzer.cn;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 浏览器缓存图片 7 天，减少重复请求
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }

    # 其余一切请求全部交给 Go：首页、/news、/page/xxx、/themes/ 静态资源、
    # /uploads/ 以及以后新增的任何路由，自动生效，nginx 永远不用再改
    location / {
        proxy_pass http://go_backend_yunzer;
        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 $scheme;
    }

    access_log  /www/wwwlogs/yunzer.com.cn.log;
    error_log   /www/wwwlogs/yunzer.com.cn.error.log;
}

# ==================== 租户官网渲染：*.yunzer.com.cn 所有子域名 ====================
server {
    listen 80;
    listen 443 ssl;
    http2 on;

    # 匹配所有子域名，如 ceshi.yunzer.com.cn（租户域名发放后无需再改 nginx）
    server_name ~^(?<subdomain>.+)\.yunzer\.com\.cn$;

    #CERT-APPLY-CHECK--START
    include /www/server/panel/vhost/nginx/well-known/yunzer.com.cn.conf;
    #CERT-APPLY-CHECK--END

    #HTTP_TO_HTTPS_START
    set $isRedcert 1;
    if ($server_port != 443) {
        set $isRedcert 2;
    }
    if ( $uri ~ /\.well-known/ ) {
        set $isRedcert 1;
    }
    if ($isRedcert != 1) {
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END

    # 注意：子域名 HTTPS 要求泛域名证书（*.yunzer.com.cn），见文档"注意事项"
    ssl_certificate    /www/server/panel/vhost/cert/yunzer.com.cn/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/yunzer.com.cn/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;

    location ~ \.well-known {
        allow all;
    }

    # 全部请求转发给 Go，由 Go 按 Host（如 ceshi.yunzer.com.cn）识别租户并渲染官网
    location / {
        proxy_pass http://go_backend_yunzer;
        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 $scheme;
    }

    access_log  /www/wwwlogs/yunzer.com.cn.tenant.log;
    error_log   /www/wwwlogs/yunzer.com.cn.tenant.error.log;
}

若管理端（platform/backend 前端）部署在专属子域名（如 admin.yunzer.com.cn），在对应站点再加一个 server_name admin.yunzer.com.cn; 精确匹配的 server 块指向其静态目录即可——精确匹配优先于子域名正则块，互不干扰。

五、租户自有域名（扑底站点 + 自动 HTTPS）

前面两节的站点只匹配 yunzer.com.cn / *.yunzer.com.cn / dh2.fun / *.dh2.fun。租户绑定自己的域名（如 www.客户公司.com）后，解析过来会落到 nginx 的默认站点，命中不了上面的任何 server_name。本节的扑底站点解决两件事：让未知域名也能进 Go，以及为这些域名提供 HTTPS 证书。

5.1 工作流程

  1. 租户在后台「我的域名」点「绑定自有域名」，填写完整域名；
  2. 系统返回 CNAME 目标 / A 记录 IP（来自 app.conf 的 customdomain_cname_target、customdomain_a_ips）；
  3. 租户到域名服务商添加解析，回来点「检测解析」；
  4. Go 用 net.LookupCNAME / net.LookupHost 校验解析是否指向平台；
  5. 校验通过后 Go 异步向 Let's Encrypt 发起 HTTP-01 申请，CA 回访 http://域名/.well-known/acme-challenge/<token>；
  6. nginx 扑底站点把该路径明文反代给 Go，Go 应答 token；
  7. 签发成功后证书写入 {ssl_cert_dir}/{域名}/fullchain.pem 与 privkey.pem，记录置 ssl_status=2、status=1，域名生效；
  8. 每 12 小时扫一次，到期前 30 天自动续期。

5.2 app.conf 需要填的五项

# 租户子域名 CNAME 到这个主机名（该主机名需已 A 记录指向本服务器）
customdomain_cname_target = sites.yunzer.com.cn

# 根域名只能用 A 记录，这里写本服务器公网 IP（多个用英文逗号分隔）
customdomain_a_ips = 1.2.3.4

# Let's Encrypt 账号邮箱
acme_email = ops@yunzer.com.cn

# 留空使用正式环境；联调先填 staging，避免打满正式环境频控
# acme_directory = https://acme-staging-v02.api.letsencrypt.org/directory
acme_directory =

# 证书落盘目录，Go 进程必须可写，nginx 必须可读
ssl_cert_dir = /www/wwwroot/ssl-certs

customdomain_cname_target 建议单独用一个平台子域（如 sites.yunzer.com.cn），指向服务器 IP。以后换服务器只改这条 A 记录，所有租户的 CNAME 都跟着走，不用逐个通知租户改解析。

5.3 扑底站点配置

新建一个宝塔站点（域名可随便填一个不用的，例如 custom-domains.local），或直接在任一站点配置文件里追加下面内容。注意 upstream 名字不能与 go_backend_dh2 / go_backend_yunzer 重复。

upstream go_backend_custom {
    server 127.0.0.1:8081;
}

# SNI 决定用哪个域名的证书目录；无 SNI 的请求回落到 _default
map $ssl_server_name $cert_host {
    ""      _default;
    default $ssl_server_name;
}

# ---------- HTTP：只负责 ACME 验证与明文访问，不做整站跳转 ----------
server {
    listen 80 default_server;
    server_name _;

    # 关键：ACME 验证不能 301 到 HTTPS。首次签发时还没有证书，
    # 跳过去 CA 会因为证书不可信而验证失败。
    location /.well-known/acme-challenge/ {
        proxy_pass http://go_backend_custom;
        proxy_set_header Host $host;
    }

    location / {
        proxy_pass http://go_backend_custom;
        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 $scheme;
    }

    access_log  /www/wwwlogs/custom-domain.log;
    error_log   /www/wwwlogs/custom-domain.error.log;
}

# ---------- HTTPS：按 SNI 从证书目录取对应域名的证书 ----------
server {
    listen 443 ssl default_server;
    http2 on;
    server_name _;

    ssl_certificate     /www/wwwroot/ssl-certs/$cert_host/fullchain.pem;
    ssl_certificate_key /www/wwwroot/ssl-certs/$cert_host/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 这里不要加 HSTS：证书是自动签的，一旦某个域名签发失败又被浏览器记住 HSTS，
    # 租户连 HTTP 兜底访问都用不了。

    location / {
        proxy_pass http://go_backend_custom;
        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 $scheme;
    }

    access_log  /www/wwwlogs/custom-domain.ssl.log;
    error_log   /www/wwwlogs/custom-domain.ssl.error.log;
}

5.4 上线前必做的四件事

  1. 放一份 _default 兜底证书。ssl_certificate 用了变量，nginx 启动时不校验文件是否存在，但握手时找不到文件会直接失败。没有 SNI 的客户端（老设备、直接用 IP 访问）会落到 _default：

    mkdir -p /www/wwwroot/ssl-certs/_default
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /www/wwwroot/ssl-certs/_default/privkey.pem \
  -out   /www/wwwroot/ssl-certs/_default/fullchain.pem \
  -subj "/CN=invalid"

  2. nginx 版本 ≥ 1.15.9。ssl_certificate 支持变量是从这个版本开始的，宝塔默认的 1.2x 都满足。低版本会报 invalid number of arguments 或直接不生效。

  3. 证书目录权限。Go 进程要能创建子目录与写文件，nginx 要能读：

    mkdir -p /www/wwwroot/ssl-certs
chown -R <go进程用户>:www /www/wwwroot/ssl-certs
chmod 755 /www/wwwroot/ssl-certs

  4. 公网 80 与 443 都要可达。HTTP-01 验证走 80 端口，被防火墙或安全组挡住会签发失败。

5.5 default_server 的影响范围

listen 80 default_server 会把「所有没匹配到具体 server_name 的请求」都吃掉。原来这类请求落到宝塔默认站点（通常是一个空白页或宝塔欢迎页）。如果服务器上还有其他靠默认站点兜底的业务，先确认它们都有精确的 server_name，否则会被这个扑底站点抢走。nginx 的匹配优先级是：精确 server_name > 前导通配 > 尾随通配 > 正则 > default_server，前面两节的配置都是精确匹配或正则，不受影响。

5.6 排查

现象 原因 处理
「解析检测」提示当前解析到别的 IP 解析没生效或填错 等 TTL 过期；dig +short 域名 核对
「解析检测」提示平台尚未配置解析目标 app.conf 两项为空 填 customdomain_cname_target / customdomain_a_ips 后重启 Go
证书状态一直「签发中」 CA 回访拿不到 token curl http://域名/.well-known/acme-challenge/test 应到 Go 而非 301
证书「签发失败」，原因含 403/404 80 端口不可达或被 HTTPS 跳转拦了 检查安全组、确认 challenge 的 location 在跳转规则之前
浏览器提示证书名称不匹配 落到了 _default 自签证书 说明 SNI 对应目录没有证书，看该域名的 ssl_status 与 ssl_error
签发失败后短时间点不动 失败冷却 30 分钟 等冷却结束再点，或先用 staging 联调

签发失败原因会写进 yz_system_tenant_domain.ssl_error，前端「证书」列悬浮即可看到。Let's Encrypt 对同一账号每小时失败次数有限制，所以代码里加了 30 分钟冷却，避免租户反复点击把额度打满。

六、重要注意事项

  1. 子域名必须用泛域名证书。租户域名是二级域名（ceshi.yunzer.com.cn），单域名证书会导致 HTTPS 证书错误。需在宝塔为 *.yunzer.com.cn、*.dh2.fun 申请泛域名证书（DNS 验证），并替换配置中的证书路径。
  2. upstream 不能重名。两个站点配置都在同一 http 上下文，本文分别用 go_backend_dh2、go_backend_yunzer；重名会 duplicate upstream 启动失败。
  3. /api/ 和 /qiniu/ 的 proxy_pass 尾部斜杠不能删。/api/ 的斜杠负责剥掉 /api 前缀（Go 路由注册在 /backend/*、/platform/*）；/qiniu/ 的斜杠负责剥掉 /qiniu 前缀，使七牛收到正确对象路径。兜底 location / 的 proxy_pass 则不带尾部斜杠（原样转发 URI）。
  4. 存储域名必须与复制的主站配置对应。使用 yunzer.com.cn 配置则后台“存储配置”中的 qiniu_domain 填 https://yunzer.com.cn/qiniu；使用 dh2.fun 配置则填 https://dh2.fun/qiniu。均不带末尾 /。
  5. 不要再给官网域名加 js|css 正则缓存 location。正则 location 优先级高于兜底前缀 location，会拦截 /themes/xxx/static/main.js 去本地 root 找文件导致 404。模板静态资源由 Go（beego）直接提供。
  6. proxy_set_header Host $host; 必须保留。Go 完全依赖 Host 识别租户；若透传成 upstream 地址，所有请求都会被识别失败。
  7. Go 侧前置条件：
    • 启动模式 APP_MODE 为 all（默认）或 index，否则官网渲染路由未注册；
    • go/themes/ 目录与 Go 服务启动目录同级（模板文件在 Go 项目目录 go/themes/{编码}/，与 platform/backend 前端项目无关）；
    • 数据库已执行 sql/yz_cms_frontend_tables.sql。
  8. 域名发放数据必须精确。yz_system_tenant_domain.full_domain 要与实际访问域名完全一致（不带协议、不带端口、不带路径），且 status=1、delete_time 为 NULL。
  9. DNS 泛解析。*.yunzer.com.cn、*.dh2.fun 需要配置泛解析 A 记录指向服务器，否则新发放的子域名无法访问（与 nginx 无关）。
  10. HSTS 提醒。配置了 Strict-Transport-Security，一旦浏览器记住，证书出问题期间该域名将无法用 HTTP 访问；测试阶段可先注释掉该行。
  11. 宝塔面板操作提示。直接编辑站点配置文件后，用 nginx -t 校验再重载；宝塔后续"站点设置"的某些操作可能重写配置文件，改前建议备份。

七、验证与排查

7.1 部署后验证顺序

# 1. 绕过 nginx 直接验证 Go（在服务器上执行）
curl -H "Host: ceshi.yunzer.com.cn" http://10.31.100.2:8081/

# 2. 验证 nginx → Go 链路
curl -k -H "Host: ceshi.yunzer.com.cn" https://127.0.0.1/

# 3. 验证七牛代理：应返回图片内容或 200/304，而不是 Go 的 404 页面
curl -I https://yunzer.com.cn/qiniu/2026/06/02/1780371759517804300.png

# 4. 自有域名：先确认扑底站点能把 challenge 明文送到 Go（不应返回 301）
curl -i -H "Host: 待绑域名" http://127.0.0.1/.well-known/acme-challenge/probe

# 5. 自有域名：确认 Go 能按 Host 命中租户
curl -H "Host: 待绑域名" http://127.0.0.1:8081/

# 6. 浏览器访问 https://ceshi.yunzer.com.cn

7.2 常见现象对照表

现象 原因 处理
Go 页面显示"站点不存在" Host 在 yz_system_tenant_domain / 域名池中查不到 核对 full_domain 拼写、status、delete_time
beego 默认 404 APP_MODE 不含 all/index，渲染路由未注册 检查 Go 启动环境变量
nginx 404（未到 Go） 请求被本地静态/正则规则拦截 检查是否残留 try_files /index.html、`js
浏览器证书错误 非泛域名证书 申请 *.域名 泛域名证书并替换路径
502 Bad Gateway Go 服务未启动或 upstream 地址错误 curl http://127.0.0.1:8081/ 验证服务存活，改 upstream
首页正常但样式丢失 /themes/ 未到达 Go 确认兜底转发存在且无 js/css 正则拦截

八、迁移服务器清单（以迁移到 192.168.1.101 为例）

  1. 新机器部署 Go：复制 go/ 目录（含 themes/、conf/app.conf），修改 app.conf 数据库连接为新库地址，启动服务；
  2. 新库初始化：导入业务数据，执行 sql/ 下全部建表/变更 SQL（尤其 yz_cms_frontend_tables.sql、alter_tenant_domain_add_custom.sql）；
  3. nginx：
    • nginx 与 Go 同机 → upstream 用 127.0.0.1:8081，配置零改动；
    • 跨机 → 只改三个 upstream 块中的 server 一行（含扑底站点的 go_backend_custom）；
  4. 证书：新机器宝塔上为两个域名重新申请/导入证书（含泛域名），路径与配置保持一致；自有域名的证书目录 /www/wwwroot/ssl-certs 整个复制过去（含 _account/key.pem——换了账号私钥等于换 ACME 账号，历史签发记录与频控额度都会重置）；
  5. DNS：将 dh2.fun、yunzer.com.cn 及泛解析 * 的 A 记录改指向新服务器 IP；customdomain_cname_target 对应子域的 A 记录也要改，租户侧的 CNAME 不用动；
  6. 验证：按第七节顺序逐一验证；
  7. 确认无误后到域名服务商处调低旧解析 TTL、观察切换。

本文档对应代码：go/controllers/tenant_site.go（Host 识别与渲染）、go/services/acme_cert.go（自动签发与续期）、go/services/domain_verify.go（解析检测）、go/controllers/acme_challenge.go（HTTP-01 应答）、go/pkg/tagengine/（标签引擎）、go/themes/default/（内置默认模板）、sql/yz_cms_frontend_tables.sql（建站数据表）、sql/alter_tenant_domain_add_custom.sql（自有域名字段）。

Reference in New Issue View Git Blame Copy Permalink