Nginx 配置

公网部署时使用 Nginx 作为反向代理，实现域名访问、HTTPS 加密、性能优化和安全防护。

何时使用 Nginx

场景	是否需要 Nginx
本机个人使用	不需要，直接访问 `localhost:3000`
内网小团队使用（<10人）	不需要，直接访问 `IP:3000`
内网多人使用	建议，提升性能
公网部署	必须，安全保障
需要域名/HTTPS	必须
多用户并发	建议，Nginx 处理静态资源，释放 Node.js

部署架构

用户 → Nginx (80/443) → 逸云 GIS (localhost:3000)

Nginx 负责处理 HTTPS、域名绑定、Gzip 压缩、静态资源缓存和安全防护，逸云 GIS 主程序仅监听本地 3000 端口。

.env 配置调整

使用 Nginx 代理后，.env 配置需要相应调整：

bash

# HTTP 端口（仅本地监听，Nginx 会代理到此端口）
PORT=3000

# 不需要 HTTPS 端口（由 Nginx 处理 SSL）
# HTTPS_PORT=3443

# 运行环境
NODE_ENV=production

# 必须开启代理信任，否则无法识别客户端真实 IP
TRUST_PROXY=true

# CORS 设置为实际域名（必须带 https:// 前缀，不要带尾部斜杠）
CORS_ORIGIN=https://eatool.cn

# 不需要配置 SSL 证书路径（由 Nginx 处理）
# SSL_CERT_PATH=
# SSL_KEY_PATH=

完整 Nginx 配置

以下配置覆盖了逸云 GIS 的所有路由，包括 API、瓦片代理、数据文件和邀请链接：

nginx

# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name eatool.cn;
    return 301 https://$server_name$request_uri;
}

