github/claude-relay-service
1
0
Fork 0
mirror of https://github.com/Wei-Shaw/claude-relay-service.git synced 2026-01-22 16:43:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 改进反向代理部署指南，新增 NPM 方案

Browse Source 
## 变更内容 / Changes

### 中文文档 (README.md)
- 重构反向代理章节结构
- 新增 Nginx Proxy Manager (NPM) 完整配置指南
- 优化 Caddy 配置说明
- 添加 Docker 环境部署注意事项
### 英文文档 (README_EN.md)
- 同步中文文档的所有改进
- 保持中英文文档一致性

## 改进点 / Improvements

- ✅ 提供两种主流反向代理方案（Caddy + NPM）
- ✅ 详细的 NPM 配置步骤（Details、SSL、Advanced）
- ✅ 针对 SSE/流式响应的优化配置
- ✅ 安全头部和性能调优建议
- ✅ Docker 环境特定说明

## 技术细节 / Technical Details

**NPM 配置包含:**
- 代理主机设置，包含正确的超时配置
- SSL/TLS 配置，启用 HSTS
- 支持流式传输的高级 Nginx 指令
- 安全头部（X-Frame-Options、CSP 等）
- 禁用代理缓冲以支持实时 SSE

**Caddy 配置更新:**
- 明确 flush_interval 用于 SSE 支持
- 改进超时设置文档
- 更好的安全头部示例
This commit is contained in:
rxchi1d
2025-10-09 14:11:26 +08:00
parent cffd023239
commit df5e04b4c4
2 changed files with 245 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
README.md
View File

@@ -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 ```bash
# Ubuntu/Debian # Ubuntu/Debian
@@ -692,23 +696,23 @@ sudo yum copr enable @caddy/caddy
sudo yum install caddy sudo yum install caddy
``` ```
**2. Caddy配置（超简单！）** **2. Caddy 配置**
编辑 `/etc/caddy/Caddyfile`： 编辑 `/etc/caddy/Caddyfile` ：
``` ```caddy
your-domain.com { your-domain.com {
# 反向代理到本地服务 # 反向代理到本地服务
reverse_proxy 127.0.0.1:3000 { reverse_proxy 127.0.0.1:3000 {
# 支持流式响应（SSE） # 支持流式响应或 SSE
flush_interval -1 flush_interval -1
# 传递真实IP # 传递真实 IP
header_up X-Real-IP {remote_host} header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host} header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme} header_up X-Forwarded-Proto {scheme}
# 超时设置（适合长连接） # 长读/写超时配置
transport http { transport http {
read_timeout 300s read_timeout 300s
write_timeout 300s write_timeout 300s
@@ -726,42 +730,132 @@ your-domain.com {
} }
``` ```
**3. 启动Caddy** **3. 启动 Caddy**
```bash ```bash
# 测试配置
sudo caddy validate --config /etc/caddy/Caddyfile sudo caddy validate --config /etc/caddy/Caddyfile
# 启动服务
sudo systemctl start caddy sudo systemctl start caddy
sudo systemctl enable caddy sudo systemctl enable caddy
# 查看状态
sudo systemctl status caddy sudo systemctl status caddy
``` ```
**4. 更新服务配置** **4. 服务配置**
修改你的服务配置，让它只监听本地： Caddy 会自动管理 HTTPS，因此可以将服务限制在本地进行监听：
```javascript ```javascript
// config/config.js // config/config.js
module.exports = { module.exports = {
server: { server: {
port: 3000, port: 3000,
host: '127.0.0.1' // 只监听本地，通过nginx代理 host: '127.0.0.1' // 只监听本地
} }
// ... 其他配置
} }
``` ```
**Caddy优势：** **Caddy 特点**
- 🔒 **自动HTTPS**: 自动申请和续期Let's Encrypt证书，零配置 * 🔒 自动 HTTPS，零配置证书管理
- 🛡️ **安全默认**: 默认启用现代安全协议和加密套件 * 🛡️ 安全默认配置，启用现代 TLS 套件
- 🚀 **流式支持**: 原生支持SSE/WebSocket等流式传输 * ⚡ HTTP/2 和流式传输支持
- 📊 **简单配置**: 配置文件极其简洁，易于维护 * 🔧 配置文件简洁，易于维护
- ⚡ **HTTP/2**: 默认启用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 容器部署
---
上述两种方案均可用于生产部署。
--- ---

151
README_EN.md
View File

@@ -327,13 +327,18 @@ redis-cli ping
## 🛠️ Advanced Usage ## 🛠️ 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** **1. Install Caddy**
```bash ```bash
# Ubuntu/Debian # Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https 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 sudo yum install caddy
``` ```
**2. Caddy Configuration (Super Simple!)** **2. Caddy Configuration**
Edit `/etc/caddy/Caddyfile`: Edit `/etc/caddy/Caddyfile`:
```
```caddy
your-domain.com { your-domain.com {
# Reverse proxy to local service # Reverse proxy to local service
reverse_proxy 127.0.0.1:3000 { reverse_proxy 127.0.0.1:3000 {
# Support streaming responses (SSE) # Support streaming responses or SSE
flush_interval -1 flush_interval -1
# Pass real IP # Pass real IP
header_up X-Real-IP {remote_host} header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host} header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme} header_up X-Forwarded-Proto {scheme}
# Timeout settings (suitable for long connections) # Long read/write timeout configuration
transport http { transport http {
read_timeout 300s read_timeout 300s
write_timeout 300s write_timeout 300s
dial_timeout 30s dial_timeout 30s
} }
} }
# Security headers # Security headers
header { header {
Strict-Transport-Security "max-age=31536000; includeSubDomains" Strict-Transport-Security "max-age=31536000; includeSubDomains"
@@ -382,38 +388,131 @@ your-domain.com {
``` ```
**3. Start Caddy** **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 start caddy
sudo systemctl enable caddy sudo systemctl enable caddy
# Check status
sudo systemctl status caddy 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 ```javascript
// config/config.js // config/config.js
module.exports = { module.exports = {
server: { server: {
port: 3000, 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:** **Caddy Features**
- 🔒 **Automatic HTTPS**: Automatically apply and renew Let's Encrypt certificates, zero configuration
- 🛡️ **Secure by Default**: Modern security protocols and cipher suites enabled by default * 🔒 Automatic HTTPS with zero-configuration certificate management
- 🚀 **Streaming Support**: Native support for SSE/WebSocket streaming * 🛡️ Secure default configuration with modern TLS suites
- 📊 **Simple Configuration**: Extremely concise configuration files, easy to maintain * ⚡ HTTP/2 and streaming support
- ⚡ **HTTP/2**: HTTP/2 enabled by default for improved performance * 🔧 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**.
--- ---