# 宝塔面板域名配置指南

> 如果您使用宝塔面板管理服务器，推荐使用宝塔自带的反向代理功能，无需手动配置 Nginx

---

## 🎯 配置概述

宝塔面板通过 Web 界面配置反向代理，将域名流量转发到 Docker 容器的端口。

### 端口映射关系

| 服务 | 环境 | Docker 容器端口 | 映射到宿主机端口 | 域名 |
|------|------|----------------|----------------|------|
| API 服务 | 生产 | 3000 | 10080 | api.pinzhuhui.com |
| API 服务 | 测试 | 3000 | 10081 | api-test.pinzhuhui.com |
| 商家后台 | 生产 | 80 | 10082 | merchant.pinzhuhui.com |
| 商家后台 | 测试 | 80 | 10083 | merchant-test.pinzhuhui.com |
| 平台后台 | 生产 | 80 | 10084 | platform-admin.pinzhuhui.com |
| 平台后台 | 测试 | 80 | 10085 | platform-admin-test.pinzhuhui.com |
| 官网 | 生产 | 80 | 10086 | www.pinzhuhui.com |
| 官网 | 测试 | 80 | 10087 | test.pinzhuhui.com |

---

## 📋 配置步骤

### 第一步：修改 Docker Compose 配置

#### 1. 修改生产环境配置

编辑 `deploy/docker/docker-compose.prod.yml`，添加端口映射：

```yaml
version: '3.8'

services:
  server:
    image: your-registry/rent-server:latest
    container_name: rent-prod-server
    restart: always
    ports:
      - "10080:3000"  # 添加端口映射
    environment:
      - NODE_ENV=production
    # ... 其他配置

  merchant-admin:
    image: your-registry/rent-merchant-admin:latest
    container_name: rent-prod-merchant
    restart: always
    ports:
      - "10082:80"  # 添加端口映射
    # ... 其他配置

  platform-admin:
    image: your-registry/rent-platform-admin:latest
    container_name: rent-prod-platform
    restart: always
    ports:
      - "10084:80"  # 添加端口映射
    # ... 其他配置

  website:
    image: your-registry/rent-website:latest
    container_name: rent-prod-website
    restart: always
    ports:
      - "10086:80"  # 添加端口映射
    # ... 其他配置
```

#### 2. 修改测试环境配置

编辑 `deploy/docker/docker-compose.test.yml`：

```yaml
version: '3.8'

services:
  server:
    image: your-registry/rent-server:latest
    container_name: rent-test-server
    restart: always
    ports:
      - "10081:3000"  # 添加端口映射
    environment:
      - NODE_ENV=test
    # ... 其他配置

  merchant-admin:
    image: your-registry/rent-merchant-admin:latest
    container_name: rent-test-merchant
    restart: always
    ports:
      - "10083:80"  # 添加端口映射
    # ... 其他配置

  platform-admin:
    image: your-registry/rent-platform-admin:latest
    container_name: rent-test-platform
    restart: always
    ports:
      - "10085:80"  # 添加端口映射
    # ... 其他配置

  website:
    image: your-registry/rent-website:latest
    container_name: rent-test-website
    restart: always
    ports:
      - "10087:80"  # 添加端口映射
    # ... 其他配置
```

#### 3. 重启 Docker 容器

```bash
# 重启生产环境
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

# 重启测试环境
docker-compose -f docker-compose.test.yml down
docker-compose -f docker-compose.test.yml up -d
```

---

### 第二步：在宝塔面板配置域名

登录宝塔面板：`http://your-server-ip:8888`

#### 1. 添加站点（生产 API）

1. 点击左侧菜单 **"网站"**
2. 点击 **"添加站点"**
3. 填写信息：
   - **域名**：`api.pinzhuhui.com`
   - **根目录**：随意填写（例如 `/www/wwwroot/api`）
   - **PHP 版本**：纯静态
   - **数据库**：不创建
4. 点击 **"提交"**

#### 2. 配置反向代理

1. 在网站列表找到 `api.pinzhuhui.com`
2. 点击 **"设置"**
3. 点击 **"反向代理"** 标签
4. 点击 **"添加反向代理"**
5. 填写配置：
   - **代理名称**：`生产API`
   - **目标URL**：`http://127.0.0.1:10080`
   - **发送域名**：`$host`
   - **内容替换**：留空
   - **高级配置**：
     ```nginx
     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;
     client_max_body_size 50m;
     ```
