签入版本

2026-09-16 10:11:44 +08:00
parent bf08cf1248
commit 20d8a85989
205 changed files with 34363 additions and 0 deletions
@@ -0,0 +1,177 @@
+# Nginx 反向代理
+
+## 概述
+
+Nginx 作为反向代理服务器，承担静态资源服务、API 请求转发、HTTPS 终端等职责。生产环境推荐使用 Nginx 作为前端入口，将 API 请求代理到后端 Tornado 服务。
+
+:::tip 架构示意
+```
+客户端 → Nginx（80/443）
+          ├─ /            → 前端静态资源（dist/）
+          ├─ /api/v1/...  → Tornado 后端（8041）
+          └─ /api/file/   → 上传文件目录
+```
+:::
+
+## 基础配置
+
+项目提供了 Nginx 配置模板 `deploy/nginx.conf`，按需修改即可使用：
+
+```nginx
+upstream tornado_backend {
+    server 127.0.0.1:8041;
+    keepalive 16;
+}
+
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    charset utf-8;
+    client_max_body_size 50m;
+
+    # 安全头
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+
+    # Gzip 压缩
+    gzip on;
+    gzip_min_length 1k;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css application/json application/javascript text/xml image/svg+xml;
+    gzip_vary on;
+
+    # 前端静态资源
+    root /data/apps/djangoadmin/frontend/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /assets/ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+        access_log off;
+    }
+
+    # API 反向代理
+    location /api/ {
+        proxy_pass http://tornado_backend/api/;
+        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 60s;
+        proxy_read_timeout 120s;
+        proxy_send_timeout 60s;
+    }
+
+    # 上传文件访问
+    location /api/file/ {
+        alias /data/apps/djangoadmin/uploads/;
+        expires 7d;
+        access_log off;
+        limit_except GET { deny all; }
+    }
+
+    # 禁止访问隐藏文件
+    location ~ /\. { deny all; }
+}
+```
+
+:::tip 配置说明
+- `upstream` + `keepalive`：长连接池减少 TCP 握手开销
+- `location /`：`try_files` 支持 SPA 路由回退
+- `location /api/`：只代理 API 请求，前端静态资源由 Nginx 直接服务
+- `location /api/file/`：通过 `alias` 访问上传文件目录，只允许 GET
+- `client_max_body_size 50m`：与后端 `UPLOAD_MAX_SIZE_MB` 保持一致
+- `proxy_read_timeout 120s`：适应大数据量导出等长耗时操作
+:::
+
+## 部署步骤
+
+```bash
+# 1. 前端构建
+cd ui && pnpm build
+
+# 2. 拷贝构建产物
+mkdir -p /data/apps/djangoadmin/frontend
+cp -r ui/dist /data/apps/djangoadmin/frontend/
+
+# 3. 拷贝 Nginx 配置
+cp deploy/nginx.conf /etc/nginx/conf.d/djangoadmin.conf
+
+# 4. 修改配置中的实际值（server_name、root 等）
+
+# 5. 检查并重载
+nginx -t && nginx -s reload
+```
+
+## HTTPS 配置
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate     /etc/nginx/ssl/cert.pem;
+    ssl_certificate_key /etc/nginx/ssl/key.pem;
+    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;
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    # HSTS（强制 HTTPS）
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    # ... 其他 location 配置同上 ...
+}
+
+# HTTP 自动跳转 HTTPS
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+:::warning SSL 证书安全
+- 证书文件权限设为 `600`，仅 Nginx 用户可读
+- 禁用 TLSv1.0/1.1，仅保留 TLSv1.2+
+- 推荐 Let's Encrypt 免费证书 + certbot 自动续期
+:::
+
+## 常用命令
+
+```bash
+nginx -t                # 检查配置语法
+nginx -s reload         # 重新加载（不停服）
+nginx -s stop           # 停止
+nginx -v                # 查看版本
+```
+
+## 常见问题
+
+### 502 Bad Gateway
+
+后端 Tornado 服务未启动或端口不对。检查：`curl http://127.0.0.1:8041/api/v1/captcha`
+
+### 413 Request Entity Too Large
+
+上传文件超过 `client_max_body_size` 限制，调大该值与后端 `UPLOAD_MAX_SIZE_MB` 一致。
+
+### 刷新页面 404
+
+缺少 `try_files $uri $uri/ /index.html`，SPA 路由需要回退到 `index.html`。
+
+### API 请求走到了前端
+
+`location /api/` 必须在 `location /` 之前定义，Nginx 按优先级匹配。
+
+## 总结
+
+Nginx 反向代理是生产部署的标准配置：`/` 服务前端静态资源、`/api/` 反向代理到 Tornado 后端、`/api/file/` 访问上传文件。关键配置包括 `try_files` 支持 SPA 路由、`client_max_body_size` 匹配上传限制、Gzip 压缩和静态资源缓存。