# 关于租户官网服务器端 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 深链接），可用折中写法：

```nginx
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/` 的尾部斜杠不能删

```nginx
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 接收图片。

例如，浏览器请求：

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

nginx 实际请求：

```text
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 → 设置 → 配置文件。整份替换。

```nginx
# ===== 后端 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 → 设置 → 配置文件。整份替换。

```nginx
# ===== 后端 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 块指向其静态目录即可——精确匹配优先于子域名正则块，互不干扰。

---

## 五、重要注意事项

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` 校验再重载；宝塔后续"站点设置"的某些操作可能重写配置文件，改前建议备份。

---

## 六、验证与排查

### 6.1 部署后验证顺序

```bash
# 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. 浏览器访问 https://ceshi.yunzer.com.cn
```

### 6.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|css` 正则 location |
| 浏览器证书错误 | 非泛域名证书 | 申请 `*.域名` 泛域名证书并替换路径 |
| 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`）；
3. **nginx**：
   - nginx 与 Go 同机 → upstream 用 `127.0.0.1:8081`，配置零改动；
   - 跨机 → 只改两个 upstream 块中的 `server` 一行；
4. **证书**：新机器宝塔上为两个域名重新申请/导入证书（含泛域名），路径与配置保持一致；
5. **DNS**：将 `dh2.fun`、`yunzer.com.cn` 及泛解析 `*` 的 A 记录改指向新服务器 IP；
6. **验证**：按第六节顺序逐一验证；
7. 确认无误后到域名服务商处调低旧解析 TTL、观察切换。

---

*本文档对应代码：`go/controllers/tenant_site.go`（Host 识别与渲染）、`go/pkg/tagengine/`（标签引擎）、`go/themes/default/`（内置默认模板）、`sql/yz_cms_frontend_tables.sql`（建站数据表）。*