X1_Site/site/HTTPS_DEPLOY.md

# HTTPS 部署指南

本文档说明如何使用 Docker Compose 进行 HTTPS 部署。

## 目录结构

```
site/
├── docker-compose.yml         # Docker Compose HTTP 配置文件（直接访问 3000 端口）
├── docker-compose.https.yml   # Docker Compose HTTPS 配置文件（通过 Nginx 反向代理）
├── nginx/
│   └── nginx.conf             # Nginx 反向代理配置
├── ssl/
│   ├── cert.pem               # SSL 证书文件（需要自行添加）
│   ├── key.pem                # SSL 私钥文件（需要自行添加）
│   └── README.md              # SSL 证书说明
└── Dockerfile                 # 应用镜像构建文件
```

## 配置文件说明

- **docker-compose.yml** - HTTP 配置（默认）
  - 直接暴露 3000 端口
  - 适用于开发环境或不需要 HTTPS 的场景
  
- **docker-compose.https.yml** - HTTPS 配置
  - 使用 Nginx 反向代理
  - 支持 HTTP 自动重定向到 HTTPS
  - 适用于生产环境

## 前置要求

1. Docker 和 Docker Compose 已安装
2. SSL 证书文件已准备好（见 `ssl/README.md`）

## 快速开始

### 1. 准备 SSL 证书

将 SSL 证书文件放置到 `ssl/` 目录：

```bash
# 证书文件
ssl/cert.pem

# 私钥文件
ssl/key.pem
```

详细说明请参考 `ssl/README.md`。

### 2. 启动服务

使用 HTTPS 配置文件启动：

```bash
cd site
docker-compose -f docker-compose.https.yml up -d
```

**注意**：使用 `-f` 参数指定 HTTPS 配置文件。如果不指定，默认使用 `docker-compose.yml`（HTTP 模式）。

### 3. 访问服务

- HTTP: http://localhost (自动重定向到 HTTPS)
- HTTPS: https://localhost

## 服务说明

### marketing-site

- 应用服务，运行在容器内部端口 3000
- 不直接暴露端口，通过 nginx 反向代理访问

### nginx

- 反向代理服务
- 监听端口 80 (HTTP) 和 443 (HTTPS)
- 自动将 HTTP 请求重定向到 HTTPS
- 提供 SSL/TLS 终止

## 常用命令

### 启动服务
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml up -d

# HTTP 模式（默认）
docker-compose up -d
```

### 停止服务
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml down

# HTTP 模式
docker-compose down
```

### 查看日志
```bash
# HTTPS 模式 - 查看所有服务日志
docker-compose -f docker-compose.https.yml logs -f

# HTTPS 模式 - 查看特定服务日志
docker-compose -f docker-compose.https.yml logs -f nginx
docker-compose -f docker-compose.https.yml logs -f marketing-site

# HTTP 模式
docker-compose logs -f
```

### 重启服务
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml restart

# HTTP 模式
docker-compose restart
```

### 重新构建应用
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml build marketing-site
docker-compose -f docker-compose.https.yml up -d

# HTTP 模式
docker-compose build marketing-site
docker-compose up -d
```

## 配置说明

### 修改端口

如需修改 HTTPS 端口，编辑 `docker-compose.https.yml`：

```yaml
nginx:
  ports:
    - "80:80"
    - "8443:443"  # 修改为 8443
```

### 修改域名

编辑 `nginx/nginx.conf`，将 `server_name _;` 替换为您的域名：

```nginx
server_name your-domain.com www.your-domain.com;
```

### 更新 SSL 证书

1. 将新证书文件放置到 `ssl/` 目录
2. 重启 nginx 服务：
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml restart nginx

# HTTP 模式不需要此操作
```

## 故障排查

### 检查容器状态
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml ps

# HTTP 模式
docker-compose ps
```

### 检查 SSL 证书
```bash
# 验证证书文件是否存在
ls -la ssl/

# 验证证书内容
openssl x509 -in ssl/cert.pem -text -noout
```

### 检查 Nginx 配置
```bash
# 进入 nginx 容器
docker exec -it nginx-https sh

# 测试配置
nginx -t
```

### 查看错误日志
```bash
# HTTPS 模式
docker-compose -f docker-compose.https.yml logs nginx

# HTTP 模式（无 nginx 服务）
docker-compose logs marketing-site
```

## 安全建议

1. ✅ 使用有效的 SSL 证书（生产环境）
2. ✅ 定期更新 SSL 证书
3. ✅ 使用强密码保护私钥文件
4. ✅ 不要将私钥文件提交到版本控制系统
5. ✅ 定期更新 Docker 镜像和依赖

## HTTP vs HTTPS 模式对比

| 特性 | HTTP 模式 | HTTPS 模式 |
|------|-----------|------------|
| 配置文件 | `docker-compose.yml` | `docker-compose.https.yml` |
| 访问端口 | 3000 | 80 (HTTP), 443 (HTTPS) |
| 访问地址 | http://localhost:3000 | http://localhost, https://localhost |
| 反向代理 | 无 | Nginx |
| SSL 证书 | 不需要 | 需要 |
| 适用场景 | 开发环境 | 生产环境 |

## 注意事项

- 首次启动 HTTPS 模式前必须准备好 SSL 证书文件
- 如果证书文件不存在，nginx 容器将无法启动
- 自签名证书仅用于开发测试，生产环境请使用有效证书
- 确保防火墙允许 80 和 443 端口访问（HTTPS 模式）
- HTTP 模式和 HTTPS 模式可以同时运行，但需要确保端口不冲突