6. 点击 **"提交"**

#### 3. 配置其他域名

按照相同步骤添加其他域名：

**商家管理后台（生产）**
- 域名：`merchant.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10082`

**平台管理后台（生产）**
- 域名：`platform-admin.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10084`

**官网（生产）**
- 域名：`www.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10086`

**测试环境 API**
- 域名：`api-test.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10081`

**测试商家后台**
- 域名：`merchant-test.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10083`

**测试平台后台**
- 域名：`platform-admin-test.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10085`

**测试官网**
- 域名：`test.pinzhuhui.com`
- 目标URL：`http://127.0.0.1:10087`

---

### 第三步：配置 SSL 证书（HTTPS）

#### 方法1：使用宝塔自动申请（推荐）

1. 在网站列表找到域名，点击 **"设置"**
2. 点击 **"SSL"** 标签
3. 选择 **"Let's Encrypt"**
4. 勾选要申请的域名
5. 填写邮箱
6. 点击 **"申请"**
7. 等待几秒，申请成功后点击 **"强制HTTPS"**

宝塔会自动配置：
- SSL 证书自动续期
- HTTP 自动跳转 HTTPS
- 证书到期提醒

#### 方法2：上传已有证书

1. 在网站设置中点击 **"SSL"** 标签
2. 选择 **"其他证书"**
3. 粘贴证书内容：
   - **证书(PEM格式)**：粘贴 `.crt` 或 `.pem` 文件内容
   - **密钥(KEY)**：粘贴 `.key` 文件内容
4. 点击 **"保存"**
5. 开启 **"强制HTTPS"**

---

### 第四步：配置防火墙

#### 宝塔安全规则

1. 点击左侧菜单 **"安全"**
2. 在 **"系统防火墙"** 中添加规则：
   - 放行端口：`10080-10087`（如果需要直接访问）
   - 通常不需要，只放行 80 和 443 即可

#### 服务器安全组

如果使用云服务器（阿里云/腾讯云），需要在控制台配置安全组：

- 放行入站规则：
  - TCP 80 端口（HTTP）
  - TCP 443 端口（HTTPS）
  - TCP 8888 端口（宝塔面板，建议修改默认端口）

---

## 🔍 验证配置

### 1. 检查端口监听

SSH 登录服务器，检查端口：

```bash
# 检查 Docker 容器端口映射
docker ps | grep rent

# 检查端口监听
netstat -tlnp | grep -E "10080|10081|10082|10083|10084|10085|10086|10087"
```

应该看到类似输出：
```
tcp6    0    0 :::10080    :::*    LISTEN    1234/docker-proxy
tcp6    0    0 :::10081    :::*    LISTEN    1235/docker-proxy
...
```

### 2. 测试本地访问

```bash
# 测试生产 API
curl http://127.0.0.1:10080

# 测试商家后台
curl http://127.0.0.1:10082

# 测试平台后台
curl http://127.0.0.1:10084
```

### 3. 测试域名访问

在浏览器或命令行测试：

```bash
# HTTP 访问
curl http://api.pinzhuhui.com
curl http://merchant.pinzhuhui.com

# HTTPS 访问
curl https://api.pinzhuhui.com
curl https://merchant.pinzhuhui.com
```

---

## 🔧 高级配置

### API 速率限制

在宝塔反向代理的高级配置中添加：

```nginx
# 限制每个 IP 每秒 30 个请求
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=30r/s;

location / {
    limit_req zone=api_limit burst=50 nodelay;
    
    proxy_pass http://127.0.0.1:10080;
    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;
    client_max_body_size 50m;
}
```

### 跨域配置（CORS）

如果前端和后端不在同一域名，需要配置 CORS：

```nginx
# 在反向代理高级配置中添加
add_header 'Access-Control-Allow-Origin' '$http_origin' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;

if ($request_method = 'OPTIONS') {
    return 204;
}
```

### WebSocket 支持

如果使用 WebSocket：

```nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
```

### 缓存静态资源

```nginx
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
    proxy_pass http://127.0.0.1:10082;
}
```

---

## 🚨 故障排查

### 问题1：域名无法访问