# HTTPS 主服务
server {
    listen 443 ssl;
    http2 on;
    server_name eatool.cn;

    # ==================== SSL 证书 ====================
    ssl_certificate /etc/nginx/certs/eatool.cn_bundle.crt;
    ssl_certificate_key /etc/nginx/certs/eatool.cn.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # ==================== 安全头 ====================
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # ==================== Gzip 压缩 ====================
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript
               application/json application/javascript
               application/xml+rss application/atom+xml
               image/svg+xml;

    # ==================== API 请求 ====================
    # /api/auth, /api/admin, /api/ai, /api/skills, /api/sag-stress 等
    location /api/ {
        proxy_pass http://localhost:3000/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;

        # 大文件上传（COG/3D Tiles 最大 2GB）
        client_max_body_size 2G;
        proxy_connect_timeout 300s;
        proxy_send_timeout 1800s;
        proxy_read_timeout 1800s;
    }

    # ==================== 瓦片代理 ====================
    # /proxy/vector-tile/fujian/...  福建矢量瓦片
    # /proxy/satellite/...           全球卫星影像
    location /proxy/ {
        proxy_pass http://localhost:3000/proxy/;
        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;
    }

    # ==================== 数据文件 ====================
    # /data/users/...  用户私有数据（需认证，Node.js 处理）
    # /data/...        公共数据（行政区划 GeoJSON 等）
    # COG 文件需要 Range 请求支持（分块加载）
    location /data/ {
        proxy_pass http://localhost:3000/data/;
        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;
        # COG Range 请求支持
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
    }

    # ==================== 邀请链接 ====================
    # /join/:token  前端 SPA 路由
    location /join/ {
        proxy_pass http://localhost:3000/join/;
        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;
    }

    # ==================== 前端页面（兜底）====================
    location / {
        proxy_pass http://localhost:3000/;
        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;
    }

    # ==================== 静态资源长缓存 ====================
    # 带 hash 的 JS/CSS/图片等，可长期缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|glb|gltf)$ {
        proxy_pass http://localhost:3000;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

配置文件位置

操作系统	配置文件路径	说明
Ubuntu/Debian	`/etc/nginx/sites-available/eatool`	创建后软链接到 `sites-enabled/`
CentOS/RHEL	`/etc/nginx/conf.d/eatool.conf`	直接放入即可
Windows	`C:\nginx\conf\nginx.conf`	在 `http {}` 块内添加 `server {}`

Nginx 会先加载主配置 nginx.conf，再通过 include 指令引入 conf.d/*.conf 或 sites-enabled/* 中的站点配置，两者都会生效。

部署步骤

bash

# 1. 安装 Nginx
sudo apt install nginx

# 2. 上传 SSL 证书
sudo mkdir -p /etc/nginx/certs
sudo cp eatool.cn_bundle.crt /etc/nginx/certs/
sudo cp eatool.cn.key /etc/nginx/certs/
sudo chmod 600 /etc/nginx/certs/eatool.cn.key

# 3. 创建站点配置
sudo nano /etc/nginx/sites-available/eatool
# 粘贴上面的完整配置，保存退出

# 4. 启用配置
sudo ln -s /etc/nginx/sites-available/eatool /etc/nginx/sites-enabled/

# 5. 检查语法
sudo nginx -t

# 6. 启动 Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

使用自有证书

如果已有 SSL 证书，将证书文件放到服务器并修改配置中的路径：

nginx

ssl_certificate /etc/nginx/certs/your-domain_bundle.crt;
ssl_certificate_key /etc/nginx/certs/your-domain.key;

使用 Let's Encrypt 免费证书

bash

# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书并自动配置 Nginx
sudo certbot --nginx -d your-domain.com

# 自动续期（certbot 会自动添加定时任务）
sudo certbot renew --dry-run

Nginx 与 .env 配合对照

Nginx 配置	对应 `.env`	关系
`client_max_body_size 2G`	`MAX_FILE_SIZE_COG=2147483648`	Nginx 限制 ≥ .env 限制
`proxy_set_header X-Forwarded-*`	`TRUST_PROXY=true`	Node.js 需要读取这些头
`server_name eatool.cn`	`CORS_ORIGIN=https://eatool.cn`	域名一致
SSL 443 端口	`HTTPS_PORT` 注释掉	Node.js 不再启动 HTTPS
`proxy_pass http://localhost:3000`	`PORT=3000`	端口一致

常见问题

Nginx 启动失败：端口被占用

bash

# 查看 80 端口占用
ss -tlnp | grep :80

# 如果被 Node.js 占用，说明 Node.js 的 PORT 设为了 80
# 修改 .env 改回 3000，然后重启 Node.js

Nginx 代理模式下，端口分工如下：

端口	由谁监听	说明
80	Nginx	HTTP 入口，重定向到 HTTPS
443	Nginx	HTTPS 入口
3000	Node.js	仅本地访问，Nginx 代理到此端口

`listen ... http2` 废弃警告

Nginx 1.25.1+ 版本中，http2 不能写在 listen 行，需要独立配置：

nginx

# 旧写法（会报 warn）
listen 443 ssl http2;

# 新写法
listen 443 ssl;
http2 on;

`invalid PID number` 错误

Nginx 尚未启动时不能使用 -s reload，需要先启动：

bash

# 第一次启动
sudo systemctl start nginx

# 之后修改配置后重载
sudo nginx -s reload

重要提示

配置 Nginx 后，确保 .env 中设置 TRUST_PROXY=true，否则系统无法正确识别客户端 IP
建议在 Nginx 层面配置 HTTPS，逸云 GIS 主程序只需运行 HTTP（3000端口），无需启动 HTTPS
3000 端口不应对外暴露，可通过防火墙限制：sudo ufw deny 3000
CORS_ORIGIN 应设置为实际域名，不要使用 *
修改 Nginx 配置后务必执行 nginx -t 检查语法，然后 nginx -s reload 重新加载

Nginx 配置 #

何时使用 Nginx #

部署架构 #

.env 配置调整 #

完整 Nginx 配置 #

配置文件位置 #

部署步骤 #

使用自有证书 #

使用 Let's Encrypt 免费证书 #

Nginx 与 .env 配合对照 #

常见问题 #

Nginx 启动失败：端口被占用 #

listen ... http2 废弃警告 #

invalid PID number 错误 #

重要提示 #

Nginx 配置

何时使用 Nginx

部署架构

.env 配置调整

完整 Nginx 配置

配置文件位置

部署步骤

使用自有证书

使用 Let's Encrypt 免费证书

Nginx 与 .env 配合对照

常见问题

Nginx 启动失败：端口被占用

`listen ... http2` 废弃警告

`invalid PID number` 错误

重要提示