OWonlyWeb

Project Docs

ItemMark 标签打印与扫码查询系统 · ItemMark-Nginx-说明.md

在线查看上传的 Markdown 项目文档。

返回作品详情下载原始文档

ItemMark 项目 Nginx 配置说明

一、Nginx 在项目中的作用

ItemMark 是统一运行在 Docker 容器内的 Web 应用，内部服务端口为 `18089`。Nginx 作为反向代理层，承担以下核心职责：

作用说明
反向代理将外网对 80/443/34433 端口的请求转发给本机 127.0.0.1:18089（Docker 容器）
SSL/TLS 终止Nginx 处理 HTTPS 加密解密（证书卸载），后端容器只需跑纯 HTTP
HTTP 自动跳转80 端口的 HTTP 请求自动 301 跳转到 HTTPS，避免明文传输
统一入口对外提供标准域名+端口访问，整合 material-info、wuping 等多个模块
证书管理集中存放和管理 HTTPS 证书，业务代码无需关心证书逻辑
外网用户 (手机/电脑)
    │
    ▼
https://code.zestrade.com:34433/
    │
    ▼
路由器 443/34433 端口映射
    │
    ▼
Nginx (0.0.0.0:443 / 0.0.0.0:34433)
    │  SSL 解密 + Host 头透传
    ▼
Docker 容器 (127.0.0.1:18089)
    │
    ▼
ItemMark Web 服务

二、工作原理

2.1 为什么需要 Nginx？

ItemMark 的 Docker 容器只把 18089 映射到了宿主机：

yaml
# docker-compose.yml
services:
  web:
    ports:
      - "18089:18089"

如果直接让外网访问 http://xxx:18089，存在三个问题：

  1. 端口不标准 — 用户需要记忆非常用端口，容易出错
  2. 无 HTTPS — 明文传输，手机浏览器/微信会拦截或提示"不安全"
  3. 无自动跳转 — 用户可能误用 HTTP，导致二维码链接失效或中间人攻击

Nginx 解决了以上所有问题：对外暴露标准的 80/443 端口，提供 HTTPS 加密，并自动把 HTTP 跳转到 HTTPS。

2.2 请求完整流向

以手机扫码访问 https://code.zestrade.com:34433/material/2101010045 为例：

步骤处理方动作
1手机浏览器DNS 解析 code.zestrade.com → 公网 IP
2路由器NAT 端口映射：公网 IP:34433 → 192.168.1.14:34433
3Nginx接收 HTTPS 请求，SSL 握手，验证证书
4Nginx解密后把请求转发到 http://127.0.0.1:18089/material/2101010045
5Nginx将后端返回的响应重新加密，回传给手机

2.3 关键请求头透传

Nginx 在反向代理时会向后端传递以下头部，确保业务逻辑正确：

nginx
proxy_set_header Host $host;                    # 保留原始域名
proxy_set_header X-Real-IP $remote_addr;        # 真实客户端 IP
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # 代理链 IP
proxy_set_header X-Forwarded-Proto $scheme;     # 原始协议 https

ItemMark 后端通过这些头部生成正确的二维码 URL、判断访问协议等。

三、配置文件说明

3.1 实际生效的系统配置

路径： /etc/nginx/sites-available/code.zestrade.com

软链接： /etc/nginx/sites-enabled/code.zestrade.com → /etc/nginx/sites-available/code.zestrade.com

⚠️ 注意： Nginx 启动时读取的是 /etc/nginx/sites-enabled/ 下的文件，修改项目目录 /root/ItemMark/config/nginx.conf 不会自动生效，必须同步到系统配置并执行 nginx -s reload。

3.2 配置内容详解

nginx
# HTTP 入口：强制跳转到 HTTPS
server {
    listen 80;
    server_name code.zestrade.com;
    return 301 https://$host$request_uri;
}

