# 域名配置指南

## 📋 域名列表

### 生产环境
- `api.pinzhuhui.com` - 后端 API 服务
- `www.pinzhuhui.com` - 官方网站
- `merchant.pinzhuhui.com` - 商家管理后台
- `platform-admin.pinzhuhui.com` - 平台管理后台

### 测试环境
- `api-test.pinzhuhui.com` - 测试 API
- `test.pinzhuhui.com` - 测试官网
- `merchant-test.pinzhuhui.com` - 测试商家后台
- `platform-admin-test.pinzhuhui.com` - 测试平台后台

---

## 🚀 快速配置步骤

### 1. DNS 解析配置

登录域名服务商控制台（阿里云/腾讯云等），添加以下 A 记录：

```
主机记录              记录类型    记录值              TTL
api                  A          YOUR_SERVER_IP      600
www                  A          YOUR_SERVER_IP      600
merchant             A          YOUR_SERVER_IP      600
platform-admin       A          YOUR_SERVER_IP      600
api-test             A          YOUR_SERVER_IP      600
test                 A          YOUR_SERVER_IP      600
merchant-test        A          YOUR_SERVER_IP      600
platform-admin-test  A          YOUR_SERVER_IP      600
```

**注意**：将 `YOUR_SERVER_IP` 替换为实际的服务器公网 IP

### 2. 启动 Nginx 网关

SSH 登录到服务器后执行：

```bash
# 进入部署目录
cd /path/to/your/deploy/docker

# 启动网关
docker-compose -f docker-compose.gateway.yml up -d

# 查看状态
docker ps | grep rent-gateway

# 查看日志
docker logs rent-gateway -f
```

### 3. 验证域名解析

```bash
# 检查 DNS 是否生效（在本地电脑执行）
ping api.pinzhuhui.com
ping merchant.pinzhuhui.com

# 或使用 nslookup
nslookup api.pinzhuhui.com
```

### 4. 测试访问

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

# 或在浏览器访问
http://api.pinzhuhui.com
http://merchant.pinzhuhui.com
```

---

## 🔒 配置 HTTPS（推荐）

### 方法1：使用 Let's Encrypt 免费证书（推荐）

#### 安装 Certbot

```bash
# Ubuntu/Debian
apt-get update
apt-get install certbot

# CentOS/RHEL
yum install certbot
```

#### 申请证书

**注意**：申请证书前需要先停止 Nginx，因为 certbot 需要占用 80 端口

```bash
# 停止网关
docker-compose -f docker-compose.gateway.yml down

# 申请证书（一次性申请所有域名）
certbot certonly --standalone \
  -d api.pinzhuhui.com \
  -d www.pinzhuhui.com \
  -d merchant.pinzhuhui.com \
  -d platform-admin.pinzhuhui.com \
  -d api-test.pinzhuhui.com \
  -d test.pinzhuhui.com \
  -d merchant-test.pinzhuhui.com \
  -d platform-admin-test.pinzhuhui.com \
  --email your-email@example.com \
  --agree-tos

# 证书存放位置：
# /etc/letsencrypt/live/api.pinzhuhui.com/fullchain.pem
# /etc/letsencrypt/live/api.pinzhuhui.com/privkey.pem
```

#### 配置 Nginx 使用证书

修改 `docker-compose.gateway.yml`，添加证书目录挂载：

```yaml
services:
  gateway:
    image: nginx:alpine
    container_name: rent-gateway
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ../nginx/gateway/gateway.conf:/etc/nginx/nginx.conf:ro
      - /etc/letsencrypt:/etc/letsencrypt:ro  # 添加这行
    networks:
      - rent-prod
      - rent-test
```

#### 修改 Nginx 配置文件

参考 `gateway-https-example.conf`，在 `gateway.conf` 中添加 HTTPS 配置。

#### 重启网关

```bash
docker-compose -f docker-compose.gateway.yml up -d
```

#### 设置证书自动续期

Let's Encrypt 证书有效期 90 天，需要定期续期：

```bash
# 创建续期脚本
cat > /etc/cron.d/certbot-renew << 'EOF'
0 0,12 * * * root certbot renew --quiet --deploy-hook "docker restart rent-gateway"
EOF

