mirror of
https://github.com/Wei-Shaw/claude-relay-service.git
synced 2026-01-22 16:43:35 +00:00
docs: 改进反向代理部署指南，新增 NPM 方案
## 变更内容 / 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
138
README.md
138
README.md
@@ -670,11 +670,15 @@ redis-cli ping
|
||||
|
||||
## 🛠️ 进阶
|
||||
|
||||
### 生产环境部署建议（重要！）
|
||||
### 反向代理部署指南
|
||||
|
||||
**强烈建议使用Caddy反向代理（自动HTTPS）**
|
||||
在生产环境中，建议通过反向代理进行连接，以便使用自动 HTTPS、安全头部和性能优化。下面提供两种常用方案： **Caddy** 和 **Nginx Proxy Manager (NPM)**。
|
||||
|
||||
建议使用Caddy作为反向代理，它会自动申请和更新SSL证书，配置更简单：
|
||||
---
|
||||
|
||||
## Caddy 方案
|
||||
|
||||
Caddy 是一款自动管理 HTTPS 证书的 Web 服务器，配置简单、性能优秀，很适合不需要 Docker 环境的部署方案。
|
||||
|
||||
**1. 安装 Caddy**
|
||||
|
||||
@@ -692,15 +696,15 @@ sudo yum copr enable @caddy/caddy
|
||||
sudo yum install caddy
|
||||
```
|
||||
|
||||
**2. Caddy配置（超简单！）**
|
||||
**2. Caddy 配置**
|
||||
|
||||
编辑 `/etc/caddy/Caddyfile` ：
|
||||
|
||||
```
|
||||
```caddy
|
||||
your-domain.com {
|
||||
# 反向代理到本地服务
|
||||
reverse_proxy 127.0.0.1:3000 {
|
||||
# 支持流式响应（SSE）
|
||||
# 支持流式响应或 SSE
|
||||
flush_interval -1
|
||||
|
||||
# 传递真实 IP
|
||||
@@ -708,7 +712,7 @@ your-domain.com {
|
||||
header_up X-Forwarded-For {remote_host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
|
||||
# 超时设置（适合长连接）
|
||||
# 长读/写超时配置
|
||||
transport http {
|
||||
read_timeout 300s
|
||||
write_timeout 300s
|
||||
@@ -729,39 +733,129 @@ your-domain.com {
|
||||
**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 容器部署
|
||||
|
||||
---
|
||||
|
||||
上述两种方案均可用于生产部署。
|
||||
|
||||
---
|
||||
|
||||
|
||||
145
README_EN.md
145
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,14 +353,15 @@ 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
|
||||
@@ -363,7 +369,7 @@ your-domain.com {
|
||||
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
|
||||
@@ -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**.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user