Nginx 反向代理
校对日期:2026-11-16。适用于社区版及全部商业版。
UJCMS 不依赖 Nginx:程序自己就能提供全部页面,包括生成的静态页。在前面加一层 Nginx 通常是为了使用 80 / 443 端口和 HTTPS 证书、 在一台服务器上放多个站点,或者让 Nginx 直接发送静态文件。本页给出配置,并说明加了代理之后必须同步修改的一项程序设置(真实 IP)。
一、基本配置:全部转发给程序
最简单也最不容易出错的做法,是把所有请求都转发给程序(以程序监听本机 8080 端口为例):
nginx
server {
listen 80;
server_name www.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $http_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_http_version 1.1;
proxy_buffering off;
proxy_connect_timeout 60s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
}
}- 超时要放宽。 AI 生成等请求耗时较长,
proxy_保持在 600 秒或以上,否则请求会被 Nginx 中途切断。read_ timeout - 不要在代理层缓存页面。 页面是否可缓存、缓存多久由程序通过响应头声明,见前台页面缓存与 CDN。
- 站点的协议和域名在后台设置。 程序生成链接时使用 配置 → 站点设置 → 基础设置 里的协议和域名,不从请求头推断; 启用 HTTPS 后记得把协议改为
https。端口在 配置 → 全局设置 → 基础设置 里,使用 80 / 443 时留空。
二、让程序拿到访客的真实 IP
经过代理之后,程序看到的来访地址是 Nginx 的地址。真实 IP 由上面配置中的 X-Forwarded-For 请求头带给程序, 但程序默认不信任这个请求头(它可以被伪造),需要明确告诉程序前面有几层代理:
yaml
# 0 = 没有代理(默认);1 = 一层反向代理;2 = CDN + 反向代理
ujcms.ip-proxy-depth: 1| 部署方式 | 在哪里设置 |
|---|---|
| Jar | config/ |
| Tomcat | WEB-INF/ |
| Docker | 环境变量 UJCMS_ |
修改后重启程序。说明:
- 程序从
X-Forwarded-For的右边数起,取第ip-proxy-depth个地址。数值必须与实际的代理层数一致:设小了拿到的是代理的地址, 设大了访客可以伪造自己的 IP。 - 设置为 1 或以上之后,程序的端口不要再直接对外开放(防火墙只放行 Nginx),否则绕过 Nginx 直接访问的人可以随意伪造 IP。
- 这个 IP 用于登录失败次数限制、后台 IP 白名单、验证码的触发、访问统计和操作日志,设置不对时这些功能都会受影响。
三、由 Nginx 直接发送静态文件(可选)
如果希望生成的静态页、上传的图片等由 Nginx 直接发送,可以把 root 指向程序的静态文件目录,文件不存在时再转发给程序:
nginx
server {
listen 80;
server_name www.example.com;
# 程序的静态文件目录:Jar 部署为 <部署目录>/static,Tomcat 部署为 tomcat/webapps/ROOT
root /opt/ujcms/static;
index index.html;
# 该目录下有安装令牌、备份文件和全文索引,不允许访问
location /WEB-INF/ {
deny all;
}
# 主题的资源目录可以直接发送
location ~* ^/themes/[^/]+/[^/]+/(assets|thumbnails|_files)/ {
try_files $uri @ujcms;
}
# 主题目录的其余部分(模板源文件)和主题安装包交给程序:程序只放行图片,其余返回 404
# (/_ 是一个不存在的文件名,写它是为了让请求总是转给程序)
location ~* ^/(themes|theme-packages)(/|$) {
try_files /_ @ujcms;
}
# 访问的是目录而地址末尾没有斜杠时,重定向到带斜杠的地址
if (-d $request_filename) {
rewrite ^/(.*[^/])$ $scheme://$host/$1/ permanent;
}
location / {
# 有对应的文件就直接发送,没有则转发给程序
try_files $uri $uri/index.html @ujcms;
}
location @ujcms {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $http_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_http_version 1.1;
proxy_buffering off;
proxy_connect_timeout 60s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
}
}使用这种配置时注意:
- 必须禁止访问
/WEB-INF/。 程序自己不会把这个目录暴露出去,但 Nginx 的root指到这里之后就需要在 Nginx 上禁止。 /themes/、/theme-packages/不能整个交给 Nginx 直接发送。 主题目录里除了样式、脚本,还有模板源文件、主题清单和演示数据,/theme-packages/里是完整的主题安装包;程序自己只放行资源目录和图片(见主题安全与部署约束的“主题文件的对外访问范围”一节),root指到这里之后要像上面那样把其余请求转回程序。两条规则的顺序不能颠倒;在后台改过这两个存储点的存储路径的, 把规则里的路径一并改掉。- 不要再按扩展名单独写
location(如location ~ \.)而不带转发。有一部分脚本、样式和编辑器文件打包在程序内部, 磁盘上没有对应的文件,这样写会让它们返回 404。需要设置缓存时间时,同样在其中使用(js|css)$ try_。files … @ujcms - 站点地图等地址始终由程序生成。
/sitemap*.xml、/robots.txt等没有对应的磁盘文件,按上面的写法会自动转发给程序; 如果另外写了规则,注意不要拦住它们,见站点地图与搜索引擎提交。 - 集群部署时静态文件目录在共享存储或对象存储上,做法不同,见集群部署。
四、常见问题
- 后台日志、访问统计里的 IP 全是
127.0.0.1或代理服务器的地址。 没有设置ujcms.,见“让程序拿到访客的真实 IP”一节。ip-proxy-depth - 耗时长的操作(如 AI 生成)中途失败,Nginx 日志里是 504。 代理超时太短,见“基本配置:全部转发给程序”一节的超时设置。
- 启用 HTTPS 后页面里的链接还是
http://。 到 配置 → 站点设置 → 基础设置 把协议改为https;使用了静态页的,再重新生成一次。