diff --git a/README.md b/README.md index 2bcf7194..9bd72d68 100644 --- a/README.md +++ b/README.md @@ -670,13 +670,17 @@ redis-cli ping ## 🛠️ 进阶 -### 生产环境部署建议(重要!) +### 反向代理部署指南 -**强烈建议使用Caddy反向代理(自动HTTPS)** +在生产环境中,建议通过反向代理进行连接,以便使用自动 HTTPS、安全头部和性能优化。下面提供两种常用方案: **Caddy** 和 **Nginx Proxy Manager (NPM)**。 -建议使用Caddy作为反向代理,它会自动申请和更新SSL证书,配置更简单: +--- -**1. 安装Caddy** +## Caddy 方案 + +Caddy 是一款自动管理 HTTPS 证书的 Web 服务器,配置简单、性能优秀,很适合不需要 Docker 环境的部署方案。 + +**1. 安装 Caddy** ```bash # Ubuntu/Debian @@ -692,23 +696,23 @@ sudo yum copr enable @caddy/caddy sudo yum install caddy ``` -**2. Caddy配置(超简单!)** +**2. Caddy 配置** -编辑 `/etc/caddy/Caddyfile`: +编辑 `/etc/caddy/Caddyfile` : -``` +```caddy your-domain.com { # 反向代理到本地服务 reverse_proxy 127.0.0.1:3000 { - # 支持流式响应(SSE) + # 支持流式响应或 SSE flush_interval -1 - # 传递真实IP + # 传递真实 IP header_up X-Real-IP {remote_host} header_up X-Forwarded-For {remote_host} header_up X-Forwarded-Proto {scheme} - # 超时设置(适合长连接) + # 长读/写超时配置 transport http { read_timeout 300s write_timeout 300s @@ -726,42 +730,132 @@ your-domain.com { } ``` -**3. 启动Caddy** +**3. 启动 Caddy** ```bash -# 测试配置 sudo caddy validate --config /etc/caddy/Caddyfile - -# 启动服务 sudo systemctl start caddy sudo systemctl enable caddy - -# 查看状态 sudo systemctl status caddy ``` -**4. 更新服务配置** +**4. 服务配置** -修改你的服务配置,让它只监听本地: +Caddy 会自动管理 HTTPS,因此可以将服务限制在本地进行监听: ```javascript // config/config.js module.exports = { server: { port: 3000, - host: '127.0.0.1' // 只监听本地,通过nginx代理 + host: '127.0.0.1' // 只监听本地 } - // ... 其他配置 } ``` -**Caddy优势:** +**Caddy 特点** -- 🔒 **自动HTTPS**: 自动申请和续期Let's Encrypt证书,零配置 -- 🛡️ **安全默认**: 默认启用现代安全协议和加密套件 -- 🚀 **流式支持**: 原生支持SSE/WebSocket等流式传输 -- 📊 **简单配置**: 配置文件极其简洁,易于维护 -- ⚡ **HTTP/2**: 默认启用HTTP/2,提升传输性能 +* 🔒 自动 HTTPS,零配置证书管理 +* 🛡️ 安全默认配置,启用现代 TLS 套件 +* ⚡ HTTP/2 和流式传输支持 +* 🔧 配置文件简洁,易于维护 + +--- + +## Nginx Proxy Manager (NPM) 方案 + +Nginx Proxy Manager 通过图形化界面管理反向代理和 HTTPS 证书,並以 Docker 容器部署。 + +**1. 在 NPM 创建新的 Proxy Host** + +Details 配置如下: + +| 项目 | 设置 | +| --------------------- | ----------------------- | +| Domain Names | relay.example.com | +| Scheme | http | +| Forward Hostname / IP | 192.168.0.1 (docker 机器 IP) | +| Forward Port | 3000 | +| Block Common Exploits | ☑️ | +| Websockets Support | ❌ **关闭** | +| Cache Assets | ❌ **关闭** | +| Access List | Publicly Accessible | + +> 注意: +> - 请确保 Claude Relay Service **监听 host 为 `0.0.0.0` 、容器 IP 或本机 IP**,以便 NPM 实现内网连接。 +> - **Websockets Support 和 Cache Assets 必须关闭**,否则会导致 SSE / 流式响应失败。 + +**2. Custom locations** + +無需添加任何内容,保持为空。 + +**3. SSL 设置** + +* **SSL Certificate**: Request a new SSL Certificate (Let's Encrypt) 或已有证书 +* ☑️ **Force SSL** +* ☑️ **HTTP/2 Support** +* ☑️ **HSTS Enabled** +* ☑️ **HSTS Subdomains** + +**4. Advanced 配置** + +Custom Nginx Configuration 中添加以下内容: + +```nginx +# 传递真实用户 IP +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; + +# 支持 WebSocket / SSE 等流式通信 +proxy_http_version 1.1; +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection "upgrade"; +proxy_buffering off; + +# 长连接 / 超时设置(适合 AI 聊天流式传输) +proxy_read_timeout 300s; +proxy_send_timeout 300s; +proxy_connect_timeout 30s; + +# ---- 安全性设置 ---- +# 严格 HTTPS 策略 (HSTS) +add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + +# 阻挡点击劫持与内容嗅探 +add_header X-Frame-Options "DENY" always; +add_header X-Content-Type-Options "nosniff" always; + +# Referrer / Permissions 限制策略 +add_header Referrer-Policy "no-referrer-when-downgrade" always; +add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; + +# 隐藏服务器信息(等效于 Caddy 的 `-Server`) +proxy_hide_header Server; + +# ---- 性能微调 ---- +# 关闭代理端缓存,确保即时响应(SSE / Streaming) +proxy_cache_bypass $http_upgrade; +proxy_no_cache $http_upgrade; +proxy_request_buffering off; +``` + +**4. 启动和验证** + +* 保存后等待 NPM 自动申请 Let's Encrypt 证书(如果有)。 +* Dashboard 中查看 Proxy Host 状态,确保显示为 "Online"。 +* 访问 `https://relay.example.com`,如果显示绿色锁图标即表示 HTTPS 正常。 + +**NPM 特点** + +* 🔒 自动申请和续期证书 +* 🔧 图形化界面,方便管理多服务 +* ⚡ 原生支持 HTTP/2 / HTTPS +* 🚀 适合 Docker 容器部署 + +--- + +上述两种方案均可用于生产部署。 --- diff --git a/README_EN.md b/README_EN.md index f7b905b6..6573021b 100644 --- a/README_EN.md +++ b/README_EN.md @@ -327,13 +327,18 @@ redis-cli ping ## 🛠️ Advanced Usage -### Production Deployment Recommendations (Important!) +### Reverse Proxy Deployment Guide -**Strongly recommend using Caddy reverse proxy (Automatic HTTPS)** +For production environments, it is recommended to use a reverse proxy for automatic HTTPS, security headers, and performance optimization. Two common solutions are provided below: **Caddy** and **Nginx Proxy Manager (NPM)**. -Recommend using Caddy as reverse proxy, it will automatically apply and renew SSL certificates with simpler configuration: +--- + +## Caddy Solution + +Caddy is a web server that automatically manages HTTPS certificates, with simple configuration and excellent performance, ideal for deployments without Docker environments. **1. Install Caddy** + ```bash # Ubuntu/Debian sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https @@ -348,29 +353,30 @@ sudo yum copr enable @caddy/caddy sudo yum install caddy ``` -**2. Caddy Configuration (Super Simple!)** +**2. Caddy Configuration** Edit `/etc/caddy/Caddyfile`: -``` + +```caddy your-domain.com { # Reverse proxy to local service reverse_proxy 127.0.0.1:3000 { - # Support streaming responses (SSE) + # Support streaming responses or SSE flush_interval -1 - + # Pass real IP header_up X-Real-IP {remote_host} header_up X-Forwarded-For {remote_host} header_up X-Forwarded-Proto {scheme} - - # Timeout settings (suitable for long connections) + + # Long read/write timeout configuration transport http { read_timeout 300s write_timeout 300s dial_timeout 30s } } - + # Security headers header { Strict-Transport-Security "max-age=31536000; includeSubDomains" @@ -382,38 +388,131 @@ your-domain.com { ``` **3. Start Caddy** -```bash -# Test configuration -sudo caddy validate --config /etc/caddy/Caddyfile -# Start service +```bash +sudo caddy validate --config /etc/caddy/Caddyfile sudo systemctl start caddy sudo systemctl enable caddy - -# Check status sudo systemctl status caddy ``` -**4. Update service configuration** +**4. Service Configuration** + +Since Caddy automatically manages HTTPS, you can restrict the service to listen locally only: -Modify your service configuration to listen only locally: ```javascript // config/config.js module.exports = { server: { port: 3000, - host: '127.0.0.1' // Listen only locally, proxy through nginx + host: '127.0.0.1' // Listen locally only } - // ... other configurations } ``` -**Caddy Advantages:** -- 🔒 **Automatic HTTPS**: Automatically apply and renew Let's Encrypt certificates, zero configuration -- 🛡️ **Secure by Default**: Modern security protocols and cipher suites enabled by default -- 🚀 **Streaming Support**: Native support for SSE/WebSocket streaming -- 📊 **Simple Configuration**: Extremely concise configuration files, easy to maintain -- ⚡ **HTTP/2**: HTTP/2 enabled by default for improved performance +**Caddy Features** + +* 🔒 Automatic HTTPS with zero-configuration certificate management +* 🛡️ Secure default configuration with modern TLS suites +* ⚡ HTTP/2 and streaming support +* 🔧 Concise configuration files, easy to maintain + +--- + +## Nginx Proxy Manager (NPM) Solution + +Nginx Proxy Manager manages reverse proxies and HTTPS certificates through a graphical interface, deployed as a Docker container. + +**1. Create a New Proxy Host in NPM** + +Configure the Details as follows: + +| Item | Setting | +| --------------------- | ------------------------ | +| Domain Names | relay.example.com | +| Scheme | http | +| Forward Hostname / IP | 192.168.0.1 (docker host IP) | +| Forward Port | 3000 | +| Block Common Exploits | ☑️ | +| Websockets Support | ❌ **Disable** | +| Cache Assets | ❌ **Disable** | +| Access List | Publicly Accessible | + +> Note: +> - Ensure Claude Relay Service **listens on `0.0.0.0`, container IP, or host IP** to allow NPM internal network connections. +> - **Websockets Support and Cache Assets must be disabled**, otherwise SSE / streaming responses will fail. + +**2. Custom locations** + +No content needed, keep it empty. + +**3. SSL Settings** + +* **SSL Certificate**: Request a new SSL Certificate (Let's Encrypt) or existing certificate +* ☑️ **Force SSL** +* ☑️ **HTTP/2 Support** +* ☑️ **HSTS Enabled** +* ☑️ **HSTS Subdomains** + +**4. Advanced Configuration** + +Add the following to Custom Nginx Configuration: + +```nginx +# Pass real user IP +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; + +# Support WebSocket / SSE streaming +proxy_http_version 1.1; +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection "upgrade"; +proxy_buffering off; + +# Long connection / timeout settings (for AI chat streaming) +proxy_read_timeout 300s; +proxy_send_timeout 300s; +proxy_connect_timeout 30s; + +# ---- Security Settings ---- +# Strict HTTPS policy (HSTS) +add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + +# Block clickjacking and content sniffing +add_header X-Frame-Options "DENY" always; +add_header X-Content-Type-Options "nosniff" always; + +# Referrer / Permissions restriction policies +add_header Referrer-Policy "no-referrer-when-downgrade" always; +add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; + +# Hide server information (equivalent to Caddy's `-Server`) +proxy_hide_header Server; + +# ---- Performance Tuning ---- +# Disable proxy caching for real-time responses (SSE / Streaming) +proxy_cache_bypass $http_upgrade; +proxy_no_cache $http_upgrade; +proxy_request_buffering off; +``` + +**5. Launch and Verify** + +* After saving, wait for NPM to automatically request Let's Encrypt certificate (if applicable). +* Check Proxy Host status in Dashboard to ensure it shows "Online". +* Visit `https://relay.example.com`, if the green lock icon appears, HTTPS is working properly. + +**NPM Features** + +* 🔒 Automatic certificate application and renewal +* 🔧 Graphical interface for easy multi-service management +* ⚡ Native HTTP/2 / HTTPS support +* 🚀 Ideal for Docker container deployments + +--- + +Both solutions are suitable for production deployment. If you use a Docker environment, **Nginx Proxy Manager is more convenient**; if you want to keep software lightweight and automated, **Caddy is a better choice**. ---