# CLAUDE.md — nginx-proxy-ai

tlyq.ai 反向代理服务，管理所有子站点的 SSL 终止、路由转发和性能优化。

## 项目概述

nginx-proxy-ai 是 tlyq.ai 域名的统一入口，负责：
- SSL/TLS 终止（所有 HTTPS 流量）
- 反向代理到后端 Docker 容器
- Gzip 压缩
- 静态资源缓存
- HTTP → HTTPS 强制跳转

## SSL 证书配置（必遵）

### 证书来源

| 证书路径 | 类型 | 用途 |
|---------|------|------|
| `/etc/letsencrypt/live/www.tlyq.ai/` | Let's Encrypt | **所有站点共用** |
| `/etc/letsencrypt/live/www.tlyq.ai-0001/` | Let's Encrypt | SSO 站点专用 |

### ⚠️ 禁止事项

1. **禁止使用 CloudFlare Origin 证书**：这是自签名证书，浏览器不信任
2. **禁止手动放置证书文件**：必须通过 certbot 申请
3. **禁止修改 `/etc/letsencrypt/` 目录权限**

### 新增站点证书流程

1. 申请证书：
   ```bash
   ssh txjp "certbot certonly --webroot -w /var/www/html -d new-site.tlyq.ai"
   ```

2. 配置 nginx 引用现有证书（推荐共用 `www.tlyq.ai`）：
   ```nginx
   ssl_certificate /etc/letsencrypt/live/www.tlyq.ai/fullchain.pem;
   ssl_certificate_key /etc/letsencrypt/live/www.tlyq.ai/privkey.pem;
   ```

3. 重载配置：
   ```bash
   ssh txjp "docker exec nginx-ai nginx -s reload"
   ```

### 证书续期检查

```bash
# 检查证书有效期
ssh txjp "openssl x509 -in /etc/letsencrypt/live/www.tlyq.ai/fullchain.pem -noout -dates"

# 检查续期定时器
ssh txjp "systemctl list-timers | grep certbot"
```

## 文件结构

```
nginx-proxy-ai/
├── nginx.conf              # 主配置（全局优化参数）
├── nginx-local.conf        # 本地测试配置
├── docker-compose.yml      # 生产 Docker 配置
├── docker-compose.local.yml # 本地测试 Docker 配置
├── conf.d/                 # 站点反向代理配置
│   ├── www-ai.conf         # www.tlyq.ai
│   ├── cloud-ai.conf       # cloud.tlyq.ai（纯静态）
│   ├── token-ai.conf       # token.tlyq.ai（纯静态）
│   ├── issue-ai.conf       # issue.tlyq.ai
│   ├── assets-ai.conf      # assets.tlyq.ai
│   ├── git-ai.conf         # git.tlyq.ai（Gitea）
│   ├── oa-ai.conf          # oa.tlyq.ai
│   ├── sso-ai.conf         # sso.tlyq.ai（Authelia）
│   ├── monitor-ai.conf     # monitor.tlyq.ai
│   ├── root-domain.conf    # tlyq.ai → www.tlyq.ai 跳转
│   └── letsencrypt.conf    # ACME HTTP-01 验证
├── certs/                  # 本地测试自签名证书（不纳入生产）
└── static/                 # 静态文件目录
```

## 部署流程

### 生产部署（txjp 服务器）

```bash
# 1. 上传配置（排除本地测试文件）
rsync -avz --exclude='node_modules' --exclude='.git' \
  --exclude='nginx-local.conf' --exclude='docker-compose.local.yml' \
  --exclude='certs/' \
  ./ txjp:/root/docker/nginx-proxy-ai/

# 2. 验证配置
ssh txjp "docker exec nginx-ai nginx -t"

# 3. 平滑重载
ssh txjp "docker exec nginx-ai nginx -s reload"
```

### 本地测试

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

## 性能优化参数

### 全局优化（nginx.conf http 块）

```nginx
# IO 优化
sendfile on;
tcp_nopush on;
tcp_nodelay on;

# Keepalive
keepalive_timeout 65;
keepalive_requests 1000;

# 客户端超时
client_max_body_size 16m;
client_body_buffer_size 128k;
client_header_timeout 30s;
send_timeout 30s;

# Gzip
gzip on;
gzip_min_length 1k;
gzip_comp_level 5;
gzip_types text/plain text/css application/json application/javascript application/xml image/svg+xml;
```

### SSL 安全配置

```nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets on;
server_tokens off;
```

### 反代默认参数

```nginx
proxy_http_version 1.1;
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;
proxy_set_header Connection "";
proxy_connect_timeout 3s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;
```

## 常用排查命令

```bash
# 配置语法检查
docker exec nginx-ai nginx -t

# 查看完整合并配置
docker exec nginx-ai nginx -T

# 查看 SSL 配置
docker exec nginx-ai nginx -T | grep -E 'ssl_protocols|ssl_ciphers|ssl_certificate'

# 测试 SSL 连接
echo | openssl s_client -connect 127.0.0.1:443 -servername www.tlyq.ai 2>/dev/null | grep -E 'Protocol|Cipher'

# 检查证书有效期
ssh txjp "openssl x509 -in /etc/letsencrypt/live/www.tlyq.ai/fullchain.pem -noout -dates"
```

## 故障排查

### SSL 不安全提示

1. 检查证书是否为 Let's Encrypt：
   ```bash
   ssh txjp "openssl x509 -in /etc/letsencrypt/live/www.tlyq.ai/fullchain.pem -noout -issuer"
   ```
   应显示 `Let's Encrypt`，而非 `CloudFlare`

2. 检查 SSL 协议和加密套件：
   ```bash
   docker exec nginx-ai nginx -T | grep -E 'ssl_protocols|ssl_ciphers'
   ```
   必须配置 `ssl_protocols TLSv1.2 TLSv1.3`

### 502 Bad Gateway

1. 检查后端容器是否运行：
   ```bash
   docker ps | grep -E 'www-ai|assets-ai|issue-ai'
   ```

2. 检查容器网络连通性：
   ```bash
   docker exec nginx-ai ping assets-ai
   ```

### 配置不生效

1. 确认配置语法正确：
   ```bash
   docker exec nginx-ai nginx -t
   ```

2. 确认已重载：
   ```bash
   docker exec nginx-ai nginx -s reload
   ```

3. 确认容器挂载路径正确：
   ```bash
   docker inspect nginx-ai | grep -A5 Mounts
   ```