docs: 添加宝塔面板反向代理配置完整指南

## 新增文档 - BAOTA_PROXY_SETUP.md - 宝塔面板域名和反向代理配置指南 ## 包含内容 ### 配置步骤 - Docker Compose 端口映射配置（生产/测试环境） - 宝塔面板添加站点和配置反向代理 - SSL 证书自动申请和续期 - 防火墙和安全组配置 ### 端口映射规划 - 生产环境：10080-10086 - 测试环境：10081-10087 - 8个服务完整映射表 ### 高级配置 - API 速率限制 - CORS 跨域配置 - WebSocket 支持 - 静态资源缓存 ### 故障排查 - 域名无法访问 - 502 Bad Gateway - SSL 证书申请失败 - 跨域错误 ### 性能优化 - Gzip 压缩 - 浏览器缓存 - HTTP/2 支持 - 监控和告警 ### 对比说明 - 宝塔面板 vs docker-compose.gateway.yml - 适用场景和选择建议 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 16:29:28 +08:00
parent 72c8add85e
commit 87e870d0cb
1 changed files with 517 additions and 0 deletions
@@ -0,0 +1,517 @@
+# 宝塔面板域名配置指南
+
+> 如果您使用宝塔面板管理服务器，推荐使用宝塔自带的反向代理功能，无需手动配置 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  
+**维护者**：开发团队