**检查清单**：
1. ✅ DNS 解析是否正确
   ```bash
   ping api.pinzhuhui.com
   nslookup api.pinzhuhui.com
   ```

2. ✅ Docker 容器是否运行
   ```bash
   docker ps | grep rent
   ```

3. ✅ 端口是否监听
   ```bash
   netstat -tlnp | grep 10080
   ```

4. ✅ 宝塔反向代理是否配置正确
   - 登录宝塔面板检查

5. ✅ 防火墙是否放行
   - 宝塔安全 → 检查端口规则
   - 云服务器安全组 → 检查入站规则

### 问题2：502 Bad Gateway

**原因**：
- Docker 容器未启动
- 端口映射错误
- 反向代理目标地址错误

**解决**：
```bash
# 检查容器状态
docker ps -a | grep rent

# 查看容器日志
docker logs rent-prod-server

# 重启容器
docker restart rent-prod-server

# 测试端口
curl http://127.0.0.1:10080
```

### 问题3：SSL 证书申请失败

**原因**：
- 域名未解析到服务器
- 80 端口被占用
- DNS 解析未生效

**解决**：
1. 确认域名已解析到服务器 IP
2. 确认 80 端口未被占用
3. 等待 DNS 完全生效（可能需要几小时）
4. 检查宝塔面板日志

### 问题4：跨域错误

**现象**：
```
Access to XMLHttpRequest at 'https://api.pinzhuhui.com' from origin 'https://merchant.pinzhuhui.com' has been blocked by CORS policy
```

**解决**：
在 API 站点的反向代理配置中添加 CORS 头（见高级配置部分）

---

## 📊 性能优化建议

### 1. 启用 Gzip 压缩

在宝塔面板：
1. 网站设置 → **"性能"** 标签
2. 开启 **"Gzip 压缩"**
3. 选择压缩级别：5（推荐）

### 2. 配置缓存

1. 网站设置 → **"缓存"** 标签
2. 开启 **"浏览器缓存"**
3. 设置静态文件缓存时间：30天

### 3. 启用 HTTP/2

1. 网站设置 → **"SSL"** 标签
2. 开启 **"HTTP/2"**（需要先配置 HTTPS）

### 4. 监控和告警

宝塔面板内置监控：
1. 点击左侧 **"监控"**
2. 查看 CPU、内存、磁盘、网络使用情况
3. 配置告警规则（短信/邮件）

---

## 🎯 与 docker-compose.gateway.yml 的对比

| 特性 | 宝塔面板 | docker-compose.gateway.yml |
|------|---------|---------------------------|
| 配置方式 | Web 界面，可视化操作 | 手动编辑配置文件 |
| SSL 证书 | 自动申请和续期 | 需要手动配置 |
| 反向代理 | 点几下即可 | 需要编写 Nginx 配置 |
| 监控告警 | 内置面板 | 需要额外工具 |
| 适用场景 | 适合运维新手 | 适合有经验的开发者 |
| 灵活性 | 中等 | 高 |

**建议**：
- ✅ 如果使用宝塔面板，**推荐使用宝塔的反向代理功能**
- ✅ 如果熟悉 Nginx 和 Docker，可以使用 `docker-compose.gateway.yml`
- ❌ **不要同时使用两者**，会导致端口冲突

---

## 📝 配置检查清单

完成配置后，检查以下项目：

- [ ] DNS 解析已配置（8个域名）
- [ ] Docker 容器端口已映射
- [ ] 宝塔面板已添加所有站点
- [ ] 反向代理已配置
- [ ] SSL 证书已申请并自动续期
- [ ] 强制 HTTPS 已开启
- [ ] 防火墙规则已配置
- [ ] 所有域名可以正常访问
- [ ] CORS 配置正确（如需要）
- [ ] 监控和告警已配置

---

## 📞 需要帮助？

配置过程中遇到问题：

1. **查看日志**
   - 宝塔面板：网站设置 → 日志
   - Docker 容器：`docker logs <container_name>`

2. **宝塔论坛**
   - https://www.bt.cn/bbs/

3. **检查文档**
   - 端口映射：`deploy/docker/docker-compose.prod.yml`
   - 域名配置：`deploy/docker/DOMAIN_SETUP.md`

---

**最后更新**：2026-06-09  
**维护者**：开发团队