# 或手动续期
certbot renew
docker restart rent-gateway
```

### 方法2：使用已有证书

如果已有证书文件：

```bash
# 创建证书目录
mkdir -p /path/to/deploy/nginx/certs

# 上传证书文件
# - domain.crt (证书文件)
# - domain.key (私钥文件)

# 修改 docker-compose.gateway.yml
volumes:
  - ../nginx/gateway/gateway.conf:/etc/nginx/nginx.conf:ro
  - ../nginx/certs:/etc/nginx/certs:ro  # 添加这行
```

---

## 🔧 修改后端 API 域名配置

### 小程序配置

修改 `apps/miniapp/src/config/env.ts`:

```typescript
export const API_BASE_URL = {
  development: 'http://localhost:3000',
  production: 'https://api.pinzhuhui.com',  // 改为生产域名
  test: 'https://api-test.pinzhuhui.com'    // 改为测试域名
}
```

### 商家管理后台配置

修改 `apps/merchant-admin/src/config/api.ts`:

```typescript
const API_BASE_URL = process.env.NODE_ENV === 'production'
  ? 'https://api.pinzhuhui.com'
  : 'http://localhost:3000';
```

### 平台管理后台配置

修改 `apps/platform-admin/src/config/api.ts`:

```typescript
const API_BASE_URL = process.env.NODE_ENV === 'production'
  ? 'https://api.pinzhuhui.com'
  : 'http://localhost:3000';
```

---

## 🔍 故障排查

### DNS 解析不生效

```bash
# 检查 DNS 是否生效
dig api.pinzhuhui.com
nslookup api.pinzhuhui.com

# 刷新本地 DNS 缓存
# Windows
ipconfig /flushdns

# macOS
sudo dscacheutil -flushcache

# Linux
sudo systemd-resolve --flush-caches
```

### Nginx 配置错误

```bash
# 测试配置文件语法
docker exec rent-gateway nginx -t

# 查看详细错误日志
docker logs rent-gateway

# 重新加载配置
docker exec rent-gateway nginx -s reload
```

### 端口被占用

```bash
# 查看端口占用
netstat -tlnp | grep :80
netstat -tlnp | grep :443

# 或使用 ss
ss -tlnp | grep :80
ss -tlnp | grep :443

# 停止占用端口的服务
systemctl stop <service-name>
```

### 证书错误

```bash
# 检查证书有效期
openssl x509 -in /etc/letsencrypt/live/api.pinzhuhui.com/fullchain.pem -noout -dates

# 测试 SSL 配置
openssl s_client -connect api.pinzhuhui.com:443

# 强制续期证书
certbot renew --force-renewal
docker restart rent-gateway
```

### 跨域问题

如果遇到跨域错误，在 Nginx 配置中添加：

```nginx
location / {
    # CORS 配置
    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;
    }

    proxy_pass http://prod_api;
    ...
}
```

---

## 📊 域名管理最佳实践

### 1. 使用泛域名证书

如果有多个子域名，可以申请泛域名证书：

```bash
certbot certonly --standalone \
  -d pinzhuhui.com \
  -d *.pinzhuhui.com \
  --email your-email@example.com \
  --agree-tos
```

### 2. CDN 加速

对于静态资源和前端页面，建议使用 CDN：
- 阿里云 CDN
- 腾讯云 CDN
- Cloudflare（免费）

### 3. 监控和告警

- 设置域名到期提醒
- 设置证书到期提醒（Let's Encrypt 60天时提醒）
- 监控网站可用性

### 4. 备案要求

如果服务器在中国大陆，域名需要 ICP 备案：
- 登录服务商备案系统
- 提交备案材料
- 等待审核（通常 7-20 个工作日）

---

## 📞 需要帮助？

- Nginx 配置文件：`deploy/nginx/gateway/gateway.conf`
- Docker Compose：`deploy/docker/docker-compose.gateway.yml`
- HTTPS 示例：`deploy/nginx/gateway/gateway-https-example.conf`

配置过程中遇到问题，请检查：
1. DNS 解析是否生效
2. 防火墙是否开放 80/443 端口
3. Nginx 容器是否正常运行
4. 证书路径是否正确
5. 后端服务是否正常启动