# HTTPS 入口：处理所有业务请求
server {
    listen 443 ssl;
    listen 34433 ssl;       # 非标准端口，用于外网备案后访问
    server_name code.zestrade.com;

    # SSL 证书（必须使用绝对路径）
    ssl_certificate     /root/ItemMark/certs/code.zestrade.com/code.zestrade.com.crt;
    ssl_certificate_key /root/ItemMark/certs/code.zestrade.com/code.zestrade.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    # 反向代理到 ItemMark Docker 容器
    location / {
        proxy_pass http://127.0.0.1:18089;
        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_read_timeout 60s;
    }
}

3.3 项目目录下的参考配置

路径： /root/ItemMark/config/nginx.conf

这个文件是项目自带的参考模板，供部署时参考。其中的证书路径写的是相对路径 ./certs/...，直接用于系统 Nginx 时会因路径解析错误导致启动失败。

正确做法： 将项目模板的内容复制到 /etc/nginx/sites-available/code.zestrade.com，并把证书路径改为绝对路径。

四、常用操作命令

bash
# 测试配置语法是否正确（修改后必做）
nginx -t

# 平滑重载配置（不中断现有连接）
nginx -s reload

# 查看 Nginx 运行状态
systemctl status nginx

# 重启 Nginx 服务（配置错误无法 reload 时使用）
systemctl restart nginx

# 查看 Nginx 访问日志
tail -f /var/log/nginx/access.log

# 查看 Nginx 错误日志
tail -f /var/log/nginx/error.log

五、注意事项与常见问题

5.1 修改配置后必须 reload

Nginx 只有在 start 或 reload 时才会重新读取配置文件。修改 /etc/nginx/sites-available/code.zestrade.com 后，必须执行：

bash
nginx -t && nginx -s reload

5.2 证书路径必须用绝对路径

系统 Nginx 的工作目录通常是 /etc/nginx 或 /，相对路径 ./certs/xxx 会解析到错误位置，导致：

nginx: [emerg] BIO_new_file("./certs/...") failed (SSL: error:02001002:system library:fopen:No such file or directory)

正确写法：

nginx
ssl_certificate /root/ItemMark/certs/code.zestrade.com/code.zestrade.com.crt;

5.3 防火墙必须放行端口

UFW 或 iptables 需要显式允许 80、443、34433：

bash
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 34433/tcp

5.4 路由器端口映射

外网访问需要路由器做 NAT 端口映射（虚拟服务器）：

外部端口内部 IP内部端口协议
80192.168.1.1480TCP
443192.168.1.14443TCP
34433192.168.1.1434433TCP
如果之前成功过后来不行，优先检查路由器映射是否因重启丢失。

5.5 二维码 URL 端口一致性

ItemMark 生成的二维码内容基于 QR_BASE_URL。如果 Nginx 监听的是 34433，则 .env 和模块配置中的 QR_BASE_URL 必须带上该端口：

ini
# config/modules/material-info.env
QR_BASE_URL=https://code.zestrade.com:34433

# config/modules/wuping.env
QR_BASE_URL=https://code.zestrade.com:34433/wuping

修改后需要重启 Docker 容器才能生效：

bash
cd /root/ItemMark && docker compose restart

5.6 域名解析检查清单

外网无法访问时，按以下顺序排查：

  1. 域名解析 — dig code.zestrade.com 是否指向正确公网 IP？
  2. 路由器映射 — 端口转发是否配置并生效？
  3. 本机防火墙 — ufw status 是否放行了对应端口？
  4. Nginx 监听 — ss -tlnp | grep ':443' 是否显示 0.0.0.0:443？
  5. 后端服务 — curl http://127.0.0.1:18089/api/health 是否返回正常？
  6. Nginx 配置 — nginx -t 是否通过？

六、总结

Nginx 在 ItemMark 项目中是外网与 Docker 容器之间的网关，负责：

  • 提供标准 HTTPS 入口（域名 + 443/34433）
  • SSL 加密卸载
  • HTTP 自动跳转
  • 请求头透传

配置核心原则： 系统配置用绝对路径、改完必 reload、防火墙和路由器要放行、二维码 URL 端口与 Nginx 监听端口保持一致。