opendance-web/deploy/proxy/nginx.conf.example

# ============================================================
# OpenDance Studio Web 服务端 —— nginx 反向代理样例（双端口）
#
# 说明：本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例，
#       由部署 `deploy/install.sh` 之外的反代负责人使用。
#
# 后端同时监听两个端口，职责不同：
#   软件 API 端口（PORT，默认 3000）—— Windows/Godot 客户端、Android App
#                                      只提供 /api、/health、/static、/contracts
#   管理端端口（ADMIN_PORT，默认 3001）—— 浏览器，提供管理页面 + 上面全部接口
#
# 两个端口都不需要在代理层托管静态文件、也不需要 SPA 回退（服务端已处理），
# 因此每个站点只要一条 `location /` 全匹配转发即可。
#
# 安装：
#   Debian/Ubuntu: /etc/nginx/sites-available/opendance.conf（再软链到 sites-enabled/）
#   RHEL 系:       /etc/nginx/conf.d/opendance.conf
# 校验并重载： nginx -t && systemctl reload nginx
#
# 想省事只挂一个域名？把两段 server 合并成一段，让另一侧的客户端直连端口即可；
# 也可以在后端设 `ADMIN_PORT=PORT` 走单端口兼容模式（此时管理页面回到 API 端口）。
# ============================================================

upstream opendance_api {
    # 软件 API 端口。同机用 127.0.0.1；异机改成实际 IP，并在后端放防火墙
    server 127.0.0.1:3000;
    keepalive 16;
}

upstream opendance_admin {
    # 管理端端口
    server 127.0.0.1:3001;
    keepalive 16;
}

# ------------------------------------------------------------
# 站点一：软件 API（给客户端调用）
# ------------------------------------------------------------
server {
    listen      80;
    listen      [::]:80;
    server_name dance-api.example.com;      # 改成实际域名或 _

    charset utf-8;

    # ★ 上传上限：后端默认允许 512 MiB，nginx 默认仅 1 MB，
    #   不改会导致 VRM / FBX / VMD 等大文件上传直接 413。
    client_max_body_size 512m;
    client_body_timeout  300s;

    access_log /var/log/nginx/opendance-api.access.log;
    error_log  /var/log/nginx/opendance-api.error.log;

    # ---- 全部请求转发给后端（/api、/health、/static、/contracts）----
    location / {
        proxy_pass         http://opendance_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;
        # 配合 upstream keepalive，避免 Connection: close
        proxy_set_header Connection        "";

        # ★ 超时：大文件上传与关键点序列下载都可能较慢
        proxy_connect_timeout 30s;
        proxy_send_timeout    300s;
        proxy_read_timeout    300s;

        # 大文件直接透传，不在代理层落盘
        proxy_request_buffering off;
        proxy_buffering         off;
    }

    # 健康检查可单独放开日志噪音（可选）
    location = /health {
        proxy_pass       http://opendance_api/health;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        access_log off;
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript
               application/x-ndjson text/xml application/xml image/svg+xml;
    gzip_min_length 1024;
}

# ------------------------------------------------------------
# 站点二：管理端（给浏览器）
#
# 建议只在内网 / VPN 内暴露，或至少加一层认证（见文件末尾）。
# 也可以把 server_name 写成内网域名，并在防火墙只放行内网来源。
# ------------------------------------------------------------
server {
    listen      80;
    listen      [::]:80;
    server_name dance-admin.example.com;    # 改成实际域名或 _

    charset utf-8;

    # 管理端同样会上传模型 / 动作，上限保持一致
    client_max_body_size 512m;
    client_body_timeout  300s;

    access_log /var/log/nginx/opendance-admin.access.log;
    error_log  /var/log/nginx/opendance-admin.error.log;

    # ---- 管理页面 + 全部接口 ----
    location / {
        proxy_pass         http://opendance_admin;
        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 30s;
        proxy_send_timeout    300s;
        proxy_read_timeout    300s;

        proxy_request_buffering off;
        proxy_buffering         off;

        # 代理层不要缓存 HTML，避免升级后页面不更新
        add_header Cache-Control "no-cache";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript
               application/x-ndjson image/svg+xml;
    gzip_min_length 1024;
}

# ============================================================
# 可选：HTTPS 终止在反代（后端只监听 HTTP）
#
# server {
#     listen 443 ssl;
#     http2 on;
#     server_name dance-admin.example.com;
#
#     ssl_certificate     /etc/nginx/ssl/opendance.crt;
#     ssl_certificate_key /etc/nginx/ssl/opendance.key;
#     ssl_protocols       TLSv1.2 TLSv1.3;
#
#     client_max_body_size 512m;
#
#     location / {
#         proxy_pass         http://opendance_admin;
#         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_send_timeout 300s;
#         proxy_read_timeout 300s;
#         proxy_request_buffering off;
#     }
# }
# ============================================================

# ============================================================
# 可选：本服务未内置登录认证
#
# 管理端建议至少加一层 Basic Auth；软件 API 若不便加认证，
# 请用 IP 白名单把来源限制为客户端所在网段。
#
# 管理端：
# location / {
#     auth_basic           "OpenDance Studio";
#     auth_basic_user_file /etc/nginx/.htpasswd;   # htpasswd -c 生成
#     proxy_pass http://opendance_admin;
#     ...
# }
#
# 软件 API：
# location / {
#     allow 192.0.2.0/24;    # 客户端所在网段
#     deny  all;
#     proxy_pass http://opendance_api;
#     ...
# }
# ============================================================